aws.iam-user

Filters

access-key

Filter IAM users based on access-key values

By default multiple uses of this filter will match on any user key satisfying either filter. To find specific keys that match multiple access-key filters, use match-operator: and

example:

policies:
  - name: iam-users-with-active-keys
    resource: iam-user
    filters:
      - type: access-key
        key: Status
        value: Active
      - type: access-key
        match-operator: and
        key: CreateDate
        value_type: age
        value: 90
properties:
  default:
    type: object
  key:
    type: string
  match-operator:
    enum:
    - and
    - or
  op:
    enum:
    - eq
    - equal
    - ne
    - not-equal
    - gt
    - greater-than
    - ge
    - gte
    - le
    - lte
    - lt
    - less-than
    - glob
    - regex
    - regex-case
    - in
    - ni
    - not-in
    - contains
    - difference
    - intersect
    - mod
  type:
    enum:
    - access-key
  value:
    oneOf:
    - type: array
    - type: string
    - type: boolean
    - type: number
    - type: 'null'
  value_from:
    additionalProperties: 'False'
    properties:
      expr:
        oneOf:
        - type: integer
        - type: string
      format:
        enum:
        - csv
        - json
        - txt
        - csv2dict
      headers:
        patternProperties:
          ? ''
          : type: string
        type: object
      query:
        type: string
      url:
        type: string
    required:
    - url
    type: object
  value_path:
    type: string
  value_regex:
    type: string
  value_type:
    enum:
    - age
    - integer
    - expiration
    - normalize
    - size
    - cidr
    - cidr_size
    - swap
    - resource_count
    - expr
    - unique_size
    - date
    - version
    - float
required:
- type

Permissions - iam:ListAccessKeys

credential

Use IAM Credential report to filter users.

The IAM Credential report aggregates multiple pieces of information on iam users. This makes it highly efficient for querying multiple aspects of a user that would otherwise require per user api calls.

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_getting-report.html

For example if we wanted to retrieve all users with mfa who have never used their password but have active access keys from the last month

- name: iam-mfa-active-keys-no-login
  resource: iam-user
  filters:
    - type: credential
      key: mfa_active
      value: true
    - type: credential
      key: password_last_used
      value: absent
    - type: credential
      key: access_keys.last_used_date
      value_type: age
      value: 30
      op: less-than

Credential Report Transforms

We perform some default transformations from the raw credential report. Sub-objects (access_key_1, cert_2) are turned into array of dictionaries for matching purposes with their common prefixes stripped. N/A values are turned into None, TRUE/FALSE are turned into boolean values.

properties:
  key:
    enum:
    - user
    - arn
    - user_creation_time
    - password_enabled
    - password_last_used
    - password_last_changed
    - password_next_rotation
    - mfa_active
    - access_keys
    - access_keys.active
    - access_keys.last_used_date
    - access_keys.last_used_region
    - access_keys.last_used_service
    - access_keys.last_rotated
    - certs
    - certs.active
    - certs.last_rotated
    title: report key to search
    type: string
  op:
    enum:
    - eq
    - equal
    - ne
    - not-equal
    - gt
    - greater-than
    - ge
    - gte
    - le
    - lte
    - lt
    - less-than
    - glob
    - regex
    - regex-case
    - in
    - ni
    - not-in
    - contains
    - difference
    - intersect
    - mod
  report_delay:
    default: 10
    title: Number of seconds to wait for report generation.
    type: number
  report_generate:
    default: true
    title: Generate a report if none is present.
    type: boolean
  report_max_age:
    default: 86400
    title: Number of seconds to consider a report valid.
    type: number
  type:
    enum:
    - credential
  value:
    oneOf:
    - type: array
    - type: string
    - type: boolean
    - type: number
    - type: 'null'
  value_type:
    enum:
    - age
    - integer
    - expiration
    - normalize
    - size
    - cidr
    - cidr_size
    - swap
    - resource_count
    - expr
    - unique_size
    - date
    - version
    - float
required:
- type

Permissions - iam:GenerateCredentialReport, iam:GetCredentialReport

group

Filter IAM users based on attached group values

example:

