inspec 1.40.0 → 1.41.0

data/docs/resources/docker_image.md.erb

@@ -6,6 +6,8 @@ title: About the docker_image Resource
 
 Use the `docker_image` InSpec audit resource to verify a docker image.
 
+<br>
+
 ## Syntax
 
 A `docker_image` resource block declares the image:
@@ -35,10 +37,27 @@ You can also pass in repository and tag as separate values
       ...
     end
 
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec `docker_image` resource.
+
+### Test a docker image
+
+    describe docker_image('alpine:latest') do
+      it { should exist }
+      its('id') { should eq 'sha256:4a415e...a526' }
+      its('image') { should eq 'alpine:latest' }
+      its('repo') { should eq 'alpine' }
+      its('tag') { should eq 'latest' }
+    end
+
+<br>
 
 ## Matchers
 
-This InSpec audit resource has the following matchers:
+This InSpec audit resource has the following matchers. For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
 
 ### exist
 
@@ -69,18 +88,3 @@ The `repo` matcher tests the value of the repository name:
 The `tag` matcher tests the value of image tag:
 
     its('tag') { should eq 'latest' }
-
-
-## Examples
-
-The following examples show how to use this InSpec `docker_image` resource.
-
-### Test a docker image
-
-    describe docker_image('alpine:latest') do
-      it { should exist }
-      its('id') { should eq 'sha256:4a415e...a526' }
-      its('image') { should eq 'alpine:latest' }
-      its('repo') { should eq 'alpine' }
-      its('tag') { should eq 'latest' }
-    end

data/docs/resources/etc_fstab.md.erb

@@ -5,13 +5,14 @@ title: About the etc_fstab Resource
 # etc_fstab
 
 Use the `etc_fstab` InSpec audit resource to test information about all partitions and storage devices on a system.
+
+<br>
+
 ## Syntax
 
 An etc_fstab rule specifies a device name, its mount point, its mount type, the options its mounted with,
 its dump options, and the order the files system should be checked.
 
-## Syntax
-
 Use the where clause to match a property to one or more rules in the fstab file.
 
     describe etc_fstab.where { device_name == 'value' } do
@@ -91,6 +92,8 @@ where
       its('file_system_options') { should cmp 0 }
     end
 
+<br>
+
 ## Examples
 
 The following examples show how to use this InSpec resource.

data/docs/resources/etc_group.md.erb

@@ -6,6 +6,8 @@ title: About the etc_group Resource
 
 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.
 
+<br>
+
 ## Syntax
 
 A `etc_group` resource block declares a collection of properties to be tested:
@@ -28,21 +30,40 @@ where
 * `.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:
+## 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
 
-### be
+    describe etc_group do
+      its('users') { should include 'my_user' }
+    end
 
-<%= partial "/shared/matcher_be" %>
+### Filter a list of groups for a specific user
 
-### cmp
+    describe etc_group.where(name: 'my_group') do
+      its('users') { should include 'my_user' }
+    end
 
-<%= partial "/shared/matcher_cmp" %>
+<br>
 
-### eq
+## Matchers
 
-<%= partial "/shared/matcher_eq" %>
+This InSpec audit resource has the following matchers. For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
 
 ### gids
 
@@ -56,14 +77,6 @@ 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:
@@ -85,32 +98,3 @@ where `item` may be one (or more) of:
 * `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

data/docs/resources/etc_hosts.md.erb

@@ -9,6 +9,8 @@ Use the `etc_hosts` InSpec audit resource to test rules set to match IP addresse
 
 An etc/hosts rule specifies an IP address and what its hostname is along with optional aliases it can have.
 
+<br>
+
 ## Syntax
 
 Use the where clause to match a property to one or more rules in the hosts file.
@@ -31,10 +33,14 @@ where
 * `primary_name` is the name associated with the ip address.
 * `all_host_names` is a list including the primary_name as the first entry followed by any aliase names the host has.
 
+<br>
+
 ## Supported Properties
 
     'ip_address', 'primary_name', 'all_host_names'
 
