inspec 1.0.0.beta2 → 1.0.0.beta3

data/docs/resources/mysql_session.md.erb

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

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