policies:
  - name: iam-users-in-admin-group
    resource: iam-user
    filters:
      - type: group
        key: GroupName
        value: Admins
properties:
  default:
    type: object
  key:
    type: string
  op:
    enum:
    - eq
    - equal
    - ne
    - not-equal
    - gt
    - greater-than
    - ge
    - gte
    - le
    - lte
    - lt
    - less-than
    - glob
    - regex
    - regex-case
    - in
    - ni
    - not-in
    - contains
    - difference
    - intersect
    - mod
  type:
    enum:
    - group
  value:
    oneOf:
    - type: array
    - type: string
    - type: boolean
    - type: number
    - type: 'null'
  value_from:
    additionalProperties: 'False'
    properties:
      expr:
        oneOf:
        - type: integer
        - type: string
      format:
        enum:
        - csv
        - json
        - txt
        - csv2dict
      headers:
        patternProperties:
          ? ''
          : type: string
        type: object
      query:
        type: string
      url:
        type: string
    required:
    - url
    type: object
  value_path:
    type: string
  value_regex:
    type: string
  value_type:
    enum:
    - age
    - integer
    - expiration
    - normalize
    - size
    - cidr
    - cidr_size
    - swap
    - resource_count
    - expr
    - unique_size
    - date
    - version
    - float
required:
- type

Permissions - iam:ListGroupsForUser

has-inline-policy

Filter IAM users that have an inline-policy attached

True: Filter users that have an inline-policy False: Filter users that do not have an inline-policy

properties:
  type:
    enum:
    - has-inline-policy
  value:
    type: boolean
required:
- type

Permissions - iam:ListUserPolicies

json-diff

Compute the diff from the current resource to a previous version.

A resource matches the filter if a diff exists between the current resource and the selected revision.

Utilizes config as a resource revision database.

Revisions can be selected by date, against the previous version, and against a locked version (requires use of is-locked filter).

properties:
  selector:
    enum:
    - previous
    - date
    - locked
  selector_value:
    type: string
  type:
    enum:
    - json-diff
required:
- type

Permissions - config:GetResourceConfigHistory

mfa-device

Filter iam-users based on mfa-device status

example:

policies:
  - name: mfa-enabled-users
    resource: iam-user
    filters:
      - type: mfa-device
        key: UserName
        value: not-null
properties:
  default:
    type: object
  key:
    type: string
  op:
    enum:
    - eq
    - equal
    - ne
    - not-equal
    - gt
    - greater-than
    - ge
    - gte
    - le
    - lte
    - lt
    - less-than
    - glob
    - regex
    - regex-case
    - in
    - ni
    - not-in
    - contains
    - difference
    - intersect
    - mod
  type:
    enum:
    - mfa-device
  value:
    oneOf:
    - type: array
    - type: string
    - type: boolean
    - type: number
    - type: 'null'
  value_from:
    additionalProperties: 'False'
    properties:
      expr:
        oneOf:
        - type: integer
        - type: string
      format:
        enum:
        - csv
        - json
        - txt
        - csv2dict
      headers:
        patternProperties:
          ? ''
          : type: string
        type: object
      query:
        type: string
      url:
        type: string
    required:
    - url
    type: object
  value_path:
    type: string
  value_regex:
    type: string
  value_type:
    enum:
    - age
    - integer
    - expiration
    - normalize
    - size
    - cidr
    - cidr_size
    - swap
    - resource_count
    - expr
    - unique_size
    - date
    - version
    - float
required:
- type

Permissions - iam:ListMFADevices

policy

Filter IAM users based on attached policy values

example:

policies:
  - name: iam-users-with-admin-access
    resource: iam-user
    filters:
      - type: policy
        key: PolicyName
        value: AdministratorAccess
        include-via: true