+<br>
+
 ## Property Examples and Return Types
 
 ### ip_address

data/docs/resources/etc_hosts_allow.md.erb

@@ -6,13 +6,13 @@ title: About the etc_hosts_allow Resource
 
 Use the `etc_hosts_allow` InSpec audit resource to test rules set to accept daemon and client traffic set in /etc/hosts.allow file.
 
+<br>
+
 ## Syntax
 
 An etc/hosts.allow rule specifies one or more daemons mapped to one or more clients,
 with zero or more options to use to accept traffic when found.
 
-## Syntax
-
 Use the where clause to match a property to one or more rules in the hosts.allow file.
 
     describe etc_hosts_allow.where { daemon == 'value' } do
@@ -33,10 +33,14 @@ where
 * `client_list` is a list of clients will be allowed to pass traffic in.
 * `options` is a list of tasks that to be done with the rule when traffic is found.
 
+<br>
+
 ## Supported Properties
 
     'daemon', 'client_list', 'options'
 
+<br>
+
 ## Property Examples and Return Types
 
 ### daemon

data/docs/resources/etc_hosts_deny.md.erb

@@ -6,13 +6,13 @@ title: About the etc_hosts_deny Resource
 
 Use the `etc_hosts_deny` InSpec audit resource to test rules set to reject daemon and client traffic set in /etc/hosts.deny.
 
+<br>
+
 ## Syntax
 
 An etc/hosts.deny rule specifies one or more daemons mapped to one or more clients,
 with zero or more options to use to reject traffic when found.
 
-## Syntax
-
 Use the where clause to match a property to one or more rules in the hosts.deny file.
 
     describe etc_hosts_deny.where { daemon == 'value' } do
@@ -33,10 +33,14 @@ where
 * `client_list` is a list of clients will be rejected to pass traffic in.
 * `options` is a list of tasks that to be done with the rule when traffic is found.
 
+<br>
+
 ## Supported Properties
 
     'daemon', 'client_list', 'options'
 
+<br>
+
 ## Property Examples and Return Types
 
 ### daemon

data/docs/resources/file.md.erb

@@ -6,6 +6,8 @@ title: About the file Resource
 
 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.
 
+<br>
+
 ## 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:
@@ -20,14 +22,183 @@ where
 * `MATCHER` is a valid matcher for this resource
 * `'value'` is the value to be tested
 
+<br>
 
-## Matchers
+## 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 cmp '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 cmp '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 cmp 'character' }
+      it { should be_character_device }
+      it { should_not be_file }
+      it { should_not be_directory }
+    end
 
-This InSpec audit resource has the following matchers:
+### Test if a file is a block device
 
-### be
+    describe file('/dev/zero') do
+      its('type') { should cmp 'block' }
+      it { should be_character_device }
+      it { should_not be_file }
+      it { should_not be_directory }
+    end
 
