inspec 2.0.17 → 2.0.32

data/docs/resources/dh_params.md.erb

@@ -25,21 +25,9 @@ A `dh_params` resource block declares a parameter file to be tested.
 
 <br>
 
-## Resource Parameter Examples
-
-### dh_params?
-
-Verify whether file contains DH parameters:
-
-    describe dh_params('/path/to/file.dh_pem') do
-      it { should be_dh_params }
-    end
-
-<br>
-
 ## Properties
 
-generator, modulus, prime_length, pem, text
+* `generator`, `modulus`, `prime_length`, `pem`, `text`
 
 <br>
 

data/docs/resources/docker.md.erb

@@ -5,7 +5,7 @@ platform: linux
 
 # 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.
+Use the `docker` InSpec audit resource to test configuration data for the Docker daemon. It is a very comprehensive resource. See also: [docker_container](docker_container) and [docker_image](docker_image), too.
 
 <br>
 
@@ -25,8 +25,8 @@ or:
 
 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`
+* `.where()` may specify a specific item and value, to which the resource parameters are compared
+* `commands`, `ids`, `images`, `labels`, `local_volumes`, `mounts`, `names`, `networks`, `ports`, `sizes`  and `status` are valid parameters for `containers`
 
 The `docker` resource block also declares allows you to write test for many images:
 
@@ -42,8 +42,7 @@ or if you want to query specific images:
 
 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`
+* `.where()` may specify a specific filter and expected value, against which parameters are compared
 
 <br>
 
@@ -69,7 +68,7 @@ The following examples show how to use this InSpec audit resource.
 ### Iterate over all containers to verify host coniguration
 
     docker.containers.ids.each do |id|
-      # call docker inspect for a specific container 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 }
@@ -90,7 +89,9 @@ The following examples show how to use this InSpec audit resource.
       its(%w(Config Healthcheck)) { should_not eq nil }
     end
 
-### Run the DevSec docker baseline  profile
+<br>
+
+## How to run the DevSec Docker baseline profile
 
 There are two ways to run the `docker-baseline` profile to test Docker via the `docker` resource.
 
@@ -108,13 +109,17 @@ Or execute the profile directly via URL:
 
 <br>
 
-## Matchers
+## Resource Parameters
 
-For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+* `commands`, `ids`, `images`, `labels`, `local_volumes`, `mounts`, `names`, `networks`, `ports`, `sizes` and `status` are valid parameters for `containers`
+
+<br>
+
+## Resource Parameter Examples
 
 ### 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
