add all partials for resources

This commit is contained in:
Dominik Richter 2016-09-22 14:43:57 +02:00
parent 7d363338b8
commit 67c990d19c
72 changed files with 6741 additions and 0 deletions

View file

@ -0,0 +1,75 @@
---
title: About the apache_conf Resource
---
# apache_conf
Use the `apache_conf` InSpec audit resource to test the configuration settings for Apache. This file is typically located under `/etc/apache2` on the Debian and Ubuntu platforms and under `/etc/httpd` on the Fedora, CentOS, RedHat Enterprise Linux, and ArchLinux platforms. The configuration settings may vary significantly from platform to platform.
# Syntax
An `apache_conf` InSpec audit resource block declares configuration settings that should be tested:
describe apache_conf('path') do
its('setting_name') { should eq 'value' }
end
where
* `'setting_name'` is a configuration setting defined in the Apache configuration file
* `('path')` is the non-default path to the Apache configuration file
* `{ should eq 'value' }` is the value that is expected
# Matchers
This InSpec audit resource matches any service that is listed in the Apache configuration file:
its('PidFile') { should_not eq '/var/run/httpd.pid' }
or:
its('Timeout') { should eq 300 }
For example:
describe apache_conf do
its('MaxClients') { should eq 100 }
its('Listen') { should eq '443'}
end
## 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 for blocking .htaccess files on CentOS
describe apache_conf do
its('AllowOverride') { should eq 'None' }
end
## Test ports for SSL
describe apache_conf do
its('Listen') { should eq '443'}
end

84
docs/resources/apt.md.erb Normal file
View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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.

View file

@ -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

View file

@ -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.

View file

@ -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.

View file

@ -0,0 +1,151 @@
---
title: About the command Resource
---
# command
Use the `command` InSpec audit resource to test an arbitrary command that is run on the system.
# 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 command('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
# 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 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). The following example shows matching output using a regular expression:
describe command('echo 1') do
its('stdout') { should match (/[0-9]/) }
end
# Examples
The following examples show how to use this InSpec audit resource.
## Test for PostgreSQL database running a RC, development, or beta release
describe command('psql -V') do
its('stdout') { should eq '/RC/' }
its('stdout') { should_not eq '/DEVEL/' }
its('stdout') { should_not eq '/BETA/' }
end
## Test standard output (stdout)
describe command('echo hello') do
its('stdout') { should eq 'hello\n' }
its('stderr') { should eq '' }
its('exit_status') { should eq 0 }
end
## Test standard error (stderr)
describe command('>&2 echo error') do
its('stdout') { should eq '' }
its('stderr') { should eq 'error\n' }
its('exit_status') { should eq 0 }
end
## Test an exit status code
describe command('exit 123') do
its('stdout') { should eq '' }
its('stderr') { should eq '' }
its('exit_status') { should eq 123 }
end
## Test if the command shell exists
describe command('/bin/sh').exist? do
it { should eq true }
end
## Test for a command that should not exist
describe command('this is not existing').exist? do
it { should eq false }
end
## Verify NTP
The following example shows how to use the `file` audit resource to verify if the `ntp.conf` and `leap-seconds` files are present, and then the `command` resource to verify if NTP is installed and running:
describe file('/etc/ntp.conf') do
it { should be_file }
end
describe file('/etc/ntp.leapseconds') do
it { should be_file }
end
describe command('pgrep ntp') do
its('exit_status') { should eq 0 }
end
## Verify WiX
Wix includes serveral tools -- such as `candle` (preprocesses and compiles source files into object files), `light` (links and binds object files to an installer database), and `heat` (harvests files from various input formats). The following example uses a whitespace array and the `file` audit resource to verify if these three tools are present:
%w(
candle.exe
heat.exe
light.exe
).each do |utility|
describe file("C:/wix/#{utility}") do
it { should be_file }
end
end

62
docs/resources/csv.md.erb Normal file
View file

@ -0,0 +1,62 @@
---
title: About the csv Resource
---
# csv
Use the `csv` InSpec audit resource to test configuration data in a CSV file.
# Syntax
A `csv` resource block declares the configuration data to be tested:
describe csv('file') do
its('name') { should eq 'foo' }
end
where
* `'file'` is the path to a CSV file
* `name` is a configuration setting in a CSV file
* `should eq 'foo'` tests a value of `name` as read from a CSV file 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 a CSV file versus the value declared in the test:
its('name') { should eq 'foo' }
# Examples
The following examples show how to use this InSpec audit resource.
## Test a CSV file
describe csv('some_file.csv') do
its('setting') { should eq 1 }
end

View file

@ -0,0 +1,43 @@
---
title: About the directory Resource
---
# directory
Use the `directory` InSpec audit resource to test if the file type is a directory. This is equivalent to using the `file` resource and the `be_directory` matcher, but provides a simpler and more direct way to test directories. All of the matchers available to `file` may be used with `directory`.
# Syntax
A `directory` resource block declares the location of the directory to be tested, and then one (or more) matchers:
describe directory('path') do
it { should MATCHER 'value' }
end
# Matchers
This resource may use any of the matchers available to the `file` resource that may be useful when testing a directory.
## 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
None.

View file

@ -0,0 +1,116 @@
---
title: About the etc_group Resource
---
# etc_group
Use the `etc_group` InSpec audit resource to test groups that are defined on Linux and Unix platforms. The `/etc/group` file stores details about each group---group name, password, group identifier, along with a comma-separate list of users that belong to the group.
# Syntax
A `etc_group` resource block declares a collection of properties to be tested:
describe etc_group('path') do
its('matcher') { should eq 'some_value' }
end
or:
describe etc_group.where(item: 'value', item: 'value') do
its('gids') { should_not contain_duplicates }
its('groups') { should include 'user_name' }
its('users') { should include 'user_name' }
end
where
* `('path')` is the non-default path to the `inetd.conf` file
* `.where()` may specify a specific item and value, to which the matchers are compared
* `'gids'`, `'groups'`, and `'users'` are valid matchers for this resource
# Matchers
This InSpec audit resource has the following matchers:
## be
<%= partial "/shared/matcher_be" %>
## cmp
<%= partial "/shared/matcher_cmp" %>
## eq
<%= partial "/shared/matcher_eq" %>
## gids
The `gids` matcher tests if the named group identifier is present or if it contains duplicates:
its('gids') { should_not contain_duplicates }
## groups
The `groups` matcher tests all groups for the named user:
its('groups') { should include 'my_group' }
## include
<%= partial "/shared/matcher_include" %>
## match
<%= partial "/shared/matcher_match" %>
## users
The `users` matcher tests all groups for the named user:
its('users') { should include 'my_user' }
## where
The `where` matcher allows the test to be focused to one (or more) specific items:
etc_group.where(item: 'value', item: 'value')
where `item` may be one (or more) of:
* `name: 'name'`
* `group_name: 'group_name'`
* `password: 'password'`
* `gid: 'gid'`
* `group_id: 'gid'`
* `users: 'user_name'`
* `members: 'member_name'`
# Examples
The following examples show how to use this InSpec audit resource.
## Test group identifiers (GIDs) for duplicates
describe etc_group do
its('gids') { should_not contain_duplicates }
end
## Test all groups to see if a specific user belongs to one (or more) groups
describe etc_group do
its('groups') { should include 'my_group' }
end
## Test all groups for a specific user name
describe etc_group do
its('users') { should include 'my_user' }
end
## Filter a list of groups for a specific user
describe etc_group.where(name: 'my_group') do
its('users') { should include 'my_user' }
end

View file

@ -0,0 +1,155 @@
---
title: About the passwd Resource
---
# passwd
Use the `passwd` InSpec audit resource to test the contents of `/etc/passwd`, which contains the following information for users that may log into the system and/or as users that own running processes. The format for `/etc/passwd` includes:
* A username
* The password for that user (on newer systems passwords should be stored in `/etc/shadow` )
* The user identifier (UID) assigned to that user
* The group identifier (GID) assigned to that user
* Additional information about that user
* That user's home directory
* That user's default command shell
These entries are defined as a colon-delimited row in the file, one row per user:
root:x:1234:5678:additional_info:/home/dir/:/bin/bash
# Syntax
A `passwd` resource block declares one (or more) users and associated user information to be tested:
describe passwd do
its('users') { should_not include 'forbidden_user' }
end
describe passwd.uid(filter) do
its('users') { should cmp 'root' }
its('count') { should eq 1 }
end
where
* `homes`, `gids`, `passwords`, `shells`, `uids`, and `users` are valid accessors for `passwd`
* `filter` one (or more) arguments, for example: `passwd.users(/name/)` used to define filtering
* `filter` may take any of the following arguments: `count` (retrieves the number of entries), `lines` (provides raw `passwd` lines), and `params` (returns an array of maps for all entries)
# Matchers
This InSpec audit resource has the following matchers:
## be
<%= partial "/shared/matcher_be" %>
## cmp
<%= partial "/shared/matcher_cmp" %>
## eq
<%= partial "/shared/matcher_eq" %>
## gids
The `gids` matcher tests if the group indentifiers in the test match group identifiers in `/etc/passwd`:
its('gids') { should include 1234 }
its('gids') { should cmp 0 }
## homes
The `homes` matcher tests the absolute path to a user's home directory:
its('home') { should eq '/' }
## include
<%= partial "/shared/matcher_include" %>
## length
The `length` matcher tests the length of a password that appears in `/etc/passwd`:
its('length') { should be <= 32 }
This matcher is best used in conjunction with filters. For example:
describe passwd.users('highlander') do
its('length') { should_not be < 16 }
end
## match
<%= partial "/shared/matcher_match" %>
## passwords
The `passwords` matcher tests if passwords are
* Encrypted
* Have direct logins disabled, as indicated by an asterisk (`*`)
* In the `/etc/shadow` file, as indicated by the letter x (`x`)
For example:
its('passwords') { should eq ['x'] }
its('passwords') { should cmp '*' }
## shells
The `shells` matcher tests the absolute path of a shell (or command) to which a user has access:
its('shells') { should_not include 'user' }
or to find all users with the nologin shell:
describe passwd.shells(/nologin/) do
its('users') { should_not include 'my_login_user' }
end
## uids
The `uids` matcher tests if the user indentifiers in the test match user identifiers in `/etc/passwd`:
its('uids') { should eq ['1234', '1235'] }
or:
describe passwd.uids(0) do
its('users') { should cmp 'root' }
its('count') { should eq 1 }
end
## users
The `users` matcher tests if the user names in the test match user names in `/etc/passwd`:
its('users') { should eq ['root', 'www-data'] }
# Examples
The following examples show how to use this InSpec audit resource.
## Test usernames and UIDs
describe passwd do
its('users') { should eq ['root', 'www-data'] }
its('uids') { should eq [0, 33] }
end
## Select one user and test for multiple occurrences
describe passwd.uids(0) do
its('users') { should cmp 'root' }
its('count') { should eq 1 }
end
describe passwd.filter(user: 'www-data') do
its('uids') { should cmp 33 }
its('count') { should eq 1 }
end

