inspec 1.0.0.beta2 → 1.0.0.beta3

data/docs/resources/sshd_config.md.erb

@@ -0,0 +1,97 @@
+---
+title: About the sshd_config Resource
+---
+
+# sshd_config
+
+Use the `sshd_config` InSpec audit resource to test configuration data for the OpenSSH daemon located at `/etc/ssh/sshd_config` on Linux and Unix platforms. sshd---the OpenSSH daemon---listens on dedicated ports, starts a daemon for each incoming connection, and then handles encryption, authentication, key exchanges, command executation, and data exchanges.
+
+# Syntax
+
+An `sshd_config` resource block declares the client OpenSSH configuration data to be tested:
+
+    describe sshd_config('path') do
+      its('name') { should include('foo') }
+    end
+
+where
+
+* `name` is a configuration setting in `sshd_config`
+* `('path')` is the non-default `/path/to/sshd_config`
+* `{ should include('foo') }` tests the value of `name` as read from `sshd_config` versus the value declared in the test
+
+
+# Matchers
+
+This InSpec audit resource has the following matchers:
+
+## be
+
+<%= partial "/shared/matcher_be" %>
+
+## cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+## eq
+
+<%= partial "/shared/matcher_eq" %>
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+## name
+
+The `name` matcher tests the value of `name` as read from `sshd_config` versus the value declared in the test:
+
+    its('name') { should cmp 'foo' }
+
+or:
+
+    its('name') {should include('bar') }
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test which variables may be sent to the server
+
+    describe sshd_config do
+      its('AcceptEnv') { should include('GORDON_SERVER') }
+    end
+
+## Test for IPv6-only addresses
+
+    describe sshd_config do
+      its('AddressFamily') { should cmp 'inet6' }
+    end
+
+## Test the Protocol setting
+
+    describe sshd_config do
+      its('Protocol') { should cmp 2 }
+    end
+
+## Test for approved, strong ciphers
+
+    describe sshd_config do
+      its('Ciphers') { should cmp('chacha20-poly1305@openssh.com,aes256-ctr,aes192-ctr,aes128-ctr') }
+    end
+
+## Test SSH protocols
+
+    describe sshd_config do
+      its('Port') { should cmp  22 }
+      its('UsePAM') { should eq 'yes' }
+      its('ListenAddress') { should eq nil }
+      its('HostKey') { should eq [
+          '/etc/ssh/ssh_host_rsa_key',
+          '/etc/ssh/ssh_host_dsa_key',
+          '/etc/ssh/ssh_host_ecdsa_key',
+        ] }
+    end

data/docs/resources/ssl.md.erb

