inspec 1.0.0 → 1.35.1

data/docs/resources/host.md.erb

@@ -6,14 +6,16 @@ title: About the host Resource
 
 Use the `host` InSpec audit resource to test the name used to refer to a specific host and its availability, including the Internet protocols and ports over which that host name should be available.
 
-# Syntax
+## Syntax
 
 A `host` resource block declares a host name, and then (depending on what is to be tested) a port and/or a protocol:
 
 .. code-block:: ruby
 
-   describe host('example.com', port: 80, proto: 'tcp') do
+   describe host('example.com', port: 80, protocol: 'tcp') do
      it { should be_reachable }
+     it { should be_resolvable }
+     its('ipaddress') { should include '12.34.56.78' }
    end
 
 where
@@ -21,65 +23,72 @@ where
 * `host()` must specify a host name and may specify a port number and/or a protocol
 * `'example.com'` is the host name
 * `port:` is the port number
-* `proto: 'name'` is the Internet protocol: TCP (`proto: 'tcp'`), UDP (`proto: 'udp'` or  ICMP (`proto: 'icmp'`))
-* `be_reachable` is a valid matcher for this resource
+* `protocol: 'name'` is the Internet protocol: TCP (`protocol: 'tcp'`), UDP (`protocol: 'udp'` or  ICMP (`protocol: 'icmp'`))
 
 
-# Matchers
+## Matchers
 
 This InSpec audit resource has the following matchers:
 
-## be
+### be
 
 <%= partial "/shared/matcher_be" %>
 
-## be_reachable
+### be_reachable
 
 The `be_reachable` matcher tests if the host name is available:
 
     it { should be_reachable }
 
-## be_resolvable
+### be_resolvable
 
 The `be_resolvable` matcher tests for host name resolution, i.e. "resolvable to an IP address":
 
     it { should be_resolvable }
 
-## cmp
+### cmp
 
 <%= partial "/shared/matcher_cmp" %>
 
-## eq
+### eq
 
 <%= partial "/shared/matcher_eq" %>
 
-## include
+### include
 
 <%= partial "/shared/matcher_include" %>
 
-## ipaddress
+### ipaddress
 
 The `ipaddress` matcher tests if a host name is resolvable to a specific IP address:
 
     its('ipaddress') { should include '93.184.216.34' }
 
-## match
+### match
 
 <%= partial "/shared/matcher_match" %>
 
-# Examples
+## Examples
 
 The following examples show how to use this InSpec audit resource.
 
-## Verify host name is reachable over a specific protocol and port number
+### Verify host name is reachable over a specific protocol and port number
 
-    describe host('example.com', port: 53, proto: 'udp') do
+    describe host('example.com', port: 80, protocol: 'tcp') do
       it { should be_reachable }
     end
 
-## Verify that a specific IP address can be resolved
+### Verify that a specific IP address can be resolved
 
-    describe host('example.com', port: 80, proto: 'tcp') do
+    describe host('example.com') do
       it { should be_resolvable }
       its('ipaddress') { should include '192.168.1.1' }
     end
+
+### Review the connection setup and socket contents when checking reachability
+
+    describe host('example.com', port: 12345, protocol: 'tcp') do
+      it { should be_reachable }
+      its('connection') { should_not match /connection refused/ }
+      its('socket') { should match /STATUS_OK/ }
+    end

data/docs/resources/http.md.erb

