inspec 0.34.1 → 1.0.0

data/docs/resources/apt.md.erb

@@ -0,0 +1,84 @@
+---
+title: About the apt Resource
+---
+
+# apt
+
+Use the `apt` InSpec audit resource to verify Apt repositories on the Debian and Ubuntu platforms, and also PPA repositories on the Ubuntu platform.
+
+# Syntax
+
+An `apt` resource block tests the contents of Apt and PPA repositories:
+
+    describe apt('path') do
+      it { should exist }
+      it { should be_enabled }
+    end
+
+where
+
+* `apt('path')` must specify an Apt or PPA repository
+* `('path')` may be an `http://` address, a `ppa:` address, or a short `repo-name/ppa` address
+* `exist` and `be_enabled` are a valid matchers for this resource
+
+
+# Matchers
+
+This InSpec audit resource has the following matchers:
+
+## be
+
+<%= partial "/shared/matcher_be" %>
+
+## be_enabled
+
+The `be_enabled` matcher tests if a package exists in the repository:
+
+    it { should be_enabled }
+
+## cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+## eq
+
+<%= partial "/shared/matcher_eq" %>
+
+## exist
+
+The `exist` matcher tests if a package exists on the system:
+
+    it { should exist }
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test if apt repository exists and is enabled
+
+    describe apt('http://ppa.launchpad.net/juju/stable/ubuntu') do
+      it { should exist }
+      it { should be_enabled }
+    end
+
+## Verify that a PPA repository exists and is enabled
+
+    describe apt('ppa:nginx/stable') do
+      it { should exist }
+      it { should be_enabled }
+    end
+
+## Verify that a repository is not present
+
+    describe apt('ubuntu-wine/ppa') do
+      it { should_not exist }
+      it { should_not be_enabled }
+    end

data/docs/resources/audit_policy.md.erb

@@ -0,0 +1,61 @@
+---
+title: About the audit_policy Resource
+---
+
+# audit_policy
+
+Use the `audit_policy` Inspec audit resource to test auditing policies on the Windows platform. An auditing policy is a category of security-related events to be audited. Auditing is disabled by default and may be enabled for categories like account management, logon events, policy changes, process tracking, privilege use, system events, or object access. For each auditing category property that is enabled, the auditing level may be set to `No Auditing`, `Not Specified`, `Success`, `Success and Failure`, or `Failure`.
+
+# Syntax
+
+An `audit_policy` resource block declares a parameter that belongs to an audit policy category or subcategory:
+
+    describe audit_policy do
+      its('parameter') { should eq 'value' }
+    end
+
+where
+
+* `'parameter'` must specify a parameter
+* `'value'` must be one of `No Auditing`, `Not Specified`, `Success`, `Success and Failure`, or `Failure`
+
+
+# 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" %>
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test that a parameter is not set to "No Auditing"
+
+    describe audit_policy do
+      its('Other Account Logon Events') { should_not eq 'No Auditing' }
+    end
+
+## Test that a parameter is set to "Success"
+
+    describe audit_policy do
+      its('User Account Management') { should eq 'Success' }
+    end

data/docs/resources/auditd_conf.md.erb

