Added missing documentation following InSpec standards, resolves #11. (…

…#16) * Added missing documentation following InSpec standards, resolves #11. Also minor corrections to a couple of resources. Used InSpec FilterTable to create first plural resource for compute instances, including exammple controls and documentation. Signed-off-by: Stuart Paterson <[email protected]> * Rubocop indentation fix for google_compute_instances. Signed-off-by: Stuart Paterson <[email protected]>
inspec · Jun 6, 2018 · 804e067 · 804e067
1 parent e6a2cc0
commit 804e067
Show file tree

Hide file tree

Showing 18 changed files with 834 additions and 4 deletions.
diff --git a/docs/resources/google_compute_address.md.erb b/docs/resources/google_compute_address.md.erb
@@ -0,0 +1,63 @@
+---
+title: About the google_compute_address Resource
+platform: gcp
+---
+
+# google\_compute\_address
+
+Use the `google_compute_address` InSpec audit resource to test properties of a single GCP compute address.
+
+<br>
+
+## Syntax
+
+A `google_compute_address` resource block declares the tests for a single GCP compute address by project, region and name.
+
+    describe google_compute_address(project: 'chef-inspec-gcp', location: 'europe-west2', name: 'compute-address') do
+      it { should exist }
+      its('name') { should eq 'compute-address' }
+      its('region') { should match 'europe-west2' }
+    end
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test that a GCP compute address IP exists
+
+    describe google_compute_address(project: 'chef-inspec-gcp', location: 'europe-west2', name: 'compute-address') do
+      its('address_ip_exists')  { should be true }
+    end
+
+### Test that a GCP compute address is in a particular status
+
+    describe google_compute_address(project: 'chef-inspec-gcp', location: 'europe-west2', name: 'compute-address') do
+      its('status') { should eq "IN_USE" }
+    end
+
+### Test that a GCP compute address IP has the expected number of users
+
+    describe google_compute_address(project: 'chef-inspec-gcp', location: 'europe-west2', name: 'compute-address') do
+      its('user_count') { should eq 1 }
+    end
+
+### Test that the first user of a GCP compute address has the expected resource name
+
+    describe google_compute_address(project: 'chef-inspec-gcp', location: 'europe-west2', name: 'compute-address') do
+      its('user_resource_name') { should eq "gcp_ext_vm_name" }
+    end
+
+<br>
+
+## Properties
+
+*  `address`, `creation_timestamp`, `description`, `id`, `kind`, `name`, `region`, `status`, `users`
+
+<br>
+
+
+## GCP Permissions
+
+Ensure the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com/) is enabled for the project where the resource is located.
diff --git a/docs/resources/google_compute_firewall.md.erb b/docs/resources/google_compute_firewall.md.erb
@@ -0,0 +1,68 @@
+---
+title: About the google_compute_firewall Resource
+platform: gcp
+---
+
+# google\_compute\_firewall
+
+Use the `google_compute_firewall` InSpec audit resource to test properties of a single GCP compute compute firewall.
+
+<br>
+
+## Syntax
+
+A `google_compute_firewall` resource block declares the tests for a single GCP compute firewall by project and name.
+
+    describe google_compute_firewall(project: 'chef-inspec-gcp', name: 'firewall-rule') do
+      it { should exist }
+      its('name') { should eq 'firewall-rule' }
+    end
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test that a GCP compute firewall allows SSH access on port 22
+
+    describe google_compute_firewall(project: 'chef-inspec-gcp', name: 'firewall-rule') do
+      its('allowed_ssh?')  { should be true }
+    end
+
+### Test that a GCP compute firewall does not allow HTTP access on port 80
+
+    describe google_compute_firewall(project: 'chef-inspec-gcp', name: 'firewall-rule') do
+      its('allowed_http?')  { should be false }
+    end
+
+### Test that a GCP compute firewall allows HTTPS access on port 443
+
+    describe google_compute_firewall(project: 'chef-inspec-gcp', name: 'firewall-rule') do
+      its('allowed_https?')  { should be true }
+    end
+
+### Test the direction of a GCP compute firewall e.g. "INGRESS" or "EGRESS"
+
+    describe google_compute_firewall(project: 'chef-inspec-gcp', name: 'firewall-rule') do
+      its('direction') { should eq "INGRESS" }
+    end
+
+### Test the source IP range list for the GCP compute firewall is not open to the world
+
+    describe google_compute_firewall(project: 'chef-inspec-gcp', name: 'firewall-rule') do
+      its('source_ranges') { should_not eq ["0.0.0.0/0"] }
+    end
+
+<br>
+
+## Properties
+
+*  `allowed`, `creation_timestamp`, `description`, `direction`, `id`, `kind`, `name`, `network`, `priority`, `source_ranges`, `target_tags`
+
+<br>
+
+
+## GCP Permissions
+
+Ensure the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com/) is enabled for the project where the resource is located.
diff --git a/docs/resources/google_compute_image.md.erb b/docs/resources/google_compute_image.md.erb
@@ -0,0 +1,50 @@
+---
+title: About the google_compute_image Resource
+platform: gcp
+---
+
+# google\_compute\_image
+
+Use the `google_compute_image` InSpec audit resource to test properties of a single GCP compute image.  This resource will attempt to retrieve a project custom image then image from a family before giving up.
+
+<br>
+
+## Syntax
+
+A `google_compute_image` resource block declares the tests for a single GCP compute image by project and name.
+
+    describe google_compute_image(project: 'chef-inspec-gcp', name: 'image-1') do
+      it { should exist }
+      its('name') { should eq 'image-1' }
+    end
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test that a GCP compute image is in a particular status e.g. "READY" means available for use
+
+    describe google_compute_image(project: 'chef-inspec-gcp', location: 'europe-west2', name: 'compute-address') do
+      its('status') { should eq "READY" }
+    end
+
+### Test that a GCP compute image has the expected family
+
+    describe google_compute_image(project: 'chef-inspec-gcp', name: 'ubuntu') do
+      its('family') { should match "ubuntu" }
+    end
+
+<br>
+
+## Properties
+
+*  `archive_size_bytes`, `creation_timestamp`, `description`, `disk_size_gb`, `family`, `guest_os_features`, `id`, `kind`, `label_fingerprint`, `licenses`, `name`, `raw_disk`, `source_type`, `status`
+
+<br>
+
+
+## GCP Permissions
+
+Ensure the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com/) is enabled for the project where the resource is located.
diff --git a/docs/resources/google_compute_instance.md.erb b/docs/resources/google_compute_instance.md.erb
@@ -0,0 +1,89 @@
+---
+title: About the google_compute_instance Resource
+platform: gcp
+---
+
+# google\_compute\_instance
+
+Use the `google_compute_instance` InSpec audit resource to test properties of a single GCP compute instance.
+
+<br>
+
+## Syntax
+
+A `google_compute_instance` resource block declares the tests for a single GCP instance by project, zone and name.
+
+    describe google_compute_instance(project: 'chef-inspec-gcp',  zone: 'us-east1-b', name: 'inspec-test-vm') do
+      it { should exist }
+      its('name') { should eq 'inspec-test-vm' }
+      its('zone') { should match 'us-east1-b' }
+    end
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test that a GCP compute instance does not exist
+
+    describe google_compute_instance(project: 'chef-inspec-gcp',  zone: 'us-east1-b', name: 'inspec-test-vm-not-there') do
+      it { should_not exist }
+    end
+
+### Test that a GCP compute instance is in the expected state ([explore possible states here](https://cloud.google.com/compute/docs/instances/checking-instance-status))
+
+    describe google_compute_instance(project: 'chef-inspec-gcp',  zone: 'us-east1-b', name: 'inspec-test-vm') do
+      its('status') { should eq 'RUNNING' }
+    end
+
+### Test that a GCP compute instance is the expected size
+
+    describe google_compute_instance(project: 'chef-inspec-gcp',  zone: 'us-east1-b', name: 'inspec-test-vm') do
+      its('machine_type') { should match "f1-micro" }
+    end
+
+### Test that a GCP compute instance has the expected CPU platform
+
+    describe google_compute_instance(project: 'chef-inspec-gcp',  zone: 'us-east1-b', name: 'inspec-test-vm') do
+      its('cpu_platform') { should match "Intel" }
+    end
+
+### Test that a GCP compute instance has the expected number of attached disks
+
+    describe google_compute_instance(project: 'chef-inspec-gcp',  zone: 'us-east1-b', name: 'inspec-test-vm') do
+      its('disk_count'){should eq 2}
+    end
+
+### Test that a GCP compute instance has the expected number of attached network interfaces
+
+    describe google_compute_instance(project: 'chef-inspec-gcp',  zone: 'us-east1-b', name: 'inspec-test-vm') do
+      its('network_interfaces_count'){should eq 1}
+    end
+
+### Test that a GCP compute instance has the expected number of tags
+
+    describe google_compute_instance(project: 'chef-inspec-gcp',  zone: 'us-east1-b', name: 'inspec-test-vm') do
+      its('tag_count'){should eq 1}
+    end
+
+### Test that a GCP compute instance has a single public IP address
+
+    describe google_compute_instance(project: 'chef-inspec-gcp',  zone: 'us-east1-b', name: 'inspec-test-vm') do
+      its('first_network_interface_nat_ip_exists'){ should be true }
+      its('first_network_interface_name'){ should eq "external-nat" }
+      its('first_network_interface_type'){ should eq "one_to_one_nat" }
+    end
+
+<br>
+
+## Properties
+
+*  `cpu_platform`, `creation_timestamp`, `deletion_protection`, `disks`, `id`, `kind`, `label_fingerprint`, `machine_type`, `metadata`, `name`, `network_interfaces`, `scheduling`, `start_restricted`, `status`, `tags`, `zone`
+
+<br>
+
+
+## GCP Permissions
+
+Ensure the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com/) is enabled for the project where the resource is located.
diff --git a/docs/resources/google_compute_instance_group.md.erb b/docs/resources/google_compute_instance_group.md.erb
@@ -0,0 +1,52 @@
+---
+title: About the google_compute_instance_group Resource
+platform: gcp
+---
+
+# google\_compute\_instance\_group
+
+Use the `google_compute_instance_group` InSpec audit resource to test properties of a single GCP compute instance group.
+
+<br>
+
+## Syntax
+
+A `google_compute_instance_group` resource block declares the tests for a single GCP compute instance group by project, zone and name.
+
+    describe google_compute_instance_group(project: 'chef-inspec-gcp', zone: 'europe-west2-a', name: 'gcp-inspec-test') do
+      it { should exist }
+      its('name') { should eq 'gcp-inspec-test' }
+      its('zone') { should match 'europe-west2-a' }
+    end
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test that a GCP compute instance group has the expected size
+
+    describe google_compute_instance_group(project: 'chef-inspec-gcp', zone: 'europe-west2-a', name: 'gcp-inspec-test') do
+      its('size') { should eq 2 }
+    end
+
+### Test that a GCP compute instance group has a port with supplied name and value
+
+    describe google_compute_instance_group(project: 'chef-inspec-gcp', zone: 'europe-west2-a', name: 'gcp-inspec-test') do
+      its('port_name') { should eq "http" }
+      its('port_value') { should eq 80 }
+    end
+
+<br>
+
+## Properties
+
+*  `creation_timestamp`, `description`, `fingerprint`, `id`, `kind`, `name`, `named_ports`, `network`, `size`, `subnetwork`, `zone`
+
+<br>
+
+
+## GCP Permissions
+
+Ensure the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com/) is enabled for the project where the resource is located.