inspec 0.34.1 → 1.0.0

data/docs/resources/npm.md.erb

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

data/docs/resources/ntp_conf.md.erb

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

data/docs/resources/oneget.md.erb

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

data/docs/resources/os.md.erb

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

data/docs/resources/os_env.md.erb

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

data/docs/resources/package.md.erb

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

data/docs/resources/parse_config.md.erb

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