-<%= partial "/shared/matcher_be" %>
+### 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('/') do
+      its('mtime') { should <= Time.now.to_i }
+      its('mtime') { 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
+
+### Test parameters of symlinked file
+
+If you need to test the parameters of the target file for a symlink, you can use the `link_path` method for the `file` resource.
+
+For example, for the following symlink:
+
+    lrwxrwxrwx. 1 root root 11 03-10 17:56 /dev/virtio-ports/com.redhat.rhevm.vdsm -> ../vport2p1
+
+... you can write controls for both the link and the target.
+
+    describe file('/dev/virtio-ports/com.redhat.rhevm.vdsm') do
+      it { should be_symlink }
+    end
+
+    virito_port_vdsm = file('/dev/virtio-ports/com.redhat.rhevm.vdsm').link_path
+    describe file(virito_port_vdsm) do
+      it { should exist }
+      it { should be_character_device }
+      it { should be_owned_by 'ovirtagent' }
+      it { should be_grouped_into 'ovirtagent' }
+    end
+
+<br>
+
+## Matchers
+
+This InSpec audit resource has the following matchers. For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
 
 ### be\_block\_device
 
@@ -137,7 +308,7 @@ a user:
 
 The `be_setgid` matcher tests if the 'setgid' permission is set on the file or directory.  On executable files, this causes the process to be started owned by the group that owns the file, rather than the primary group of the invocating user.  This can result in escalation of privilege.  On Linux, when setgid is set on directories, setgid causes newly created files and directories to be owned by the group that owns the setgid parent directory; additionally, newly created subdirectories will have the setgid bit set.  To use this matcher:
 
-    it { should be_setgid } 
+    it { should be_setgid }
 
 ### be_socket
 
@@ -149,13 +320,13 @@ The `be_socket` matcher tests if the file exists as socket (`.sock`), such as `/
 
 The `be_sticky` matcher tests if the 'sticky bit' permission is set on the directory.  On directories, this restricts file deletion to the owner of the file, even if the permission of the parent directory would normally permit deletion by others.  This is commonly used on /tmp filesystems.  To use this matcher:
 
-    it { should be_sticky } 
+    it { should be_sticky }
 
 ### be_setuid
 
 The `be_setuid` matcher tests if the 'setuid' permission is set on the file.  On executable files, this causes the process to be started owned by the user that owns the file, rather than invocating user.  This can result in escalation of privilege.  To use this matcher:
 
-    it { should be_setuid } 
+    it { should be_setuid }
 
 ### be_symlink
 
@@ -191,10 +362,6 @@ 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:
@@ -209,10 +376,6 @@ The following complete example tests the `pg_hba.conf` file in PostgreSQL for MD
       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:
@@ -237,10 +400,6 @@ 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. If the file is a symlink,
@@ -248,10 +407,6 @@ InSpec will resolve the symlink and return the ultimate linked file:
 
     its('link_path') { 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:
@@ -266,15 +421,11 @@ The `mode` matcher tests if the mode assigned to the file matches the specified
 
 ### 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:
+The `mtime` matcher tests if the file modification time for the file matches the specified value. The mtime, where supported, is returned as the number of seconds since the epoch.
 
-    describe file('/').mtime.to_i do
-      it { should <= Time.now.to_i }
-      it { should >= Time.now.to_i - 1000}
+    describe file('/') do
+      its('mtime') { should <= Time.now.to_i }
+      its('mtime') { should >= Time.now.to_i - 1000 }
     end
 
 ### owner
@@ -317,191 +468,26 @@ Less than:
 
 ### type
 
-The `type` matcher tests if the first letter of the file's mode string contains one of the following characters:
+The `type` matcher tests for the file type. The available types are:
+
+* `file`: the object is a file
+* `directory`: the object is a directory
+* `link`: the object is a symbolic link
+* `pipe`: the object is a named pipe
+* `socket`: the object is a socket
+* `character_device`: the object is a character device
+* `block_device`: the object is a block device
+* `door`: the object is a door device
 
-* `-` 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
+The `type` method usually returns the type as a Ruby "symbol". We recommend using the `cmp` matcher to match
+either by symbol or string.
 
 For example:
 
-    its('type') { should eq 'file' }
+    its('type') { should eq :file }
+    its('type') { should cmp '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
-
-### Test parameters of symlinked file
-
-If you need to test the parameters of the target file for a symlink, you can use the `link_path` method for the `file` resource.
-
-For example, for the following symlink:
-
-    lrwxrwxrwx. 1 root root 11 03-10 17:56 /dev/virtio-ports/com.redhat.rhevm.vdsm -> ../vport2p1
-
-... you can write controls for both the link and the target.
-
-    describe file('/dev/virtio-ports/com.redhat.rhevm.vdsm') do
-      it { should be_symlink }
-    end
-
-    virito_port_vdsm = file('/dev/virtio-ports/com.redhat.rhevm.vdsm').link_path
-    describe file(virito_port_vdsm) do
-      it { should exist }
-      it { should be_character_device }
-      it { should be_owned_by 'ovirtagent' }
-      it { should be_grouped_into 'ovirtagent' }
-    end
+    its('type') { should eq :socket }
+    its('type') { should cmp 'socket' }