inspec 2.1.72 → 2.1.78

data/docs/resources/aws_iam_policy.md.erb

@@ -56,7 +56,7 @@ The following examples show how to use this InSpec audit resource.
       # Verify that there is at least one statement allowing access to S3
       it { should have_statement(Action: 's3:PutObject', Effect: 'allow') }
 
-      # have_statement does not expand wildcards. If you want to verify 
+      # have_statement does not expand wildcards. If you want to verify
       # they are absent, an explicit check is required.
       it { should_not have_statement(Action: 's3:*') }
     end
@@ -125,11 +125,11 @@ Returns the default version of the policy document after decoding as a Ruby hash
 
 For details regarding the contents of this structure, refer to the [AWS IAM Policy JSON Reference](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html).  A set of examples is [also available](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_examples.html).
 
-Example: 
+Example:
 
     # Fetch the policy structure as a Ruby object
     policy_struct = aws_iam_policy('my-policy').policy
-    # Write a manually-constructed test to check that the policy 
+    # Write a manually-constructed test to check that the policy
     # has an IP constraint on the first statement
     # ( Based on https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_examples_aws_deny-ip.html )
     describe 'Check that we are restricting IP access' do
@@ -195,10 +195,10 @@ Examines the list of statements contained in the policy and passes if at least o
 
 Please note the following about the behavior of `have_statement`:
 * `Action`, `Sid`, and `Resource` allow using a regular expression as the search critera instead of a string literal.
-* it does not support wildcard expansion; to check for a wildcard value, check for it explicitly. For example, if the policy includes a statement with `"Action": "s3:*"` and the test checks for `Action: "s3:PutObject"`, the test _will not match_. You must write an additional test checking for the wildcard case. 
+* it does not support wildcard expansion; to check for a wildcard value, check for it explicitly. For example, if the policy includes a statement with `"Action": "s3:*"` and the test checks for `Action: "s3:PutObject"`, the test _will not match_. You must write an additional test checking for the wildcard case.
 * it supports searching list values. For example, if a statement contains a list of 3 resources, and a `have_statement` test specifes _one_ of those resources, it will match.
 * `Action` and `Resource` allow using a list of string literals or regular expressions in a test, in which case _all_ must match on the _same_ statement for the test to match. Order is ignored.
-* it does not support the `Principal` or `Conditional` key, or any of `NotAction`, `NotPrincipal`, or `NotResource`.
+* it does not support the `[Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal)` or `Conditional` key, or any of `NotAction`, `Not[Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal)`, or `NotResource`.
 
 Examples:
 
@@ -210,7 +210,7 @@ Examples:
     # Verify bob is allowed to manage things on S3 buckets that start with bobs-stuff
     describe aws_iam_policy('bob-is-a-packrat') do
       it { should have_statement(Effect: 'Allow',
-                                 # Using the AWS wildcard - this must match exactly 
+                                 # Using the AWS wildcard - this must match exactly
                                  Resource: 'arn:aws:s3:::bobs-stuff*',
                                  # Specify a list of actions - all must match, no others, order isn't important
                                  Action: ['s3:PutObject', 's3:GetObject', 's3:DeleteObject'])}
@@ -220,7 +220,7 @@ Examples:
       it { should_not have_statement(Effect: 'Allow', Action: 's3:*')}
       it { should_not have_statement(Effect: 'Allow', Action: '*')}
 
-      # An alternative to checking for wildcards is to specify the 
+      # An alternative to checking for wildcards is to specify the
       # statements you expect, then restrict statement count
       its('statement_count') { should cmp 1 }
     end
@@ -230,10 +230,16 @@ Examples:
       # Check to see if anything mentions RDS at all.
       # This catches `rds:CreateDBinstance` and `rds:*`, but would not catch '*'.
       it { should_not have_statement(Action: /^rds:.+$/)}