@@ -0,0 +1,104 @@
+---
+title: About the http Resource
+---
+
+# http
+
+Use the `http` InSpec audit resource to test an http endpoint.
+
+<p class="warning">Currently, this resource always executes on the host on which <code>inspec exec</code> is run, even if you use the <code>--target</code> option to remotely scan a different host.<br>
+<br>
+This will be corrected in a future version of InSpec. New InSpec releases are posted in the <a href="https://discourse.chef.io/c/chef-release" target="_blank">Release Announcements Category in Discourse</a>.</p>
+
+## Syntax
+
+An `http` resource block declares the configuration settings to be tested:
+
+    describe http('url', auth: {user: 'user', pass: 'test'}, params: {params}, method: 'method', headers: {headers}, data: data, open_timeout: 60, read_timeout: 60, ssl_verify: true) do
+      its('status') { should eq number }
+      its('body') { should eq 'body' }
+      its('headers.name') { should eq 'header' }
+    end
+
+where
+
+* `('url')` is the url to test
+* `auth: { user: 'user', pass: 'test' }` may be specified for basic auth request
+* `{params}` may be specified for http request parameters
+* `'method'` may be specified for http request method (default to 'GET')
+* `{headers}` may be specified for http request headers
+* `data` may be specified for http request body
+* `open_timeout` may be specified for a timeout for opening connections (default to 60)
+* `read_timeout` may be specified for a timeout for reading connections (default to 60)
+* `ssl_verify` may be specified to enable or disable verification of SSL certificates (default to `true`)
+
+## Matchers
+
+This InSpec audit resource has the following matchers:
+
+### be
+
+<%= partial "/shared/matcher_be" %>
+
+### body
+
+The `body` matcher tests body content of http response:
+
+   its('body') { should eq 'hello\n' }
+
+### cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+### eq
+
+<%= partial "/shared/matcher_eq" %>
+
+### headers
+
+The `headers` matcher returns an hash of all http headers:
+
+    its('headers') { should eq {} }
+
+Individual headers can be tested via:
+
+    its('headers.Content-Type') { should cmp 'text/html' }
+
+### include
+
+<%= partial "/shared/matcher_include" %>
+
+### match
+
+<%= partial "/shared/matcher_match" %>
+
+### status
+
+The `status` matcher tests status of the http response:
+
+    its('status') { should eq 200 }
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### 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

data/docs/resources/iis_app.md.erb

