aws_iam_user

Use the aws_iam_user InSpec audit resource to test properties of a single AWS IAM user.

To test properties of more than one user, use the aws_iam_users resource.

To test properties of the special AWS root user (which owns the account), use the aws_iam_root_user resource.


Availability

Installation

This resource is distributed along with InSpec itself. You can use it automatically.

Version

This resource first became available in v2.0.16 of InSpec.

Resource Parameters

An aws_iam_user resource block declares a user by name, and then lists tests to be performed.

describe aws_iam_user(username: 'test_user') do
  it { should exist }
end


Examples

The following examples show how to use this InSpec audit resource.

Test that a user does not exist

describe aws_iam_user(username: 'gone') do
  it { should_not exist }
end

Test that a user has multi-factor authentication enabled

describe aws_iam_user(username: 'test_user') do
  it { should have_mfa_enabled }
end

Test that a service user does not have a password

describe aws_iam_user(username: 'test_user') do
  it { should have_console_password }
end


Properties

attached_policy_arns

Returns a list of IAM Managed Policy ARNs as strings that identify the policies that are attached to the user. If there are no attached policies, returns an empty list.

describe aws_iam_user('bob') do
  # This is a customer-managed policy
  its('attached_policy_arns') { should include 'arn:aws:iam::123456789012:policy/test-inline-policy-01' }
  # This is an AWS-managed policy
  its('attached_policy_arns') { should include 'arn:aws:iam::aws:policy/AlexaForBusinessGatewayExecution' }
end

attached_policy_names

Returns a list of IAM Managed Policy Names as strings that identify the policies that are attached to the user. If there are no attached policies, returns an empty list.

describe aws_iam_user('bob') do
  # This is a customer-managed policy
  its('attached_policy_names') { should include 'test-inline-policy-01' }
  # This is an AWS-managed policy
  its('attached_policy_names') { should include 'AlexaForBusinessGatewayExecution' }
end

inline_policy_names

Returns a list of IAM Inline Policy Names as strings that identify the inline policies that are directly embedded in the user. If there are no embedded policies, returns an empty list.

describe aws_iam_user('bob') do
  its('inline_policy_names') { should include 'test-inline-policy-01' }
  its('inline_policy_names.count') { should eq 1 }
end

Matchers

This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our universal matchers page.

have_attached_policies

The have\_attached\_policies matcher tests if the user has at least one IAM managed policy attached to the user.

describe aws_iam_user('bob') do
  it { should_not have_attached_policies }
end

have_console_password

The have_console_password matcher tests if the user has a password that could be used to log into the AWS web console.

it { should have_console_password }

have_inline_policies

The have\_inline\_policies matcher tests if the user has at least one IAM policy embedded directly in the user record.

describe aws_iam_user('bob') do
  it { should_not have_inline_policies }
end

have_mfa_enabled

The have_mfa_enabled matcher tests if the user has Multi-Factor Authentication enabled, requiring them to enter a secondary code when they login to the web console.

it { should have_mfa_enabled }

AWS Permissions

Your Principal will need the iam:GetUser, iam:GetLoginProfile, iam:ListMFADevices, iam:ListAccessKeys, iam:ListUserPolicies, and iam:ListAttachedUserPolicies actions set to allow.

You can find detailed documentation at Actions, Resources, and Condition Keys for Identity And Access Management.