inspec 1.0.0 → 1.35.1

data/docs/resources/file.md.erb

@@ -6,7 +6,7 @@ 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.
 
-# Syntax
+## 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:
 
@@ -21,33 +21,33 @@ where
 * `'value'` is the value to be tested
 
 
-# Matchers
+## Matchers
 
 This InSpec audit resource has the following matchers:
 
-## be
+### be
 
 <%= partial "/shared/matcher_be" %>
 
-## be_block_device
+### 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
+### 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
+### 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
+### be_executable
 
 The `be_executable` matcher tests if the file exists as an executable:
 
@@ -65,49 +65,49 @@ a user:
 
     it { should be_executable.by_user('user') }
 
-## be_file
+### 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
+### 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
+### be_immutable
 
 The `be_immutable` matcher tests if the file is immutable, i.e. "cannot be changed":
 
     it { should be_immutable }
 
-## be_linked_to
+### 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
+### be_mounted
 
 The `be_mounted` matcher tests if the file is accessible from the file system:
 
     it { should be_mounted }
 
-## be_owned_by
+### 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
+### 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
+### be_readable
 
 The `be_readable` matcher tests if the file is readable:
 
@@ -125,25 +125,25 @@ a user:
 
     it { should be_readable.by_user('user') }
 
-## be_socket
+### 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
+### 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
+### be_version
 
 The `be_version` matcher tests the version of the file:
 
     it { should be_version '1.2.3' }
 
-## be_writable
+### be_writable
 
 The `be_writable` matcher tests if the file is writable:
 
@@ -161,11 +161,11 @@ a user:
 
     it { should be_writable.by_user('user') }
 
-## cmp
+### cmp
 
 <%= partial "/shared/matcher_cmp" %>
 
-## content
+### 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:
 
@@ -179,67 +179,67 @@ 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
+### eq
 
 <%= partial "/shared/matcher_eq" %>
 
-## exist
+### exist
 
 The `exist` matcher tests if the named file exists:
 
     it { should exist }
 
-## file_version
+### 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
+### group
 
 The `group` matcher tests if the group to which a file belongs matches the specified value:
 
     its('group') { should eq 'admins' }
 
-## have_mode
+### have_mode
 
 The `have_mode` matcher tests if a file has a mode assigned to it:
 
     it { should have_mode }
 
-## include
+### include
 
 <%= partial "/shared/matcher_include" %>
 
-## link_path
+### 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
+### 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
+### match
 
 <%= partial "/shared/matcher_match" %>
 
-## md5sum
+### md5sum
 
 The `md5sum` matcher tests if the MD5 checksum for a file matches the specified value:
 
     its('md5sum') { should eq '3329x3hf9130gjs9jlasf2305mx91s4j' }
 
-## mode
+### mode
 
 The `mode` matcher tests if the mode assigned to the file matches the specified value:
 
     its('mode') { should cmp '0644' }
 
-## mtime
+### mtime
 
 The `mtime` matcher tests if the file modification time for the file matches the specified value:
 
@@ -252,31 +252,31 @@ or:
       it { should >= Time.now.to_i - 1000}
     end
 
-## owner
+### owner
 
 The `owner` matcher tests if the owner of the file matches the specified value:
 
     its('owner') { should eq 'root' }
 
-## product_version
+### 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
+### 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
+### sha256sum
 
 The `sha256sum` matcher tests if the SHA-256 checksum for a file matches the specified value:
 
     its('sha256sum') { should eq 'b837ch38lh19bb8eaopl8jvxwd2e4g58jn9lkho1w3ed9jbkeicalplaad9k0pjn' }
 
-## size
+### size
 
 The `size` matcher tests if a file's size matches, is greater than, or is less than the specified value. For example, equal:
 
@@ -290,7 +290,7 @@ Less than:
 
     its('size') { should < 10240 }
 
-## type
+### type
 
 The `type` matcher tests if the first letter of the file's mode string contains one of the following characters:
 
@@ -311,11 +311,11 @@ or:
 
     its('type') { should eq 'socket' }
 
-# Examples
+## Examples
 
 The following examples show how to use this InSpec audit resource.
 
-## Test the contents of a file for MD5 requirements
+### 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/ }
@@ -323,26 +323,26 @@ The following examples show how to use this InSpec audit resource.
       its('content') { should match %r{/host\s.*?all\s.*?all\s.*?::1\/128\s.*?md5/} }
     end
 
-## Test if a file exists
+### Test if a file exists
 
     describe file('/tmp') do
      it { should exist }
     end
 
-## Test that a file does not exist
+### Test that a file does not exist
 
     describe file('/tmpest') do
      it { should_not exist }
     end
 
-## Test if a path is a directory
+### 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
+### Test if a path is a file and not a directory
 
     describe file('/proc/version') do
       its('type') { should eq 'file' }
@@ -350,7 +350,7 @@ The following examples show how to use this InSpec audit resource.
       it { should_not be_directory }
     end
 
-## Test if a file is a symbolic link
+### Test if a file is a symbolic link
 
     describe file('/dev/stdout') do
       its('type') { should eq 'symlink' }
@@ -359,7 +359,7 @@ The following examples show how to use this InSpec audit resource.
       it { should_not be_directory }
     end
 
-## Test if a file is a character device
+### Test if a file is a character device
 
     describe file('/dev/zero') do
       its('type') { should eq 'character' }