@@ -0,0 +1,79 @@
+---
+title: About the auditd_conf Resource
+---
+
+# auditd_conf
+
+Use the `auditd_conf` InSpec audit resource to test the configuration settings for the audit daemon. This file is typically located under `/etc/audit/auditd.conf'` on Unix and Linux platforms.
+
+# Syntax
+
+A `auditd_conf` resource block declares configuration settings that should be tested:
+
+    describe auditd_conf('path') do
+      its('keyword') { should cmp 'value' }
+    end
+
+where
+
+* `'keyword'` is a configuration setting defined in the `auditd.conf` configuration file
+* `('path')` is the non-default path to the `auditd.conf` configuration file
+* `{ should cmp '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" %>
+
+## keyword
+
+This matcher will matche any keyword that is listed in the `auditd.conf` configuration file. Option names and values are case-insensitive:
+
+    its('log_format') { should cmp 'raw' }
+
+or:
+
+    its('max_log_file') { should cmp 6 }
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test the auditd.conf file
+
+    describe auditd_conf do
+      its('log_file') { should cmp '/full/path/to/file' }
+      its('log_format') { should cmp 'raw' }
+      its('flush') { should cmp 'none' }
+      its('freq') { should cmp 1 }
+      its('num_logs') { should cmp 0 }
+      its('max_log_file') { should cmp 6 }
+      its('max_log_file_action') { should cmp 'email' }
+      its('space_left') { should cmp 2 }
+      its('action_mail_acct') { should cmp 'root' }
+      its('space_left_action') { should cmp 'email' }
+      its('admin_space_left') { should cmp 1 }
+      its('admin_space_left_action') { should cmp 'halt' }
+      its('disk_full_action') { should cmp 'halt' }
+      its('disk_error_action') { should cmp 'halt' }
+    end

data/docs/resources/auditd_rules.md.erb

@@ -0,0 +1,132 @@
+---
+title: About the auditd_rules Resource
+---
+
+# auditd_rules
+
+Use the `auditd_rules` InSpec audit resource to test the rules for logging that exist on the system. The `audit.rules` file is typically located under `/etc/audit/` and contains the list of rules that define what is captured in log files. This resource uses `auditctl` to query the run-time `auditd` rules setup, which may be different from `audit.rules`.
+
+
+# Syntax
+
+An `auditd_rules` resource block declares one (or more) rules to be tested, and then what that rule should do. The syntax depends on the version of `audit`:
+
+For `audit` >= 2.3:
+
+    describe auditd_rules do
+      its('lines') { should contain_match(rule) }
+    end
+
+For `audit` < 2.3:
+
+    describe audit_daemon_rules do
+      its("LIST_RULES") {
+        rule
+      }
+    end
+
+For example:
+
+    describe auditd_rules do
+      its('LIST_RULES') { should eq [
+        'exit,always syscall=rmdir,unlink',
+        'exit,always auid=1001 (0x3e9) syscall=open',
+        'exit,always watch=/etc/group perm=wa',
+        'exit,always watch=/etc/passwd perm=wa',
+        'exit,always watch=/etc/shadow perm=wa',
+        'exit,always watch=/etc/sudoers perm=wa',
+        'exit,always watch=/etc/secret_directory perm=r',
+      ] }
+    end
+
+or test that individual rules are defined:
+
+    describe auditd_rules do
+      its('LIST_RULES') {
+        should contain_match(/^exit,always watch=\/etc\/group perm=wa key=identity/)
+      }
+      its('LIST_RULES') {
+        should contain_match(/^exit,always watch=\/etc\/passwd perm=wa key=identity/)
+      }
+      its('LIST_RULES') {
+        should contain_match(/^exit,always watch=\/etc\/gshadow perm=wa key=identity/)
+      }
+      its('LIST_RULES') {
+        should contain_match(/^exit,always watch=\/etc\/shadow perm=wa key=identity/)
+      }
+      its('LIST_RULES') {
+        should contain_match(/^exit,always watch=\/etc\/security\/opasswd perm=wa key=identity/)
+      }
+    end
+
+where each test must declare one (or more) rules to be tested.
+
+
+# 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" %>
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test if a rule contains a matching element that is identified by a regular expression
+
+For `audit` >= 2.3:
+
+    describe auditd_rules do
+      its('lines') { should contain_match(%r{-w /etc/ssh/sshd_config/}) }
+    end
+
+For `audit` < 2.3:
+
+    describe audit_daemon_rules do
+      its("LIST_RULES") {
+        should contain_match(/^exit,always arch=.*\
+        key=time-change\
+        syscall=adjtimex,settimeofday/)
+      }
+    end
+
+
+## Query the audit daemon status
+
+    describe auditd_rules.status('backlog') do
+      it { should cmp 0 }
+    end
+
+## Query properties of rules targeting specific syscalls or files
+
+    describe auditd_rules.syscall('open').action do
+      it { should eq(['always']) }
+    end
+
+    describe auditd_rules.key('sshd_config') do
+      its('permissions') { should contain_match(/x/) }
+    end
+
+Filters may be chained. For example:
+
+    describe auditd_rules.syscall('open').action('always').list do
+      it { should eq(['exit']) }
+    end

data/docs/resources/bash.md.erb

@@ -0,0 +1,84 @@
+---
+title: About the bash Resource
+---
+
+# bash
+
+Use the `bash` InSpec audit resource to test an arbitrary command that is run on the system using a Bash script.
+
+# Syntax
+
+A `command` resource block declares a command to be run, one (or more) expected outputs, and the location to which that output is sent:
+
+    describe bash('command') do
+      it { should exist }
+      its('matcher') { should eq 'output' }
+    end
+
+where
+
+* `'command'` must specify a command 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
+
+For example:
+
+    describe bash('ls -al /') do
+      its('stdout') { should match /bin/ }
+      its('stderr') { should eq '' }
+      its('exit_status') { should eq 0 }
+    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" %>
+
+## exist
+
+The `exist` matcher tests if a command may be run on the system:
+
+    it { should exist }
+
+## exit_status
+
+The `exit_status` matcher tests the exit status for the command:
+
+    its('exit_status') { should eq 0 }
+
+## 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 '' }
+
+## stdout
+
+The `stdout` matcher tests results of the command as returned in standard output (stdout).
+
+    its('stdout') { should match /bin/ }
+
+
+# Examples
+
+None.

data/docs/resources/bond.md.erb

@@ -0,0 +1,97 @@
+---
+title: About the bond Resource
+---
+
+# bond
+
+Use the `bond` InSpec audit resource to test a logical, bonded network interface (i.e. "two or more network interfaces aggregated into a single, logical network interface"). On Linux platforms, any value in the `/proc/net/bonding` directory may be tested.
+
+# Syntax
+
+A `bond` resource block declares a bonded network interface, and then specifies the properties of that bonded network interface to be tested:
+
+    describe bond('name') do
+      it { should exist }
+    end
+
+where
+
+* `'name'` is the name of the bonded network interface
+* `{ should exist }` is a valid matcher for this resource
+
+
+# Matchers
+
+This InSpec audit resource has the following matchers:
+
+## be
+
+<%= partial "/shared/matcher_be" %>
+
+## cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+## content
+
+The `content` matcher tests if contents in the file that defines the bonded network interface match the value specified in the test. The values of the `content` matcher are arbitrary:
+
+    its('content') { should match('value') }
+
+## eq
+
+<%= partial "/shared/matcher_eq" %>
+
+## exist
+
+The `exist` matcher tests if the bonded network interface is available:
+
+    it { should exist }
+
+## have_interface
+
+The `have_interface` matcher tests if the bonded network interface has one (or more) secondary interfaces:
+
+    it { should have_interface }
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## interfaces
+
+The `interfaces` matcher tests if the named secondary interfaces are available:
+
+    its('interfaces') { should eq ['eth0', 'eth1', ...] }
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+## params
+
+The `params` matcher tests arbitrary parameters for the bonded network interface:
+
+    its('params') { should eq 'value' }
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test if eth0 is a secondary interface for bond0
+
+    describe bond('bond0') do
+      it { should exist }
+      it { should have_interface 'eth0' }
+    end
+
+## Test parameters for bond0
+
+    describe bond('bond0') do
+      its('Bonding Mode') { should eq 'IEEE 802.3ad Dynamic link aggregation' }
+      its('Transmit Hash Policy') { should eq 'layer3+4 (1)' }
+      its('MII Status') { should eq 'up' }
+      its('MII Polling Interval (ms)') { should eq '100' }
+      its('Up Delay (ms)') { should eq '0' }
+      its('Down Delay (ms)') { should eq '0' }
+    end

data/docs/resources/bridge.md.erb

@@ -0,0 +1,67 @@
+---
+title: About the bridge Resource
+---
+
+# bridge
+
+Use the `bridge` InSpec audit resource to test basic network bridge properties, such as name, if an interface is defined, and the associations for any defined interface.
+
+* On Linux platforms, any value in the `/sys/class/net/{interface}/bridge` directory may be tested
+* On the Windows platform, the `Get-NetAdapter` cmdlet is associated with the `Get-NetAdapterBinding` cmdlet and returns the `ComponentID ms_bridge` value as a JSON object
+
+# Syntax
+
+A `bridge` resource block declares the bridge to be tested and what interface it should be associated with:
+
+    describe bridge('br0') do
+      it { should exist }
+      it { should have_interface 'eth0' }
+    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" %>
+
+## exist
+
+The `exist` matcher tests if the network bridge is available:
+
+    it { should exist }
+
+## have_interface
+
+The `have_interface` matcher tests if the named interface is defined for the network bridge:
+
+    it { should have_interface 'eth0' }
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## interfaces
+
+The `interfaces` matcher tests if the named interface is present:
+
+    its('interfaces') { should eq 'foo' }
+    its('interfaces') { should eq 'bar' }
+    its('interfaces') { should include('foo') }
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+# Examples
+
+None.

data/docs/resources/bsd_service.md.erb

@@ -0,0 +1,76 @@
+---
+title: About the bsd_service Resource
+---
+
+# bsd_service
+
+Use the `bsd_service` InSpec audit resource to test a service using a Berkeley OS-style `init` on the FreeBSD platform.
+
+# Syntax
+
+A `bsd_service` resource block declares the name of a service and then one (or more) matchers to test the state of the service:
+
+    describe bsd_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 bsd_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.