inspec 0.34.1 → 1.0.0

data/docs/resources/parse_config_file.md.erb

@@ -0,0 +1,143 @@
+---
+title: About the parse_config_file Resource
+---
+
+# parse_config_file
+
+Use the `parse_config_file` InSpec audit resource to test arbitrary configuration files. It works in the same way as `parse_config`. Instead of using a command output, this resource works with files.
+
+# Syntax
+
+A `parse_config_file` InSpec audit resource block declares the location of the configuration file to be tested, and then which settings in that file are to be tested.
+
+    describe parse_config_file('/path/to/file', { data_config_option: value } ) do
+      its('setting') { should eq 1 }
+    end
+
+or:
+
+    options = {
+      assignment_re: /^\s*([^:]*?)\s*:\s*(.*?)\s*$/,
+      multiple_values: true
+    }
+
+    describe parse_config_file('path/to/file', options) do
+      its('setting') { should eq 1 }
+    end
+
+where each test
+
+* Must declare the location of the configuration file to be tested
+* Must declare one (or more) settings to be tested
+* May run a command to `stdout`, and then run the test against that output
+* May use options to define how configuration data is to be parsed
+
+# Options
+
+This resource supports the following options for parsing configuration data. Use them in an `options` block stated outside of (and immediately before) the actual test:
+
+    options = {
+        assignment_re: /^\s*([^:]*?)\s*:\s*(.*?)\s*$/,
+        multiple_values: true
+      }
+    describe parse_config_file('path/to/file',  options) do
+      its('setting') { should eq 1 }
+    end
+
+# Matchers
+
+This InSpec audit resource has the following matchers:
+
+## assignment_re
+
+Use `assignment_re` to test a key value using a regular expression:
+
+    'key = value'
+
+may be tested using the following regular expression, which determines assignment from key to value:
+
+    assignment_re: /^\s*([^=]*?)\s*=\s*(.*?)\s*$/
+
+## be
+
+<%= partial "/shared/matcher_be" %>
+
+## cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+## comment_char
+
+Use `comment_char` to test for comments in a configuration file:
+
+    comment_char: '#'
+
+## eq
+
+<%= partial "/shared/matcher_eq" %>
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## key_vals
+
+Use `key_vals` to test how many values a key contains:
+
+    key = a b c
+
+contains three values. To test that value to ensure it only contains one, use:
+
+    key_vals: 1
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+## multiple_values
+
+Use `multiple_values` if the source file uses the same key multiple times. All values will be aggregated in an array:
+
+    # # file structure:
+    # key = a
+    # key = b
+    # key2 = c
+    params['key'] = ['a', 'b']
+    params['key2'] = ['c']
+
+To use plain key value mapping, use `multiple_values: false`:
+
+    # # file structure:
+    # key = a
+    # key = b
+    # key2 = c
+    params['key'] = 'b'
+    params['key2'] = 'c'
+
+## standalone_comments
+
+Use `standalone_comments` to parse comments as a line, otherwise inline comments are allowed:
+
+    'key = value # comment'
+    params['key'] = 'value # comment'
+
+Use `standalone_comments: false`, to parse the following:
+
+    'key = value # comment'
+    params['key'] = 'value'
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test a configuration setting
+
+    describe parse_config_file('/path/to/file.conf') do
+     its('PARAM_X') { should eq 'Y' }
+    end
+
+## Use options, and then test a configuration setting
+
+    describe parse_config_file('/path/to/file.conf', { multiple_values: true }) do
+     its('PARAM_X') { should include 'Y' }
+    end

data/docs/resources/pip.md.erb

@@ -0,0 +1,74 @@
+---
+title: About the pip Resource
+---
+
+# pip
+
+Use the `pip` InSpec audit resource to test packages that are installed using the Python PIP installer.
+
+# Syntax
+
+A `pip` resource block declares a package and (optionally) a package version:
+
+    describe pip('Jinja2') do
+      it { should be_installed }
+    end
+
+where
+
+* `'Jinja2'` is the name of the package
+* `be_installed` tests to see if the `Jinja2` package is installed
+
+
+# Matchers
+
+This InSpec audit resource has the following matchers:
+
+## be
+
+<%= partial "/shared/matcher_be" %>
+
+## be_installed
+
+The `be_installed` matcher tests if the named package is installed on the system:
+
+    it { should be_installed }
+
+## cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+## eq
+
+<%= partial "/shared/matcher_eq" %>
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+## version
+
+The `version` matcher tests if the named package version is on the system:
+
+    its('version') { should eq '1.2.3' }
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test if Jinja2 is installed on the system
+
+    describe pip('Jinja2') do
+      it { should be_installed }
+    end
+
+## Test if Jinja2 2.8 is installed on the system
+
+    describe pip('Jinja2') do
+      it { should be_installed }
+      its('version') { should eq '2.8' }
+    end