@@ -368,7 +368,7 @@ The following examples show how to use this InSpec audit resource.
       it { should_not be_directory }
     end
 
-## Test if a file is a block device
+### Test if a file is a block device
 
     describe file('/dev/zero') do
       its('type') { should eq 'block' }
@@ -377,51 +377,51 @@ The following examples show how to use this InSpec audit resource.
       it { should_not be_directory }
     end
 
-## Test the mode for a file
+### Test the mode for a file
 
     describe file('/dev') do
      its('mode') { should cmp '00755' }
     end
 
-## Test the owner of a file
+### 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
+### 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
+### 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
+### 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
+### 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
+### Test that a file is not mounted
 
     describe file('/proc/cpuinfo') do
       it { should_not be_mounted }
     end
 
-## Test an MD5 checksum
+### Test an MD5 checksum
 
     require 'digest'
     cpuinfo = file('/proc/cpuinfo').content
@@ -432,7 +432,7 @@ The following examples show how to use this InSpec audit resource.
       its('md5sum') { should eq md5sum }
     end
 
-## Test an SHA-256 checksum
+### Test an SHA-256 checksum
 
     require 'digest'
     cpuinfo = file('/proc/cpuinfo').content
@@ -443,7 +443,7 @@ The following examples show how to use this InSpec audit resource.
       its('sha256sum') { should eq sha256sum }
     end
 
-## Verify NTP
+### 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:
 
@@ -458,3 +458,25 @@ The following example shows how to use the `file` audit resource to verify if th
     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

data/docs/resources/gem.md.erb

@@ -6,68 +6,87 @@ title: About the gem Resource
 
 Use the `gem` InSpec audit resource to test if a global Gem package is installed.
 
-# Syntax
+## Syntax
 
 A `gem` resource block declares a package and (optionally) a package version:
 
-    describe gem('gem_package_name') do
+    describe gem('gem_package_name', 'gem_binary') do
       it { should be_installed }
     end
 
 where
 
 * `('gem_package_name')` must specify a Gem package, such as `'rubocop'`
+* `('gem_binary')` can specify the path to a non-default gem binary, defaults to `'gem'`
 * `be_installed` is a valid matcher for this resource
 
-# Matchers
+## Matchers
 
 This InSpec audit resource has the following matchers:
 
-## be
+### be
 
 <%= partial "/shared/matcher_be" %>
 
-## be_installed
+### be_installed
 
 The `be_installed` matcher tests if the named Gem package is installed:
 
     it { should be_installed }
 
-## cmp
+### cmp
 
 <%= partial "/shared/matcher_cmp" %>
 
-## eq
+### eq
 
 <%= partial "/shared/matcher_eq" %>
 
-## include
+### include
 
 <%= partial "/shared/matcher_include" %>
 
-## match
+### match
 
 <%= partial "/shared/matcher_match" %>
 
-## version
+### version
 
 The `version` matcher tests if the named package version is on the system:
 
     its('version') { should eq '0.33.0' }
 
-# Examples
+## Examples
 
 The following examples show how to use this InSpec audit resource.
 
-## Verify that a gem package is installed, with a specific version
+### 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
+### Verify that a gem package is not installed
 
     describe gem('rubocop') do
       it { should_not be_installed }
     end
+
+### Verify that a gem package is installed in an omnibus environment
+
+    describe gem('pry', '/opt/ruby-2.3.1/embedded/bin/gem') do
+      it { should be_installed }
+    end
+
+### Verify that a gem package is installed in a chef omnibus environment
+
+    describe gem('chef-sugar', :chef) do
+      it { should be_installed }
+    end
+
+### Verify that a gem package is installed in a chef-server omnibus environment
+
+    describe gem('knife-backup', :chef_server) do
+      it { should be_installed }
+    end

data/docs/resources/group.md.erb

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

data/docs/resources/grub_conf.md.erb

@@ -6,7 +6,7 @@ title: About the grub_conf Resource
 
 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
+## Syntax
 
 A `grub_conf` resource block declares a list of settings in a `grub.conf` file:
 
@@ -29,35 +29,35 @@ where
 * `'value'` is the value that is expected
 
 
-# Matchers
+## Matchers
 
 This InSpec audit resource has the following matchers:
 
-## be
+### be
 
 <%= partial "/shared/matcher_be" %>
 
-## cmp
+### cmp
 
 <%= partial "/shared/matcher_cmp" %>
 
-## eq
+### eq
 
 <%= partial "/shared/matcher_eq" %>
 
-## include
+### include
 
 <%= partial "/shared/matcher_include" %>
 
-## match
+### match
 
 <%= partial "/shared/matcher_match" %>
 
-# Examples
+## Examples
 
 The following examples show how to use this InSpec audit resource.
 
-## Test a grub.conf file
+### Test a grub.conf file
 
 A Grub configuration file located at `/etc/grub.conf` is similar to the following:
 
@@ -99,7 +99,7 @@ The following test verifies the `ramdisk_size` for the non-deault kernel:
        its('kernel') { should include 'ramdisk_size=400000' }
      end
 
-## Test a configuration file and boot configuration
+### 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' }
@@ -108,7 +108,7 @@ The following test verifies the `ramdisk_size` for the non-deault kernel:
       its('timeout') { should eq '5' }
     end
 
-## Test a specific kernel
+### 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' }