+`containers` returns information about containers as returned by [docker ps -a](https://docs.docker.com/engine/reference/commandline/ps/).
 
     describe docker.containers do
       its('ids') { should include 'sha:71b5df59...442b' }
@@ -124,10 +129,17 @@ For a full list of available matchers, please visit our [matchers page](https://
       its('labels') { should include 'License=GPLv2,Vendor=CentOS' }
     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
 
 ### 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
+`images` returns information about Docker image as returned by [docker images](https://docs.docker.com/engine/reference/commandline/images/).
 
     describe docker.images do
       its('ids') { should include 'sha:12b5df59...442b' }
@@ -136,6 +148,14 @@ For a full list of available matchers, please visit our [matchers page](https://
       its('sizes') { should_not include "1.41 GB" }
     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
+
 ### version
 
 `info` returns the parsed result of [docker version](https://docs.docker.com/engine/reference/commandline/version/)
@@ -145,20 +165,55 @@ For a full list of available matchers, please visit our [matchers page](https://
       its('Client.Version') { should cmp >= '1.12'}
     end
 
+<br>
 
-### info
+## Properties
 
-`info` returns the parsed result of [docker info](https://docs.docker.com/engine/reference/commandline/info/)
+* `id`, `image`, `repo`, `tag`, `ports`, `command`
 
-    describe docker.info do
-      its('Configuration.Path') { should eq 'value' }
+<br>
+
+## Property Examples
+
+### id
+
+    describe docker_container(name: 'an-echo-server') do
+      its('id') { should_not eq '' }
     end
 
+### image
 
-### object('id')
+  describe docker_container(name: 'an-echo-server') do
+    its('image') { should eq 'busybox:latest' }
+  end
 
-`object` returns low-level information about docker objects. It is calling [docker inspect](https://docs.docker.com/engine/reference/commandline/info/) under the hood.
+### repo
 
-    describe docker.object(id) do
-      its('Configuration.Path') { should eq 'value' }
+    describe docker_container(name: 'an-echo-server') do
+      its('repo') { should eq 'busybox' }
+    end
+
+### tag
+
+    describe docker_container(name: 'an-echo-server') do
+      its('tag') { should eq 'latest' }
+    end
+
+### ports
+
+    describe docker_container(name: 'an-echo-server') do
+      its('ports') { should eq "0.0.0.0:1234->1234/tcp" }
+    end
+
+### command
+
+    describe docker_container(name: 'an-echo-server') do
+      its('command') { should eq 'nc -ll -p 1234 -e /bin/cat' }
     end
+
+<br>
+
+## Matchers
+
+For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+

data/docs/resources/host.md.erb

@@ -28,10 +28,24 @@ where
 
 <br>
 
-## Examples
+## Resource Properties
+
+* `connection`, `ipaddress`, `protocol`, `socket`
+
+<br>
+
+## Resource Examples
 
 The following examples show how to use this InSpec audit resource.
 
+### ipaddress
+
+The `ipaddress` matcher tests if a host name is resolvable to a specific IP address:
+
+    describe host('example.com') do
+      its('ipaddress') { should include '93.184.216.34' }
+    end
+
 ### Verify host name is reachable over a specific protocol and port number
 
     describe host('example.com', port: 80, protocol: 'tcp') do
@@ -42,7 +56,7 @@ The following examples show how to use this InSpec audit resource.
 
     describe host('example.com') do
       it { should be_resolvable }
-      its('ipaddress') { should include '192.168.1.1' }
+      its('ipaddress') { should include '93.184.216.34' }
     end
 
 ### Review the connection setup and socket contents when checking reachability
@@ -57,7 +71,7 @@ The following examples show how to use this InSpec audit resource.
 
 ## Matchers
 
-For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/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_reachable
 
@@ -70,9 +84,3 @@ The `be_reachable` matcher tests if the host name is available:
 The `be_resolvable` matcher tests for host name resolution, i.e. "resolvable to an IP address":
 
     it { should be_resolvable }
-
-### ipaddress
-
-The `ipaddress` matcher tests if a host name is resolvable to a specific IP address:
-
-    its('ipaddress') { should include '93.184.216.34' }

data/docs/resources/http.md.erb

@@ -33,6 +33,33 @@ where
 
 <br>
 
+## Example
+
+The following examples show how to use this InSpec audit resource. An `http` resource block declares the configuration settings to be tested:
+
+### Simple http test
+
+For example, a service is listening on default http port can be tested like this:
+
+    describe http('http://localhost') do
+      its('status') { should cmp 200 }
+    end
+
+### Complex http test
+
+    describe http('http://localhost:8080/ping',
+                  auth: {user: 'user', pass: 'test'},
+                  params: {format: 'html'},
+                  method: 'POST',
+                  headers: {'Content-Type' => 'application/json'},
+                  data: '{"data":{"a":"1","b":"five"}}') do
+      its('status') { should cmp 200 }
+      its('body') { should cmp 'pong' }
+      its('headers.Content-Type') { should cmp 'text/html' }
+    end
+
+<br>
+
 ## Local vs. Remote
 
 Beginning with InSpec 1.41, you can enable the ability to have the HTTP test execute on the remote target:
@@ -45,39 +72,102 @@ In InSpec 2.0, the HTTP test will automatically execute remotely whenever InSpec
 
 <br>
 
-## Properties
+## Parameters
 
-body, headers, http_method, status,
+* `url`, `auth`, `params`, `method`, `headers`, `data`, `open_timeout`, `read_timeout`, `ssl_verify`
 
-<br>
+## Parameter Examples
 
-## Property Examples
+### url
 
-The following examples show how to use this InSpec audit resource.
+`('url')` is the url to test.
 
-### Simple http test
+    describe http('http://localhost:8080/ping') do
+      ...
+    end
 
-For example, a service is listening on default http port can be tested like this:
+### auth
 
-    describe http('http://localhost') do
-      its('status') { should cmp 200 }
+`auth: { user: 'user', pass: 'test' }` may be specified for basic auth request.
+
+    describe http('http://localhost:8080/ping',
+                  auth: {user: 'user', pass: 'test'}) do
+      ...
     end
 
-### Complex http test
+### params
+
+`{params}` may be specified for http request parameters.
 
     describe http('http://localhost:8080/ping',
-                  auth: {user: 'user', pass: 'test'},
-                  params: {format: 'html'},
-                  method: 'POST',
-                  headers: {'Content-Type' => 'application/json'},
+                  params: {format: 'html'}) do
+      ...
+    end
+
+### method
+
+`'method'` may be specified for http request method (default to 'GET').
+
+    describe http('http://localhost:8080/ping',
+                  method: 'POST') do
+      ...
+    end
+
+### headers 
+
+`{headers}` may be specified for http request headers.
+
+    describe http('http://localhost:8080/ping',
+                  headers: {'Content-Type' => 'application/json'}) do
+      ...
+    end
+
+### data
+
+`data` may be specified for http request body.
+
+        describe http('http://localhost:8080/ping',
                   data: '{"data":{"a":"1","b":"five"}}') do
-      its('status') { should cmp 200 }
-      its('body') { should cmp 'pong' }
-      its('headers.Content-Type') { should cmp 'text/html' }
+          ...
+        end
+
+### open_timeout
+
+`open_timeout` may be specified for a timeout for opening connections (default to 60).
+
+    describe('http://localhost:8080/ping', 
+                  open_timeout: '90') do
+      ...
+    end
+
+### read_timeout
+
+`read_timeout` may be specified for a timeout for reading connections (default to 60).
+
+    describe('http://localhost:8080/ping', 
+                  read_timeout: '90') do
+      ...
     end
 
+### ssl_verify
+
+`ssl_verify` may be specified to enable or disable verification of SSL certificates (default to `true`).
+
+    describe('http://localhost:8080/ping', 
+                  ssl_verify: 'true') do
+      ...
+    end
+
+<br>
+
+## Properties
+
+* `body`, `headers`, `http_method`, `status`,
+
 <br>
 
+## Property Examples
+
 ### body
 
 The `body` matcher tests body content of http response:
@@ -99,3 +189,9 @@ Individual headers can be tested via:
 The `status` matcher tests status of the http response:
 
     its('status') { should eq 200 }
+
+<br>
+
+## Matchers
+
+For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).

data/docs/resources/json.md.erb

@@ -43,6 +43,12 @@ where
 
 The following examples show how to use this InSpec audit resource.
 
+### name
+
+The `name` matcher tests the value of the filename as read from a JSON file versus the value declared in the test:
+
+    its('name') { should eq '/tmp/example.json' }
+
 ### Test a cookbook version in a policyfile.lock.json file
 
     describe json('policyfile.lock.json') do
@@ -55,8 +61,3 @@ The following examples show how to use this InSpec audit resource.
 
 For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
 
-### name
-
-The `name` matcher tests the value of `name` as read from a JSON file versus the value declared in the test:
-
-    its('name') { should eq 'foo' }

data/docs/resources/kernel_module.md.erb

@@ -18,7 +18,7 @@ method.
 ## Syntax
 
 A `kernel_module` resource block declares a module name, and then tests if that
-module is a loadable kernel module, if it is enabled, disabled or if it is
+module is a loaded kernel module, if it is enabled, disabled or if it is
 blacklisted:
 
     describe kernel_module('module_name') do
@@ -30,7 +30,7 @@ blacklisted:
 where
 
 * `'module_name'` must specify a kernel module, such as `'bridge'`
-* `{ should be_loaded }` tests if the module is a loadable kernel module
+* `{ should be_loaded }` tests if the module is a loaded kernel module
 * `{ should be_blacklisted }` tests if the module is blacklisted or if the module is disabled via a fake install using /bin/false or /bin/true
 * `{ should be_disabled }` tests if the module is disabled via a fake install using /bin/false or /bin/true
 
@@ -40,14 +40,20 @@ where
 
 The following examples show how to use this InSpec audit resource.
 
-### Test a modules 'version'
+### version
+
+The `version` property tests if the kernel module on the system has the correct version:
+
+    its('version') { should eq '3.2.2' }
+
+### Test a kernel module's 'version'
 
       describe kernel_module('bridge') do
         it { should be_loaded }
-        its(:version) { should cmp >= '2.2.2' }
+        its('version') { should cmp >= '2.2.2' }
       end
 
-### Test if a module is loaded, not disabled and not blacklisted
+### Test if a kernel module is loaded, not disabled, and not blacklisted
 
       describe kernel_module('video') do
         it { should be_loaded }
@@ -55,34 +61,34 @@ The following examples show how to use this InSpec audit resource.
         it { should_not be_blacklisted }
       end
 
-### Check if a module is blacklisted
+### Check if a kernel module is blacklisted
 
       describe kernel_module('floppy') do
         it { should be_blacklisted }
       end
 
-### Ensure a module is *not* blacklisted and it is loaded
+### Check if  a kernel module is *not* blacklisted and is loaded
 
       describe kernel_module('video') do
         it { should_not be_blacklisted }
         it { should be_loaded }
       end
 
-### Ensure a module is disabled via 'bin_false'
+### Check if  a kernel module is disabled via 'bin_false'
 
       describe kernel_module('sstfb') do
         it { should_not be_loaded }
         it { should be_disabled }
       end
 
-### Ensure a module is 'blacklisted'/'disabled' via 'bin_true'
+### Check if  a kernel module is 'blacklisted'/'disabled' via 'bin_true'
 
       describe kernel_module('nvidiafb') do
         it { should_not be_loaded }
         it { should be_blacklisted }
       end
 
-### Ensure a module is not loaded
+### Check if  a kernel module is not loaded
 
       describe kernel_module('dhcp') do
         it { should_not be_loaded }
@@ -94,14 +100,21 @@ The following examples show how to use this InSpec audit resource.
 
 For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
 
-### be_loaded
 
-The `be_loaded` matcher tests if the module is a loadable kernel module:
+### be_blacklisted
 
-    it { should be_loaded }
+The `be_blacklisted` matcher tests if the kernel module is a blacklisted module:
 
-### version
+    it { should be_blacklisted }
 
-The `version` matcher tests if the named module version is on the system:
+### be_disabled
 
-    its(:version) { should eq '3.2.2' }
+The `be_disabled` matcher tests if the kernel module is disabled:
+
+    it { should be_disabled }
+
+### be_loaded
+
+The `be_loaded` matcher tests if the kernel module is loaded:
+
+    it { should be_loaded }

data/docs/shell.md

@@ -26,7 +26,7 @@ $ inspec help shell # This will describe inspec shell usage
 
 If you wish to connect to a remote machine (called a target within
 InSpec), you can use the `-t` flag. We support connecting using ssh,
-WinRm and docker. If no target is provided, we implicitly support the
+WinRm and Docker. If no target is provided, we implicitly support the
 "local" target - i.e. tests running on the current machine running
 InSpec. For an ssh connection, use `-i` for specifying ssh key files,
 and the `--sudo*` commands for requesting a privilege escalation after
@@ -37,20 +37,17 @@ path, `--ssl` to use SSL for transport layer encryption.
 $ inspec shell -t ssh://root@192.168.64.2:11022  # Login to remote machine using ssh as root.
 $ inspec shell -t ssh://user@hostname:1234 -i /path/to/user_key  # Login to hostname on port 1234 as user using given ssh key.
 $ inspec shell -t winrm://UserName:Password@windowsmachine:1234  # Login to windowsmachine over WinRM as UserName.
-$ inspec shell -t docker://container_id # Login to a docker container.
+$ inspec shell -t docker://container_id # Login to a Docker container.
 ```
 
-## Resource packs
+## Resource Packs
 
-The InSpec shell may use additional keywords provided in resource packs.
-A resource pack is a profile that defines new language terms that can
-be used in InSpec. For example, the profile in `examples/profile` in
-the InSpec git repo defines a `gordon_config` resource. To use these
-resources with the InSpec shell, you will need to download and specify
-them as a dependency.
+Use resource packs to share custom resources with other InSpec users.
+A resource pack is an InSpec profile that contains only custom resources and no other controls or tests.
 
-To use the `gordon_config` resource that is provided in the `examples/profile`
-in the InSpec repo you can run the following:
+For example, the profile in [`examples/profile`](https://github.com/chef/inspec/tree/master/examples/profile)in the InSpec git repo defines a [`gordon_config` resource](https://github.com/chef/inspec/blob/master/examples/profile/controls/gordon.rb). To use these resources within the InSpec shell, you will need to download and specify them as a dependency.
+
+Once you have local access to the profile, you can use the `gordon_config` custom resource provided in the `examples/profile` GitHub repo in your local environment :
 
 ```bash
 inspec shell --depends examples/profile
@@ -97,12 +94,12 @@ $ inspec shell
 Welcome to the interactive InSpec Shell
 To find out how to use it, type: help
 
-inspec> file('/Users/ksubramanian').directory?
+inspec> file('/Users/myuser').directory?
 => true
 inspec> os_env('HOME')
 => Environment variable HOME
 inspec> os_env('HOME').content
-=> /Users/ksubramanian
+=> /Users/myuser
 inspec> exit
 ```
 
@@ -126,10 +123,10 @@ replaced with the redefinition and the control is re-run.
 ```bash
 inspec> control 'my_control' do
 inspec>   describe os_env('HOME') do
-inspec>     its('content') { should eq '/Users/ksubramanian' }
+inspec>     its('content') { should eq '/Users/myuser' }
 inspec>   end
 inspec> end
-  ✔  my_control: Environment variable HOME content should eq "/Users/ksubramanian"
+  ✔  my_control: Environment variable HOME content should eq "/Users/myuser"
 
   Summary: 1 successful, 0 failures, 0 skipped
 ```
@@ -158,15 +155,61 @@ If you wish to run a single InSpec command and fetch its results, you
 may use the `-c` flag. This is similar to using `bash -c`.
 
 ```bash
-$ inspec shell -c 'describe file("/Users/ksubramanian") do it { should exist } end'}
+$ inspec shell -c 'describe file("/Users/myuser") do it { should exist } end'
 Target:  local://
 
-  ✔  File /Users/ksubramanian should exist
+  ✔  File /Users/myuser should exist
 
 Summary: 1 successful, 0 failures, 0 skipped
 ```
 
 ```bash
-$ inspec shell --format json -c 'describe file("/Users/ksubramanian") do it { should exist } end'
-{"version":"0.30.0","profiles":{"":{"supports":[],"controls":{"(generated from in_memory.rb:1 5aab65c33fb1f133d9244017958eef64)":{"title":null,"desc":null,"impact":0.5,"refs":[],"tags":{},"code":"          rule = rule_class.new(id, profile_id, {}) do\n            res = describe(*args, &block)\n          end\n","source_location":{"ref":"/Users/ksubramanian/repo/chef/inspec/lib/inspec/profile_context.rb","line":184},"results":[{"status":"passed","code_desc":"File /Users/ksubramanian should exist","run_time":0.000747,"start_time":"2016-08-16 11:41:40 -0400"}]}},"groups":{"in_memory.rb":{"title":null,"controls":["(generated from in_memory.rb:1 5aab65c33fb1f133d9244017958eef64)"]}},"attributes":[]}},"other_checks":[],"summary":{"duration":0.001078,"example_count":1,"failure_count":0,"skip_count":0}}}
+$ inspec shell --format json -c 'describe file("/Users/test") do it { should exist } end'
+{
+  "version": "1.49.2",
+  "controls": [{
+    "status": "passed",
+    "code_desc": "File /Users/test should exist",
+    "run_time": 0.002374,
+    "start_time": "2018-01-06 18:32:38 -0500"
+  }],
+  "other_checks": [],
+  "profiles": [{
+    "name": "inspec-shell",
+    "supports": [],
+    "controls": [{
+      "title": null,
+      "desc": null,
+      "impact": 0.5,
+      "refs": [],
+      "tags": {},
+      "code": "",
+      "source_location": {
+        "ref": "/usr/local/lib/ruby/gems/2.4.0/gems/inspec-1.49.2/lib/inspec/control_eval_context.rb",
+        "line": 89
+      },
+      "id": "(generated from (eval):1 7b6f82c2cc5e4205b3e2c97c8e855f2d)",
+      "results": [{
+        "status": "passed",
+        "code_desc": "File /Users/test should exist",
+        "run_time": 0.002374,
+        "start_time": "2018-01-06 18:32:38 -0500"
+      }]
+    }],
+    "groups": [{
+      "title": null,
+      "controls": ["(generated from (eval):1 7b6f82c2cc5e4205b3e2c97c8e855f2d)"],
+      "id": "unknown"
+    }],
+    "attributes": [],
+    "sha256": "29c070a90b7e3521babf618215573284a790d92907783d5b2c138f411bfd2e74"
+  }],
+  "platform": {
+    "name": "mac_os_x",
+    "release": "17.3.0"
+  },
+  "statistics": {
+    "duration": 0.003171
+  }
+}
 ```