inspec 1.0.0.beta2 → 1.0.0.beta3

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

data/docs/resources/process.md.erb

@@ -0,0 +1,73 @@
+---
+title: About the processes Resource
+---
+
+# processes
+
+Use the `processes` InSpec audit resource to test properties for programs that are running on the system.
+
+# Syntax
+
+A `processes` resource block declares the name of the process to be tested, and then declares one (or more) property/value pairs:
+
+    describe processes('process_name') do
+      its('property_name') { should eq ['property_value'] }
+    end
+
+where
+
+* `processes('process_name')` must specify the name of a process that is running on the system
+* `property_name` may be used to test user (`its('users')`) and state properties (`its('states')`)
+
+
+# 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" %>
+
+## property_name
+
+The `property_name` matcher tests the named property for the specified value:
+
+    its('property_name') { should eq ['property_value'] }
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test if the list length for the mysqld process is 1
+
+    describe processes('mysqld') do
+      its('list.length') { should eq 1 }
+    end
+
+## Test if the init process is owned by the root user
+
+    describe processes('init') do
+      its('users') { should eq ['root'] }
+    end
+
+## Test if a high-priority process is running
+
+    describe processes('some_process') do
+      its('states') { should eq ['R<'] }
+    end