inspec 1.51.25 → 2.0.16

data/docs/resources/aws_iam_group.md.erb

@@ -0,0 +1,46 @@
+---
+title: About the aws_iam_group Resource
+platform: aws
+---
+
+# aws\_iam\_group
+
+Use the `aws_iam_group` InSpec audit resource to test properties of a single IAM group.
+
+To test properties of multiple or all groups, use the `aws_iam_groups` resource.
+
+<br>
+
+## Syntax
+
+An `aws_iam_group` resource block identifies a group by group name.
+
+    # Find a group by group name
+    describe aws_iam_group('mygroup') do
+      it { should exist }
+    end
+
+    # Hash syntax for group name
+    describe aws_iam_group(group_name: 'mygroup') do
+      it { should exist }
+    end
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+As this is the initial release of `aws_iam_group`, its limited functionality precludes examples.
+
+<br>
+
+## Matchers
+
+### exists
+
+The control will pass if a group with the given group name exists.
+
+    describe aws_iam_group('mygroup')
+      it { should exist }
+    end

data/docs/resources/aws_iam_groups.md.erb

@@ -0,0 +1,43 @@
+---
+title: About the aws_iam_groups Resource
+platform: aws
+---
+
+# aws\_iam\_groups
+
+Use the `aws_iam_groups` InSpec audit resource to test properties of all or multiple groups.
+
+To test properties of a single group, use the `aws_iam_group` resource.
+
+<br>
+
+## 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
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+As this is the initial release of `aws_iam_groups`, its limited functionality precludes examples.
+
+<br>
+
+## Matchers
+
+For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/). 
+
+### 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

data/docs/resources/aws_iam_password_policy.md.erb

@@ -0,0 +1,76 @@
+---
+title: About the aws_iam_password_policy Resource
+platform: aws
+---
+
+# aws\_iam\_password\_policy
+
+Use the `aws_iam_password_policy` InSpec audit resource to test properties of the AWS IAM Password Policy.
+
+<br>
+
+## Syntax
+
+An `aws_iam_password_policy` resource block takes no parameters.  Several properties and matchers are available.
+
+    describe aws_iam_password_policy do
+      it { should require_lowercase_characters }
+    end
+
+<br>
+
+## Properties
+
+* `max_password_age_in_days`,  `minimum_password_length`, `number_of_passwords_to_remember`
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test that the IAM Password Policy requires lowercase characters, uppercase characters, numbers, symbols, and a minimum length greater than eight
+
+    describe aws_iam_password_policy do
+      it { should require_lowercase_characters }
+      it { should require_uppercase_characters }
+      it { should require_symbols }
+      it { should require_numbers }
+      its('minimum_password_length') { should be > 8 }
+    end
+
+### Test that the IAM Password Policy allows users to change their password
+
+    describe aws_iam_password_policy do
+      it { should allow_users_to_change_passwords }
+    end
+
+### Test that the IAM Password Policy expires passwords
+
+    describe aws_iam_password_policy do
+      it { should expire_passwords }
+    end
+
+### Test that the IAM Password Policy has a max password age
+
+    describe aws_iam_password_policy do
+      its('max_password_age_in_days') { should be 90 }
+    end
+
+### Test that the IAM Password Policy prevents password reuse
+
+    describe aws_iam_password_policy do
+      it { should prevent_password_reuse }
+    end
+
+### Test that the IAM Password Policy requires users to remember 3 previous passwords
+
+    describe aws_iam_password_policy do
+      its('number_of_passwords_to_remember') { should eq 3 }
+    end
+
+<br>
+
+## Matchers
+
+This resource uses the following special matchers. For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/). 
+
+* `allows_users_to_change_passwords`, `expire_passwords`, `prevent_password_reuse`, `require_lowercase_characters` , `require_uppercase_characters`, `require_numbers`, `require_symbols`

data/docs/resources/aws_iam_policies.md.erb

@@ -0,0 +1,82 @@
+---
+title: About the aws_iam_policies Resource
+platform: aws
+---
+
+# aws\_iam\_policies
+
+Use the `aws_iam_policies` InSpec audit resource to test properties of some or all AWS IAM Policies.
+
+A policy is an entity in AWS that, when attached to an identity or resource, defines their permissions. AWS evaluates these policies when a principal, such as a user, makes a request. Permissions in the policies determine if the request is allowed or denied. 
+
+Each IAM Policy is uniquely identified by either its `policy_name` or `arn`.
+
+<br>
+
+## Syntax
+
+An `aws_iam_policies` resource block collects a group of IAM Policies and then tests that group.
+
+    # Verify the policy specified by the policy name is included in IAM Policies in the AWS account.
+    describe aws_iam_policies do
+      its('policy_names') { should include('test-policy-1') }
+    end
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+As this is the initial release of `aws_iam_policies`, its limited functionality precludes examples.
+
+<br>
+
+## Properties
+
+* `arns`, `entries`, `policy_names`
+
+<br>
+
+## Property Examples
+
+### policy\_names
+
+Provides a list of policy names for all IAM Policies in the AWS account.
+
+    describe aws_iam_policies do
+      its('policy_names') { should include('test-policy-1') }
+    end
+
+### arns
+
+Provides a list of policy arns for all IAM Policies in the AWS account.
+
+    describe aws_iam_policies do
+      its('arns') { should include('arn:aws:iam::aws:policy/test-policy-1') }
+    end
+
+### entries
+
+Provides access to the raw results of the query.  This can be useful for checking counts and other advanced operations.
+
+    # Allow at most 100 IAM Policies on the account
+    describe aws_iam_policies do
+      its('entries.count') { should be <= 100}
+    end
+
+<br>
+
+## Matchers
+
+For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/). 
+
+### exists
+
+The control will pass if the filter returns at least one result. Use `should_not` if you expect zero matches.
+
+    # Verify that at least one IAM Policies exists.
+    describe aws_iam_policies
+      it { should exist }
+    end   
+