@@ -0,0 +1,126 @@
+---
+title: About the iis_app Resource
+---
+
+# iis_app
+
+Use the `iis_app` InSpec audit resource to test the state of IIS on Windows Server 2012 (and later).
+
+## Syntax
+
+An `iis_app` resource block declares details about the named site:
+
+    describe iis_app('application_path', 'site_name') do
+      it { should exist }
+      it { should have_application_pool('application_pool') }
+      it { should have_protocols('protocol') }
+      it { should have_site_name('site') }
+      it { should have_physical_path('physical_path') }
+      it { should have_path('application_path') }
+    end
+
+where
+
+* `'application_path'` is the path to the application, such as `'/myapp'`
+* `'site_name'` is the name of the site, such as `'Default Web Site'`
+* `('application_pool')` is the name of the application pool in which the site's root application is run, such as `'DefaultAppPool'`
+* `('protocols')` is a binding for the site, such as `'http'`. A site may have multiple bindings; therefore, use a `have_protocol` matcher for each site protocol to be tested
+* `('physical_path') is the physical path to the application, such as `'C:\\inetpub\\wwwroot\\myapp'`
+
+For example:
+
+    describe iis_app('/myapp', 'Default Web Site') do
+      it { should exist }
+      it { should have_application_pool('MyAppPool') }
+      it { should have_protocols('http') }
+      it { should have_site_name('Default Web Site') }
+      it { should have_physical_path('C:\\inetpub\\wwwroot\\myapp') }
+      it { should have_path('\\My Application') }
+    end
+
+## Matchers
+
+This InSpec audit resource has the following matchers:
+
+### cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+### eq
+
+<%= partial "/shared/matcher_eq" %>
+
+### exist
+
+The `exist` matcher tests if the site exists:
+
+    it { should exist }
+
+### have\_application\_pool
+
+The `have_application_pool` matcher tests if the named application pool exists for the web application:
+
+    it { should have_application_pool('DefaultAppPool') }
+
+### have_protocol
+
+The `have_protocol` matcher tests if the specified protocol exists for the web application:
+
+    it { should have_protocol('http') }
+
+or:
+
+    it { should have_protocol('https') }
+
+A web application may have multiple bindings; use a `have_protocol` matcher for each unique web application binding to be tested.
+
+##### Protocol Attributes
+
+The `have_protocol` matcher can also test attributes that are defined for a web application enabledProtocols.
+
+    it { should have_protocol('http') }
+
+For example, testing a site that doesn't have https enabled:
+
+    it { should_not have_protocol('https') }
+    it { should have_protocol('http') }
+
+Testing a web application with https enabled and http enabled:
+
+    it { should have_protocol('https') }
+    it { should have_protocol('http') }
+
+### have_physical_path
+
+The `have_physical_path` matcher tests if the named path is defined for the web application:
+
+    it { should have_physical_path('C:\\inetpub\\wwwroot') }
+
+### include
+
+<%= partial "/shared/matcher_include" %>
+
+### match
+
+<%= partial "/shared/matcher_match" %>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test a default IIS web application
+
+    describe iis_app('Default Web Site') do
+      it { should exist }
+      it { should be_running }
+      it { should have_app_pool('DefaultAppPool') }
+      it { should have_binding('http *:80:') }
+      it { should have_path('%SystemDrive%\\inetpub\\wwwroot') }
+    end
+
+### Test if IIS service is running
+
+    describe service('W3SVC') do
+      it { should be_installed }
+      it { should be_running }
+    end

data/docs/resources/iis_site.md.erb

@@ -6,7 +6,7 @@ title: About the iis_site Resource
 
 Use the `iis_site` InSpec audit resource to test the state of IIS on Windows Server 2012 (and later).
 
-# Syntax
+## Syntax
 
 An `iis_site` resource block declares details about the named site:
 
@@ -36,35 +36,35 @@ For example:
       it { should have_path('C:\\inetpub\\wwwroot') }
     end
 
-# Matchers
+## Matchers
 
 This InSpec audit resource has the following matchers:
 
-## be
+### be
 
 <%= partial "/shared/matcher_be" %>
 
-## be_running
+### be_running
 
 The `be_running` matcher tests if the site is running:
 
     it { should be_running }
 
-## cmp
+### cmp
 
 <%= partial "/shared/matcher_cmp" %>
 
-## eq
+### eq
 
 <%= partial "/shared/matcher_eq" %>
 
-## exist
+### exist
 
 The `exist` matcher tests if the site exists:
 
     it { should exist }
 
-## have_app_pool
+### have\_app\_pool
 
 The `have_app_pool` matcher tests if the named application pool exists for the site:
 
@@ -74,7 +74,7 @@ For example, testing if a site's application pool inherits the settings of the p
 
     it { should have_app_pool('/') }
 
-## have_binding
+### have_binding
 
 The `have_binding` matcher tests if the specified binding exists for the site:
 
@@ -86,7 +86,7 @@ or:
 
 A site may have multiple bindings; use a `have_binding` matcher for each unique site binding to be tested.
 
-### Binding Attributes
+##### Binding Attributes
 
 The `have_binding` matcher can also test attributes that are defined for a site binding. For example, the `sslFlags` attribute defines if SSL is enabled, and (when enabled) what level of SSL is applied to the site.
 
@@ -106,35 +106,35 @@ Testing a site with 128-bit SSL enabled:
 
     it { should have_binding('https :443:www.contoso.com sslFlags=Ssl128') }
 
-## have_path
+### have_path
 
 The `have_path` matcher tests if the named path is defined for the site:
 
     it { should have_path('C:\\inetpub\\wwwroot') }
 
-## include
+### include
 
 <%= partial "/shared/matcher_include" %>
 
-## match
+### match
 
 <%= partial "/shared/matcher_match" %>
 
-# Examples
+## Examples
 
 The following examples show how to use this InSpec audit resource.
 
-## Test a default IIS site
+### Test a default IIS site
 
     describe iis_site('Default Web Site') do
       it { should exist }
       it { should be_running }
       it { should have_app_pool('DefaultAppPool') }
       it { should have_binding('http *:80:') }
-      it { should have_path('%SystemDrive%\\inetpub\\wwwroot\\') }
+      it { should have_path('%SystemDrive%\\inetpub\\wwwroot') }
     end
 
-## Test if IIS service is running
+### Test if IIS service is running
 
     describe service('W3SVC') do
       it { should be_installed }

data/docs/resources/inetd_conf.md.erb

@@ -6,7 +6,7 @@ title: About the inetd_conf Resource
 
 Use the `inetd_conf` InSpec audit resource to test if a service is listed in the `inetd.conf` file on Linux and Unix platforms. inetd---the Internet service daemon---listens on dedicated ports, and then loads the appropriate program based on a request. The `inetd.conf` file is typically located at `/etc/inetd.conf` and contains a list of Internet services associated to the ports on which that service will listen. Only enabled services may handle a request; only services that are required by the system should be enabled.`
 
