inspec 2.1.84 → 2.2.10

data/docs/matchers.md

@@ -55,58 +55,58 @@ end
 
 * Compare strings to numbers
 
-    ```ruby
-    describe sshd_config do
-      its('Protocol') { should eq '2' }
+```ruby
+describe sshd_config do
+  its('Protocol') { should eq '2' }
 
-      its('Protocol') { should cmp '2' }
-      its('Protocol') { should cmp 2 }
-    end
-    ```
+  its('Protocol') { should cmp '2' }
+  its('Protocol') { should cmp 2 }
+end
+```
 
 * String comparisons are not case-sensitive
 
-    ```ruby
-    describe auditd_conf do
-      its('log_format') { should cmp 'raw' }
-      its('log_format') { should cmp 'RAW' }
-    end
-    ```
+```ruby
+describe auditd_conf do
+  its('log_format') { should cmp 'raw' }
+  its('log_format') { should cmp 'RAW' }
+end
+```
 * Recognize versions embedded in strings
 
-    ```ruby
-    describe package(curl) do
-      its('version') { should cmp > '7.35.0-1ubuntu2.10' }
-    end
-    ```
+```ruby
+describe package(curl) do
+  its('version') { should cmp > '7.35.0-1ubuntu2.10' }
+end
+```
 
 * Compare arrays with only one entry to a value
 
-    ```ruby
-    describe passwd.uids(0) do
-      its('users') { should cmp 'root' }
-      its('users') { should cmp ['root'] }
-    end
-    ```
+```ruby
+describe passwd.uids(0) do
+  its('users') { should cmp 'root' }
+  its('users') { should cmp ['root'] }
+end
+```
 
 * Single-value arrays of strings may also be compared to a regex
 
-    ```ruby
-    describe auditd_conf do
-      its('log_format') { should cmp /raw/i }
-    end
-    ```
+```ruby
+describe auditd_conf do
+  its('log_format') { should cmp /raw/i }
+end
+```
 
 * Improved printing of octal comparisons
 
-    ```ruby
-    describe file('/proc/cpuinfo') do
-      its('mode') { should cmp '0345' }
-    end
+```ruby
+describe file('/proc/cpuinfo') do
+  its('mode') { should cmp '0345' }
+end
 
-    expected: 0345
-    got: 0444
-    ```
+expected: 0345
+got: 0444
+```
 <br>
 
 ## eq

data/docs/profiles.md

@@ -29,7 +29,7 @@ where:
 * `files` is the directory with additional files that a profile can access (optional)
 * `README.md` should be used to explain the profile, its scope, and usage
 
