inspec 2.1.43 → 2.1.54

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 20615575585069d827d93b1bda43540f5cb7b0fc
-  data.tar.gz: ba4ce3f0d578f97e2aee6304326bc81f40cc50f7
+  metadata.gz: 70091b75b95f9e09f83249bc3ed5de294da9989c
+  data.tar.gz: c481fe8cdd37aae2eecc2ce18481924d0f9dcead
 SHA512:
-  metadata.gz: e55df70b1b8dd5bc9f86029354cbf3c179237a5a777dd73e60351286900ba13e97d9d2a60a5446928e2b1296563696e951cd2fca7c050a8c855a4e91950726f3
-  data.tar.gz: f98ba1d732e28565113d7bc5eb91440736abc4c847954a0663cf9313773039cbef11814ad4d7b087cfd1a06fa094e33c67b832128dee504533a67abde8803017
+  metadata.gz: 43840caed0f0399d671b5514940f7c9dc2c73cdac09820609e9bd132cc0b7c30d4985690c8674638473aea52b5644a658eafb2feac4a399e3182078d4edd4693
+  data.tar.gz: 3d1e4c52daf5a58b8ea2b1f0705e7fb375a1579d4b279cc774058e015c6dfe9efea650ba2400e6ee8ec0aa78427975e13abac78ace6c8885fc35567572a462d9

data/CHANGELOG.md

@@ -1,36 +1,58 @@
 # Change Log
 <!-- usage documentation: http://expeditor-docs.es.chef.io/configuration/changelog/ -->
-<!-- latest_release 2.1.43 -->
-## [v2.1.43](https://github.com/chef/inspec/tree/v2.1.43) (2018-04-12)
+<!-- latest_release 2.1.54 -->
+## [v2.1.54](https://github.com/chef/inspec/tree/v2.1.54) (2018-04-19)
 
