aws_iam_groups

Use the aws_iam_groups Chef InSpec audit resource to test properties of all or multiple groups.

To test properties of a single group, use the aws_iam_group resource.


Availability

Installation

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

Version

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

Syntax

An aws_iam_groups resource block uses an optional filter to select a collection of IAM groups and then tests that collection.

# The control will pass if the filter returns at least one result. Use `should_not` if you expect zero matches.
describe aws_iam_groups do
  it { should exist }
end


Examples

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

As this is the initial release of aws_iam_groups, its limited functionality precludes examples.


Filter Criteria

group_name

Filters the IAM groups by their group name, a string. If you know the exact group name, use aws_iam_group (singular) instead. This criteria may be used when you know a pattern of the name.

# Use a regex to find groups ending with 'Admins'
describe aws_iam_groups.where(group_name: /Admins$/) do
  its('group_names') { should include 'FriendlyAdmins' }
  its('group_names') { shoud_not include 'ShunnedAdmins' }
end

Properties

group_names

An Array of Strings, reflecting the IAM group names matched by the filter. If no groups matched, this will be empty. You can also use this with aws_iam_group to enumerate groups.

# Check for friendly people
describe aws_iam_groups.where(group_name: /Admins$/) do
  its('group_names') { should include 'FriendlyAdmins' }
  its('group_names') { should include 'KindAdmins' }
end

# Use to loop and fetch groups individually for auditing in detail
# Without a `where`, this fetches all groups
aws_iam_groups.group_names.each do |group_names|
  # A roundabout way of saying "bob should not be in any groups"
  describe aws_iam_group(group_name) do
    its('users') { should_not include 'bob' }
  end
end

Matchers

This resource has no resource-specific matchers. For a full list of available matchers, please visit our Universal Matchers page.

exists

The control will pass if the filter returns at least one result. Use should_not if you expect zero matches.

describe aws_iam_groups
  it { should exist }
end

AWS Permissions

Your Principal will need the iam:ListGroups action with Effect set to Allow.

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