-# Syntax
+## Syntax
 
 An `inetd_conf` resource block declares the list of services that are enabled in the `inetd.conf` file:
 
@@ -21,7 +21,7 @@ where
 * `should eq 'value'` is the value that is expected
 
 
-# Matchers
+## Matchers
 
 This resource matches any service that is listed in the `inetd.conf` file. You may want to ensure that specific services do not listen via `inetd.conf`:
 
@@ -43,31 +43,31 @@ For example:
       its('exec') { should eq nil }
     end
 
-## be
+### be
 
 <%= partial "/shared/matcher_be" %>
 
-## cmp
+### cmp
 
 <%= partial "/shared/matcher_cmp" %>
 
-## eq
+### eq
 
 <%= partial "/shared/matcher_eq" %>
 
-## include
+### include
 
 <%= partial "/shared/matcher_include" %>
 
-## match
+### match
 
 <%= partial "/shared/matcher_match" %>
 
-# Examples
+## Examples
 
 The following examples show how to use this InSpec audit resource.
 
-## Verify that FTP is disabled
+### Verify that FTP is disabled
 
 The contents if the `inetd.conf` file contain the following:
 
@@ -88,7 +88,7 @@ Because both the `ftp` and `telnet` Internet services are commented out (`#`), b
 
 then the same test will return `false` for `ftp` and the entire test will fail.
 
-## Test if telnet is installed
+### Test if telnet is installed
 
     describe package('telnetd') do
       it { should_not be_installed }

data/docs/resources/ini.md.erb

@@ -6,7 +6,7 @@ title: About the ini Resource
 
 Use the `ini` InSpec audit resource to test settings in an INI file.
 
-# Syntax
+## Syntax
 
 An `ini` resource block declares the configuration settings to be tested:
 
@@ -27,35 +27,35 @@ For example:
       its('server') { should eq '192.0.2.62' }
     end
 
-# 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" %>
 
-## include
+### include
 
 <%= partial "/shared/matcher_include" %>
 
-## match
+### match
 
 <%= partial "/shared/matcher_match" %>
 
-# Examples
+## Examples
 
 The following examples show how to use this InSpec audit resource.
 
-## Test SMTP settings in a PHP INI file
+### Test SMTP settings in a PHP INI file
 
 For example, a PHP INI file located at contains the following settings:
 

data/docs/resources/interface.md.erb

@@ -4,63 +4,63 @@ title: About the interface Resource
 
 # interface
 
-Use the `interface` InSpec audit resource to test basic network adapter properties, such as name, status, state, address, and link speed (in MB/sec).
+Use the `interface` InSpec audit resource to test basic network adapter properties, such as name, status, and link speed (in MB/sec).
 
 * On Linux platforms, `/sys/class/net/#{iface}` is used as source
 * On the Windows platform, the `Get-NetAdapter` cmdlet is used as source
 
-# Syntax
+## Syntax
 
 An `interface` resource block declares network interface properties to be tested:
 
-    describe interface do
+    describe interface('eth0') do
       it { should be_up }
       its('speed') { should eq 1000 }
       its('name') { should eq eth0 }
     end
 
-# Matchers
+## Matchers
 
 This InSpec audit resource has the following matchers:
 
-## be
+### be
 
 <%= partial "/shared/matcher_be" %>
 
-## be_up
+### be_up
 
 The `be_up` matcher tests if the network interface is available:
 
     it { should be_up }
 
-## cmp
+### cmp
 
 <%= partial "/shared/matcher_cmp" %>
 
-## eq
+### eq
 
 <%= partial "/shared/matcher_eq" %>
 
-## include
+### include
 
 <%= partial "/shared/matcher_include" %>
 
-## match
+### match
 
 <%= partial "/shared/matcher_match" %>
 
-## name
+### name
 
 The `name` matcher tests if the named network interface exists:
 
     its('name') { should eq eth0 }
 
-## speed
+### speed
 
 The `speed` matcher tests the speed of the network interface, in MB/sec:
 
     its('speed') { should eq 1000 }
 
-# Examples
+## Examples
 
 None.