inspec 1.0.0 → 1.35.1

data/docs/resources/docker.md.erb

@@ -0,0 +1,160 @@
+---
+title: About the docker Resource
+---
+
+# docker
+
+Use the `docker` InSpec audit resource to test configuration data for docker daemon. It is a very comprehensive resource. Please have a look at [docker_container](docker_container) and [docker_image](docker_image), too.
+
+## Syntax
+
+A `docker` resource block declares allows you to write test for many containers:
+
+    describe docker.containers do
+      its('images') { should_not include 'u12:latest' }
+    end
+
+or:
+
+    describe docker.containers.where { name == 'flamboyant_colden' } do
+      it { should be_running }
+    end
+
+where
+
+* `.where()` may specify a specific item and value, to which the matchers are compared
+* `commands`, `ids`, `images`, `labels`, `local_volumes`, `mounts`, `names`, `networks`, `ports`, `sizes`  and `'status'` are valid matchers for `containers`
+
+The `docker` resource block also declares allows you to write test for many images:
+
+    describe docker.images do
+      its('repositories') { should_not include 'inssecure_image' }
+    end
+
+or if you want to query specific images:
+
+    describe docker.images.where { repository == 'ubuntu' && tag == '12.04' } do
+      it { should_not exist }
+    end
+
+where
+
+* `.where()` may specify a specific item and value, to which the matchers are compared
+* `commands`, `ids`, `images`, `labels`, `local_volumes`, `mounts`, `names`, `networks`, `ports`, `sizes`  and `'status'` are valid matchers for `containers`
+
+
+
+## Matchers
+
+This InSpec audit resource has the following matchers:
+
+### containers
+
+`containers` returns information about containers as returned by [docker ps -a](https://docs.docker.com/engine/reference/commandline/ps/). You can determine specific information about
+
+    describe docker.containers do
+      its('ids') { should include 'sha:71b5df59...442b' }
+      its('commands') { should_not include '/bin/sh' }
+      its('images') { should_not include 'u12:latest' }
+      its('ports') { should include '0.0.0.0:1234->1234/tcp' }
+      its('labels') { should include 'License=GPLv2,Vendor=CentOS' }
+    end
+
+
+### images
+
+`images` returns information about docker image as returned by [docker images](https://docs.docker.com/engine/reference/commandline/images/). You can determine specific information about
+
+    describe docker.images do
+      its('ids') { should include 'sha:12b5df59...442b' }
+      its('repositories') { should_not include 'my_image' }
+      its('tags') { should_not include 'unwanted_tag' }
+      its('sizes') { should_not include "1.41 GB" }
+    end
+
+### version
+
+`info` returns the parsed result of [docker version](https://docs.docker.com/engine/reference/commandline/version/)
+
+    describe docker.version do
+      its('Server.Version') { should cmp >= '1.12'}
+      its('Client.Version') { should cmp >= '1.12'}
+    end
+
+
+### info
+
+`info` returns the parsed result of [docker info](https://docs.docker.com/engine/reference/commandline/info/)
+
+    describe docker.info do
+      its('Configuration.Path') { should eq 'value' }
+    end
+
+
+### object('id')
+
+`object` returns low-level information about docker objects. It is calling [docker inspect](https://docs.docker.com/engine/reference/commandline/info/) under the hood.
+
+    describe docker.object(id) do
+      its('Configuration.Path') { should eq 'value' }
+    end
+
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Return all running containers
+
+    docker.containers.running?.ids.each do |id|
+      describe docker.object(id) do
+        its('State.Health.Status') { should eq 'healthy' }
+      end
+    end
+
+### Verify a Docker Server and Client version
+
+    describe docker.version do
+      its('Server.Version') { should cmp >= '1.12'}
+      its('Client.Version') { should cmp >= '1.12'}
+    end
+
+### Iterate over all containers to verify host coniguration
+
+    docker.containers.ids.each do |id|
+      # call docker inspect for a specific container id
+      describe docker.object(id) do
+        its(%w(HostConfig Privileged)) { should cmp false }
+        its(%w(HostConfig Privileged)) { should_not cmp true }
+      end
+    end
+
+### Iterate over all images to verify the container was built without ADD instruction
+
+    docker.images.ids.each do |id|
+      describe command("docker history #{id}| grep 'ADD'") do
+        its('stdout') { should eq '' }
+      end
+    end
+
+### Verify that health-checks are enabled for a container
+
+    describe docker.object('71b5df59442b') do
+      its(%w(Config Healthcheck)) { should_not eq nil }
+    end
+
+### Run the DevSec docker baseline  profile
+
+There are two ways to run the `docker-baseline` profile to test Docker via the `docker` resource.
+
+Clone the profile:
+
+    $ git clone https://github.com/dev-sec/cis-docker-benchmark.git
+
+and then run:
+
+    $ inspec exec cis-docker-benchmark
+
+Or execute the profile directly via URL:
+
+    $ inspec exec https://github.com/dev-sec/cis-docker-benchmark

data/docs/resources/docker_container.md.erb

@@ -0,0 +1,89 @@
+---
+title: About the docker_container Resource
+---
+
+# docker_container
+
+Use the `docker_container` InSpec audit resource to test a docker container.
+
+## Syntax
+
+A `docker_container` resource block declares the configuration data to be tested:
+
+    describe docker_container('container') do
+      it { should exist }
+      it { should be_running }
+      its('id') { should_not eq '' }
+      its('image') { should eq 'busybox:latest' }
+      its('repo') { should eq 'busybox' }
+      its('tag') { should eq 'latest' }
+      its('ports') { should eq [] }
+      its('command') { should eq 'nc -ll -p 1234 -e /bin/cat' }
+    end
+
+The container name can also be passed with the `name` argument:
+
+    describe docker_container(name: 'an-echo-server') do
+      it { should exist }
+      it { should be_running }
+    end
+
+Alternatively, you can pass in the container id:
+
+    describe docker_container(id: '71b5df59442b') do
+      it { should exist }
+      it { should be_running }
+    end
+
+
+## Matchers
+
+This InSpec audit resource has the following matchers:
+
+### id
+
+The `id` matcher tests the container id:
+
+    its('id') { should eq 'sha:71b5df59...442b' }
+
+### repo
+
+The `repo` matcher tests the value of the image repository:
+
+    its('repo') { should eq 'busybox' }
+
+### tag
+
+The `tag` matcher tests the value of the image tag:
+
+    its('tag') { should eq 'latest' }
+
+### ports
+
+The `ports` matcher tests the value the docker ports:
+
+    its('ports') { should eq '0.0.0.0:1234->1234/tcp' }
+
+### command
+
+The `command` matcher tests the value of the container run command:
+
+    its('command') { should eq 'nc -ll -p 1234 -e /bin/cat' }
+
+
+## Examples
+
+The following examples show how to use this InSpec resource.
+
+### Verify an running container:
+
+    describe docker_container('an-echo-server') do
+      it { should exist }
+      it { should be_running }
+      its('id') { should_not eq '' }
+      its('image') { should eq 'busybox:latest' }
+      its('repo') { should eq 'busybox' }
+      its('tag') { should eq 'latest' }
+      its('ports') { should eq [] }
+      its('command') { should eq 'nc -ll -p 1234 -e /bin/cat' }
+    end

data/docs/resources/docker_image.md.erb

@@ -0,0 +1,86 @@
+---
+title: About the docker_image Resource
+---
+
+# docker_image
+
+Use the `docker_image` InSpec audit resource to verify a docker image.
+
+## Syntax
+
+A `docker_image` resource block declares the image:
+
+    describe docker_image('alpine:latest') do
+      it { should exist }
+      its('id') { should eq 'sha256:4a415e...a526' }
+      its('repo') { should eq 'alpine' }
+      its('tag') { should eq 'latest' }
+    end
+
+The resource allows you to pass in an image id:
+
+    describe docker_image(id: alpine_id) do
+      ...
+    end
+
+If the tag is missing for an image, `latest` is assumed as default:
+
+    describe docker_image('alpine') do
+      ...
+    end
+
+You can also pass in repository and tag as separate values
+
+    describe docker_image(repo: 'alpine', tag: 'latest') do
+      ...
+    end
+
+
+## Matchers
+
+This InSpec audit resource has the following matchers:
+
+### exist
+
+The `exist` matcher tests if the image is available on the node:
+
+    it { should exist }
+
+### id
+
+The `id` matcher returns the full image id:
+
+    its('id') { should eq 'sha256:4a415e3663882fbc554ee830889c68a33b3585503892cc718a4698e91ef2a526' }
+
+### image
+
+The `image` matcher tests the value of the image. It is a combination of `repository/tag`:
+
+    its('image') { should eq 'alpine:latest' }
+
+### repo
+
+The `repo` matcher tests the value of the repository name:
+
+    its('repo') { should eq 'alpine' }
+
+### tag
+
+The `tag` matcher tests the value of image tag:
+
+    its('tag') { should eq 'latest' }
+
+
+## Examples
+
+The following examples show how to use this InSpec `docker_image` resource.
+
+### Test a docker image
+
+    describe docker_image('alpine:latest') do
+      it { should exist }
+      its('id') { should eq 'sha256:4a415e...a526' }
+      its('image') { should eq 'alpine:latest' }
+      its('repo') { should eq 'alpine' }
+      its('tag') { should eq 'latest' }
+    end

data/docs/resources/etc_group.md.erb

@@ -6,7 +6,7 @@ title: About the etc_group Resource
 
 Use the `etc_group` InSpec audit resource to test groups that are defined on Linux and Unix platforms. The `/etc/group` file stores details about each group---group name, password, group identifier, along with a comma-separate list of users that belong to the group.
 
-# Syntax
+## Syntax
 
 A `etc_group` resource block declares a collection of properties to be tested:
 
@@ -28,49 +28,49 @@ where
 * `.where()` may specify a specific item and value, to which the matchers are compared
 * `'gids'`, `'groups'`, and `'users'` are valid matchers for this resource
 
-# Matchers
+## Matchers
 
 This InSpec audit resource has the following matchers:
 
-## be
+### be
 
 <%= partial "/shared/matcher_be" %>
 
-## cmp
+### cmp
 
 <%= partial "/shared/matcher_cmp" %>
 
-## eq
+### eq
 
 <%= partial "/shared/matcher_eq" %>
 
-## gids
+### gids
 
 The `gids` matcher tests if the named group identifier is present or if it contains duplicates:
 
     its('gids') { should_not contain_duplicates }
 
-## groups
+### groups
 
 The `groups` matcher tests all groups for the named user:
 
     its('groups') { should include 'my_group' }
 
-## include
+### include
 
 <%= partial "/shared/matcher_include" %>
 
-## match
+### match
 
 <%= partial "/shared/matcher_match" %>
 
-## users
+### users
 
 The `users` matcher tests all groups for the named user:
 
     its('users') { should include 'my_user' }
 
-## where
+### where
 
 The `where` matcher allows the test to be focused to one (or more) specific items:
 
@@ -87,29 +87,29 @@ where `item` may be one (or more) of:
 * `members: 'member_name'`
 
 
-# Examples
+## Examples
 
 The following examples show how to use this InSpec audit resource.
 
-## Test group identifiers (GIDs) for duplicates
+### Test group identifiers (GIDs) for duplicates
 
     describe etc_group do
       its('gids') { should_not contain_duplicates }
     end
 
-## Test all groups to see if a specific user belongs to one (or more) groups
+### Test all groups to see if a specific user belongs to one (or more) groups
 
     describe etc_group do
       its('groups') { should include 'my_group' }
     end
 
-## Test all groups for a specific user name
+### Test all groups for a specific user name
 
     describe etc_group do
       its('users') { should include 'my_user' }
     end
 
-## Filter a list of groups for a specific user
+### Filter a list of groups for a specific user
 
     describe etc_group.where(name: 'my_group') do
       its('users') { should include 'my_user' }

data/docs/resources/etc_hosts.md.erb

@@ -0,0 +1,62 @@
+---
+title: About the etc_hosts Resource
+---
+
+# etc_hosts
+
+Use the `etc_hosts` InSpec audit resource to test rules set to match IP addresses with hostnames.
+## Syntax
+
+An etc/hosts rule specifies an IP address and what its hostname is along with optional aliases it can have.
+
+## Syntax
+
+Use the where clause to match a property to one or more rules in the hosts file.
+
+    describe etc_hosts.where { ip_address == 'value' } do
+      its('primary_name') { should cmp 'hostname' }
+      its('all_host_names') { should cmp 'list' }
+    end
+
+Use the optional constructor parameter to give an alternative path to hosts file
+
+    describe etc_hosts('path/to/hosts').where { ip_address == 'value' } do
+      its('primary_name') { should cmp 'hostname' }
+      its('all_host_names') { should cmp 'list' }
+    end
+
+where
+
+* `ip_address` is the ip address of the hostname in either ipv4 or ipv6 format.
+* `primary_name` is the name associated with the ip address.
+* `all_host_names` is a list including the primary_name as the first entry followed by any aliase names the host has.
+
+## Supported Properties
+
+    'ip_address', 'primary_name', 'all_host_names'
+
+## Property Examples and Return Types
+
+### ip_address
+
+`ip_address` returns a string array of ip addresses specified in the etc/hosts file.
+
+    describe etc_hosts.where { primary_name == 'localhost' } do
+      its('ip_address') { should cmp '127.0.1.154' }
+    end
+
+### primary_name
+
+`primary_name` returns a string array of primary_names specified in the etc/hosts file.
+
+    describe etc_hosts.where { ip_address == '::1' } do
+      its('primary_name') { should cmp 'localhost' }
+    end
+
+### all_host_names
+
+`all_host_names` returns a two dimensional string array where each entry has the primary_name first followed by any aliases.
+
+    describe etc_hosts.where { ip_address == '127.0.1.154' } do
+      its('all_host_names') { should eq [['localhost', 'localhost.localdomain', 'localhost4', 'localhost4.localdomain4'],  ['localhost', 'localhost.localdomain', 'localhost6', 'localhost6.localdomain6']] }
+    end