properties:
  default:
    type: object
  include-via:
    type: boolean
  key:
    type: string
  op:
    enum:
    - eq
    - equal
    - ne
    - not-equal
    - gt
    - greater-than
    - ge
    - gte
    - le
    - lte
    - lt
    - less-than
    - glob
    - regex
    - regex-case
    - in
    - ni
    - not-in
    - contains
    - difference
    - intersect
    - mod
  type:
    enum:
    - policy
  value:
    oneOf:
    - type: array
    - type: string
    - type: boolean
    - type: number
    - type: 'null'
  value_from:
    additionalProperties: 'False'
    properties:
      expr:
        oneOf:
        - type: integer
        - type: string
      format:
        enum:
        - csv
        - json
        - txt
        - csv2dict
      headers:
        patternProperties:
          ? ''
          : type: string
        type: object
      query:
        type: string
      url:
        type: string
    required:
    - url
    type: object
  value_path:
    type: string
  value_regex:
    type: string
  value_type:
    enum:
    - age
    - integer
    - expiration
    - normalize
    - size
    - cidr
    - cidr_size
    - swap
    - resource_count
    - expr
    - unique_size
    - date
    - version
    - float
required:
- type

Permissions - iam:ListAttachedUserPolicies, iam:ListGroupsForUser, iam:ListAttachedGroupPolicies

ssh-key

Filter IAM users based on uploaded SSH public keys

example:

policies:
  - name: iam-users-with-old-ssh-keys
    resource: iam-user
    filters:
      - type: ssh-key
        key: Status
        value: Active
      - type: ssh-key
        key: UploadDate
        value_type: age
        value: 90
properties:
  default:
    type: object
  key:
    type: string
  op:
    enum:
    - eq
    - equal
    - ne
    - not-equal
    - gt
    - greater-than
    - ge
    - gte
    - le
    - lte
    - lt
    - less-than
    - glob
    - regex
    - regex-case
    - in
    - ni
    - not-in
    - contains
    - difference
    - intersect
    - mod
  type:
    enum:
    - ssh-key
  value:
    oneOf:
    - type: array
    - type: string
    - type: boolean
    - type: number
    - type: 'null'
  value_from:
    additionalProperties: 'False'
    properties:
      expr:
        oneOf:
        - type: integer
        - type: string
      format:
        enum:
        - csv
        - json
        - txt
        - csv2dict
      headers:
        patternProperties:
          ? ''
          : type: string
        type: object
      query:
        type: string
      url:
        type: string
    required:
    - url
    type: object
  value_path:
    type: string
  value_regex:
    type: string
  value_type:
    enum:
    - age
    - integer
    - expiration
    - normalize
    - size
    - cidr
    - cidr_size
    - swap
    - resource_count
    - expr
    - unique_size
    - date
    - version
    - float
required:
- type

Permissions - iam:ListSSHPublicKeys

Actions

delete

Delete a user or properties of a user.

For example if you want to have a whitelist of valid (machine-)users and want to ensure that no users have been clicked without documentation.