-See a complete example profile in the InSpec open source repository: [https://github.com/chef/inspec/tree/master/examples/profile](https://github.com/chef/inspec/tree/master/examples/profile)
+See a complete example profile in the InSpec open source repository: [Example InSpec Profile](https://github.com/chef/inspec/tree/master/examples/profile)
 
 Also check out [Explore InSpec resources](https://learn.chef.io/modules/explore-inspec-resources#/) on Learn Chef Rally to learn more about how profiles are structured with hands-on examples.
 
@@ -300,7 +300,7 @@ The following command runs the tests and applies the secrets specified in `profi
 
     $ inspec exec examples/profile-attribute --attrs examples/profile-attribute.yml
 
-See the full example in the InSpec open source repository: https://github.com/chef/inspec/tree/master/examples/profile-attribute
+See the full example in the InSpec open source repository: [Example InSpec Profile with Attributes](https://github.com/chef/inspec/tree/master/examples/profile-attribute)
 
 # Profile files
 

data/docs/resources/apache.md.erb

@@ -28,7 +28,7 @@ where
 
 ## Properties
 
-* 'service', 'conf_dir', 'conf_path', 'user'
+* `service`, `conf_dir`, `conf_path`, `user`
 
 <br>
 

data/docs/resources/aws_elb.md.erb

@@ -0,0 +1,144 @@
+---
+title: About the aws_elb Resource
+platform: aws
+---
+
+# aws\_elb
+
+Use the `aws_elb` InSpec audit resource to test properties of a single AWS Elastic Load Balancer (ELB, also known as a Classic Load Balancer).
+
+To audit ELBs in bulk or to search, use `aws_elbs` (plural).
+
+<br>
+
+## Resource Parameters
+
+An `aws_elb` resource block declares the tests for a single AWS ELB by ELB name.
+
+    describe aws_elb('my-elb') do
+      it { should exist }
+    end
+
+    describe aws_elb(elb_name: 'my-elb') do
+      its('instance_ids.count') { should cmp 2 }
+    end
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test that an ELB does not exist
+
+    describe aws_elb('bad-elb') do
+      it { should_not exist }
+    end
+
+### Test that an ELB has a presence in at least two availability zones
+
+    describe aws_elb('web') do
+      its('availability_zones.count') { should be > 1 }
+    end
+
+<br>
+
+## Properties
+
+### availability\_zones
+
+Returns an array of strings identifying which availability zones in which the load balancer is located.
+
+    # Verify we are in both us-east-2a and us-east-2b
+    describe aws_elb('web-elb') do
+      its('availability_zones') { should include 'us-east-2a' }
+      its('availability_zones') { should include 'us-east-2b' }
+    end
+
+### dns\_name
+
+Returns the FQDN of the load balancer.  This is the hostname which is exposed to the world.
+
+    # Ensure that the ELB has a DNS name
+    describe aws_elb('web-elb') do
+      its('dns_name') { should match /\.com/ }
+    end
+
+### elb\_name
+
+The name of the ELB within AWS. The ELB name is unique within the region.
+
+    # Ensure that the ELB's name is what we said it was
+    describe aws_elb('web-elb') do
+      its('elb_name') { should match /web-elb/ }
+    end
+
+### external\_ports
+
+Returns an array of integers reflecting the public-facing ports on which the load balancer will be listening for traffic.
+
+    # Ensure that we are listening on port 80 and nothing else
+    describe aws_elb('web-elb') do
+      its('external_ports') { should include 80 }
+      its('external_ports.count') { should cmp 1 }
+    end
+
+### instance\_ids
+
+Returns an array of strings reflecting the instance IDs of the EC2 instances attached to the ELB.
+
+    # Ensure that a specific instance is attached
+    describe aws_elb('web-elb') do
+      its('instance_ids') { should include 'i-12345678' }
+    end
+
+
+### internal\_ports
+
+Returns an array of integers reflecting the EC2-facing ports on which the load balancer will be sending traffic to.
+
+    # Ensure that we are sending traffic to port 80 on the instances and nothing else
+    describe aws_elb('web-elb') do
+      its('internal_ports') { should include 80 }
+      its('internal_ports.count') { should cmp 1 }
+    end
+
+### security\_group\_ids
+
+Returns an array of strings reflecting the security group IDs (firewall rule sets) assigned to the ELB.
+
+    # Ensure that a specific SG ID is assigned
+    describe aws_elb('web-elb') do
+      its('security_group_ids') { should include 'sg-12345678' }
+    end
+
+### subnet\_ids
+
+Returns an array of strings reflecting the subnet IDs on which the ELB is located.
+
+    # Ensure that the ELB is on a specific subnet
+    describe aws_elb('web-elb') do
+      its('subnet_ids') { should include 'subnet-12345678' }
+    end
+
+### vpc\_id
+
+Returns a String reflecting the ID of the VPC in which the ELB is located.
+
+    # Ensure that the ELB is on a specific VPC
+    describe aws_elb('web-elb') do
+      its('vpc_id') { should cmp 'vpc-12345678' }
+    end
+
+<br>
+
+## Matchers
+
+This InSpec audit resource has no special matchers. For a full list of available matchers, please visit our [Universal Matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+
+## AWS Permissions
+
+Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `elasticloadbalancing:DescribeLoadBalancers` action set to Allow.
+
+You can find detailed documentation at [Authentication and Access Control for Your Load Balancers](https://docs.aws.amazon.com/elasticloadbalancing/latest/userguide/load-balancer-authentication-access-control.html)

data/docs/resources/aws_elbs.md.erb

@@ -0,0 +1,242 @@
+---
+title: About the aws_elbs Resource
+platform: aws
+---
+
+# aws\_elbs
+
+Use the `aws_elbs` InSpec audit resource to test properties of AWS Elastic Load Balancers (ELBs, also known as a Classic Load Balancers) in bulk, or to search for a group of them based on their properties.
+
+To audit a specific ELB in detail when its name is known, use `aws_elb` (singular).
+
+<br>
+
+## Syntax
+
+An `aws_elb` resource block uses an optional filter to select a group of ELBs and then tests that group.
+
+    # Check that you have at aleast one ELB
+    describe aws_elbs do
+      it { should exist }
+    end
+
+    # Ensure that you have at least one ELB in a specific VPC
+    describe aws_elb.where(vpc_id: 'vpc-12345678') do
+      it { should exist }
+    end
+
+<br>
+
+## Filter Criteria
+
+Use filter criteria with `where` to search for ELBs by their properties.  `where` may be used in method mode (as in `aws_elbs.where(criterion: value)`) or in block mode (as in `aws_elbs.where { any code here }`). Several criteria on this resource may only be used with block-mode, because they are list-based.
+
+### availability\_zones
+
+An array of strings identifying which availability zones in which the load balancer is located. This criterion must be used with block-mode `where`.
+
+    # Find ELBs with a footprint in us-east-2a
+    describe aws_elbs.where {  availability_zones.include? 'us-east-2a' } do
+      it { should exist }
+    end
+
+### dns\_name
+
+Returns the FQDN of the load balancer.  This is the hostname which is exposed to the world.
+
+    # Find ELBs that have the letter z in their DNS name
+    describe aws_elbs.where(dns_name: /z/) do
+      it { should exist }
+    end
+
+### elb\_name
+
+The name of the ELB within AWS. The ELB name is unique within the region. If you know the full ELB name, you should use the `aws_elb` resource instead, as it is much more efficient for testing a specific ELB.
+
+    # Find ELBs whose name ends in `prod`
+    describe aws_elbs.where(elb_name: /prod$/) do
+      it { should exist }
+    end
+
+### external\_ports
+
+An array of integers reflecting the public-facing ports on which the load balancer will be listening for traffic. This criterion must be used with block-mode `where`.
+
+    # Find ELBs listening on port 80
+    describe aws_elbs.where { external_ports.include? 80 } do
+      it { should exist }
+    end
+
+### instance\_ids
+
+An array of strings reflecting the instance IDs of the EC2 instances attached to the ELB. This criterion must be used with block-mode `where`.
+
+    # Find ELBs with at least 3 instances
+    describe aws_elbs.where { instance_ids.count > 2 } do
+      it { should exist }
+    end
+
+
+### internal\_ports
+
+An array of integers reflecting the EC2-facing ports on which the load balancer will be sending traffic to. This criterion must be used with block-mode `where`.
+
+    # Find ELBs sending traffic to port 80
+    describe aws_elbs.where { internal_ports.include? 80 } do
+      it { should exist }
+    end
+
+### security\_group\_ids
+
+An array of strings reflecting the security group IDs (firewall rule sets) assigned to the ELB. This criterion must be used with block-mode `where`.
+
+    # Find ELBs using a particular security group
+    describe aws_elbs.where { security_group_ids.include? 'sg-12345678' } do
+      it { should exist }
+    end
+
+### subnet\_ids
+
+An array of strings reflecting the subnet IDs on which the ELB is located. This criterion must be used with block-mode `where`.
+
+    # Find ELBs located on a particular subnet
+    describe aws_elbs.where { subnet_ids.include? 'subnet-12345678' } do
+      it { should exist }
+    end
+
+### vpc\_id
+
+A String reflecting the ID of the VPC in which the ELB is located.
+
+    # Find all ELBs in a specific VPC.
+    describe aws_elbs.where(vpc_id: 'vpc-12345678') do
+      it { should exist }    
+    end
+
+<br>
+
+## Properties
+
+### availability\_zones
+
+An array of strings identifying which availability zones in which the selected load balancers are located. The array is de-duplicated.
+
+    # Ensure none of our ELBs are in us-east-1c
+    describe aws_elbs do
+      its('availability_zones') { should_not include 'us-east-1c' }
+    end
+
+### count
+
+Returns an integer reflecting the number of matched ELBs.
+
+    # Ensure we have 4 ELBs total.
+    describe aws_elbs do
+      its('count') { should cmp 4 }
+    end
+
+### dns\_names
+
+An array of FQDNs of the selected load balancers.  These are the hostnames which are exposed to the world.
+
+    # Ensure none of the DNS names are an old name
+    describe aws_elbs do
+      its('dns_names') { should_not include 'some.horrid.name' }
+    end
+
+### elb\_names
+
+The names of the selected ELBs within AWS. The ELB name is unique within the region. 
+
+    # You can use this to enumerate the ELBs for detailed tests
+    # Search using the plural, analyze using the singular.
+    aws_elbs.where { instance_ports.include? 80 }.elb_names.each do |elb_name|
+      describe aws_elb(elb_name) do
+        its('security_group_ids') { should include 'sg-12345678' }
+      end
+    end
+
+### external\_ports
+
+An array of integers reflecting the public-facing ports on which the selected load balancers will be listening for traffic. The array is de-duplicated.
+
+    # Ensure that the only ports we are listening on are 80 and 443
+    describe aws_elbs do
+      its('external_ports') { should include 80 }
+      its('external_ports') { should include 443 }
+      its('external_ports.count') { should cmp 2 }      
+    end
+
+
+### instance\_ids
+
+An array of strings reflecting the instance IDs of the EC2 instances attached to the selected ELBs.
+
+    # Ensure there are 10-20 instances total attached to all ELBs
+    describe aws_elbs do
+      its('instance_ids.count') { should be >= 10 }
+      its('instance_ids.count') { should be <= 20 }
+    end
+
+### internal\_ports
+
+An array of integers reflecting the EC2-facing ports on which the selected load balancers will be sending traffic to. The array is de-duplicated.
+
+    # Ensure all ELBs only talk to port 80
+    describe aws_elbs do
+      its('internal_ports') { should contain 80 }
+      its('internal_ports.count') { should cmp 1 }
+    end
+
+### security\_group\_ids
+
+An array of strings reflecting the security group IDs (firewall rule sets) assigned to the selected ELBs. The array is de-duplicated.
+
+    # Ensure all ELBs are using one specific security group
+    describe aws_elbs do
+      its('security_group_ids') { should include 'sg-12345678' }
+      its('security_group_ids.count') { should cmp 1 }      
+    end
+
+### subnet\_ids
+
+An array of strings reflecting the subnet IDs on which the selected ELBs are located. The array is de-duplicated.
+
+    # Ensure all ELBs are on a particular subnet
+    describe aws_elbs do
+      its('subnet_ids') { should include 'subnet-12345678' }
+      its('subnet_ids.count') { should cmp 1 }
+    end
+
+### vpc\_ids
+
+An array of strings reflecting the ID of the VPCs in which the selected ELBs are located. The array is de-duplicated.
+
+    # Ensure all ELBs are in one VPC
+    describe aws_elbs do
+      its('vpc_ids.count') { should cmp 1 }
+    end
+
+## 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/).
+
+### exists
+
+The audit test will pass if at least one ELB was matched by the filter.  Use with `should_not` to test for absence.
+
+    # We like z's in our DNS names
+    describe aws_elbs.where(dns_name: /z/) do
+      it { should exist }
+    end
+
+    # But k's are just awful
+    describe aws_elbs.where(dns_name: /k/) 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 `elasticloadbalancing:DescribeLoadBalancers` action set to Allow.
+
+You can find detailed documentation at [Authentication and Access Control for Your Load Balancers](https://docs.aws.amazon.com/elasticloadbalancing/latest/userguide/load-balancer-authentication-access-control.html)