-#### Merged Pull Requests
-- powershell resource: Add support line for Unix [#2952](https://github.com/chef/inspec/pull/2952) ([jerryaldrichiii](https://github.com/jerryaldrichiii))
+#### Bug Fixes
+- Add missing `git` to Dockerfile. [#2969](https://github.com/chef/inspec/pull/2969) ([miah](https://github.com/miah))
 <!-- latest_release -->
 
-<!-- release_rollup since=2.1.30 -->
-### Changes since 2.1.30 release
-
-#### Enhancements
-- Add Cisco IOS `enable_password` support [#2905](https://github.com/chef/inspec/pull/2905) ([jerryaldrichiii](https://github.com/jerryaldrichiii)) <!-- 2.1.42 -->
-- Require a key attribute for the key_rsa resource [#2891](https://github.com/chef/inspec/pull/2891) ([omar-irizarry](https://github.com/omar-irizarry)) <!-- 2.1.41 -->
-- Ensure @params in shadow resource always has a valid value. [#2939](https://github.com/chef/inspec/pull/2939) ([miah](https://github.com/miah)) <!-- 2.1.39 -->
-- Add warning when returning DEFAULT_ATTRIBUTE [#2934](https://github.com/chef/inspec/pull/2934) ([TrevorBramble](https://github.com/TrevorBramble)) <!-- 2.1.35 -->
+<!-- release_rollup since=2.1.43 -->
+### Changes since 2.1.43 release
 
 #### Merged Pull Requests
-- powershell resource: Add support line for Unix [#2952](https://github.com/chef/inspec/pull/2952) ([jerryaldrichiii](https://github.com/jerryaldrichiii)) <!-- 2.1.43 -->
-- Fixes configuration for Azure integrationt tests [#2941](https://github.com/chef/inspec/pull/2941) ([dmccown](https://github.com/dmccown)) <!-- 2.1.36 -->
-- Update filesystem.md.erb [#2909](https://github.com/chef/inspec/pull/2909) ([tlmikulski](https://github.com/tlmikulski)) <!-- 2.1.34 -->
+- Add A2 support to the inspec-compliance toolset [#2963](https://github.com/chef/inspec/pull/2963) ([jquick](https://github.com/jquick)) <!-- 2.1.52 -->
 
 #### New Features
-- Basic fields for aws_vpcs [#2930](https://github.com/chef/inspec/pull/2930) ([clintoncwolfe](https://github.com/clintoncwolfe)) <!-- 2.1.40 -->
-- Policy Statement Search capability for aws_iam_policy [#2918](https://github.com/chef/inspec/pull/2918) ([clintoncwolfe](https://github.com/clintoncwolfe)) <!-- 2.1.38 -->
-- New attribute JUnit reporter - target [#2839](https://github.com/chef/inspec/pull/2839) ([piotrgo](https://github.com/piotrgo)) <!-- 2.1.37 -->
-- AWS Security Group Rules properties and matchers [#2876](https://github.com/chef/inspec/pull/2876) ([clintoncwolfe](https://github.com/clintoncwolfe)) <!-- 2.1.33 -->
-- aws_cloudtrail_trail feature: test how many days ago logs were delivered [#2887](https://github.com/chef/inspec/pull/2887) ([dromazmj](https://github.com/dromazmj)) <!-- 2.1.32 -->
-- aws_iam_group feature: test users in an iam group [#2888](https://github.com/chef/inspec/pull/2888) ([dromazmj](https://github.com/dromazmj)) <!-- 2.1.31 -->
+- Inline and attached policies for aws_iam_user and aws_iam_users [#2947](https://github.com/chef/inspec/pull/2947) ([clintoncwolfe](https://github.com/clintoncwolfe)) <!-- 2.1.48 -->
+
+#### Bug Fixes
+- Add missing `git` to Dockerfile. [#2969](https://github.com/chef/inspec/pull/2969) ([miah](https://github.com/miah)) <!-- 2.1.54 -->
+- updating kitchen-puppet example for the `puppet_apply` provisioner [#2972](https://github.com/chef/inspec/pull/2972) ([moutons](https://github.com/moutons)) <!-- 2.1.49 -->
+- Policy statement search: don&#39;t stacktrace on missing field [#2962](https://github.com/chef/inspec/pull/2962) ([clintoncwolfe](https://github.com/clintoncwolfe)) <!-- 2.1.47 -->
+- Fixed numerous naming errors in aws_iam_vpcs integration tests [#2961](https://github.com/chef/inspec/pull/2961) ([clintoncwolfe](https://github.com/clintoncwolfe)) <!-- 2.1.46 -->
+- aws_iam_policy statement search fix for degenerate policies [#2958](https://github.com/chef/inspec/pull/2958) ([clintoncwolfe](https://github.com/clintoncwolfe)) <!-- 2.1.45 -->
+
+#### Enhancements
+- Make names for AWS Config service objects optional [#2928](https://github.com/chef/inspec/pull/2928) ([clintoncwolfe](https://github.com/clintoncwolfe)) <!-- 2.1.53 -->
+- Upgrade Terraform version pins for integration testing [#2968](https://github.com/chef/inspec/pull/2968) ([clintoncwolfe](https://github.com/clintoncwolfe)) <!-- 2.1.51 -->
+- Amazon linux service mgmt detection [#2970](https://github.com/chef/inspec/pull/2970) ([meringu](https://github.com/meringu)) <!-- 2.1.50 -->
+- updating output for aws_iam_role to match other AWS resources [#2960](https://github.com/chef/inspec/pull/2960) ([tmonk42](https://github.com/tmonk42)) <!-- 2.1.44 -->
 <!-- release_rollup -->
 
 <!-- latest_stable_release -->
+## [v2.1.43](https://github.com/chef/inspec/tree/v2.1.43) (2018-04-12)
+
+#### New Features
+- aws_iam_group feature: test users in an iam group [#2888](https://github.com/chef/inspec/pull/2888) ([dromazmj](https://github.com/dromazmj))
+- aws_cloudtrail_trail feature: test how many days ago logs were delivered [#2887](https://github.com/chef/inspec/pull/2887) ([dromazmj](https://github.com/dromazmj))
+- AWS Security Group Rules properties and matchers [#2876](https://github.com/chef/inspec/pull/2876) ([clintoncwolfe](https://github.com/clintoncwolfe))
+- New attribute JUnit reporter - target [#2839](https://github.com/chef/inspec/pull/2839) ([piotrgo](https://github.com/piotrgo))
+- Policy Statement Search capability for aws_iam_policy [#2918](https://github.com/chef/inspec/pull/2918) ([clintoncwolfe](https://github.com/clintoncwolfe))
+- Basic fields for aws_vpcs [#2930](https://github.com/chef/inspec/pull/2930) ([clintoncwolfe](https://github.com/clintoncwolfe))
+
+#### Enhancements
+- Add warning when returning DEFAULT_ATTRIBUTE [#2934](https://github.com/chef/inspec/pull/2934) ([TrevorBramble](https://github.com/TrevorBramble))
+- Ensure @params in shadow resource always has a valid value. [#2939](https://github.com/chef/inspec/pull/2939) ([miah](https://github.com/miah))
+- Require a key attribute for the key_rsa resource [#2891](https://github.com/chef/inspec/pull/2891) ([omar-irizarry](https://github.com/omar-irizarry))
+- Add Cisco IOS `enable_password` support [#2905](https://github.com/chef/inspec/pull/2905) ([jerryaldrichiii](https://github.com/jerryaldrichiii))
+
+#### Merged Pull Requests
+- Update filesystem.md.erb [#2909](https://github.com/chef/inspec/pull/2909) ([tlmikulski](https://github.com/tlmikulski))
+- Fixes configuration for Azure integrationt tests [#2941](https://github.com/chef/inspec/pull/2941) ([dmccown](https://github.com/dmccown))
+- powershell resource: Add support line for Unix [#2952](https://github.com/chef/inspec/pull/2952) ([jerryaldrichiii](https://github.com/jerryaldrichiii))
+<!-- latest_stable_release -->
+
 ## [v2.1.30](https://github.com/chef/inspec/tree/v2.1.30) (2018-04-05)
 
 #### New Resources
@@ -47,7 +69,6 @@
 - Added a description to steer people to correct resource [#2908](https://github.com/chef/inspec/pull/2908) ([username-is-already-taken2](https://github.com/username-is-already-taken2))
 - Update example resource syntax [#2904](https://github.com/chef/inspec/pull/2904) ([jerryaldrichiii](https://github.com/jerryaldrichiii))
 - Add automate reporter [#2902](https://github.com/chef/inspec/pull/2902) ([jquick](https://github.com/jquick))
-<!-- latest_stable_release -->
 
 ## [v2.1.21](https://github.com/chef/inspec/tree/v2.1.21) (2018-03-29)
 

data/Rakefile

@@ -105,10 +105,10 @@ namespace :test do
         abort("You must set the environment variable AWS_REGION") unless ENV['AWS_REGION']
         puts "----> Checking for required AWS profile..."
         sh("aws configure get aws_access_key_id --profile inspec-aws-test-#{account} > /dev/null")
-        sh("cd #{integration_dir}/build/ && terraform init")
+        sh("cd #{integration_dir}/build/ && terraform init -upgrade")
         sh("cd #{integration_dir}/build/ && terraform workspace new #{tf_workspace}")
-        sh("cd #{integration_dir}/build/ && AWS_PROFILE=inspec-aws-test-#{account} terraform plan")
-        sh("cd #{integration_dir}/build/ && AWS_PROFILE=inspec-aws-test-#{account} terraform apply")
+        sh("cd #{integration_dir}/build/ && AWS_PROFILE=inspec-aws-test-#{account} terraform plan -out inspec-aws-#{account}.plan")
+        sh("cd #{integration_dir}/build/ && AWS_PROFILE=inspec-aws-test-#{account} terraform apply -auto-approve inspec-aws-#{account}.plan")
         Rake::Task["test:aws:dump_attrs:#{account}"].execute
       end
 
@@ -158,7 +158,7 @@ namespace :test do
       tf_workspace = args[:tf_workspace] || ENV['INSPEC_TERRAFORM_ENV']
       abort("You must either call the top-level test:azure task, or set the INSPEC_TERRAFORM_ENV variable.") unless tf_workspace
       puts '----> Setup'
-      sh("cd #{integration_dir}/build/ && terraform init")
+      sh("cd #{integration_dir}/build/ && terraform init -upgrade")
       sh("cd #{integration_dir}/build/ && terraform workspace new #{tf_workspace}")
 
       # Generate Azure crendentials

data/docs/resources/{aws_config_delivery_channel.md → aws_config_delivery_channel.md.erb}

@@ -4,16 +4,20 @@ title: About the aws_config_delivery_channel Resource
 
 # aws_config_delivery_channel
 
-The AWS Config service can monitor and record changes to your AWS resource configurations.  A Delivery Channel can record the changes
+The AWS Config service can monitor and record changes to your AWS resource configurations. A Delivery Channel can record the changes
 to an S3 Bucket, an SNS or both.
 
 Use the `aws_config_delivery_channel` InSpec audit resource to examine how the AWS Config service delivers those change notifications.
 
+As of April 2018, each AWS region may have only one Delivery Channel.
+
 <br>
 
-## Syntax
+## Resource Parameters
+
+An `aws_config_delivery_channel` resource block declares the tests for a single AWS Config Delivery Channel.
 
-An `aws_config_delivery_channel` resource block declares the tests for a single AWS Config delivery channel.
+You may specify the Delivery Channel name:
 
     describe aws_config_delivery_channel('my_channel') do
       it { should exist }
@@ -23,29 +27,52 @@ An `aws_config_delivery_channel` resource block declares the tests for a single
       it { should exist }
     end
 
+However, since you may only have one Delivery Channel per region, and InSpec connections are per-region, you may also omit the `channel_name` to obtain the one Delivery Channel (if any) that exists:
+
+    describe aws_config_delivery_channel do
+      it { should exist }
+    end
+
 <br>
 
 ## Examples
 
 The following examples show how to use this InSpec audit resource.
 
-### Test how frequent the channel writes configuration changes to the s3 bucket.
+### Test how frequently the channel writes configuration changes to the s3 bucket.
 
     describe aws_config_delivery_channel(channel_name: 'my-recorder') do
       its(delivery_frequency_in_hours) { should be > 3 }
     end
     
 ## Properties
-    
-### s3_bucket_name
 
-Provides the name of the s3 bucket that the channel sends configuration changes to.  This is an optional value since a Delivery Channel can also talk to an SNS.
+### channel\_name
+
+Returns the name of the Delivery Channel.
+
+    describe aws_config_delivery_channel do
+      its('channel_name') { should cmp 'my-channel' }
+    end
+
+### delivery\_frequency\_in\_hours
+
+Provides how often the AWS Config sends configuration changes to the s3 bucket in the delivery channel.
+
+    describe aws_config_delivery_channel(channel_name: 'my_channel')
+      its('delivery_frequency_in_hours') { should eq 24 }
+      its('delivery_frequency_in_hours') { should be > 24 }
+    end
+
+### s3\_bucket\_name
+
+Provides the name of the s3 bucket that the channel sends configuration changes to. This is an optional value since a Delivery Channel can also talk to an SNS.
 
     describe aws_config_delivery_channel(channel_name: 'my_channel')
       its('s3_bucket_name') { should eq 'my_bucket' }
     end
     
-### s3_key_prefix
+### s3\_key\_prefix
 
 Provides the s3 object key prefix (or "path") under which configuration data will be recorded.
 
@@ -53,7 +80,7 @@ Provides the s3 object key prefix (or "path") under which configuration data wil
       its('s3_key_prefix') { should eq 'log/' }
     end
     
-### sns_topic_arn
+### sns\_topic\_arn
 
 Provides the ARN of the SNS topic for which the channel sends notifications about configuration changes.
 
@@ -61,19 +88,9 @@ Provides the ARN of the SNS topic for which the channel sends notifications abou
       its('sns_topic_arn') { should eq 'arn:aws:sns:us-east-1:721741954427:sns_topic' }
     end
     
-### delivery_frequency_in_hours
-
-Provides how often the AWS Config sends configuration changes to the s3 bucket in the delivery channel.
-
-    describe aws_config_delivery_channel(channel_name: 'my_channel')
-      its('delivery_frequency_in_hours') { should eq 24 }
-      its('delivery_frequency_in_hours') { should be > 24 }
-    end
-    
-    
 <br>
 
 ## Matchers
 
-This resource provides no matchers, aside from the standard exists matcher.
+This resource provides no matchers, aside from the standard `exist` matcher.
 

data/docs/resources/aws_config_recorder.md.erb

@@ -8,12 +8,16 @@ Use the `aws_config_recorder` InSpec audit resource to test properties of your A
 
 The AWS Config service can monitor and record changes to your AWS resource configurations.  The Aws Config Recorder is used to detect changes in resource configurations and capture these changes as configuration items.
 
+As of April 2018, you are only permitted one configuration recorder per region.
+
 <br>
 
-## Syntax
+## Resource Parameters
 
 An `aws_config_recorder` resource block declares the tests for a single AWS configuration recorder.
 
+You may specify a recorder by name:
+
     describe aws_config_recorder('my_recorder') do
       it { should exist }
     end
@@ -22,6 +26,12 @@ An `aws_config_recorder` resource block declares the tests for a single AWS conf
       it { should exist }
     end
 
+However, since you may only have one recorder per region, and InSpec connections are per-region, you may also omit the `recorder_name` to obtain the one recorder (if any) that exists:
+
+    describe aws_config_recorder do
+      it { should exist }
+    end
+
 <br>
 
 ## Examples

data/docs/resources/aws_iam_user.md.erb

@@ -13,7 +13,7 @@ To test properties of the special AWS root user (which owns the account), use th
 
 <br>
 
-## Syntax
+## Resource Parameters
 
 An `aws_iam_user` resource block declares a user by name, and then lists tests to be performed.
 
@@ -47,9 +47,51 @@ The following examples show how to use this InSpec audit resource.
 
 <br>
 
+## 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 [matchers page](https://www.inspec.io/docs/reference/matchers/).
+This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [universal matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### 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
 
@@ -57,8 +99,17 @@ The `have_console_password` matcher tests if the user has a password that could
 
     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 }
+ 

data/docs/resources/aws_iam_users.md.erb

@@ -15,20 +15,20 @@ To test properties of the special AWS root user (which owns the account), use th
 
 ## Syntax
 
-An `aws_iam_users` resource block users a filter to select a group of users and then tests that group
+An `aws_iam_users` resource block uses a filter to select a group of users and then tests that group. With no filter, it returns all AWS IAM users.
 
+    # No filter
+    # We expect 42 users
+    describe aws_iam_users do
+      its('usernames.count') { should eq 42 }
+    end
+
+    # Using a filter
+    # All users should have MFA (no user without MFA should exist)
     describe aws_iam_users.where(has_mfa_enabled?: false) do
       it { should_not exist }
     end
 
-<br>
-
-## Filter Criteria
-
-* `has_mfa_enabled`, `has_console_password`, `password_ever_used?`, `password_never_used?`, `password_last_used_days_ago`, `username`
-
-<br>
-
 ## Examples
 
 The following examples show how to use this InSpec audit resource.
@@ -84,7 +84,190 @@ The following examples show how to use this InSpec audit resource.
 
 <br>
 
+## Filter Criteria
+
+You may pass filter criteria to `where` to narrow down the result set.
+
+### has\_attached\_policies
+
+True or false. Filters the users to include only those that have at least one IAM managed policy attached to the user.
+
+    # Don't attach policies to users
+    describe aws_iam_users.where(has_attached_policies: true) do
+      it { should_not exist }
+    end
+
+### has\_console\_password
+
+True or false. Filters the users to include only those that have a console password (that is, they are able to login to the AWS web UI using a password). 
+
+    # No console passwords for anyone
+    describe aws_iam_users.where(has_console_password: true) do
+      it { should_not exist }
+    end
+
+### has\_inline\_policies
+
+True or false. Filters the users to include only those that have at least one IAM policy directly embedded in the user record.
+
+    # Embedding policies is usually hard to manage
+    describe aws_iam_users.where(has_inline_policies: true) do
+      it { should_not exist }
+    end
+
+### has\_mfa\_enabled
+
+True or false. Filters the users to include only those that have some kind of Mult-Factor Authentication enabled (virtual or hardware).
+
+    # Require MFA for everyone
+    describe aws_iam_users.where(has_mfa_enabled: false) do
+      it { should_not exist }
+    end
+
+### password\_ever\_used
+
+True or false. Filters the users to include only those that have used their password at least once.
+
+    # Someone should have used their password
+    describe aws_iam_users.where(password_ever_used: true) do
+      it { should exist }
+    end
+
+### password\_last\_used_days\_ago
+
+Integer. Filters the users to include only those who used their password a certain number of days ago. '0' means today.
+
+    # Bob should login every day
+    describe aws_iam_users.where(password_ever_used: true, password_last_used_days_ago:0) do
+      its('usernames') { should include 'bob' }
+    end
+
+    # This filter is often more useful in block mode, using a greater-than
+    # Here, audit users who have not logged in in the last 30 days 
+    describe aws_iam_users.where do 
+      password_ever_used && password_last_used_days_ago > 30
+    end do
+      it { should_not exist' }
+    end
+
+### password\_never\_used
+
+True or false. Filters the users to include only those that have used _never_ their password.
+
+    # No zombie accounts!
+    describe aws_iam_users.where(password_never_used: true) do
+      it { should_not exist }
+    end
+
+### username
+
+String. Filters the users to include only those whose username matches the value you provide.
+
+    # Block mode example (recommended)
+    # Service users should not have a password
+    describe aws_iam_users.where { username.start_with?('service') } do
+      it { should_not have_console_password }
+    end
+
+    # Method call example. This is a poor use of aws_iam_users (plural); 
+    # if you want to audit an individual user whose username you know, use 
+    # aws_iam_user (singular)
+    # Verify Bob exists
+    describe aws_iam_users.where(username: 'bob') do
+      it { should exist }
+    end
+
+## Properties
+
+Properties are used with the `its` test to obtain information about the matched users. Properties always return arrays, though they may be empty.
+
+### attached\_policy\_arns
+
+Array of strings. Each entry is the ARN of an IAM managed policy that is attached to at least one matched user. The list is de-duplicated, so if you have five users that are all attached to the same policy, `attached_policy_arns` will return only one ARN, not five.
+
+    # Service users should be attached to a custom service policy
+    describe aws_iam_users.where { username.start_with?('service') } do
+      its('attached_policy_arns') { should include  'arn:aws:iam::123456789012:policy/MyServicePolicy' }
+    end
+
+### attached\_policy\_names
+
+Array of strings. Each entry is the friendly name of an IAM managed policy that is attached to at least one matched user. The list is de-duplicated, so if you have five users that are all attached to the same policy, `attached_policy_names` will return only one name, not five.
+
+    # Service users should be attached to a custom service policy
+    # and not include Admin policy!
+    describe aws_iam_users.where { username.start_with?('service') } do
+      its('attached_policy_names') { should include  'MyServicePolicy' }
+      its('attached_policy_names') { should_not include  'AdministratorAccess' }
+    end
+
+### inline\_policy\_names
+
+Array of strings. Each entry is the name of an embedded policy that is embedded in at least one matched user. Keep in mind that each user has a copy of a policy (which can then be modified). This means that two users can have an embedded policy with the same name, but very different contents. The list is de-duplicated, so if you have five users that have an inline policy with the same name, `inline_policy_names` will return only one name, not five.
+
+    # Service users should have a bespoke policy
+    describe aws_iam_users.where { username.start_with?('service') } do
+      its('inline_policy_names') { should include  'some-bespoke-policy' }
+    end
+
+### usernames
+
+Array of strings. Each entry is the name of a user that matched. There will be exactly as many usernames here as there were users that matched, though it is possible to have non-unique usernames.
+
+    # 42 Users, including Bob, should have a password.
+    describe aws_iam_users.where(has_console_password: true) do
+      its('usernames') { should include  'bob' }
+      its('usernames.count') { should eq 42 }
+    end
+
 ## Matchers
 
-This InSpec audit resource has no specific matchers. 
-For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+This InSpec audit resource has the following resource-specific matchers. 
+For a full list of available matchers, please visit our [universal matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+As a plural resource, all matchers beginning with `have_` will return true if _any_ of the selected users match.
+
+### exist
+
+The test passes if the filtered user set is not empty. This basic matcher is frequently used with `should_not` to detect undesired conditions.
+
+    # Require MFA for everyone
+    describe aws_iam_users.where(has_mfa_enabled: false) do
+      it { should_not exist }
+    end
+
+### have\_attached\_policies
+
+The test passes if at least one user in the filtered set has at least one attached IAM managed policy.
+
+    # Bachelors don't have attachments
+    describe aws_iam_users.where { username =~ /bachelor/ } do
+      it { should_not have_attached_policies }
+    end
+
+### have\_console\_password
+
+The test passes if at least one user in the filtered set has a console password.
+
+    describe aws_iam_users do
+      it { should_not have_console_password }
+    end
+
+### have\_inline\_policies
+
+The test passes if at least one user in the filtered set has at least one embedded policy.
+
+    # No one should have an inline policy
+    describe aws_iam_users do
+      it { should_not have_inline_policies }
+    end
+
+### have\_mfa\_enabled
+
+The test passes if at least one user in the filtered set has MFA enabled (virtual or hardware).
+
+    # At least one person should use MFA.
+    # This does not mean ALL users have MFA.
+    describe aws_iam_users do
+      it { should have_mfa_enabled }
+    end