View file

@ -0,0 +1,149 @@
---
title: About the shadow Resource
---
# shadow
Use the `shadow` InSpec audit resource to test the contents of `/etc/shadow`, which contains password details that are only readable by the `root` user. The format for `/etc/shadow` includes:
* A username
* The password for that user (on newer systems passwords should be stored in `/etc/shadow` )
* The last time a password was changed
* The minimum number of days a password must exist, before it may be changed
* The maximum number of days after which a password must be changed
* The number of days a user is warned about an expiring password
* The number of days a user must be inactive before the user account is disabled
* The number of days a user account has been disabled
These entries are defined as a colon-delimited row in the file, one row per user:
dannos:Gb7crrO5CDF.:10063:0:99999:7:::
# Syntax
A `shadow` resource block declares one (or more) users and associated user information to be tested:
describe shadow do
its('users') { should_not include 'forbidden_user' }
end
or with a filter:
describe shadow.uid(filter) do
its('users') { should cmp 'root' }
its('count') { should eq 1 }
end
where
* `homes`, `gids`, `passwords`, `shells`, `uids`, and `users` are valid accessors for `passwd`
* `filter` one (or more) arguments, for example: `passwd.users(/name/)` used to define filtering; `filter` may take any of the following arguments: `count` (retrieves the number of entries), `lines` (provides raw `passwd` lines), and `params` (returns an array of maps for all entries)
# Matchers
This InSpec audit resource has the following matchers:
## be
<%= partial "/shared/matcher_be" %>
## cmp
<%= partial "/shared/matcher_cmp" %>
## count
The `count` matcher tests the number of times the named user appears in `/etc/shadow`:
its('count') { should eq 1 }
TThis matcher is best used in conjunction with filters. For example:
describe shadow.users('dannos') do
its('count') { should eq 1 }
end
## eq
<%= partial "/shared/matcher_eq" %>
## expiry_dates
The `expiry_dates` matcher tests the number of days a user account has been disabled:
its('expiry_dates') { should eq '' }
## inactive_days
The `inactive_days` matcher tests the number of days a user must be inactive before the user account is disabled:
its('inactive_days') { should eq '' }
## include
<%= partial "/shared/matcher_include" %>
## last_changes
The `last_changes` matcher tests the last time a password was changed:
its('last_changes') { should eq '' }
## match
<%= partial "/shared/matcher_match" %>
## max_days
The `max_days` matcher tests the maximum number of days after which a password must be changed:
its('max_days') { should eq 90 }
## min_days
The `min_days` matcher tests the minimum number of days a password must exist, before it may be changed:
its('min_days') { should eq 0 }
## passwords
The `passwords` matcher tests if passwords are
* Encrypted
* Have direct logins disabled, as indicated by an asterisk (`*`)
* In the `/etc/shadow` file, as indicated by the letter x (`x`)
For example:
its('passwords') { should eq ['x'] }
its('passwords') { should cmp '*' }
## users
The `users` matcher tests if the user name exists `/etc/shadow`:
its('users') { should eq 'root' }
## warn_days
The `warn_days` matcher tests the number of days a user is warned about an expiring password:
its('warn_days') { should eq 7 }
# Examples
The following examples show how to use this InSpec audit resource.
## Test for a forbidden user
describe shadow do
its('users') { should_not include 'forbidden_user' }
end
## Test that a user appears one time
describe shadow.users('bin') do
its('passwords') { should cmp 'x' }
its('count') { should eq 1 }
end

460
docs/resources/file.md.erb Normal file
View file

@ -0,0 +1,460 @@
---
title: About the file Resource
---
# file
Use the `file` InSpec audit resource to test all system file types, including files, directories, symbolic links, named pipes, sockets, character devices, block devices, and doors.
# Syntax
A `file` resource block declares the location of the file type to be tested, what type that file should be (if required), and then one (or more) matchers:
describe file('path') do
it { should MATCHER 'value' }
end
where
* `('path')` is the name of the file and/or the path to the file
* `MATCHER` is a valid matcher for this resource
* `'value'` is the value to be tested
# Matchers
This InSpec audit resource has the following matchers:
## be
<%= partial "/shared/matcher_be" %>
## be_block_device
The `be_block_device` matcher tests if the file exists as a block device, such as `/dev/disk0` or `/dev/disk0s9`:
it { should be_block_device }
## be_character_device
The `be_character_device` matcher tests if the file exists as a character device (that corresponds to a block device), such as `/dev/rdisk0` or `/dev/rdisk0s9`:
it { should be_character_device }
## be_directory
The `be_directory` matcher tests if the file exists as a directory, such as `/etc/passwd`, `/etc/shadow`, or `/var/log/httpd`:
it { should be_directory }
## be_executable
The `be_executable` matcher tests if the file exists as an executable:
it { should be_executable }
The `be_executable` matcher may also test if the file is executable by a specific owner, group, or user. For example, a group:
it { should be_executable.by('group') }
an owner:
it { should be_executable.by('owner') }
a user:
it { should be_executable.by_user('user') }
## be_file
The `be_file` matcher tests if the file exists as a file. This can be useful with configuration files like `/etc/passwd` where there typically is not an associated file extension---`passwd.txt`:
it { should be_file }
## be_grouped_into
The `be_grouped_into` matcher tests if the file exists as part of the named group:
it { should be_grouped_into 'group' }
## be_immutable
The `be_immutable` matcher tests if the file is immutable, i.e. "cannot be changed":
it { should be_immutable }
## be_linked_to
The `be_linked_to` matcher tests if the file is linked to the named target:
it { should be_linked_to '/etc/target-file' }
## be_mounted
The `be_mounted` matcher tests if the file is accessible from the file system:
it { should be_mounted }
## be_owned_by
The `be_owned_by` matcher tests if the file is owned by the named user, such as `root`:
it { should be_owned_by 'root' }
## be_pipe
The `be_pipe` matcher tests if the file exists as first-in, first-out special file (`.fifo`) that is typically used to define a named pipe, such as `/var/log/nginx/access.log.fifo`:
it { should be_pipe }
## be_readable
The `be_readable` matcher tests if the file is readable:
it { should be_readable }
The `be_readable` matcher may also test if the file is readable by a specific owner, group, or user. For example, a group:
it { should be_readable.by('group') }
an owner:
it { should be_readable.by('owner') }
a user:
it { should be_readable.by_user('user') }
## be_socket
The `be_socket` matcher tests if the file exists as socket (`.sock`), such as `/var/run/php-fpm.sock`:
it { should be_socket }
## be_symlink
The `be_symlink` matcher tests if the file exists as a symbolic, or soft link that contains an absolute or relative path reference to another file:
it { should be_symlink }
## be_version
The `be_version` matcher tests the version of the file:
it { should be_version '1.2.3' }
## be_writable
The `be_writable` matcher tests if the file is writable:
it { should be_writable }
The `be_writable` matcher may also test if the file is writable by a specific owner, group, or user. For example, a group:
it { should be_writable.by('group') }
an owner:
it { should be_writable.by('owner') }
a user:
it { should be_writable.by_user('user') }
## cmp
<%= partial "/shared/matcher_cmp" %>
## content
The `content` matcher tests if contents in the file match the value specified in a regular expression. The values of the `content` matcher are arbitrary and depend on the file type being tested and also the type of information that is expected to be in that file:
its('content') { should match REGEX }
The following complete example tests the `pg_hba.conf` file in PostgreSQL for MD5 requirements. The tests look at all `host` and `local` settings in that file, and then compare the MD5 checksums against the values in the test:
describe file(hba_config_file) do
its('content') { should match(%r{local\s.*?all\s.*?all\s.*?md5}) }
its('content') { should match(%r{host\s.*?all\s.*?all\s.*?127.0.0.1\/32\s.*?md5}) }
its('content') { should match(%r{host\s.*?all\s.*?all\s.*?::1\/128\s.*?md5})
end
## eq
<%= partial "/shared/matcher_eq" %>
## exist
The `exist` matcher tests if the named file exists:
it { should exist }
## file_version
The `file_version` matcher tests if the file's version matches the specified value. The difference between a file's "file version" and "product version" is that the file version is the version number of the file itself, whereas the product version is the version number associated with the application from which that file originates:
its('file_version') { should eq '1.2.3' }
## group
The `group` matcher tests if the group to which a file belongs matches the specified value:
its('group') { should eq 'admins' }
## have_mode
The `have_mode` matcher tests if a file has a mode assigned to it:
it { should have_mode }
## include
<%= partial "/shared/matcher_include" %>
## link_path
The `link_path` matcher tests if the file exists at the specified path:
its('link_path') { should eq '/some/path/to/file' }
## link_target
The `link_target` matcher tests if a file that is linked to this file exists at the specified path:
its('link_target') { should eq '/some/path/to/file' }
## match
<%= partial "/shared/matcher_match" %>
## md5sum
The `md5sum` matcher tests if the MD5 checksum for a file matches the specified value:
its('md5sum') { should eq '3329x3hf9130gjs9jlasf2305mx91s4j' }
## mode
The `mode` matcher tests if the mode assigned to the file matches the specified value:
its('mode') { should cmp '0644' }
## mtime
The `mtime` matcher tests if the file modification time for the file matches the specified value:
its('mtime') { should eq 'October 31 2015 12:10:45' }
or:
describe file('/').mtime.to_i do
it { should <= Time.now.to_i }
it { should >= Time.now.to_i - 1000}
end
## owner
The `owner` matcher tests if the owner of the file matches the specified value:
its('owner') { should eq 'root' }
## product_version
The `product_version` matcher tests if the file's product version matches the specified value. The difference between a file's "file version" and "product version" is that the file version is the version number of the file itself, whereas the product version is the version number associated with the application from which that file originates:
its('product_version') { should eq 2.3.4 }
## selinux_label
The `selinux_label` matcher tests if the SELinux label for a file matches the specified value:
its('selinux_label') { should eq 'system_u:system_r:httpd_t:s0' }
## sha256sum
The `sha256sum` matcher tests if the SHA-256 checksum for a file matches the specified value:
its('sha256sum') { should eq 'b837ch38lh19bb8eaopl8jvxwd2e4g58jn9lkho1w3ed9jbkeicalplaad9k0pjn' }
## size
The `size` matcher tests if a file's size matches, is greater than, or is less than the specified value. For example, equal:
its('size') { should eq 32375 }
Greater than:
its('size') { should > 64 }
Less than:
its('size') { should < 10240 }
## type
The `type` matcher tests if the first letter of the file's mode string contains one of the following characters:
* `-` or `f` (the file is a file); use `'file` to test for this file type
* `d` (the file is a directory); use `'directory` to test for this file type
* `l` (the file is a symbolic link); use `'link` to test for this file type
* `p` (the file is a named pipe); use `'pipe` to test for this file type
* `s` (the file is a socket); use `'socket` to test for this file type
* `c` (the file is a character device); use `'character` to test for this file type
* `b` (the file is a block device); use `'block` to test for this file type
* `D` (the file is a door); use `'door` to test for this file type
For example:
its('type') { should eq 'file' }
or:
its('type') { should eq 'socket' }
# Examples
The following examples show how to use this InSpec audit resource.
## Test the contents of a file for MD5 requirements
describe file(hba_config_file) do
its('content') { should match /local\s.*?all\s.*?all\s.*?md5/ }
its('content') { should match %r{/host\s.*?all\s.*?all\s.*?127.0.0.1\/32\s.*?md5/} }
its('content') { should match %r{/host\s.*?all\s.*?all\s.*?::1\/128\s.*?md5/} }
end
## Test if a file exists
describe file('/tmp') do
it { should exist }
end
## Test that a file does not exist
describe file('/tmpest') do
it { should_not exist }
end
## Test if a path is a directory
describe file('/tmp') do
its('type') { should eq :directory }
it { should be_directory }
end
## Test if a path is a file and not a directory
describe file('/proc/version') do
its('type') { should eq 'file' }
it { should be_file }
it { should_not be_directory }
end
## Test if a file is a symbolic link
describe file('/dev/stdout') do
its('type') { should eq 'symlink' }
it { should be_symlink }
it { should_not be_file }
it { should_not be_directory }
end
## Test if a file is a character device
describe file('/dev/zero') do
its('type') { should eq 'character' }
it { should be_character_device }
it { should_not be_file }
it { should_not be_directory }
end
## Test if a file is a block device
describe file('/dev/zero') do
its('type') { should eq 'block' }
it { should be_character_device }
it { should_not be_file }
it { should_not be_directory }
end
## Test the mode for a file
describe file('/dev') do
its('mode') { should cmp '00755' }
end
## Test the owner of a file
describe file('/root') do
its('owner') { should eq 'root' }
end
## Test if a file is owned by the root user
describe file('/dev') do
it { should be_owned_by 'root' }
end
## Test the mtime for a file
describe file('/').mtime.to_i do
it { should <= Time.now.to_i }
it { should >= Time.now.to_i - 1000}
end
## Test that a file's size is between 64 and 10240
describe file('/') do
its('size') { should be > 64 }
its('size') { should be < 10240 }
end
## Test that a file's size is zero
describe file('/proc/cpuinfo') do
its('size') { should be 0 }
end
## Test that a file is not mounted
describe file('/proc/cpuinfo') do
it { should_not be_mounted }
end
## Test an MD5 checksum
require 'digest'
cpuinfo = file('/proc/cpuinfo').content
md5sum = Digest::MD5.hexdigest(cpuinfo)
describe file('/proc/cpuinfo') do
its('md5sum') { should eq md5sum }
end
## Test an SHA-256 checksum
require 'digest'
cpuinfo = file('/proc/cpuinfo').content
sha256sum = Digest::SHA256.hexdigest(cpuinfo)
describe file('/proc/cpuinfo') do
its('sha256sum') { should eq sha256sum }
end
## Verify NTP
The following example shows how to use the `file` audit resource to verify if the `ntp.conf` and `leap-seconds` files are present, and then the `command` resource to verify if NTP is installed and running:
describe file('/etc/ntp.conf') do
it { should be_file }
end
describe file('/etc/ntp.leapseconds') do
it { should be_file }
end
describe command('pgrep ntp') do
its('exit_status') { should eq 0 }
end

73
docs/resources/gem.md.erb Normal file
View file

@ -0,0 +1,73 @@
---
title: About the gem Resource
---
# gem
Use the `gem` InSpec audit resource to test if a global Gem package is installed.
# Syntax
A `gem` resource block declares a package and (optionally) a package version:
describe gem('gem_package_name') do
it { should be_installed }
end
where
* `('gem_package_name')` must specify a Gem package, such as `'rubocop'`
* `be_installed` is a valid matcher for this resource
# Matchers
This InSpec audit resource has the following matchers:
## be
<%= partial "/shared/matcher_be" %>
## be_installed
The `be_installed` matcher tests if the named Gem package is installed:
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 '0.33.0' }
# Examples
The following examples show how to use this InSpec audit resource.
## Verify that a gem package is installed, with a specific version
describe gem('rubocop') do
it { should be_installed }
its('version') { should eq '0.33.0' }
end
## Verify that a gem package is not installed
describe gem('rubocop') do
it { should_not be_installed }
end

