inspec 2.1.0 → 2.1.10

data/docs/resources/aws_s3_bucket_object.md.erb

@@ -0,0 +1,83 @@
+---
+title: About the aws_s3_bucket_object Resource
+---
+
+# aws\_s3\_bucket\_object
+
+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.  
+
+
+<br>
+
+## Limitations
+
+S3 object security is a complex matter.  For details on how AWS evaluates requests for access, please see [the AWS documentation](https://docs.aws.amazon.com/AmazonS3/latest/dev/how-s3-evaluates-access-control.html).  S3 buckets and the objects they contain support three different types of access control: bucket ACLs, bucket policies, and object ACLs.
+
+As of January 2018, this resource supports evaluating S3 Object ACLs. In particular, users of the `be_public` matcher should carefully examine the conditions under which the matcher will detect an insecure bucket.  See the `be_public` section under the Matchers section below.
+
+## Syntax
+
+An `aws_s3_bucket_object` resource block declares a bucket and an object key by name, and then lists tests to be performed.
+
+    describe aws_s3_bucket_object(bucket_name: 'test_bucket', key: 'test_object_key') do
+      it { should exist }
+      it { should_not be_public }
+    end
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test a object's object-level ACL
+
+    describe aws_s3_bucket_object(bucket_name: 'test_bucket', key: 'test_key') do
+      its('object_acl.count') { should eq 1 }
+    end
+
+### Check to see if a object appears to be exposed to the public
+
+    # See Limitations section above
+    describe aws_s3_bucket_object(bucket_name: 'test_bucket', key: 'test_key') do
+      it { should_not be_public }
+    end
+<br>
+
+## Unsupported Properties
+
+### object\_acl
+
+The `object_acl` property is a low-level property that lists the individual Object ACL grants that are in effect on the object.  Other higher-level properties, such as be\_public, are more concise and easier to use.  You can use the `object_acl` property to investigate which grants are in effect, causing be\_public to fail.
+
+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)
+    all_users_grants = object_acl.select do |g|
+      g.grantee.type == 'Group' && g.grantee.uri =~ /AllUsers/
+    end
+
+    # Look for grants to "AuthenticatedUsers" (that is, any authenticated AWS user - nearly public)
+    auth_grants = object_acl.select do |g|
+      g.grantee.type == 'Group' && g.grantee.uri =~ /AuthenticatedUsers/
+    end
+
+## Matchers
+
+This InSpec audit resource has the following special matchers. For a full list of available matchers (such as `exist`) please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### be\_public
+
+The `be_public` matcher tests if the object has potentially insecure access controls. This high-level matcher detects several insecure conditions, which may be enhanced in the future. Currently, the matcher reports an insecure object if any of the following conditions are met:
+
+  1. A object ACL grant exists for the 'AllUsers' group
+  2. A object ACL grant exists for the 'AuthenticatedUsers' group
+
+Note: This resource does not detect insecure bucket ACLs.
+
+    it { should_not be_public }

data/docs/resources/aws_security_group.md.erb