data/docs/resources/aws_iam_policy.md.erb

@@ -0,0 +1,146 @@
+---
+title: About the aws_iam_policy Resource
+platform: aws
+---
+
+# aws\_iam\_policy
+
+Use the `aws_iam_policy` InSpec audit resource to test properties of a single managed AWS IAM Policy.
+
+A policy is an entity in AWS that, when attached to an identity or resource, defines their permissions. AWS evaluates these policies when a principal, such as a user, makes a request. Permissions in the policies determine if the request is allowed or denied. 
+
+Each IAM Policy is uniquely identified by either its policy_name or arn.
+
+<br>
+
+## Syntax
+
+An `aws_iam_policy` resource block identifies a policy by policy name.
+
+    # Find a policy by name
+    describe aws_iam_policy('AWSSupportAccess') do
+      it { should exist }
+    end
+
+    # Find a customer-managed by name
+    describe aws_iam_policy('customer-managed-policy') do
+      it { should exist }
+    end
+
+    # Hash syntax for policy name
+    describe aws_iam_policy(policy_name: 'AWSSupportAccess') do
+      it { should exist }
+    end
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test that a policy does exist
+
+    describe aws_iam_policy('AWSSupportAccess') do
+      it { should exist }
+    end
+
+### Test that a policy is attached to at least one entity
+
+    describe aws_iam_policy('AWSSupportAccess') do
+      it { should be_attached }
+    end
+
+<br>
+
+## Properties
+
+* `arn`, `attachment_count`, `attached_groups`, `attached_roles`,`attached_users`, `default_version_id`
+
+## Property Examples
+
+### arn
+
+"The ARN identifier of the specified policy. An ARN uniquely identifies the policy within AWS."
+
+    describe aws_iam_policy('AWSSupportAccess') do
+      its('arn') { should cmp "arn:aws:iam::aws:policy/AWSSupportAccess" }
+    end
+
+### attachment\_count
+
+The count of attached entities for the specified policy.
+
+    describe aws_iam_policy('AWSSupportAccess') do
+      its('attachment_count') { should cmp 1 }
+    end
+
+### attached\_groups
+
+The list of groupnames of the groups attached to the policy.
+
+    describe aws_iam_policy('AWSSupportAccess') do
+      its('attached_groups') { should include "test-group" }
+    end
+
+### attached\_roles
+
+The list of rolenames of the roles attached to the policy.
+
+    describe aws_iam_policy('AWSSupportAccess') do
+      its('attached_roles') { should include "test-role" }
+    end
+
+### attached\_users
+
+The list of usernames of the users attached to the policy.
+
+    describe aws_iam_policy('AWSSupportAccess') do
+      its('attached_users') { should include "test-user" }
+    end
+
+### default\_version\_id
+
+The 'default_version_id' value of the specified policy.
+
+    describe aws_iam_policy('AWSSupportAccess') do
+      its('default_version_id') { should cmp "v1" }
+    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/).
+
+### be\_attached
+
+The test will pass if the identified policy is attached to at least one IAM user, group, or role.
+
+    describe aws_iam_policy('AWSSupportAccess') do
+      it { should be_attached }
+    end
+
+### be\_attached\_to\_group(GROUPNAME)
+
+The test will pass if the identified policy attached the specified group.
+
+    describe aws_iam_policy('AWSSupportAccess') do
+      it { should be_attached_to_group(GROUPNAME) }
+    end
+
+### be\_attached\_to\_user(USERNAME)
+
+The test will pass if the identified policy attached the specified user.
+
+    describe aws_iam_policy('AWSSupportAccess') do
+      it { should be_attached_to_user(USERNAME) }
+    end
+
+### be\_attached\_to\_role(ROLENAME)
+
+The test will pass if the identified policy attached the specified role.
+
+    describe aws_iam_policy('AWSSupportAccess') do
+      it { should be_attached_to_role(ROLENAME) }
+    end
+
+

data/docs/resources/aws_iam_role.md.erb

@@ -0,0 +1,65 @@
+---
+title: About the aws_iam_role Resource
+platform: aws
+---
+
+# aws\_iam\_role
+
+Use the `aws_iam_role` InSpec audit resource to test properties of a single IAM Role. A Role is a collection of permissions that may be temporarily assumed by a user, EC2 Instance, Lambda Function, or certain other resources.
+
+<br>
+
+## Syntax
+
+  # Ensure that a certain role exists by name
+  describe aws_iam_role('my-role') do
+    it { should exist }
+  end
+
+<br>
+
+## Resource Parameters
+
+### role\_name
+
+This resource expects a single parameter that uniquely identifies the IAM Role, the Role Name. You may pass it as a string, or as the value in a hash:
+
+  describe aws_iam_role('my-role') do
+    it { should exist }
+  end
+  # Same
+  describe aws_iam_role(role_name: 'my-role') do
+    it { should exist }
+  end
+
+<br>
+
+## Properties
+
+### description
+
+A textual description of the IAM Role.
+
+    describe aws_iam_role('my-role') do
+      its('description') { should be('Our most important Role')}
+    end
+
+<br>
+
+## 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/).
+
+### exist
+
+Indicates that the Role Name provided was found. Use should_not to test for IAM Roles that should not exist.
+
+    describe aws_iam_role('should-be-there') do
+      it { should exist }
+    end
+
+    describe aws_iam_role('should-not-be-there') do
+      it { should_not exist }
+    end
+
+