View file

@ -0,0 +1,74 @@
---
title: About the group Resource
---
# group
Use the `group` InSpec audit resource to test groups on the system.
# Syntax
A `group` resource block declares a group, and then the details to be tested, such as if the group is a local group, the group identifier, or if the group exists:
describe group('group_name') do
it { should exist }
its('gid') { should eq 0 }
end
where
* `'group_name'` must specify the name of a group on the system
* `exist` and `'gid'` are valid matchers for this resource
# Matchers
This InSpec audit resource has the following matchers:
## be
<%= partial "/shared/matcher_be" %>
## be_local
The `be_local` matcher tests if the group is a local group:
it { should be_local }
## cmp
<%= partial "/shared/matcher_cmp" %>
## eq
<%= partial "/shared/matcher_eq" %>
## exist
The `exist` matcher tests if the named user exists:
it { should exist }
## gid
The `gid` matcher tests the named group identifier:
its('gid') { should eq 1234 }
## include
<%= partial "/shared/matcher_include" %>
## match
<%= partial "/shared/matcher_match" %>
# Examples
The following examples show how to use this InSpec audit resource.
## Test the group identifier for the root group
describe group('root') do
it { should exist }
its('gid') { should eq 0 }
end

View file

@ -0,0 +1,115 @@
---
title: About the grub_conf Resource
---
# grub_conf
Grub is a boot loader on the Linux platform used to load and then transfer control to an operating system kernel, after which that kernel initializes the rest of the operating system. Use the `grub_conf` InSpec audit resource to test boot loader configuration settings that are defined in the `grub.conf` configuration file.
# Syntax
A `grub_conf` resource block declares a list of settings in a `grub.conf` file:
describe grub_conf('path', 'kernel') do
its('setting') { should eq 'value' }
end
or:
describe grub_conf('path') do
its('default') { should eq '0' } #
its('setting') { should eq 'value' }
end
where
* `'service_name'` is a service listed in the `grub.conf` file
* `'path'` is the path to the `grub.conf` file
* `'kernel'` specifies the default kernel (by using `'default'`) or a specific kernel; `'default'` defines the position in the list of kernels at which the default kernel is defined, i.e. `should eq '0'` for the first kernel listed or `'path', 'default'` to use the default kernel as specified in the `grub.conf` file
* `'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" %>
# Examples
The following examples show how to use this InSpec audit resource.
## Test a grub.conf file
A Grub configuration file located at `/etc/grub.conf` is similar to the following:
# grub.conf generated by anaconda
#
# Note that you do not have to rerun grub after making changes to this file
# NOTICE: You have a /boot partition. This means that
# all kernel and initrd paths are relative to /boot/, eg.
# root (hd0,0)
# kernel /vmlinuz-version ro root=/dev/hda6
# initrd /initrd-version.img
#boot=/dev/hda
default=0
timeout=10
splashimage=(hd0,0)/grub/splash.xpm.gz
title Red Hat Enterprise Linux ES (2.6.32-573.7.1.el6.x86_64)
root (hd0,0)
kernel /vmlinuz-2.6.32-573.7.1.el6.x86_64 ro root=/dev/hda6
initrd /initrd-2.6.32-573.7.1.el6.x86_64.img
title Red Hat Enterprise Linux ES (2.6.32-358.14.1.el6.x86_64)
root (hd0,0)
kernel /vmlinuz-2.6.32-358.14.1.el6.x86_64 ro root=/dev/hda6 ramdisk_size=400000
initrd /initrd-2.6.32-358.14.1.el6.x86_64.img
This file defines two versions of RedHat Enterprise Linux, with version `2.6.32-573.7.1.el6.x86_64` specified as the default.
The following test verifies the kernel, ensures that kernel is the default kernel, its initial RAM disk (`initrd`), and the timeout:
describe grub_conf('/etc/grub.conf', 'default') do
its('kernel') { should include '/vmlinuz-2.6.32-573.7.1.el6.x86_64' }
its('initrd') { should include '/initrd-2.6.32-573.7.1.el6.x86_64.img' }
its('default') { should_not eq '1' }
its('timeout') { should eq '10' }
end
The following test verifies the `ramdisk_size` for the non-deault kernel:
describe grub_conf('/etc/grub.conf', 'Red Hat Enterprise Linux ES (2.6.32-358.14.1.el6.x86_64)') do
its('kernel') { should include 'ramdisk_size=400000' }
end
## Test a configuration file and boot configuration
describe grub_conf('/etc/grub.conf', 'default') do
its('kernel') { should include '/vmlinuz-2.6.32-573.7.1.el6.x86_64' }
its('initrd') { should include '/initramfs-2.6.32-573.el6.x86_64.img=1' }
its('default') { should_not eq '1' }
its('timeout') { should eq '5' }
end
## Test a specific kernel
grub_conf('/etc/grub.conf', 'CentOS (2.6.32-573.12.1.el6.x86_64)') do
its('kernel') { should include 'audit=1' }
end

View file

@ -0,0 +1,85 @@
---
title: About the host Resource
---
# host
Use the `host` InSpec audit resource to test the name used to refer to a specific host and its availability, including the Internet protocols and ports over which that host name should be available.
# Syntax
A `host` resource block declares a host name, and then (depending on what is to be tested) a port and/or a protocol:
.. code-block:: ruby
describe host('example.com', port: 80, proto: 'tcp') do
it { should be_reachable }
end
where
* `host()` must specify a host name and may specify a port number and/or a protocol
* `'example.com'` is the host name
* `port:` is the port number
* `proto: 'name'` is the Internet protocol: TCP (`proto: 'tcp'`), UDP (`proto: 'udp'` or ICMP (`proto: 'icmp'`))
* `be_reachable` is a valid matcher for this resource
# Matchers
This InSpec audit resource has the following matchers:
## be
<%= partial "/shared/matcher_be" %>
## be_reachable
The `be_reachable` matcher tests if the host name is available:
it { should be_reachable }
## be_resolvable
The `be_resolvable` matcher tests for host name resolution, i.e. "resolvable to an IP address":
it { should be_resolvable }
## cmp
<%= partial "/shared/matcher_cmp" %>
## eq
<%= partial "/shared/matcher_eq" %>
## include
<%= partial "/shared/matcher_include" %>
## ipaddress
The `ipaddress` matcher tests if a host name is resolvable to a specific IP address:
its('ipaddress') { should include '93.184.216.34' }
## match
<%= partial "/shared/matcher_match" %>
# Examples
The following examples show how to use this InSpec audit resource.
## Verify host name is reachable over a specific protocol and port number
describe host('example.com', port: 53, proto: 'udp') do
it { should be_reachable }
end
## Verify that a specific IP address can be resolved
describe host('example.com', port: 80, proto: 'tcp') do
it { should be_resolvable }
its('ipaddress') { should include '192.168.1.1' }
end

View file

@ -0,0 +1,142 @@
---
title: About the iis_site Resource
---
# iis_site
Use the `iis_site` InSpec audit resource to test the state of IIS on Windows Server 2012 (and later).
# Syntax
An `iis_site` resource block declares details about the named site:
describe iis_site('site_name') do
it { should exist }
it { should be_running }
it { should have_app_pool('app_pool_name') }
it { should have_binding('binding_details') }
it { should have_path('path_to_site') }
end
where
* `'site_name'` is the name of the site, such as `'Default Web Site'`
* `('app_pool_name')` is the name of the application pool in which the site's root application is run, such as `'DefaultAppPool'`
* `('binding_details')` is a binding for the site, such as `'net.pipe *'`. A site may have multiple bindings; therefore, use a `have_binding` matcher for each site binding to be tested
* `('path_to_site')` is the path to the site, such as `'C:\\inetpub\\wwwroot'`
For example:
describe iis_site('Default Web Site') do
it { should exist }
it { should be_running }
it { should have_app_pool('DefaultAppPool') }
it { should have_binding('https :443:www.contoso.com sslFlags=0') }
it { should have_binding('net.pipe *') }
it { should have_path('C:\\inetpub\\wwwroot') }
end
# Matchers
This InSpec audit resource has the following matchers:
## be
<%= partial "/shared/matcher_be" %>
## be_running
The `be_running` matcher tests if the site is running:
it { should be_running }
## cmp
<%= partial "/shared/matcher_cmp" %>
## eq
<%= partial "/shared/matcher_eq" %>
## exist
The `exist` matcher tests if the site exists:
it { should exist }
## have_app_pool
The `have_app_pool` matcher tests if the named application pool exists for the site:
it { should have_app_pool('DefaultAppPool') }
For example, testing if a site's application pool inherits the settings of the parent application pool:
it { should have_app_pool('/') }
## have_binding
The `have_binding` matcher tests if the specified binding exists for the site:
it { should have_binding('http :80:*') }
or:
it { should have_binding('net.pipe *') }
A site may have multiple bindings; use a `have_binding` matcher for each unique site binding to be tested.
### Binding Attributes
The `have_binding` matcher can also test attributes that are defined for a site binding. For example, the `sslFlags` attribute defines if SSL is enabled, and (when enabled) what level of SSL is applied to the site.
Testing a site with SSL disabled:
it { should have_binding('https :443:www.contoso.com sslFlags=0') }
Testing a site with SSL enabled:
it { should have_binding('https :443:www.contoso.com sslFlags=Ssl') }
Testing a site with certificate mapping authentication enabled:
it { should have_binding('https :443:www.contoso.com sslFlags=SslMapCert') }
Testing a site with 128-bit SSL enabled:
it { should have_binding('https :443:www.contoso.com sslFlags=Ssl128') }
## have_path
The `have_path` matcher tests if the named path is defined for the site:
it { should have_path('C:\\inetpub\\wwwroot') }
## include
<%= partial "/shared/matcher_include" %>
## match
<%= partial "/shared/matcher_match" %>
# Examples
The following examples show how to use this InSpec audit resource.
## Test a default IIS site
describe iis_site('Default Web Site') do
it { should exist }
it { should be_running }
it { should have_app_pool('DefaultAppPool') }
it { should have_binding('http *:80:') }
it { should have_path('%SystemDrive%\\inetpub\\wwwroot\\') }
end
## Test if IIS service is running
describe service('W3SVC') do
it { should be_installed }
it { should be_running }
end

View file

@ -0,0 +1,99 @@
---
title: About the inetd_conf Resource
---
# inetd_conf
Use the `inetd_conf` InSpec audit resource to test if a service is listed in the `inetd.conf` file on Linux and Unix platforms. inetd---the Internet service daemon---listens on dedicated ports, and then loads the appropriate program based on a request. The `inetd.conf` file is typically located at `/etc/inetd.conf` and contains a list of Internet services associated to the ports on which that service will listen. Only enabled services may handle a request; only services that are required by the system should be enabled.`
# Syntax
An `inetd_conf` resource block declares the list of services that are enabled in the `inetd.conf` file:
describe inetd_conf('path') do
its('service_name') { should eq 'value' }
end
where
* `'service_name'` is a service listed in the `inetd.conf` file
* `('path')` is the non-default path to the `inetd.conf` file
* `should eq 'value'` is the value that is expected
# Matchers
This resource matches any service that is listed in the `inetd.conf` file. You may want to ensure that specific services do not listen via `inetd.conf`:
its('shell') { should eq nil }
or:
its('netstat') { should eq nil }
or:
its('systat') { should eq nil }
For example:
describe inetd_conf do
its('shell') { should eq nil }
its('login') { should eq nil }
its('exec') { should eq nil }
end
## 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.
## Verify that FTP is disabled
The contents if the `inetd.conf` file contain the following:
#ftp stream tcp nowait root /usr/sbin/tcpd in.ftpd -l -a
#telnet stream tcp nowait root /usr/sbin/tcpd in.telnetd
and the following test is defined:
describe inetd_conf do
its('ftp') { should eq nil }
its('telnet') { should eq nil }
end
Because both the `ftp` and `telnet` Internet services are commented out (`#`), both services are disabled. Consequently, both tests will return `true`. However, if the `inetd.conf` file is set as follows:
ftp stream tcp nowait root /usr/sbin/tcpd in.ftpd -l -a
#telnet stream tcp nowait root /usr/sbin/tcpd in.telnetd
then the same test will return `false` for `ftp` and the entire test will fail.
## Test if telnet is installed
describe package('telnetd') do
it { should_not be_installed }
end
describe inetd_conf do
its('telnet') { should eq nil }
end