@@ -1,151 +1,151 @@
----
-title: About the aws_security_group Resource
----
-
-# aws\_security\_group
-
-Use the `aws_security_group` InSpec audit resource to test detailed properties of an individual Security Group (SG).
-
-SGs are a networking construct which contain ingress and egress rules for network communications.  SGs may be attached to EC2 instances, as well as certain other AWS resources.  Along with Network Access Control Lists, SGs are one of the two main mechanisms of enforcing network-level security.
-
-<br>
-
-## Syntax
-
-An `aws_security_group` resource block uses resource parameters to search for a Security Group and then tests that Security Group. If no SGs match, no error is raised, but the `exists` matcher returns `false` and all properties will be `nil`. If more than one SG matches (due to vague search parameters), an error is raised.
-
-    # Ensure you have a security group with a certain ID
-    # This is "safe" - SG IDs are unique within an account
-    describe aws_security_group('sg-12345678') do
-      it { should exist }
-    end
-
-    # Ensure you have a security group with a certain ID
-    # This uses hash syntax
-    describe aws_security_group(id: 'sg-12345678') 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_security_group`, its limited functionality precludes examples.
-
-<br>
-
-## Resource Parameters
-
-This InSpec resource accepts the following parameters, which are used to search for the Security Group.
-
-### id, group\_id
-
-The Security Group ID of the Security Group. This is of the format `sg-` followed by 8 hexadecimal characters.  The ID is unique within your AWS account; using ID ensures that you will never match more than one SG. The ID is also the default resource parameter, so you may omit the hash syntax.
-
-    # Using Hash syntax
-    describe aws_security_group(id: 'sg-12345678') do
-      it { should exist }
-    end
-
-    # group_id is an alias for id
-    describe aws_security_group(group_id: 'sg-12345678') do
-      it { should exist }
-    end
-
-    # Or omit hash syntax, rely on it being the default parameter
-    describe aws_security_group('sg-12345678') do
-      it { should exist }
-    end
-
-### group\_name
-
-The string name of the Security Group.  Every VPC has a security group named 'default'. Names are unique within a VPC, but not within an AWS account.
-
-    # Get default security group for a certain VPC
-    describe aws_security_group(group_name: 'default', vpc_id: vpc_id: 'vpc-12345678') do
-      it { should exist }
-    end
-
-    # This will throw an error if there is a 'backend' SG in more than one VPC.
-    describe aws_security_group(group_name: 'backend') do
-      it { should exist }
-    end
-
-### vpc\_id
-
-A string identifying the VPC that contains the security group. Since VPCs commonly contain many SGs, you should add additional parameters to ensure you find exactly one SG.
-
-    # This will error if there is more than the default SG
-    describe aws_security_group(vpc_id: 'vpc-12345678') do
-      it { should exist }
-    end
-
-<br>
-## Properties
-
-* `description`, `group_id', `group_name`, `vpc_id`
-
-<br>
-
-## Property Examples
-
-### description
-
-A String reflecting the human-meaningful description that was given to the SG at creation time.
-
-    # Require a description of a particular group
-    describe aws_security_group('sg-12345678') do
-      its('description') { should_not be_empty }
-    end
-
-### group\_id
-
-Provides the Security Group ID.
-
-    # Inspect the group ID of the default group
-    describe aws_security_group(group_name: 'default', vpc_id: vpc_id: 'vpc-12345678') do
-      its('group_id') { should cmp 'sg-12345678' }
-    end
-
-    # Store the group ID in a Ruby variable for use elsewhere
-    sg_id = aws_security_group(group_name: 'default', vpc_id: vpc_id: 'vpc-12345678').group_id
-
-### group\_name
-
-A String reflecting the name that was given to the SG at creation time.
-
-    # Inspect the group name of a particular group
-    describe aws_security_group('sg-12345678') do
-      its('group_name') { should cmp 'my_group' }
-    end
-
-### vpc\_id
-
-A String in the format 'vpc-' followed by 8 hexadecimal characters reflecting VPC that contains the security group.
-
-    # Inspec the VPC ID of a particular group
-    describe aws_security_group('sg-12345678') do
-      its('vpc_id') { should cmp 'vpc-12345678' }
-    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/).
-
-### exists
-
-The control will pass if the specified SG was found.  Use `should_not` if you want to verify that the specified SG does not exist.
-
-    # You will always have at least one SG, the VPC default SG
-    describe aws_security_group(group_name: 'default')
-      it { should exist }
-    end
-
-    # Make sure we don't have any security groups with the name 'nogood'
-    describe aws_security_group(group_name: 'nogood')
-      it { should_not exist }
-    end
+---
+title: About the aws_security_group Resource
+---
+
+# aws\_security\_group
+
+Use the `aws_security_group` InSpec audit resource to test detailed properties of an individual Security Group (SG).
+
+SGs are a networking construct which contain ingress and egress rules for network communications.  SGs may be attached to EC2 instances, as well as certain other AWS resources.  Along with Network Access Control Lists, SGs are one of the two main mechanisms of enforcing network-level security.
+
+<br>
+
+## Syntax
+
+An `aws_security_group` resource block uses resource parameters to search for a Security Group and then tests that Security Group. If no SGs match, no error is raised, but the `exists` matcher returns `false` and all properties will be `nil`. If more than one SG matches (due to vague search parameters), an error is raised.
+
+    # Ensure you have a security group with a certain ID
+    # This is "safe" - SG IDs are unique within an account
+    describe aws_security_group('sg-12345678') do
+      it { should exist }
+    end
+
+    # Ensure you have a security group with a certain ID
+    # This uses hash syntax
+    describe aws_security_group(id: 'sg-12345678') 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_security_group`, its limited functionality precludes examples.
+
+<br>
+
+## Resource Parameters
+
+This InSpec resource accepts the following parameters, which are used to search for the Security Group.
+
+### id, group\_id
+
+The Security Group ID of the Security Group. This is of the format `sg-` followed by 8 hexadecimal characters.  The ID is unique within your AWS account; using ID ensures that you will never match more than one SG. The ID is also the default resource parameter, so you may omit the hash syntax.
+
+    # Using Hash syntax
+    describe aws_security_group(id: 'sg-12345678') do
+      it { should exist }
+    end
+
+    # group_id is an alias for id
+    describe aws_security_group(group_id: 'sg-12345678') do
+      it { should exist }
+    end
+
+    # Or omit hash syntax, rely on it being the default parameter
+    describe aws_security_group('sg-12345678') do
+      it { should exist }
+    end
+
+### group\_name
+
+The string name of the Security Group.  Every VPC has a security group named 'default'. Names are unique within a VPC, but not within an AWS account.
+
+    # Get default security group for a certain VPC
+    describe aws_security_group(group_name: 'default', vpc_id: vpc_id: 'vpc-12345678') do
+      it { should exist }
+    end
+
+    # This will throw an error if there is a 'backend' SG in more than one VPC.
+    describe aws_security_group(group_name: 'backend') do
+      it { should exist }
+    end
+
+### vpc\_id
+
+A string identifying the VPC that contains the security group. Since VPCs commonly contain many SGs, you should add additional parameters to ensure you find exactly one SG.
+
+    # This will error if there is more than the default SG
+    describe aws_security_group(vpc_id: 'vpc-12345678') do
+      it { should exist }
+    end
+
+<br>
+## Properties
+
+* `description`, `group_id', `group_name`, `vpc_id`
+
+<br>
+
+## Property Examples
+
+### description
+
+A String reflecting the human-meaningful description that was given to the SG at creation time.
+
+    # Require a description of a particular group
+    describe aws_security_group('sg-12345678') do
+      its('description') { should_not be_empty }
+    end
+
+### group\_id
+
+Provides the Security Group ID.
+
+    # Inspect the group ID of the default group
+    describe aws_security_group(group_name: 'default', vpc_id: vpc_id: 'vpc-12345678') do
+      its('group_id') { should cmp 'sg-12345678' }
+    end
+
+    # Store the group ID in a Ruby variable for use elsewhere
+    sg_id = aws_security_group(group_name: 'default', vpc_id: vpc_id: 'vpc-12345678').group_id
+
+### group\_name
+
+A String reflecting the name that was given to the SG at creation time.
+
+    # Inspect the group name of a particular group
+    describe aws_security_group('sg-12345678') do
+      its('group_name') { should cmp 'my_group' }
+    end
+
+### vpc\_id
+
+A String in the format 'vpc-' followed by 8 hexadecimal characters reflecting VPC that contains the security group.
+
+    # Inspec the VPC ID of a particular group
+    describe aws_security_group('sg-12345678') do
+      its('vpc_id') { should cmp 'vpc-12345678' }
+    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/).
+
+### exists
+
+The control will pass if the specified SG was found.  Use `should_not` if you want to verify that the specified SG does not exist.
+
+    # You will always have at least one SG, the VPC default SG
+    describe aws_security_group(group_name: 'default')
+      it { should exist }
+    end
+
+    # Make sure we don't have any security groups with the name 'nogood'
+    describe aws_security_group(group_name: 'nogood')
+      it { should_not exist }
+    end

