inspec-core 2.1.67

data/docs/resources/ssl.md.erb

@@ -0,0 +1,119 @@
+---
+title: About the ssl Resource
+platform: os
+---
+
+# ssl
+
+Use the `ssl` InSpec audit resource to test SSL settings for the named port.
+
+<br>
+
+## 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`
+
+<br>
+
+## 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
+
+<br>
+
+## Matchers
+
+For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### 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
+
+### protocols
+
+The `protocols` matcher tests what protocol versions (SSLv3, TLSv1.1, etc) are enabled:
+
+    its('protocols') { should eq 'ssl2' }
+
+or:
+
+    describe ssl(port: 443).protocols('ssl2') do
+      it { should_not be_enabled }
+    end

data/docs/resources/sys_info.md.erb

@@ -0,0 +1,42 @@
+---
+title: About the sys_info Resource
+platform: os
+---
+
+# 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.
+
+<br>
+
+## Syntax
+
+An `sys_info` resource block declares the hostname to be tested:
+
+    describe sys_info do
+      its('hostname') { should eq 'value' }
+    end
+
+<br>
+
+## 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
+
+<br>
+
+## Matchers
+
+For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### hostname
+
+The `hostname` matcher tests the host for which standard output is returned:
+
+    its('hostname') { should eq 'value' }

data/docs/resources/systemd_service.md.erb

@@ -0,0 +1,57 @@
+---
+title: About the systemd_service Resource
+platform: linux
+---
+
+# systemd_service
+
+Use the `systemd_service` InSpec audit resource to test a service using SystemD.
+
+<br>
+
+## 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
+
+<br>
+
+## Matchers
+
+For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### 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 }

data/docs/resources/sysv_service.md.erb

@@ -0,0 +1,57 @@
+---
+title: About the sysv_service Resource
+platform: linux
+---
+
+# sysv_service
+
+Use the `sysv_service` InSpec audit resource to test a service using SystemV.
+
+<br>
+
+## 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
+
+<br>
+
+## Matchers
+
+For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### 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 }

data/docs/resources/upstart_service.md.erb

@@ -0,0 +1,57 @@
+---
+title: About the upstart_service Resource
+platform: linux
+---
+
+# upstart_service
+
+Use the `upstart_service` InSpec audit resource to test a service using Upstart.
+
+<br>
+
+## 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
+
+<br>
+
+## Matchers
+
+For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### 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 }

data/docs/resources/user.md.erb

@@ -0,0 +1,140 @@
+---
+title: About the user Resource
+platform: os
+---
+
+# user
+
+Use the `user` InSpec audit resource to test user profiles for a single, known/expected local user, including the groups to which that user belongs, the frequency of required password changes, and the directory paths to home and shell.
+
+<br>
+
+## Syntax
+
+A `user` resource block declares a user name, and then one (or more) matchers:
+
+    describe user('root') do
+      it { should exist }
+      its('uid') { should eq 1234 }
+      its('gid') { should eq 1234 }
+      its('group') { should eq 'root' }
+      its('groups') { should eq ['root', 'other']}
+      its('home') { should eq '/root' }
+      its('shell') { should eq '/bin/bash' }
+      its('mindays') { should eq 0 }
+      its('maxdays') { should eq 90 }
+      its('warndays') { should eq 8 }
+    end
+
+where
+
+* `('root')` is the user to be tested
+* `it { should exist }` tests if the user exists
+* `gid`, `group`, `groups`, `home`, `maxdays`, `mindays`, `shell`, `uid`, and `warndays` are valid matchers for this resource
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Verify available users for the MySQL server
+
+    describe user('root') do
+      it { should exist }
+      its('uid') { should eq 0 }
+      its('groups') { should eq ['root'] }
+    end
+
+    describe user('mysql') do
+     it { should_not exist }
+    end
+
+### Test users on multiple platforms
+
+The `nginx` user is typically `www-data`, but on CentOS it's `nginx`. The following example shows how to test for the `nginx` user with a single test, but accounting for all platforms:
+
+    web_user = 'www-data'
+    web_user = 'nginx' if os[:family] == 'centos'
+
+    describe user(web_user) do
+      it { should exist }
+    end
+
+<br>
+
+## Matchers
+
+For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### exist
+
+The `exist` matcher tests if the named user exists:
+
+    it { should exist }
+
+### gid
+
+The `gid` matcher tests the group identifier:
+
+    its('gid') { should eq 1234 }
+
+where `1234` represents the user identifier.
+
+### group
+
+The `group` matcher tests the group to which the user belongs:
+
+    its('group') { should eq 'root' }
+
+where `root` represents the group.
+
+### groups
+
+The `groups` matcher tests two (or more) groups to which the user belongs:
+
+    its('groups') { should eq ['root', 'other'] }
+
+### home
+
+The `home` matcher tests the home directory path for the user:
+
+    its('home') { should eq '/root' }
+
+### maxdays
+
+The `maxdays` matcher tests the maximum number of days between password changes:
+
+    its('maxdays') { should eq 99 }
+
+where `99` represents the maximum number of days.
+
+### mindays
+
+The `mindays` matcher tests the minimum number of days between password changes:
+
+    its('mindays') { should eq 0 }
+
+where `0` represents the maximum number of days.
+
+### shell
+
+The `shell` matcher tests the path to the default shell for the user:
+
+    its('shell') { should eq '/bin/bash' }
+
+### uid
+
+The `uid` matcher tests the user identifier:
+
+    its('uid') { should eq 1234 }
+
+where `1234` represents the user identifier.
+
+### warndays
+
+The `warndays` matcher tests the number of days a user is warned before a password must be changed:
+
+    its('warndays') { should eq 5 }
+
+where `5` represents the number of days a user is warned.