69
docs/resources/ini.md.erb Normal file
View file

@ -0,0 +1,69 @@
---
title: About the ini Resource
---
# ini
Use the `ini` InSpec audit resource to test settings in an INI file.
# Syntax
An `ini` resource block declares the configuration settings to be tested:
describe ini('path') do
its('setting_name') { should eq 'value' }
end
where
* `'setting_name'` is a synchronization setting defined in the INI file
* `('path')` is the path to the INI file
* `{ should eq 'value' }` is the value that is expected
For example:
describe ini('path/to/ini_file.ini') do
its('port') { should eq '143' }
its('server') { should eq '192.0.2.62' }
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" %>
## include
<%= partial "/shared/matcher_include" %>
## match
<%= partial "/shared/matcher_match" %>
# Examples
The following examples show how to use this InSpec audit resource.
## Test SMTP settings in a PHP INI file
For example, a PHP INI file located at contains the following settings:
; SMTP = smtp.gmail.com
; smtp_port = 465
and can be tested like this:
describe ini(/etc/php5/apache2/php.ini) do
its('smtp_port') { should eq('465') }
end

View file

@ -0,0 +1,66 @@
---
title: About the interface Resource
---
# interface
Use the `interface` InSpec audit resource to test basic network adapter properties, such as name, status, state, address, and link speed (in MB/sec).
* On Linux platforms, `/sys/class/net/#{iface}` is used as source
* On the Windows platform, the `Get-NetAdapter` cmdlet is used as source
# Syntax
An `interface` resource block declares network interface properties to be tested:
describe interface do
it { should be_up }
its('speed') { should eq 1000 }
its('name') { should eq eth0 }
end
# Matchers
This InSpec audit resource has the following matchers:
## be
<%= partial "/shared/matcher_be" %>
## be_up
The `be_up` matcher tests if the network interface is available:
it { should be_up }
## 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 if the named network interface exists:
its('name') { should eq eth0 }
## speed
The `speed` matcher tests the speed of the network interface, in MB/sec:
its('speed') { should eq 1000 }
# Examples
None.

View file

@ -0,0 +1,70 @@
---
title: About the iptables Resource
---
# iptables
Use the `iptables` InSpec audit resource to test rules that are defined in `iptables`, which maintains tables of IP packet filtering rules. There may be more than one table. Each table contains one (or more) chains (both built-in and custom). A chain is a list of rules that match packets. When the rule matches, the rule defines what target to assign to the packet.
# Syntax
A `iptables` resource block declares tests for rules in IP tables:
describe iptables(rule:'name', table:'name', chain: 'name') do
it { should have_rule('RULE') }
end
where
* `iptables()` may specify any combination of `rule`, `table`, or `chain`
* `rule:'name'` is the name of a rule that matches a set of packets
* `table:'name'` is the packet matching table against which the test is run
* `chain: 'name'` is the name of a user-defined chain or one of `ACCEPT`, `DROP`, `QUEUE`, or `RETURN`
* `have_rule('RULE')` tests that rule in the iptables file
# Matchers
This InSpec audit resource has the following matchers:
## be
<%= partial "/shared/matcher_be" %>
## cmp
<%= partial "/shared/matcher_cmp" %>
## eq
<%= partial "/shared/matcher_eq" %>
## have_rule
The `have_rule` matcher tests the named rule against the information in the `iptables` file:
it { should have_rule('RULE') }
## include
<%= partial "/shared/matcher_include" %>
## match
<%= partial "/shared/matcher_match" %>
# Examples
The following examples show how to use this InSpec audit resource.
## Test if the IP table allows a packet through
describe iptables do
it { should have_rule('-P INPUT ACCEPT') }
end
## Test if the IP table allows a packet through, for a specific table and chain
describe iptables(table:'mangle', chain: 'input') do
it { should have_rule('-P INPUT ACCEPT') }
end

View file

@ -0,0 +1,76 @@
---
title: About the json Resource
---
# json
Use the `json` InSpec audit resource to test data in a JSON file.
# Syntax
A `json` resource block declares the data to be tested. Assume the following JSON file:
{
"name" : "hello",
"meta" : {
"creator" : "John Doe"
},
"array": [
"zero",
"one"
]
}
This file can be queried using:
describe json('/paht/to/name.json') do
its('name') { should eq 'hello' }
its(['meta','creator']) { should eq 'John Doe' }
its(['array', 1]) { should eq 'one' }
end
where
* `name` is a configuration setting in a JSON file
* `should eq 'foo'` tests a value of `name` as read from a JSON file 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 a JSON file versus the value declared in the test:
its('name') { should eq 'foo' }
# Examples
The following examples show how to use this InSpec audit resource.
## Test a cookbook version in a policyfile.lock.json file
describe json('policyfile.lock.json') do
its(['cookbook_locks', 'omnibus', 'version']) { should eq('2.2.0') }
end

View file