data/docs/resources/port.md.erb

@@ -0,0 +1,150 @@
+---
+title: About the port Resource
+---
+
+# port
+
+Use the `port` InSpec audit resource to test basic port properties, such as port, process, if it's listening.
+
+# Syntax
+
+A `port` resource block declares a port, and then depending on what needs to be tested, a process, protocol, process identifier, and its state (is it listening?):
+
+    describe port(514) do
+      it { should be_listening }
+      its('processes') {should include 'syslog'}
+    end
+
+where the `processes` returns the processes listening on port 514.
+
+A filter may specify an attribute:
+
+    describe port.where { protocol =~ /tcp/ && port > 22 && port < 80 } do
+      it { should_not be_listening }
+    end
+
+where
+
+* `.where{}` specifies a block in which one (or more) attributes---`port`, `address`, `protocol`, `process`, `pid`, or `listening?`----scope the test to ports that match those attributes
+
+For example, to test if the SSH daemon is available on a Linux machine via the default port (22):
+
+    describe port(22) do
+      its('processes') { should include 'sshd' }
+      its('protocols') { should include 'tcp' }
+      its('addresses') { should include '0.0.0.0' }
+    end
+
+# Matchers
+
+This InSpec audit resource has the following matchers:
+
+## address
+
+The `addresses` matcher tests if the specified address is associated with a port:
+
+    its('addresses') { should include '0.0.0.0' }
+
+## be
+
+<%= partial "/shared/matcher_be" %>
+
+## be_listening
+
+The `be_listening` matcher tests if the port is listening for traffic:
+
+    it { should be_listening }
+
+## cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+## eq
+
+<%= partial "/shared/matcher_eq" %>
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+## pids
+
+The `pids` matcher tests the process identifiers (PIDs):
+
+    its('pids') { should eq ['27808'] }
+
+## processes
+
+The `processes` matcher tests if the named process is running on the system:
+
+    its('processes') { should eq ['syslog'] }
+
+## protocols
+
+The `protocols` matcher tests the Internet protocol: ICMP (`'icmp'`), TCP (`'tcp'` or `'tcp6'`), or UDP (`'udp'` or `'udp6'`):
+
+    its('protocols') { should include 'tcp' }
+
+or for the IPv6 protocol:
+
+    its('protocols') { should include 'tcp6' }
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test port 80, listening with the TCP protocol
+
+    describe port(80) do
+      it { should be_listening }
+      its('protocols') {should eq ['tcp']}
+    end
+
+## Test port 80, on a specific address
+
+A specific port address may be checked using either of the following examples:
+
+    describe port(80) do
+      it { should be_listening }
+      its('addresses') {should include '0.0.0.0'}
+    end
+
+or:
+
+    describe port('0.0.0.0', 80) do
+      it { should be_listening }
+    end
+
+## Test port 80, listening with TCP version IPv6 protocol
+
+    describe port(80) do
+      it { should be_listening }
+      its('protocols') {should eq ['tcp6']}
+    end
+
+## Test that only secure ports accept requests
+
+    describe port(80) do
+      it { should_not be_listening }
+    end
+
+    describe port(443) do
+      it { should be_listening }
+      its('protocols') {should eq ['tcp']}
+    end
+
+## Verify port 65432 is not listening
+
+    describe port(22) do
+      it { should be_listening }
+      its('protocols') { should include('tcp') }
+      its('protocols') { should_not include('udp') }
+    end
+
+    describe port(65432) do
+      it { should_not be_listening }
+    end

data/docs/resources/postgres_conf.md.erb

@@ -0,0 +1,90 @@
+---
+title: About the postgres_conf Resource
+---
+
+# postgres_conf
+
+Use the `postgres_conf` InSpec audit resource to test the contents of the configuration file for PostgreSQL, typically located at `/etc/postgresql/<version>/main/postgresql.conf` or `/var/lib/postgres/data/postgresql.conf`, depending on the platform.
+
+# Syntax
+
+A `postgres_conf` resource block declares one (or more) settings in the `postgresql.conf` file, and then compares the setting in the configuration file to the value stated in the test:
+
+    describe postgres_conf('path') do
+      its('setting') { should eq 'value' }
+    end
+
+where
+
+* `'setting'` specifies a setting in the `postgresql.conf` file
+* `('path')` is the non-default path to the `postgresql.conf` file (optional)
+* `should eq 'value'` is the value that is expected
+
+# 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" %>
+
+## setting
+
+The `setting` matcher tests specific, named settings in the `postgresql.conf` file:
+
+    its('setting') { should eq 'value' }
+
+Use a `setting` matcher for each setting to be tested.
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test the maximum number of allowed client connections
+
+    describe postgres_conf do
+      its('max_connections') { should eq '5' }
+    end
+
+## Test system logging
+
+    describe postgres_conf do
+      its('logging_collector') { should eq 'on' }
+      its('log_connections') { should eq 'on' }
+      its('log_disconnections') { should eq 'on' }
+      its('log_duration') { should eq 'on' }
+      its('log_hostname') { should eq 'on' }
+      its('log_line_prefix') { should eq '%t %u %d %h' }
+    end
+
+## Test the port on which PostgreSQL listens
+
+    describe postgres_conf do
+      its('port') { should eq '5432' }
+    end
+
+## Test the Unix socket settings
+
+    describe postgres_conf do
+      its('unix_socket_directories') { should eq '.s.PGSQL.5432' }
+      its('unix_socket_group') { should eq nil }
+      its('unix_socket_permissions') { should eq '0770' }
+    end
+
+where `unix_socket_group` is set to the PostgreSQL default setting (the group to which the server user belongs).