You can use both the ‘credential’ or the ‘username’ filter. ‘credential’ will have an SLA of 4h, (http://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_getting-report.html), but the added benefit of performing less API calls, whereas ‘username’ will make more API calls, but have a SLA of your cache.

example:
# using a 'credential' filter'
- name: iam-only-whitelisted-users-credential
  resource: iam-user
  filters:
    - type: credential
      key: user
      op: not-in
      value:
        - valid-user-1
        - valid-user-2
  actions:
    - delete

# using a 'username' filter with 'UserName'
- name: iam-only-whitelisted-users-username
  resource: iam-user
  filters:
    - type: value
      key: UserName
      op: not-in
      value:
        - valid-user-1
        - valid-user-2
  actions:
    - delete

 # using a 'username' filter with 'Arn'
- name: iam-only-whitelisted-users-arn
  resource: iam-user
  filters:
    - type: value
      key: Arn
      op: not-in
      value:
        - arn:aws:iam:123456789012:user/valid-user-1
        - arn:aws:iam:123456789012:user/valid-user-2
  actions:
    - delete

Additionally, you can specify the options to delete properties of an iam-user, including console-access, access-keys, attached-user-policies, inline-user-policies, mfa-devices, groups, ssh-keys, signing-certificates, and service-specific-credentials.

Note: using options will _not_ delete the user itself, only the items specified by options that are attached to the respective iam-user. To delete a user completely, use the delete action without specifying options.

example:
- name: delete-console-access-unless-valid
  comment: |
    finds iam-users with console access and deletes console access unless
    the username is included in whitelist
  resource: iam-user
  filters:
    - type: value
      key: UserName
      op: not-in
      value:
        - valid-user-1
        - valid-user-2
    - type: credential
      key: password_enabled
      value: true
  actions:
    - type: delete
      options:
        - console-access

- name: delete-misc-access-for-iam-user
  comment: |
    deletes multiple options from test_user
  resource: iam-user
  filters:
    - UserName: test_user
  actions:
    - type: delete
      options:
        - mfa-devices
        - access-keys
        - ssh-keys
properties:
  options:
    items:
      enum:
      - console-access
      - access-keys
      - attached-user-policies
      - inline-user-policies
      - mfa-devices
      - groups
      - ssh-keys
      - signing-certificates
      - service-specific-credentials
      - user-policies
      type: string
    type: array
  type:
    enum:
    - delete
required:
- type

Permissions - iam:ListAttachedUserPolicies, iam:ListAccessKeys, iam:ListGroupsForUser, iam:ListMFADevices, iam:ListServiceSpecificCredentials, iam:ListSigningCertificates, iam:ListSSHPublicKeys, iam:DeactivateMFADevice, iam:DeleteAccessKey, iam:DeleteLoginProfile, iam:DeleteSigningCertificate, iam:DeleteSSHPublicKey, iam:DeleteUser, iam:DeleteUserPolicy, iam:DetachUserPolicy, iam:RemoveUserFromGroup

delete-ssh-keys

Delete or disable a user’s SSH keys.

For example to delete keys after 90 days:

example:
- name: iam-user-delete-ssh-keys
  resource: iam-user
  actions:
    - type: delete-ssh-keys
properties:
  disable:
    type: boolean
  matched:
    type: boolean
  type:
    enum:
    - delete-ssh-keys
required:
- type

Permissions - iam:ListSSHPublicKeys, iam:UpdateSSHPublicKey, iam:DeleteSSHPublicKey

remove-keys

Delete or disable user’s access keys.

For example if we wanted to disable keys after 90 days of non-use and delete them after 180 days of nonuse:

example:
- name: iam-mfa-active-key-no-login
  resource: iam-user
  actions:
    - type: remove-keys
      disable: true
      age: 90
    - type: remove-keys
      age: 180
properties:
  age:
    type: number
  disable:
    type: boolean
  matched:
    type: boolean
  type:
    enum:
    - remove-keys
required:
- type

Permissions - iam:ListAccessKeys, iam:UpdateAccessKey, iam:DeleteAccessKey

set-boundary

Set IAM Permission boundary on an IAM Role or User.

A role or user can only have a single permission boundary set.

properties:
  policy:
    type: string
  state:
    enum:
    - present
    - absent
  type:
    enum:
    - set-boundary
required:
- type

Permissions - iam:PutUserPermissionsBoundary

set-groups

Set a specific IAM user as added/removed from a group

example:
- name: iam-user-add-remove
  resource: iam-user
  filters:
    - type: value
      key: UserName
      value: Bob
  actions:
    - type: set-groups
      state: remove
      group: Admin
properties:
  group:
    type: string
  state:
    enum:
    - add
    - remove
  type:
    enum:
    - set-groups
required:
- state
- group
- type

Permissions - iam:AddUserToGroup, iam:RemoveUserFromGroup

set-policy

Set a specific IAM policy as attached or detached on a user.

You will identify the policy by its arn.

Returns a list of roles modified by the action.

For example, if you want to automatically attach a single policy while detaching all exisitng policies:

example:
- name: iam-attach-user-policy
  resource: iam-user
  filters:
    - type: value
      key: UserName
      op: not-in
      value:
        - AdminUser1
        - AdminUser2
  actions:
    - type: set-policy
      state: detached
      arn: arn:aws:iam::aws:policy/AdministratorAccess
properties:
  arn:
    type: string
  state:
    enum:
    - attached
    - detached
  type:
    enum:
    - set-policy
required:
- state
- arn
- type

Permissions - iam:AttachUserPolicy, iam:DetachUserPolicy, iam:ListAttachedUserPolicies