@ -0,0 +1,60 @@
---
title: About the kernel_module Resource
---
# kernel_module
Use the `kernel_module` InSpec audit resource to test kernel modules on Linux platforms. These parameters are located under `/lib/modules`. Any submodule may be tested using this resource.
# Syntax
A `kernel_module` resource block declares a module name, and then tests if that module is a loadable kernel module:
describe kernel_module('module_name') do
it { should be_loaded }
end
where
* `'module_name'` must specify a kernel module, such as `'bridge'`
* `{ should be_loaded }` tests if the module is a loadable kernel module
# Matchers
This InSpec audit resource has the following matchers:
## be
<%= partial "/shared/matcher_be" %>
## be_loaded
The `be_loaded` matcher tests if the module is a loadable kernel module:
it { should be_loaded }
## 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 module is loaded
describe kernel_module('bridge') do
it { should be_loaded }
end

View file

@ -0,0 +1,72 @@
---
title: About the kernel_parameter Resource
---
# kernel_parameter
Use the `kernel_parameter` InSpec audit resource to test kernel parameters on Linux platforms.
# Syntax
A `kernel_parameter` resource block declares a parameter and then a value to be tested:
describe kernel_parameter('path.to.parameter') do
its('value') { should eq 0 }
end
where
* `'kernel.parameter'` must specify a kernel parameter, such as `'net.ipv4.conf.all.forwarding'`
* `{ should eq 0 }` states the value 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" %>
## value
The `value` matcher tests the value assigned to the named IP address versus the value declared in the test:
its('value') { should eq 0 }
# Examples
The following examples show how to use this InSpec audit resource.
## Test if global forwarding is enabled for an IPv4 address
describe kernel_parameter('net.ipv4.conf.all.forwarding') do
its('value') { should eq 1 }
end
## Test if global forwarding is disabled for an IPv6 address
describe kernel_parameter('net.ipv6.conf.all.forwarding') do
its('value') { should eq 0 }
end
## Test if an IPv6 address accepts redirects
describe kernel_parameter('net.ipv6.conf.interface.accept_redirects') do
its('value') { should eq 'true' }
end

View file

@ -0,0 +1,76 @@
---
title: About the launchd_service Resource
---
# launchd_service
Use the ``launchd_service`` InSpec audit resource to test a service using Launchd.
# Syntax
A ``launchd_service`` resource block declares the name of a service and then one (or more) matchers to test the state of the service:
describe launchd_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 launchd_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.

View file

@ -0,0 +1,80 @@
---
title: About the limits_conf Resource
---
# limits_conf
Use the `limits_conf` InSpec audit resource to test configuration settings in the `/etc/security/limits.conf` file. The `limits.conf` defines limits for processes (by user and/or group names) and helps ensure that the system on which those processes are running remains stable. Each process may be assigned a hard or soft limit.
* Soft limits are maintained by the shell and defines the number of file handles (or open files) available to the user or group after login
* Hard limits are maintained by the kernel and defines the maximum number of allowed file handles
Entries in the `limits.conf` file are similar to:
grantmc soft nofile 4096
grantmc hard nofile 63536
^^^^^^^^^ ^^^^ ^^^^^^ ^^^^^
domain type item value
# Syntax
A `limits_conf` resource block declares a domain to be tested, along with associated type, item, and value:
describe limits_conf('path') do
its('domain') { should include ['type', 'item', 'value'] }
its('domain') { should eq ['type', 'item', 'value'] }
end
where
* `('path')` is the non-default path to the `inetd.conf` file
* `'domain'` is a user or group name, such as `grantmc`
* `'type'` is either `hard` or `soft`
* `'item'` is the item for which limits are defined, such as `core`, `nofile`, `stack`, `nproc`, `priority`, or `maxlogins`
* `'value'` is the value associated with the `item`
# Matchers
This InSpec audit resource has the following matchers:
## be
<%= partial "/shared/matcher_be" %>
## cmp
<%= partial "/shared/matcher_cmp" %>
## domain
The `domain` matcher tests the domain in the `limits.conf` file, along with associated type, item, and value:
its('domain') { should include ['type', 'item', 'value'] }
`
For example:
its('grantmc') { should include ['hard', 'nofile', '63536'] }
## 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 limits
describe limits_conf('path') do
its('*') { should include ['soft', 'core', '0'], ['hard', 'rss', '10000'] }
its('ftp') { should eq ['hard', 'nproc', '0'] }
end

View file

@ -0,0 +1,77 @@
---
title: About the login_defs Resource
---
# login_defs
Use the `login_defs` InSpec audit resource to test configuration settings in the `/etc/login.defs` file. The `logins.defs` file defines site-specific configuration for the shadow password suite on Linux and Unix platforms, such as password expiration ranges, minimum/maximum values for automatic selection of user and group identifiers, or the method with which passwords are encrypted.
# Syntax
A `login_defs` resource block declares the `login.defs` configuration data to be tested:
describe login_defs do
its('name') { should include('foo') }
end
where
* `name` is a configuration setting in `login.defs`
* `{ should include('foo') }` tests the value of `name` as read from `login.defs` 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 `login.defs` versus the value declared in the test:
its('name') { should eq 'foo' }
# Examples
The following examples show how to use this InSpec audit resource.
## Test password expiration settings
describe login_defs do
its('PASS_MAX_DAYS') { should eq '180' }
its('PASS_MIN_DAYS') { should eq '1' }
its('PASS_MIN_LEN') { should eq '15' }
its('PASS_WARN_AGE') { should eq '30' }
end
## Test the encryption method
describe login_defs do
its('ENCRYPT_METHOD') { should eq 'SHA512' }
end
## Test umask setting
describe login_def do
its('UMASK') { should eq '077' }
its('PASS_MAX_DAYS') { should eq '90' }
end

View file

@ -0,0 +1,83 @@
---
title: About the mount Resource
---
# mount
Use the `mount` InSpec audit resource to test the mount points on Linux systems.
# Syntax
An `mount` resource block declares the synchronization settings that should be tested:
describe mount('path') do
it { should MATCHER 'value' }
end
where
* `('path')` is the path to the mounted directory
* `MATCHER` is a valid matcher for this resource
* `'value'` is the value to be tested
# Matchers
This InSpec audit resource has the following matchers:
## be
<%= partial "/shared/matcher_be" %>
## be_mounted
The `be_mounted` matcher tests if the file is accessible from the file system:
it { should be_mounted }
## cmp
<%= partial "/shared/matcher_cmp" %>
## device
The `device` matcher tests the device from the `fstab` table:
its('device') { should eq '/dev/mapper/VolGroup-lv_root' }
## eq
<%= partial "/shared/matcher_eq" %>
## include
<%= partial "/shared/matcher_include" %>
## match
<%= partial "/shared/matcher_match" %>
## options
The `options` matcher tests the mount options for the file system from the `fstab` table:
its('options') { should eq ['rw', 'mode=620'] }
## type
The `type` matcher tests the file system type:
its('type') { should eq 'ext4' }
# Examples
The following examples show how to use this InSpec audit resource.
## Test a the mount point on '/'
describe mount('/') do
it { should be_mounted }
its('device') { should eq '/dev/mapper/VolGroup-lv_root' }
its('type') { should eq 'ext4' }
its('options') { should eq ['rw', 'mode=620'] }
end

View file

@ -0,0 +1,102 @@
---
title: About the mysql_conf Resource
---
# mysql_conf
Use the `mysql_conf` InSpec audit resource to test the contents of the configuration file for MySQL, typically located at `/etc/mysql/my.cnf` or `/etc/my.cnf`.
# Syntax
A `mysql_conf` resource block declares one (or more) settings in the `my.cnf` file, and then compares the setting in the configuration file to the value stated in the test:
describe mysql_conf('path') do
its('setting') { should eq 'value' }
end
where
* `'setting'` specifies a setting in the `my.cnf` file, such as `max_connections`
* `('path')` is the non-default path to the `my.cnf` file
* `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 `my.cnf` 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 connections
describe mysql_conf do
its('max_connections') { should eq '505' }
its('max_user_connections') { should eq '500' }
end
## Test slow query logging**
describe mysql_conf do
its('slow_query_log_file') { should eq 'hostname_slow.log' }
its('slow_query_log') { should eq '0' }
its('log_queries_not_using_indexes') { should eq '1' }
its('long_query_time') { should eq '0.5' }
its('min_examined_row_limit') { should eq '100' }
end
## Test the port and socket on which MySQL listens
describe mysql_conf do
its('port') { should eq '3306' }
its('socket') { should eq '/var/run/mysqld/mysql.sock' }
end
## Test connection and thread variables
describe mysql_conf do
its('port') { should eq '3306' }
its('socket') { should eq '/var/run/mysqld/mysql.sock' }
its('max_allowed_packet') { should eq '12M' }
its('default_storage_engine') { should eq 'InnoDB' }
its('character_set_server') { should eq 'utf8' }
its('collation_server') { should eq 'utf8_general_ci' }
its('max_connections') { should eq '505' }
its('max_user_connections') { should eq '500' }
its('thread_cache_size') { should eq '505' }
end
## Test the safe-user-create parameter
describe mysql_conf.params('mysqld') do
its('safe-user-create') { should eq('1') }
end

View file

@ -0,0 +1,63 @@
---
title: About the mysql_session Resource
---
# mysql_session
Use the `mysql_session` InSpec audit resource to test SQL commands run against a MySQL database.
# Syntax
A `mysql_session` resource block declares the username and password to use for the session, and then the command to be run:
describe mysql_session('username', 'password').query('QUERY') do
its('output') { should eq('') }
end
where
* `mysql_session` declares a username and password with permission to run the query
* `query('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 for matching databases
sql = mysql_session('my_user','password')
describe sql.query('show databases like \'test\';') do
its('stdout') { should_not match(/test/) }
end

75
docs/resources/npm.md.erb Normal file
View file

@ -0,0 +1,75 @@
---
title: About the npm Resource
---
# npm
Use the `npm` InSpec audit resource to test if a global NPM package is installed. NPM is the the package manager for Node.js packages (https://docs.npmjs.com), such as Bower and StatsD.
# Syntax
A `npm` resource block declares a package and (optionally) a package version:
describe gem('npm_package_name') do
it { should be_installed }
end
where
* `('npm_package_name')` must specify an NPM package, such as `'bower'` or `'statsd'`
* `be_installed` is a valid matcher for this resource
# Matchers
This InSpec audit resource has the following matchers:
## be
<%= partial "/shared/matcher_be" %>
## be_installed
The `be_installed` matcher tests if the named Gem package and package version (if specified) is installed:
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.
## Verify that bower is installed, with a specific version
describe npm('bower') do
it { should be_installed }
its('version') { should eq '1.4.1' }
end
## Verify that statsd is not installed
describe npm('statsd') do
it { should_not be_installed }
end

View file

@ -0,0 +1,76 @@
---
title: About the ntp_conf Resource
---
# ntp_conf
Use the `ntp_conf` InSpec audit resource to test the synchronization settings defined in the `ntp.conf` file. This file is typically located at `/etc/ntp.conf`.
# Syntax
An `ntp_conf` resource block declares the synchronization settings that should be tested:
describe ntp_conf('path') do
its('setting_name') { should eq 'value' }
end
where
* `'setting_name'` is a synchronization setting defined in the `ntp.conf` file
* `('path')` is the non-default path to the `ntp.conf` file
* `{ should eq 'value' }` is the value that is expected
# Matchers
This resource matches any service that is listed in the `ntp.conf` file:
its('server') { should_not eq nil }
or:
its('restrict') { should include '-4 default kod notrap nomodify nopeer noquery'}
For example:
describe ntp_conf do
its('server') { should_not eq nil }
its('restrict') { should include '-4 default kod notrap nomodify nopeer noquery'}
end
## 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 for clock drift against named servers
describe ntp_conf do
its('driftfile') { should eq '/var/lib/ntp/ntp.drift' }
its('server') { should eq [
0.ubuntu.pool.ntp.org,
1.ubuntu.pool.ntp.org,
2.ubuntu.pool.ntp.org
] }
end

View file

@ -0,0 +1,67 @@
---
title: About the oneget Resource
---
# oneget
Use the `oneget` InSpec audit resource to test if the named package and/or package version is installed on the system. This resource uses Oneget, which is `part of the Windows Management Framework 5.0 and Windows 10 <https://github.com/OneGet/oneget>`__. This resource uses the `Get-Package` cmdlet to return all of the package names in the Oneget repository.
# Syntax
A `oneget` resource block declares a package and (optionally) a package version:
describe oneget('name') do
it { should be_installed }
end
where
* `('name')` must specify the name of a package, such as `'VLC'`
* `be_installed` is a valid matcher for this resource
# 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 VLC is installed
describe oneget('VLC') do
it { should be_installed }
end