data/docs/resources/aws_security_groups.md.erb

@@ -1,91 +1,91 @@
----
-title: About the aws_security_groups Resource
-platform: aws
----
-
-# aws\_security\_groups
-
-Use the `aws_security_groups` InSpec audit resource to test properties of some or all security groups.
-
-Security groups are a networking construct that contain ingress and egress rules for network communications. Security groups may be attached to EC2 instances, as well as certain other AWS resources. Along with Network Access Control Lists, Security Groups are one of the two main mechanisms of enforcing network-level security.
-
-<br>
-
-## Syntax
-
-An `aws_security_groups` resource block uses an optional filter to select a group of security groups and then tests that group.
-
-    # Verify you have more than the default security group
-    describe aws_security_groups do
-      its('entries.count') { should be > 1 }
-    end
-
-<br>
-
-## Examples
-
-The following examples show how to use this InSpec audit resource.
-
-As this is the initial release of `aws_security_groups`, its limited functionality precludes examples.
-
-<br>
-
-## Filter Criteria
-
-### vpc\_id
-
-A string identifying the VPC which contains the security group.
-
-    # Look for a particular security group in just one VPC
-    describe aws_security_groups.where( vpc_id: 'vpc-12345678') do
-      its('group_ids') { should include('sg-abcdef12')}
-    end
-
-### group\_name
-
-A string identifying a group. Since groups are contained in VPCs, group names are unique within the AWS account, but not across VPCs.
-
-    # Examine the default security group in all VPCs
-    describe aws_security_groups.where( group_name: 'default') do
-      it { should exist }
-    end
-
-<br>
-
-## Properties
-
-* `entries`, `group_ids`
-
-<br>
-
-## Property Examples
-
-### 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 security groups on the account
-    describe aws_security_groups do
-      its('entries.count') { should be <= 100}
-    end
-
-### group\_ids
-
-Provides a list of all security group IDs matched.
-
-    describe aws_security_groups do
-      its('group_ids') { should include('sg-12345678') }
-    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/).
-
-### exists
-
-The control will pass if the filter returns at least one result. Use `should_not` if you expect zero matches.
-
-    # You will always have at least one SG, the VPC default SG
-    describe aws_security_groups
-      it { should exist }
-    end
+---
+title: About the aws_security_groups Resource
+platform: aws
+---
+
+# aws\_security\_groups
+
+Use the `aws_security_groups` InSpec audit resource to test properties of some or all security groups.
+
+Security groups are a networking construct that contain ingress and egress rules for network communications. Security groups may be attached to EC2 instances, as well as certain other AWS resources. Along with Network Access Control Lists, Security Groups are one of the two main mechanisms of enforcing network-level security.
+
+<br>
+
+## Syntax
+
+An `aws_security_groups` resource block uses an optional filter to select a group of security groups and then tests that group.
+
+    # Verify you have more than the default security group
+    describe aws_security_groups do
+      its('entries.count') { should be > 1 }
+    end
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+As this is the initial release of `aws_security_groups`, its limited functionality precludes examples.
+
+<br>
+
+## Filter Criteria
+
+### vpc\_id
+
+A string identifying the VPC which contains the security group.
+
+    # Look for a particular security group in just one VPC
+    describe aws_security_groups.where( vpc_id: 'vpc-12345678') do
+      its('group_ids') { should include('sg-abcdef12')}
+    end
+
+### group\_name
+
+A string identifying a group. Since groups are contained in VPCs, group names are unique within the AWS account, but not across VPCs.
+
+    # Examine the default security group in all VPCs
+    describe aws_security_groups.where( group_name: 'default') do
+      it { should exist }
+    end
+
+<br>
+
+## Properties
+
+* `entries`, `group_ids`
+
+<br>
+
+## Property Examples
+
+### 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 security groups on the account
+    describe aws_security_groups do
+      its('entries.count') { should be <= 100}
+    end
+
+### group\_ids
+
+Provides a list of all security group IDs matched.
+
+    describe aws_security_groups do
+      its('group_ids') { should include('sg-12345678') }
+    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/).
+
+### exists
+
+The control will pass if the filter returns at least one result. Use `should_not` if you expect zero matches.
+
+    # You will always have at least one SG, the VPC default SG
+    describe aws_security_groups
+      it { should exist }
+    end