-      
+
       # This policy should refer to both sally and kim's s3 buckets.
       # This will only match if there is a statement that refers to both resources.
       it { should have_statement(Resource: [/arn:aws:s3.+:sally/, /arn:aws:s3.+:kim/]) }
       # The following also matches on a statement mentioning only one of them
       it { should have_statement(Resource: /arn:aws:s3.+:(sally|kim)/) }
     end
+
+## AWS Permissions
+
+Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `iam:GetPolicy`, `iam:ListPolicy`, and `iam:ListEntitiesForPolicy` actions set to allow.
+
+You can find detailed documentation at [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

data/docs/resources/aws_iam_role.md.erb

@@ -61,3 +61,9 @@ Indicates that the Role Name provided was found. Use `should_not` to test for IA
     describe aws_iam_role('should-not-be-there') do
       it { should_not exist }
     end
+
+## AWS Permissions
+
+Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `iam:GetRole` action with Effect set to Allow.
+
+You can find detailed documentation at [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

data/docs/resources/aws_iam_root_user.md.erb

@@ -68,3 +68,9 @@ The `have_virtual_mfa_enabled` matcher tests if the AWS root user has Virtual Mu
 The `have_access_key` matcher tests if the AWS root user has at least one access key.
 
     it { should have_access_key }
+
+## AWS Permissions
+
+Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `iam:GetAccountSummary` action with Effect set to Allow.
+
+You can find detailed documentation at [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

data/docs/resources/aws_iam_user.md.erb

@@ -57,7 +57,7 @@ Returns a list of IAM Managed Policy ARNs as strings that identify the policies
       # 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' }      
+      its('attached_policy_arns') { should include 'arn:aws:iam::aws:policy/AlexaForBusinessGatewayExecution' }
     end
 
 ### attached\_policy\_names
@@ -68,7 +68,7 @@ Returns a list of IAM Managed Policy Names as strings that identify the policies
       # 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' }      
+      its('attached_policy_names') { should include 'AlexaForBusinessGatewayExecution' }
     end
 
 ### inline\_policy\_names
@@ -77,7 +77,7 @@ Returns a list of IAM Inline Policy Names as strings that identify the inline po
 
     describe aws_iam_user('bob') do
       its('inline_policy_names') { should include 'test-inline-policy-01' }
-      its('inline_policy_names.count') { should eq 1 }      
+      its('inline_policy_names.count') { should eq 1 }
     end
 
 
@@ -112,4 +112,9 @@ The `have\_inline\_policies` matcher tests if the user has at least one IAM poli
 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-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](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

data/docs/resources/aws_iam_users.md.erb

@@ -99,7 +99,7 @@ True or false. Filters the users to include only those that have at least one IA
 
 ### 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). 
+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
@@ -143,8 +143,8 @@ Integer. Filters the users to include only those who used their password a certa
     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 
+    # 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' }
@@ -169,8 +169,8 @@ String. Filters the users to include only those whose username matches the value
       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 
+    # 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
@@ -222,7 +222,7 @@ Array of strings. Each entry is the name of a user that matched. There will be e
 
 ## Matchers
 
-This InSpec audit resource has the following resource-specific 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.
@@ -271,3 +271,9 @@ The test passes if at least one user in the filtered set has MFA enabled (virtua
     describe aws_iam_users do
       it { should have_mfa_enabled }
     end
+
+## AWS Permissions
+
+Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `iam:ListUsers`, `iam:GetLoginProfile`, `iam:ListMFADevices`, `iam:ListAccessKeys`, `iam:ListUserPolicies`, and `iam:ListAttachedUserPolicies` action with Effect set to Allow.
+
+You can find detailed documentation at [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

data/docs/resources/aws_kms_key.md.erb

@@ -22,7 +22,7 @@ An aws_kms_key resource block identifies a key by key_arn or the key id.
     describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
       it { should exist }
     end
-    
+
     # Find a kms key by just the id
     describe aws_kms_key('4321dcba-21io-23de-85he-ab0987654321') do
       it { should exist }
@@ -79,7 +79,7 @@ The ARN identifier of the specified key. An ARN uniquely identifies the key with
 
 ### creation_date
 
-Specifies the date and time when the key was created. 
+Specifies the date and time when the key was created.
 
     # Makes sure that the key was created at least 10 days ago
     describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
@@ -138,14 +138,14 @@ The test will pass if the specified key's key_state is set to enabled.
     describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
       it { should be_enabled }
     end
-    
+
 ### be\_external
 Provides whether the source of the key's key material is external or not.  If it is not external than it was created by AWS KMS.  When it is external, the key material was imported from an existing key management infrastructure or the key lacks key material.
 
     describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
       its { should be_external }
     end
-    
+
 ### be\_managed\_by\_aws
 
 Provides whether or not the key manager is from AWS. If it is not managed by AWS, it is managed by the customer.
@@ -153,7 +153,7 @@ Provides whether or not the key manager is from AWS. If it is not managed by AWS
     describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
       its { should be_managed_by_aws }
     end
-    
+
 ### have\_key\_expiration
 
 Specifies whether the key's key material expires. This value is null unless the keys Origin is External.
@@ -169,3 +169,9 @@ The test will pass if automatic rotation of the key material is enabled for the
     describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
       it { should have_rotation_enabled }
     end
+
+## AWS Permissions
+
+Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `kms:DescribeKey`, and `kms:GetKeyRotationStatus` actions set to allow.
+
+You can find detailed documentation at [Actions, Resources, and Condition Keys for AWS Key Management Service](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awskeymanagementservice.html).

data/docs/resources/aws_kms_keys.md.erb

@@ -7,7 +7,7 @@ platform: aws
 
 Use the `aws_kms_keys` InSpec audit resource to test properties of some or all AWS KMS Keys.
 
-AWS Key Management Service (KMS) is a managed service that makes creating and controlling your encryption keys for your data easier. KMS uses Hardware Security Modules (HSMs) to protect the security of your keys. 
+AWS Key Management Service (KMS) is a managed service that makes creating and controlling your encryption keys for your data easier. KMS uses Hardware Security Modules (HSMs) to protect the security of your keys.
 
 AWS Key Management Service is integrated with several other AWS services to help you protect the data you store with these services.
 
@@ -80,5 +80,10 @@ The control will pass if the filter returns at least one result. Use `should_not
     # Verify that at least one KMS Key exists.
     describe aws_kms_keys
       it { should exist }
-    end   
+    end
+
+## AWS Permissions
+
+Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `kms:ListKeys` action with Effect set to Allow.
 
+You can find detailed documentation at [Actions, Resources, and Condition Keys for AWS Key Management Service](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awskeymanagementservice.html).

data/docs/resources/aws_rds_instance.md.erb

@@ -58,3 +58,9 @@ The control will pass if the specified RDS instance was found.  Use should_not i
     describe aws_rds_instance('nogood') do
       it { should_not exist }
     end
+
+## AWS Permissions
+
+Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `rds:DescribeDBInstances` action with Effect set to Allow.
+
+You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon RDS](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonrds.html).

data/docs/resources/aws_route_table.md.erb

@@ -45,3 +45,9 @@ Indicates that the Route Table provided was found.  Use `should_not` to test for
     describe aws_route_table('should-not-be-there') do
       it { should_not exist }
     end
+
+## AWS Permissions
+
+Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `ec2:DescribeRouteTables` action with Effect set to Allow.
+
+You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon EC2](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonec2.html).

data/docs/resources/aws_route_tables.md.erb

@@ -47,3 +47,9 @@ Lists all of the Route Table IDs.
     describe aws_route_tables do
       its('route_table_ids') { should include 'rtb-12345678' }
     end
+
+## AWS Permissions
+
+Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `ec2:DescribeRouteTables` action with Effect set to Allow.
+
+You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon EC2](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonec2.html).

data/docs/resources/aws_s3_bucket.md.erb

@@ -79,7 +79,7 @@ The `bucket_acl` property is a low-level property that lists the individual Buck
 
 The value of bucket_acl is  an array of simple objects.  Each object has a `permission` property and a `grantee` property.  The `permission` property will be a string such as 'READ', 'WRITE' etc (See the [AWS documentation](https://docs.aws.amazon.com/sdkforruby/api/Aws/S3/Client.html#get_bucket_acl-instance_method) for a full list).  The `grantee` property contains sub-properties, such as `type` and `uri`.
 
-    
+
     bucket_acl = aws_s3_bucket('my-bucket')
 
     # Look for grants to "AllUsers" (that is, the public)
@@ -138,3 +138,9 @@ The `have_access_logging_enabled` matcher tests if access logging is enabled for
 The `have_default_encryption_enabled` matcher tests if default encryption is enabled for the s3 bucket.
 
     it { should have_default_encryption_enabled }
+
+## AWS Permissions
+
+Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `s3:GetBucketAcl`, `s3:GetBucketLocation`, `s3:GetBucketLogging`, `s3:GetBucketPolicy`, and `s3:GetEncryptionConfiguration` actions set to allow.
+
+You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon S3](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazons3.html).

data/docs/resources/aws_s3_bucket_object.md.erb

@@ -6,7 +6,7 @@ title: About the aws_s3_bucket_object Resource
 
 Use the `aws_s3_bucket_object` InSpec audit resource to test properties of a single AWS bucket object.
 
-Each S3 Object has a 'key' which can be thought of as the name of the S3 Object which uniquely identifies it.  
+Each S3 Object has a 'key' which can be thought of as the name of the S3 Object which uniquely identifies it.
 
 
 <br>
@@ -54,7 +54,7 @@ The `object_acl` property is a low-level property that lists the individual Obje
 
 The value of object_acl is an Array of simple objects.  Each object has a `permission` property and a `grantee` property.  The `permission` property will be a string such as 'READ', 'WRITE' etc (See the [AWS documentation](https://docs.aws.amazon.com/sdkforruby/api/Aws/S3/Client.html#get_bucket_acl-instance_method) for a full list).  The `grantee` property contains sub-properties, such as `type` and `uri`.
 
-    
+
     object_acl = aws_s3_bucket_object(bucket_name: 'my_bucket', key: 'object_key')
 
     # Look for grants to "AllUsers" (that is, the public)
@@ -81,3 +81,9 @@ The `be_public` matcher tests if the object has potentially insecure access cont
 Note: This resource does not detect insecure bucket ACLs.
 
     it { should_not be_public }
+
+## AWS Permissions
+
+Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `s3:GetObject`, and `s3:GetObjectAcl` actions set to allow.
+
+You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon S3](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazons3.html).

data/docs/resources/aws_s3_buckets.md.erb

@@ -45,9 +45,15 @@ The control will pass if the resource contains at least one bucket.
 
 Provides an array of strings containing the names of the buckets.
 
-    # Examine what buckets have been created. 
+    # Examine what buckets have been created.
     describe aws_s3_buckets do
       its('bucket_names') { should eq ['my_bucket'] }
       # OR
       its('bucket_names') { should include 'my_bucket' }
     end
+
+## AWS Permissions
+
+Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `s3:ListAllMyBuckets` action with Effect set to Allow.
+
+You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon S3](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazons3.html).

data/docs/resources/aws_security_group.md.erb

@@ -20,7 +20,7 @@ While this resource provides facilities for searching inbound and outbound rules
 
 ## Syntax
 
-Resource parameters: group_id, group_name, id, vpc_id 
+Resource parameters: group_id, group_name, id, vpc_id
 
 An `aws_security_group` resource block uses resource parameters to search for and then test a Security Group. If no SGs match, no error is raised, but the `exists` matcher returns `false`, and all scalar properties are `nil`. List properties returned under these conditions are empty lists. If more than one SG matches (due to vague search parameters), an error is raised.
 
@@ -36,13 +36,13 @@ An `aws_security_group` resource block uses resource parameters to search for an
       it { should exist }
     end
 
-    # Ensure you have a Security Group with a specific name.  Names are 
+    # Ensure you have a Security Group with a specific name.  Names are
     # unique within a VPC but not across VPCs.
     # Using only Group returns an error if multiple SGs match.
     describe aws_security_group(group_name: 'my-group') do
       it { should exist }
     end
-    # Add vpc_id to ensure uniqueness. 
+    # Add vpc_id to ensure uniqueness.
     describe aws_security_group(group_name: 'my-group', vpc_id: 'vpc-12345678') do
       it { should exist }
     end
@@ -53,15 +53,15 @@ An `aws_security_group` resource block uses resource parameters to search for an
 
 The following examples show how to use this InSpec audit resource.
 
-    # Ensure that the linux_servers Security Group permits 
+    # Ensure that the linux_servers Security Group permits
     # SSH from the 10.5.0.0/16 range, but not the world.
     describe aws_security_group(group_name: linux_servers) do
-      # This passes if any inbound rule exists that specifies 
+      # This passes if any inbound rule exists that specifies
       # port 22 and the given IP range, regardless of protocol, etc.
       it { should allow_in(port: 22, ipv4_range: '10.5.0.0/16') }
 
       # This passes so long as no inbound rule that specifies port 22 exists
-      # with a source IP range of 0.0.0.0/0.  Other properties are ignored. 
+      # with a source IP range of 0.0.0.0/0.  Other properties are ignored.
       it { should_not allow_in(port: 22, ipv4_range: '0.0.0.0/0') }
 
     end
@@ -69,13 +69,13 @@ The following examples show how to use this InSpec audit resource.
     # Ensure that the careful_updates Security Group may only initiate contact with specific IPs.
     describe aws_security_group(group_name: 'careful_updates') do
 
-      # If you have two rules, with one CIDR each: 
+      # If you have two rules, with one CIDR each:
       [ '10.7.23.12/32', '10.8.23.12/32' ].each do |allowed_destination|
         # This doesn't care about which ports are enabled
         it { should allow_out(ipv4_range: allowed_destination) }
       end
 
-      # If you have one rule with two CIDRs: 
+      # If you have one rule with two CIDRs:
       it { should allow_out(ipv4_range: [ '10.7.23.12/32', '10.8.23.12/32' ] }
 
       # Expect exactly three rules.
@@ -185,7 +185,7 @@ If the Security Group could not be found (that is, `exists` is false), `inbound_
 
 A list of the rules that the Security Group applies to outgoing network traffic initiated by the AWS resource in the Security Group. This is a low-level property that is used by the [`allow_out`](#allow_out) matcher; see it for detailed examples. `outbound_rules` is provided here for those wishing to use Ruby code to inspect the rules directly, instead of using higher-level matchers.
 
-Order is critical in these rules, as the sequentially first rule to match is applied to network traffic. Outbound rules are typically used when it is desirable to restrict which portions of the internet, if any, a resource may access. By default, AWS includes an allow-all rule as the last outbound rule; note that Terraform removes this implicit rule. 
+Order is critical in these rules, as the sequentially first rule to match is applied to network traffic. Outbound rules are typically used when it is desirable to restrict which portions of the internet, if any, a resource may access. By default, AWS includes an allow-all rule as the last outbound rule; note that Terraform removes this implicit rule.
 
 If the Security Group could not be found (that is, `exists` is false), `outbound_rules` returns an empty list.
 
@@ -218,9 +218,9 @@ This InSpec audit resource has the following special matchers. For a full list o
 
 ### allow\_out\_only
 
-The `allow` series of matchers enable you to perform queries about what network traffic would be permitted through the Security Group rule set. 
+The `allow` series of matchers enable you to perform queries about what network traffic would be permitted through the Security Group rule set.
 
-`allow_in` and `allow_in_exactly` examine inbound rules, and `allow_out` and `allow_out_exactly` examine outbound rules. 
+`allow_in` and `allow_in_exactly` examine inbound rules, and `allow_out` and `allow_out_exactly` examine outbound rules.
 
 `allow_in` and `allow_out` examine if at least one rule that matches the criteria exists. `allow_in` and `allow_out` also perform inexact (ie, range-based or subset-based) matching on ports and IP addresses ranges, allowing you to specify a candidate port or IP address and determine if it is covered by a rule.
 
@@ -229,12 +229,12 @@ The `allow` series of matchers enable you to perform queries about what network
 The matchers accept a key-value list of search criteria.  For a rule to match, it must match all provided criteria.
 
   * from_port - Determines if a rule exists whose port range begins at the specified number. The word 'from_' does *not* relate to inbound/outbound directionality; it relates to the port range ("counting _from_"). `from_port` is an exact criterion; so if the rule allows 1000-2000 and you specify a `from_port` of 1001, it does not match.
-  * ipv4_range - Specifies an IPv4 address or subnet as a CIDR, or a list of them, to be checked as a permissible origin (for `allow_in`) or destination (for `allow_out`) for traffic.  Each AWS Security Group rule may have multiple allowed source IP ranges. 
+  * ipv4_range - Specifies an IPv4 address or subnet as a CIDR, or a list of them, to be checked as a permissible origin (for `allow_in`) or destination (for `allow_out`) for traffic.  Each AWS Security Group rule may have multiple allowed source IP ranges.
   * port - Determines if a particular TCP/IP port is reachable. allow_in and allow_out examine whether the specified port is included in the port range of a rule, while allow_in. You may specify the port as a string (`'22'`) or as a number.
   * position - A one-based index into the list of rules. If provided, this restricts the evaluation to the rule at that position. You may also use the special values `:first` and `:last`. `position` may also be used to enable `allow_in_only` and `allow_out_only` to work with multi-rule Security Groups.
   * protocol - Specifies the IP protocol. 'tcp', 'udp', and 'icmp' are some typical values. The string "-1" or 'any' is used to indicate any protocol.
   * to_port - Determines if a rule exists whose port range ends at the specified number. The word 'to_' does *not* relate to inbound/outbound directionality; it relates to the port range ("counting _to_"). `to_port` is an exact criterion; so if the rule allows 1000-2000 and you specify a `to_port` of 1999, it does not match.
-  
+
     describe aws_security_group(group_name: 'mixed-functionality-group') do
       # Allow RDP from defined range
       it { should allow_in(port: 3389, ipv4_range: '10.5.0.0/16') }
@@ -258,23 +258,23 @@ The matchers accept a key-value list of search criteria.  For a rule to match, i
       it { should_not allow_in(ipv4_range: '0.0.0.0/0') }
     end
 
-    # Suppose you have a Group that should allow SSH and RDP from 
-    # the admin network, 10.5.0.0/16. The resource has 2 rules to 
+    # Suppose you have a Group that should allow SSH and RDP from
+    # the admin network, 10.5.0.0/16. The resource has 2 rules to
     # allow this, and you want to ensure no others have been added.
     describe aws_security_group(group_name: 'admin-group') do
       # Allow RDP from a defined range and nothing else
       # The SG must have this rule in position 1 and it must match this exactly
       it { should allow_in_only(port: 3389, ipv4_range: '10.5.0.0/16', position: 1) }
 
-      # Specify position 2 for the SSH rule.  Without `position`, 
+      # Specify position 2 for the SSH rule.  Without `position`,
       # allow_in_only only allows one rule, total.
       it { should allow_in_only(port: 22, ipv4_range: '10.5.0.0/16', position: 2) }
 
-      # Because this is an _only matcher, this fails - _only matchers 
+      # Because this is an _only matcher, this fails - _only matchers
       # use exact IP matching.
       it { should allow_in_only(port: 3389, ipv4_range: '10.5.1.34/32', position: 1) }
     end
-    
+
 ### exists
 
 The control passes if the specified Security Group was found.  Use `should_not` if you want to verify that the specified SG does not exist.
@@ -288,3 +288,9 @@ The control passes if the specified Security Group was found.  Use `should_not`
     describe aws_security_group(group_name: 'nogood')
       it { should_not exist }
     end
+
+## AWS Permissions
+
+Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `ec2:DescribeSecurityGroups` action with Effect set to Allow.
+
+You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon EC2](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonec2.html).