154
docs/resources/os.md.erb Normal file
View file

@ -0,0 +1,154 @@
---
title: About the os Resource
---
# os
Use the `os` InSpec audit resource to test the platform on which the system is running.
# Syntax
An `os` resource block declares the platform to be tested. The platform may specified via matcher or control block name. For example, using a matcher:
describe os[:family] do
it { should eq 'platform_name' }
end
or using the block name:
describe os[:family_name] do
...
end
* `'platform_name'` (a string) or `:family_name` (a symbol) is one of `aix`, `bsd`, `darwin`, `debian`, `hpux`, `linux`, `redhat`, `solaris`, `suse`, `unix`, or `windows`
# 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" %>
# os.family? Helpers
The `os` audit resource includes a collection of helpers that enable more granular testing of platforms, platform names, architectures, and releases. Use any of the following platform-specific helpers to test for specific platforms:
* `aix?`
* `bsd?` (including Darwin, FreeBSD, NetBSD, and OpenBSD)
* `darwin?`
* `debian?`
* `hpux?`
* `linux?` (including Alpine Linux, Amazon Linux, ArchLinux, CoreOS, Exherbo, Fedora, Gentoo, and Slackware)
* `redhat?`
* `solaris?` (including Nexenta Core, OmniOS, Open Indiana, Solaris Open, and SmartOS)
* `suse?`
* `unix?`
* `windows?`
For example, to test for Darwin use:
describe os.bsd? do
it { should eq true }
end
To test for Windows use:
describe os.windows? do
it { should eq true }
end
and to test for Redhat use:
describe os.redhat? do
it { should eq true }
end
Use the following helpers to test for operating system names, releases, and architectures:
describe os.name do
it { should eq 'foo' }
end
describe os.release do
it { should eq 'foo' }
end
describe os.arch do
it { should eq 'foo' }
end
# os[:family] Symbols
Use `os[:family]` to enable more granular testing of platforms, platform names, architectures, and releases. Use any of the following platform-specific symbols to test for specific platforms:
* `:aix`
* `:bsd` For platforms that are part of the Berkeley OS family: `:darwin`, `:freebsd`, `:netbsd`, and `:openbsd`.
* `:debian`
* `:hpux`
* `:linux`. For platforms that are part of the Linux family: `:alpine`, `:amazon`, `:arch`, `:coreos`, `:exherbo`, `:fedora`, `:gentoo`, and `:slackware`.
* `:redhat`
* `:solaris`. For platforms that are part of the Solaris family: `:nexentacore`, `:omnios`, `:openindiana`, `:opensolaris`, and `:smartos`.
* `:suse`
* `:unix`
* `:windows`
For example, both of the following tests should have the same result:
if os[:family] == 'debian'
describe port(69) do
its('processes') { should include 'in.tftpd' }
end
elsif os[:family] == 'rhel'
describe port(69) do
its('processes') { should include 'xinetd' }
end
end
if os[:debian]
describe port(69) do
its('processes') { should include 'in.tftpd' }
end
elsif os[:rhel]
describe port(69) do
its('processes') { should include 'xinetd' }
end
end
# Examples
The following examples show how to use this InSpec audit resource.
## Test for RedHat
describe os[:family] do
it { should eq 'redhat' }
end
## Test for Ubuntu
describe os[:family] do
it { should eq 'debian' }
end
## Test for Microsoft Windows
describe os[:family] do
it { should eq 'windows' }
end

View file

@ -0,0 +1,98 @@
---
title: About the os_env Resource
---
# os_env
Use the `os_env` InSpec audit resource to test the environment variables for the platform on which the system is running.
# Syntax
A `os_env` resource block declares an environment variable, and then declares its value:
describe os_env('VARIABLE') do
its('matcher') { should eq 1 }
end
where
* `('VARIABLE')` must specify an environment variable, such as `PATH`
* `matcher` 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 return the value of the environment variable:
its('content') { should eq '/usr/local/bin:/usr/local/sbin:/usr/sbin:/usr/bin:/sbin' }
## eq
<%= partial "/shared/matcher_eq" %>
## include
<%= partial "/shared/matcher_include" %>
## match
<%= partial "/shared/matcher_match" %>
## split
The `split` splits the content with the `:` deliminator:
its('split') { should include (':') }
or:
its('split') { should_not include ('.') }
Use `-1` to test for cases where there is a trailing colon (`:`), such as `dir1::dir2:`:
its('split') { should include ('-1') }
# Examples
The following examples show how to use this InSpec audit resource.
## Test the PATH environment variable
describe os_env('PATH') do
its('split') { should_not include('') }
its('split') { should_not include('.') }
end
## Test Habitat environment variables
Habitat uses the `os_env` resource to test environment variables. The environment variables are first defined in a whitespace array, after which each environment variable is tested:
hab_env_vars = %w(HAB_AUTH_TOKEN
HAB_CACHE_KEY_PATH
HAB_DEPOT_URL
HAB_ORG
HAB_ORIGIN
HAB_ORIGIN_KEYS
HAB_RING
HAB_RING_KEY
HAB_STUDIOS_HOME
HAB_STUDIO_ROOT
HAB_USER)
hab_env_vars.each do |e|
describe os_env(e) do
its('content') { should eq nil }
end
end

View file

@ -0,0 +1,115 @@
---
title: About the package Resource
---
# package
Use the `package` InSpec audit resource to test if the named package and/or package version is installed on the system.
# Syntax
A `package` resource block declares a package and (optionally) a package version:
describe package('name') do
it { should be_installed }
end
where
* `('name')` must specify the name of a package, such as `'nginx'`
* `be_installed` is a valid matcher for this resource
# 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 nginx version 1.9.5 is installed
describe package('nginx') do
it { should be_installed }
its('version') { should eq 1.9.5 }
end
## Test that a package is not installed
describe package('some_package') do
it { should_not be_installed }
end
## Test if telnet is installed
describe package('telnetd') do
it { should_not be_installed }
end
describe inetd_conf do
its('telnet') { should eq nil }
end
## Test if ClamAV (an antivirus engine) is installed and running
describe package('clamav') do
it { should be_installed }
its('version') { should eq '0.98.7' }
end
describe service('clamd') do
it { should_not be_enabled }
it { should_not be_installed }
it { should_not be_running }
end
## Verify if Memcached is installed, enabled, and running
Memcached is an in-memory key-value store that helps improve the performance of database-driven websites and can be installed, maintained, and tested using the `memcached` cookbook (maintained by Chef). The following example is from the `memcached` cookbook and shows how to use a combination of the `package`, `service`, and `port` InSpec audit resources to test if Memcached is installed, enabled, and running:
describe package('memcached') do
it { should be_installed }
end
describe service('memcached') do
it { should be_installed }
it { should be_enabled }
it { should be_running }
end
describe port(11_211) do
it { should be_listening }
end

View file