@@ -0,0 +1,133 @@
+---
+title: About the ssl Resource
+---
+
+# ssl
+
+Use the `ssl` InSpec audit resource to test SSL settings for the named port.
+
+# Syntax
+
+An `ssl` resource block declares an SSL port, and then other properties of the test like cipher and/or protocol:
+
+    describe ssl(port: #) do
+      it { should be_enabled }
+    end
+
+or:
+
+    describe ssl(port: #).filter('value') do
+      it { should be_enabled }
+    end
+
+where
+
+* `ssl(port: #)` is the port number, such as `ssl(port: 443)`
+* `filter` may take any of the following arguments: `ciphers`, `protocols`, and `handshake`
+
+
+# Matchers
+
+This InSpec audit resource has the following matchers:
+
+## be
+
+<%= partial "/shared/matcher_be" %>
+
+## be_enabled
+
+The `be_enabled` matcher tests if SSL is enabled:
+
+    it { should be_enabled }
+
+## ciphers
+
+The `ciphers` matcher tests the named cipher:
+
+    its('ciphers') { should_not eq '/rc4/i' }
+
+or:
+
+    describe ssl(port: 443).ciphers(/rc4/i) do
+      it { should_not be_enabled }
+    end
+
+## cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+## eq
+
+<%= partial "/shared/matcher_eq" %>
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+## protocols
+
+The `protocols` matcher tests the number of times the named user appears in `/etc/shadow`:
+
+    its('protocols') { should eq 'ssl2' }
+
+or:
+
+    describe ssl(port: 443).protocols('ssl2') do
+      it { should_not be_enabled }
+    end
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Run the ssl-benchmark example profile
+
+The following shows how to use the `ssl` InSpec audit resource to find all TCP ports on the system, including IPv4 and IPv6. (This is a partial example based on the `ssl_text.rb` file in the `ssl-benchmark` profile on GitHub.)
+
+    ...
+
+    control 'tls1.2' do
+      title 'Run TLS 1.2 whenever SSL is active on a port'
+      impact 0.5
+
+      sslports.each do |socket|
+        proc_desc = "on node == #{command('hostname').stdout.strip} running #{socket.process.inspect} (#{socket.pid})"
+        describe ssl(port: socket.port).protocols('tls1.2') do
+          it(proc_desc) { should be_enabled }
+          it { should be_enabled }
+        end
+      end
+    end
+
+    ...
+
+    control 'rc4' do
+      title 'Disable RC4 ciphers from all exposed SSL/TLS ports and versions.'
+      impact 0.5
+
+      sslports.each do |socket|
+        proc_desc = "on node == #{command('hostname').stdout.strip} running #{socket.process.inspect} (#{socket.pid})"
+        describe ssl(port: socket.port).ciphers(/rc4/i) do
+          it(proc_desc) { should_not be_enabled }
+          it { should_not be_enabled }
+        end
+      end
+    end
+
+There are two ways to run the `ssl-benchmark` example profile to test SSL via the `ssl` resource.
+
+Clone the profile:
+
+    $ git clone https://github.com/dev-sec/ssl-benchmark
+
+and then run:
+
+    $ inspec exec ssl-benchmark
+
+Or execute the profile directly via URL:
+
+    $ inspec exec https://github.com/dev-sec/ssl-benchmark

data/docs/resources/sys_info.md.erb

@@ -0,0 +1,55 @@
+---
+title: About the sys_info Resource
+---
+
+# sys_info
+
+Use the `sys_info` InSpec audit resource to test for operating system properties for the named host, and then returns that info as standard output.
+
+# Syntax
+
+An `sys_info` resource block declares the hostname to be tested:
+
+    describe sys_info do
+      its('hostname') { should eq 'value' }
+    end
+
+# Matchers
+
+This InSpec audit resource has the following matchers:
+
+## be
+
+<%= partial "/shared/matcher_be" %>
+
+## cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+## eq
+
+<%= partial "/shared/matcher_eq" %>
+
+## hostname
+
+The `hostname` matcher tests the host for which standard output is returned:
+
+    its('hostname') { should eq 'value' }
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Get system information for example.com
+
+    describe sys_info do
+      its('hostname') { should eq 'example.com' }
+    end

data/docs/resources/systemd_service.md.erb

@@ -0,0 +1,76 @@
+---
+title: About the systemd_service Resource
+---
+
+# systemd_service
+
+Use the `systemd_service` InSpec audit resource to test a service using SystemD.
+
+# Syntax
+
+A `systemd_service` resource block declares the name of a service and then one (or more) matchers to test the state of the service:
+
+    describe systemd_service('service_name') do
+      it { should be_installed }
+      it { should be_enabled }
+      it { should be_running }
+    end
+
+where
+
+* `('service_name')` must specify a service name
+* `be_installed`, `be_enabled`, and `be_running` are valid matchers for this resource; all matchers available to the `service` resource may be used
+
+The path to the service manager's control may be specified for situations where the path isn't available in the current `PATH`. For example:
+
+    describe systemd_service('service_name', '/path/to/control') do
+      it { should be_enabled }
+      it { should be_installed }
+      it { should be_running }
+    end
+
+# Matchers
+
+This InSpec audit resource has the following matchers:
+
+## be
+
+<%= partial "/shared/matcher_be" %>
+
+## be_enabled
+
+The `be_enabled` matcher tests if the named service is enabled:
+
+    it { should be_enabled }
+
+## be_installed
+
+The `be_installed` matcher tests if the named service is installed:
+
+    it { should be_installed }
+
+## be_running
+
+The `be_running` matcher tests if the named service is running:
+
+    it { should be_running }
+
+## cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+## eq
+
+<%= partial "/shared/matcher_eq" %>
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+# Examples
+
+None.

data/docs/resources/sysv_service.md.erb

@@ -0,0 +1,76 @@
+---
+title: About the sysv_service Resource
+---
+
+# sysv_service
+
+Use the `sysv_service` InSpec audit resource to test a service using SystemV.
+
+# Syntax
+
+A `sysv_service` resource block declares the name of a service and then one (or more) matchers to test the state of the service:
+
+    describe sysv_service('service_name') do
+      it { should be_installed }
+      it { should be_enabled }
+      it { should be_running }
+    end
+
+where
+
+* `('service_name')` must specify a service name
+* `be_installed`, `be_enabled`, and `be_running` are valid matchers for this resource; all matchers available to the `service` resource may be used
+
+The path to the service manager's control may be specified for situations where the path isn't available in the current `PATH`. For example:
+
+    describe sysv_service('service_name', '/path/to/control') do
+      it { should be_enabled }
+      it { should be_installed }
+      it { should be_running }
+    end
+
+# Matchers
+
+This InSpec audit resource has the following matchers:
+
+## be
+
+<%= partial "/shared/matcher_be" %>
+
+## be_enabled
+
+The `be_enabled` matcher tests if the named service is enabled:
+
+    it { should be_enabled }
+
+## be_installed
+
+The `be_installed` matcher tests if the named service is installed:
+
+    it { should be_installed }
+
+## be_running
+
+The `be_running` matcher tests if the named service is running:
+
+    it { should be_running }
+
+## cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+## eq
+
+<%= partial "/shared/matcher_eq" %>
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+# Examples
+
+None.

data/docs/resources/upstart_service.md.erb

@@ -0,0 +1,76 @@
+---
+title: About the upstart_service Resource
+---
+
+# upstart_service
+
+Use the `upstart_service` InSpec audit resource to test a service using Upstart.
+
+# Syntax
+
+An `upstart_service` resource block declares the name of a service and then one (or more) matchers to test the state of the service:
+
+    describe upstart_service('service_name') do
+      it { should be_installed }
+      it { should be_enabled }
+      it { should be_running }
+    end
+
+where
+
+* `('service_name')` must specify a service name
+* `be_installed`, `be_enabled`, and `be_running` are valid matchers for this resource; all matchers available to the `service` resource may be used
+
+The path to the service manager's control may be specified for situations where the path isn't available in the current `PATH`. For example:
+
+    describe upstart_service('service_name', '/path/to/control') do
+      it { should be_enabled }
+      it { should be_installed }
+      it { should be_running }
+    end
+
+# Matchers
+
+This InSpec audit resource has the following matchers:
+
+## be
+
+<%= partial "/shared/matcher_be" %>
+
+## be_enabled
+
+The `be_enabled` matcher tests if the named service is enabled:
+
+    it { should be_enabled }
+
+## be_installed
+
+The `be_installed` matcher tests if the named service is installed:
+
+    it { should be_installed }
+
+## be_running
+
+The `be_running` matcher tests if the named service is running:
+
+    it { should be_running }
+
+## cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+## eq
+
+<%= partial "/shared/matcher_eq" %>
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+# Examples
+
+None.