data/docs/resources/postgres_session.md.erb

@@ -0,0 +1,75 @@
+---
+title: About the postgres_session Resource
+---
+
+# postgres_session
+
+Use the `postgres_session` InSpec audit resource to test SQL commands run against a PostgreSQL database.
+
+# Syntax
+
+A `postgres_session` resource block declares the username and password to use for the session, and then the command to be run:
+
+    sql = postgres_session('username', 'password')
+
+    describe sql.query('SELECT * FROM pg_shadow WHERE passwd IS NULL;') do
+      its('output') { should eq('') }
+    end
+
+where
+
+* `sql = postgres_session` declares a username and password with permission to run the query
+* `sql.query('')` contains the query to be run
+* `its('output') { should eq('') }` compares the results of the query against the expected result 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" %>
+
+## output
+
+The `output` matcher tests the results of the query:
+
+    its('output') { should eq(/^0/) }
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test the PostgreSQL shadow password
+
+    sql = postgres_session('my_user', 'password')
+
+    describe sql.query('SELECT * FROM pg_shadow WHERE passwd IS NULL;') do
+      its('output') { should eq('') }
+    end
+
+## Test for risky database entries
+
+    describe postgres_session('my_user', 'password').query('SELECT count (*)
+                  FROM pg_language
+                  WHERE lanpltrusted = \'f\'
+                  AND lanname!=\'internal\'
+                  AND lanname!=\'c\';') do
+      its('output') { should eq '0' }
+    end

data/docs/resources/powershell.md.erb

@@ -0,0 +1,116 @@
+---
+title: About the powershell Resource
+---
+
+# powershell
+
+Use the `powershell` InSpec audit resource to test a Powershell script on the Windows platform.
+
+# Syntax
+
+A `powershell` resource block declares a Powershell script to be tested, and then compares the output of that command to the matcher in the test:
+
+    script = <<-EOH
+      # a PowerShell script
+    EOH
+
+    describe script(script) do
+      its('matcher') { should eq 'output' }
+    end
+
+where
+
+* `'script'` must specify a Powershell script to be run
+* `'matcher'` is one of `exit_status`, `stderr`, or `stdout`
+* `'output'` tests the output of the command run on the system versus the output value stated 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" %>
+
+## exit_status
+
+The `exit_status` matcher tests the exit status for the command:
+
+    its('exit_status') { should eq 123 }
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+## stderr
+
+The `stderr` matcher tests results of the command as returned in standard error (stderr):
+
+    its('stderr') { should eq 'error' }
+
+## stdout
+
+The `stdout` matcher tests results of the command as returned in standard output (stdout):
+
+    its('stdout') { should eq '/^1$/' }
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Get all groups of Administrator user
+
+    script = <<-EOH
+      # find user
+      $user = Get-WmiObject Win32_UserAccount -filter "Name = 'Administrator'"
+      # get related groups
+      $groups = $user.GetRelated('Win32_Group') | Select-Object -Property Caption, Domain, Name, LocalAccount, SID, SIDType, Status
+      $groups | ConvertTo-Json
+    EOH
+
+    describe powershell(script) do
+      its('stdout') { should_not eq '' }
+    end
+
+## Write-Output 'hello'
+
+The following Powershell script:
+
+    script = <<-EOH
+      Write-Output 'hello'
+    EOH
+
+can be tested in the following ways.
+
+For a newline:
+
+    describe powershell(script) do
+      its('stdout') { should eq "hello\r\n" }
+      its('stderr') { should eq '' }
+    end
+
+Removing whitespace `\r\n` from `stdout`:
+
+    describe powershell(script) do
+      its('strip') { should eq "hello" }
+    end
+
+No newline:
+
+    describe powershell("'hello' | Write-Host -NoNewLine") do
+      its('stdout') { should eq 'hello' }
+      its('stderr') { should eq '' }
+    end