@ -0,0 +1,122 @@
---
title: About the parse_config Resource
---
# parse_config
Use the `parse_config` InSpec audit resource to test arbitrary configuration files.
# Syntax
A `parse_config` resource block declares the location of the configuration setting to be tested, and then what value is to be tested. Because this resource relies on arbitrary configuration files, the test itself is often arbitrary and relies on custom Ruby code:
output = command('some-command').stdout
describe parse_config(output, { data_config_option: value } ) do
its('setting') { should eq 1 }
end
or:
audit = command('/sbin/auditctl -l').stdout
options = {
assignment_re: /^\s*([^:]*?)\s*:\s*(.*?)\s*$/,
multiple_values: true
}
describe parse_config(audit, 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
# 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
None.

View file

@ -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

74
docs/resources/pip.md.erb Normal file
View file

@ -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

150
docs/resources/port.md.erb Normal file
View file

@ -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

View file

@ -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).

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -0,0 +1,149 @@
---
title: About the registry_key Resource
---
# registry_key
Use the `registry_key` InSpec audit resource to test key values in the Windows registry.
# Syntax
A `registry_key` resource block declares the item in the Windows registry, the path to a setting under that item, and then one (or more) name/value pairs to be tested.
Use a registry key name and path:
describe registry_key('Task Scheduler','HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\Schedule') do
its('Start') { should eq 2 }
end
Use only a registry key path:
describe registry_key('Task Scheduler','HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\Schedule') do
its('Start') { should eq 2 }
end
Or use a Ruby Hash:
describe registry_key({
name: 'Task Scheduler',
hive: 'HKEY_LOCAL_MACHINE',
key: ''\SYSTEM\CurrentControlSet\services\Schedule'
}) do
its('Start') { should eq 2 }
end
## Registry Key Path Separators
A Windows registry key can be used as a string in Ruby code, such as when a registry key is used as the name of a recipe. In Ruby, when a registry key is enclosed in a double-quoted string (`" "`), the same backslash character (`\`) that is used to define the registry key path separator is also used in Ruby to define an escape character. Therefore, the registry key path separators must be escaped when they are enclosed in a double-quoted string. For example, the following registry key:
HKCU\SOFTWARE\Policies\Microsoft\Windows\CurrentVersion\Themes
may be encloused in a single-quoted string with a single backslash:
'HKCU\SOFTWARE\path\to\key\Themes'
or may be enclosed in a double-quoted string with an extra backslash as an escape character:
"HKCU\\SOFTWARE\\path\\to\\key\\Themes"
# Matchers
This InSpec audit resource has the following matchers:
## be
<%= partial "/shared/matcher_be" %>
## children
The `children` matcher return all of the child items of a registry key. A regular expression may be used to filter child items:
describe registry_key('Key Name', '\path\to\key').children(regex)
...
end
For example, to get all child items for a registry key:
describe registry_key('Task Scheduler','HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet').children do
it { should_not eq [] }
end
The following example shows how find a property that may exist against multiple registry keys, and then test that property for every registry key in which that property is located:
describe registry_key({
hive: HKEY_USERS
}).children(/^S-1-5-21-[0-9]+-[0-9]+-[0-9]+-[0-9]{3,}\\Software\\Policies\\Microsoft\\Windows\\Installer/).each
{ |key|
describe registry_key(key) do
its('AlwaysInstallElevated') { should eq 'value' }
end
}
## cmp
<%= partial "/shared/matcher_cmp" %>
## eq
<%= partial "/shared/matcher_eq" %>
## exist
The `exist` matcher tests if the registry key is present:
it { should exist }
## have_property
The `have_property` matcher tests if a property exists for a registry key:
it { should have_property 'value' }
## have_property_value
The `have_property_value` matcher tests if a property value exists for a registry key:
it { should have_property_value 'value' }
## have_value
The `have_value` matcher tests if a value exists for a registry key:
it { should have_value 'value' }
## include
<%= partial "/shared/matcher_include" %>
## match
<%= partial "/shared/matcher_match" %>
## name
The `name` matcher tests the value for the specified registry setting:
its('name') { should eq 'value' }
# Examples
The following examples show how to use this InSpec audit resource.
## Test the start time for the Schedule service
describe registry_key('Task Scheduler','HKEY_LOCAL_MACHINE\...\Schedule') do
its('Start') { should eq 2 }
end
where `'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\Schedule'` is the full path to the setting.
## Use a regular expression in responses
describe registry_key({
hive: 'HKEY_LOCAL_MACHINE',
key: 'SOFTWARE\Microsoft\Windows NT\CurrentVersion'
}) do
its('ProductName') { should match /^[a-zA-Z0-9\(\)\s]*2012\s[rR]2[a-zA-Z0-9\(\)\s]*$/ }
end

View file

@ -0,0 +1,76 @@
---
title: About the runit_service Resource
---
# runit_service
Use the `runit_service` InSpec audit resource to test a service using runit.
# Syntax
A `runit_service` resource block declares the name of a service and then one (or more) matchers to test the state of the service:
describe runit_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 runit_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.

View file

@ -0,0 +1,61 @@
---
title: About the security_policy Resource
---
# security_policy
Use the `security_policy` InSpec audit resource to test security policies on the Windows platform.
# Syntax
A `security_policy` resource block declares the name of a security policy and the value to be tested:
describe security_policy do
its('policy_name') { should eq 'value' }
end
where
* `'policy_name'` must specify a security policy
* `{ should eq 'value' }` tests the value of `policy_name` against 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" %>
## policy_name
The `policy_name` matcher must be the name of a security policy:
its('SeNetworkLogonRight') { should eq '*S-1-5-11' }
# Examples
The following examples show how to use this InSpec audit resource.
## Verify that only the Administrators group has remote access
describe security_policy do
its('SeRemoteInteractiveLogonRight') { should eq '*S-1-5-32-544' }
end

View file

@ -0,0 +1,135 @@
---
title: About the service Resource
---
# service
Use the `service` InSpec audit resource to test if the named service is installed, running and/or enabled.
Under some circumstances, it may be necessary to specify the service manager by using one of the following service manager-specific resources: `bsd_service`, `launchd_service`, `runit_service`, `systemd_service`, `sysv_service`, oe `upstart_service`. These resources are based on the `service` resource.
# Syntax
A `service` resource block declares the name of a service and then one (or more) matchers to test the state of the service:
describe 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
# 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
The following examples show how to use this InSpec audit resource.
## Test if the postgresql service is both running and enabled
describe service('postgresql') do
it { should be_enabled }
it { should be_running }
end
## Test if the mysql service is both running and enabled
describe service('mysqld') do
it { should be_enabled }
it { should be_running }
end
## Test if ClamAV (an antivirus engine) is installed and running
describe package('clamav') do
it { should be_installed }
its('version') { should eq '0.98.7' }
end
describe service('clamd') do
it { should_not be_enabled }
it { should_not be_installed }
it { should_not be_running }
end
## Test Unix System V run levels
On targets that are using SystemV services, the existing run levels can also be checked:
describe service('sshd').runlevels do
its('keys') { should include(2) }
end
describe service('sshd').runlevels(2,4) do
it { should be_enabled }
end
## Override the service manager
Under some circumstances, it may be required to override the logic in place to select the right service manager. For example, to check a service managed by Upstart:
describe upstart_service('service') do
it { should_not be_enabled }
it { should be_installed }
it { should be_running }
end
This is also possible with `systemd_service`, `runit_service`, `sysv_service`, `bsd_service`, and `launchd_service`. Provide the control command when it is not to be found at the default location. For example, if the `sv` command for services managed by runit is not in the `PATH`:
describe runit_service('service', '/opt/chef/embedded/sbin/sv') do
it { should be_enabled }
it { should be_installed }
it { should be_running }
end
## Verify that IIS is running
describe service('W3SVC') do
it { should be_installed }
it { should be_running }
end

View file

@ -0,0 +1,94 @@
---
title: About the ssh_config Resource
---
# ssh_config
Use the `ssh_config` InSpec audit resource to test OpenSSH client configuration data located at `/etc/ssh/ssh_config` on Linux and Unix platforms.
# Syntax
An `ssh_config` resource block declares the client OpenSSH configuration data to be tested:
describe ssh_config('path') do
its('name') { should include('foo') }
end
where
* `name` is a configuration setting in `ssh_config`
* `('path')` is the non-default `/path/to/ssh_config`
* `{ should include('foo') }` tests the value of `name` as read from `ssh_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 `ssh_config` versus the value declared in the test:
its('name') { should eq 'foo' }
or:
its('name') { should include('bar') }
# Examples
The following examples show how to use this InSpec audit resource.
## Test SSH configuration settings
describe ssh_config do
its('cipher') { should contain '3des' }
its('port') { should eq '22' }
its('hostname') { should include('example.com') }
end
## Test which variables from the local environment are sent to the server
only_if do
command('sshd').exist? or command('ssh').exists?
end
describe ssh_config do
its('SendEnv') { should include('GORDON_CLIENT') }
end
## Test owner and group permissions
describe ssh_config do
its('owner') { should eq 'root' }
its('mode') { should cmp '0644' }
end
## Test SSH configuration
describe ssh_config do
its('Host') { should eq '*' }
its('Tunnel') { should eq nil }
its('SendEnv') { should eq 'LANG LC_*' }
its('HashKnownHosts') { should eq 'yes' }
end

View file

@ -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

133
docs/resources/ssl.md.erb Normal file
View file

@ -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

View file

@ -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

View file

@ -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.

View file

@ -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.

View file

@ -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.

154
docs/resources/user.md.erb Normal file
View file

@ -0,0 +1,154 @@
---
title: About the user Resource
---
# 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.
# 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
# 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 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' }
## include
<%= partial "/shared/matcher_include" %>
## match
<%= partial "/shared/matcher_match" %>
## 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.
# 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 }
it { should belong_to_group 'root' }
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

140
docs/resources/users.md.erb Normal file
View file

@ -0,0 +1,140 @@
---
title: About the users Resource
---
# users
Use the `users` InSpec audit resource to look up all local users available on the system, and then test specific properties of those users. This resource does not return information about users that may be located on other systems, such as LDAP or Active Directory.
# Syntax
A `users` resource block declares a user name, and then one (or more) matchers:
describe users.where(uid: 0).entries do
it { should eq ['root'] }
its('uids') { should eq [1234] }
its('gids') { should eq [1234] }
end
where
* `gid`, `group`, `groups`, `home`, `maxdays`, `mindays`, `shell`, `uid`, and `warndays` are valid matchers for this resource
* `where(uid: 0).entries` represents a filter that runs the test only against matching users
For example:
describe users.where { username =~ /.*/ } do
it { should exist }
end
or:
describe users.where { uid =~ /^S-1-5-[0-9-]+-501$/ } do
it { should exist }
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 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' }
## include
<%= partial "/shared/matcher_include" %>
## match
<%= partial "/shared/matcher_match" %>
## 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.
# Examples
The following examples show how to use this InSpec audit resource.
## Use a regular expression to find users
describe users.where { uid =~ /S\-1\-5\-21\-\d+\-\d+\-\d+\-500/ } do
it { should exist }
end

View file

@ -0,0 +1,69 @@
---
title: About the vbscript Resource
---
# vbscript
Use the `vbscript` InSpec audit resource to test a VBScript on the Windows platform.
# Syntax
A `vbscript` resource block tests the output of a VBScript on the Windows platform:
describe vbscript('script_name') do
its('stdout') { should eq 'output' }
end
where
* `'script_name'` is the name of the VBScript to test
* `('output')` is the expected output of the VBScript
# 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 a VBScript
A VBScript file similar to:
vbscript = <<-EOH
WScript.Echo "hello"
EOH
may be tested for multiple lines:
describe vbscript(vbscript) do
its('stdout') { should eq "hello\r\n" }
end
and tested for whitespace removal from standard output:
describe vbscript(vbscript) do
its('strip') { should eq "hello" }
end

View file

@ -0,0 +1,61 @@
---
title: About the windows_feature Resource
---
# windows_feature
Use the `windows_feature` InSpec audit resource to test features on Windows via the `Get-WindowsFeature` cmdlet.
# Syntax
A `windows_feature` resource block declares the name of the Windows feature, tests if that feature is installed, and then returns information about that feature:
describe windows_feature('feature_name') do
it { should be_installed }
end
where
* `('feature_name')` must specify a Windows feature name, such as `DHCP Server` or `IIS-Webserver`
* `be_installed` is a valid matcher for this resource
# Matchers
This InSpec audit resource has the following matchers:
## be
<%= partial "/shared/matcher_be" %>
## be_installed
The `be_installed` matcher tests if the named Windows feature is installed:
it { should be_installed }
## 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 the DHCP Server feature
describe windows_feature('DHCP Server') do
it{ should be_installed }
end

95
docs/resources/wmi.md.erb Normal file
View file

@ -0,0 +1,95 @@
---
title: About the wmi Resource
---
# wmi
Use the `wmi` InSpec audit resource to test WMI settings on the Windows platform.
# Syntax
A `wmi` resource block tests WMI settings on the Windows platform:
describe wmi({
class: 'class_name'
namespace: 'path\\to\\setting'
filter: 'filter'
query: 'query'
}) do
its('setting_name') { should eq '' }
end
where
* `class`, `namespace`, `filter`, and `query` comprise a Ruby Hash of the WMI object
* `('class')` is the WMI class to which the setting belongs, such as `win32_service`
* `('namespace')` is path to that object, such as `root\\cimv2`
* Use `('filter')` fine-tune the information defined by the WMI class, such as to find a specific service (`filter: "name like '%winrm%'")`, to find a specific setting (`filter: 'KeyName = \'MinimumPasswordAge\' And precedence=1'`), and so on
* Use `('query')` to run a query that returns data to be tested, such as `"SELECT Setting FROM RSOP_SecuritySettingBoolean WHERE KeyName='LSAAnonymousNameLookup' AND Precedence=1"`
* `('setting_name')` is a setting in the WMI object to be tested, and then `should eq ''` is the expected value for that setting
For example, both of the following tests will verify if WinRM is present on the target node. The first tests if WinRM belongs to the list of services running under the `win32_service` class:
describe wmi({class: 'win32_service'}) do
its('DisplayName') { should include 'Windows Remote Management (WS-Management)'}
end
and the second uses a filter in the Ruby Hash to first identify WinRM, and then perform additional tests:
describe wmi({
class: 'win32_service',
filter: "name like '%winrm%'"
}) do
its('Status') { should cmp 'ok' }
its('State') { should cmp 'Running' }
its('ExitCode') { should cmp 0 }
its('DisplayName') { should eq 'Windows Remote Management (WS-Management)'}
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" %>
## include
<%= partial "/shared/matcher_include" %>
## match
<%= partial "/shared/matcher_match" %>
# Examples
The following examples show how to use this InSpec audit resource.
## Test a password expiration policy
describe wmi({
class: 'RSOP_SecuritySettingNumeric',
namespace: 'root\\rsop\\computer',
filter: 'KeyName = \'MinimumPasswordAge\' And precedence=1'
}) do
its('Setting') { should eq 1 }
end
## Test if an anonymous user can query the Local Security Authority (LSA)
describe wmi({
namespace: 'root\rsop\computer',
query: "SELECT Setting FROM RSOP_SecuritySettingBoolean WHERE KeyName='LSAAnonymousNameLookup' AND Precedence=1"
}) do
its('Setting') { should eq false }
end

View file

@ -0,0 +1,170 @@
---
title: About the xinetd_conf Resource
---
# xinetd_conf
Use the `xinetd_conf` InSpec audit resource to test services under `/etc/xinet.d` on Linux and Unix platforms. xinetd---the extended Internet service daemon---listens on all ports, and then loads the appropriate program based on a request. The `xinetd.conf` file is typically located at `/etc/xinetd.conf` and contains a list of Internet services associated to the ports on which that service will listen. Only enabled services may handle a request; only services that are required by the system should be enabled.
# Syntax
An `xinetd_conf` resource block declares settings found in a `xinetd.conf` file for the named service:
describe xinetd_conf('service_name') do
it { should be_enabled } # or be_disabled
its('setting') { should eq 'value' }
end
where
* `'service_name'` is a service located under `/etc/xinet.d`
* `('setting')` is a setting in the `xinetd.conf` file
* `should eq 'value'` is the value that is expected
# Matchers
This InSpec audit resource has the following matchers:
## be
<%= partial "/shared/matcher_be" %>
## be_enabed
The `be_enabled` matcher tests if a service listed under `/etc/xinet.d` is enabled:
it { should be_enabled }
## cmp
<%= partial "/shared/matcher_cmp" %>
## eq
<%= partial "/shared/matcher_eq" %>
## ids
The `ids` matcher tests if the named service is located under `/etc/xinet.d`:
its('ids') { should include 'service_name' }
For example:
its('ids') { should include 'chargen-stream chargen-dgram'}
## include
<%= partial "/shared/matcher_include" %>
## match
<%= partial "/shared/matcher_match" %>
## services
The `services` matcher tests if the named service is listed under `/etc/xinet.d`:
its('services') { should include 'service_name' }
## socket_types
The `socket_types` matcher tests if a service listed under `/etc/xinet.d` is configured to use the named socket type:
its('socket_types') { should eq 'socket' }
where `socket` is one of `dgram`, `raw`, or `stream`. For a UDP-based service:
its('socket_types') { should eq 'dgram' }
For a raw socket (such as a service using a non-standard protocol or a service that requires direct access to IP):
its('socket_types') { should eq 'raw' }
For a TCP-based service:
its('socket_types') { should eq 'stream' }
## types
The `types` matcher tests the service type:
its('type') { should eq 'TYPE' }
where `'TYPE'` is `INTERNAL` (for a service provided by xinetd), `RPC` (for a service based on remote procedure call), or `UNLISTED` (for services not under `/etc/services` or `/etc/rpc`).
## wait
The `wait` matcher tests how a service handles incoming connections.
For UDP (`dgram`) socket types the `wait` matcher should test for `yes`:
its('socket_types') { should eq 'dgram' }
its('wait') { should eq 'yes' }
For TCP (`stream`) socket types the `wait` matcher should test for `no`:
its('socket_types') { should eq 'stream' }
its('wait') { should eq 'no' }
# Examples
The following examples show how to use this InSpec audit resource.
## Test a socket_type
The network socket type: `dgram` (a datagram-based service), `raw` (a service that requires direct access to an IP address), `stream` (a stream-based service), or `seqpacket` (a service that requires a sequenced packet).
describe xinetd_conf.services('service_name') do
its('socket_types') { should include 'dgram' }
end
## Test a service type
The type of service: `INTERNAL` (a service provided by xinetd), `RPC` (an RPC-based service), `TCPMUX` (a service that is started on a well-known TPCMUX port), or `UNLISTED` (a service that is not listed in a standard system file location).
describe xinetd_conf.services('service_name') do
its('type') { should include 'RPC' }
end
## Test the telnet service
For example, a `telnet` file under `/etc/xinet.d` contains the following settings:
service telnet
{
disable = yes
flags = REUSE
socket_type = stream
wait = no
user = root
server = /usr/sbin/in.telnetd
log_on_failure += USERID
}
Some examples of tests that can be run against that file include:
describe xinetd_conf.services('telnet') do
it { should be_disabled }
end
and
describe xinetd_conf.services('telnet') do
its('socket_type') { should include 'stream' }
end
and
describe xinetd_conf.services('telnet') do
its('wait') { should eq 'no' }
end
All three settings can be tested in the same block as well:
describe xinetd_conf.services('telnet') do
it { should be_disabled }
its('socket_type') { should include 'stream' }
its('wait') { should eq 'no' }
end

View file

@ -0,0 +1,69 @@
---
title: About the yaml Resource
---
# yaml
Use the `yaml` InSpec audit resource to test configuration data in a Yaml file.
# Syntax
A `yaml` resource block declares the configuration data to be tested. Assume the following Yaml file:
name: foo
array:
- zero
- one
This file can be queried using:
describe yaml do
its('name') { should eq 'foo' }
its(['array', 1]) { should eq 'one' }
end
where
* `name` is a configuration setting in a Yaml file
* `should eq 'foo'` tests a value of `name` as read from a Yaml file 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 a Yaml file versus the value declared in the test:
its('name') { should eq 'foo' }
# Examples
The following examples show how to use this InSpec audit resource.
## Test a kitchen.yml file driver
describe yaml('.kitchen.yaml') do
its('driver.name') { should eq('vagrant') }
end

103
docs/resources/yum.md.erb Normal file
View file

@ -0,0 +1,103 @@
---
title: About the yum Resource
---
# yum
Use the `yum` InSpec audit resource to test packages in the Yum repository.
# Syntax
A `yum` resource block declares a package repo, tests if the package repository is present, and if it that package repository is a valid package source (i.e. "is enabled"):
describe yum.repo('name') do
it { should exist }
it { should be_enabled }
end
where
* `repo('name')` is the (optional) name of a package repo, using either a full identifier (`'updates/7/x86_64'`) or a short identifier (`'updates'`)
# Matchers
This InSpec audit resource has the following matchers:
## be
<%= partial "/shared/matcher_be" %>
## be_enabled
The `be_enabled` matcher tests if the package repository is a valid package source:
it { should be_enabled }
## cmp
<%= partial "/shared/matcher_cmp" %>
## eq
<%= partial "/shared/matcher_eq" %>
## exist
The `exist` matcher tests if the package repository exists:
it { should exist }
## include
<%= partial "/shared/matcher_include" %>
## match
<%= partial "/shared/matcher_match" %>
## repo('name')
The `repo('name')` matcher names a specific package repository:
describe yum.repo('epel') do
...
end
## repos
The `repos` matcher tests if a named repo, using either a full identifier (`'updates/7/x86_64'`) or a short identifier (`'updates'`), is included in the Yum repo:
its('repos') { should include 'some_repo' }
## shortname
The `shortname` matcher names a specific package repository's group identifier. For example, if a repository's group name is "Directory Server", the corresponding group idenfier is typically "directory-server":
describe yum.repo('Directory Server') do
its('shortname') { should eq 'directory-server' }
end
# Examples
The following examples show how to use this InSpec audit resource.
## Test if the yum repo exists
describe yum do
its('repos') { should exist }
end
## Test if the 'base/7/x86_64' repo exists and is enabled
describe yum do
its('repos') { should include 'base/7/x86_64' }
its('epel') { should exist }
its('epel') { should be_enabled }
end
## Test if a specific yum repo exists
describe yum.repo('epel') do
it { should exist }
it { should be_enabled }
end

View file

@ -0,0 +1 @@
Use the `be` matcher to use a comparison operator---`=` (equal to), `>` (greater than), `<` (less than), `>=` (greater than or equal to), and `<=` (less than or equal to)---to compare two values: `its('value') { should be >= value }`, `its('value') { should be < value }`, and so on.

View file

@ -0,0 +1,45 @@
Use the `cmp` matcher compare two values, such as comparing strings to numbers, comparing a single value to an array of values, comparing an array of strings to a regular expression, improving the printing of octal values, and comparing while ignoring case sensitivity.
Compare a single value to an array:
describe some_resource do
its('users') { should cmp 'root' }
its('users') { should cmp ['root'] }
end
Compare strings and regular expressions:
describe some_resource do
its('setting') { should cmp /raw/i }
end
Compare strings and numbers:
describe some_resource do
its('setting') { should eq '2' }
end
vs:
describe some_resource do
its('setting') { should cmp '2' }
its('setting') { should cmp 2 }
end
Ignoring case sensitivity:
.. code-block:: ruby
describe some_resource do
its('setting') { should cmp 'raw' }
its('setting') { should cmp 'RAW' }
end
Printing octal values:
describe some_resource('/proc/cpuinfo') do
its('mode') { should cmp '0345' }
end
expected: 0345
got: 0444

View file

@ -0,0 +1,3 @@
Use the `eq` matcher to test the equality of two values: `its('Port') { should eq '22' }`.
Using `its('Port') { should eq 22 }` will fail because `22` is not a string value! Use the `cmp` matcher for less restrictive value comparisons.

View file

@ -0,0 +1 @@
Use the `include` matcher to verify that a string value is included in a list: `its('list') { should include 'string' }`.

View file

@ -0,0 +1 @@
Use the `match` matcher to check if a string matches a regular expression: `its('string') { should_not match /regex/ }`.