inspec 0.34.1 → 1.0.0

data/docs/resources/grub_conf.md.erb

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

data/docs/resources/host.md.erb

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

data/docs/resources/iis_site.md.erb

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

data/docs/resources/inetd_conf.md.erb

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

data/docs/resources/ini.md.erb

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

data/docs/resources/interface.md.erb

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

data/docs/resources/iptables.md.erb

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