inspec 1.31.0 → 1.45.9

data/docs/resources/elasticsearch.md.erb

@@ -0,0 +1,245 @@
+---
+title: The Elasticsearch Resource
+---
+
+# elasticsearch
+
+The `elasticsearch` resource allows testing of a node status against a running
+Elasticsearch cluster. InSpec will retrieve the node list from the cluster node URL
+provided (defaults to `http://localhost:9200`) and provide the ability to query
+a variety of settings and statuses.
+
+## Syntax
+
+    describe elasticsearch do
+      its('property') { should cmp 'value' }
+    end
+
+The `elasticsearch` resource accepts a number of optional values:
+
+ * `url`: the top-level URL of an Elasticsearch node in the cluster. If your Elasticsearch installation is not served out of the top-level directory at the host, be sure to specific the full URL; for example: `http://my-load-balancer/elasticsearch`. Default: `http://localhost:9200`
+ * `username`: a username to use to log in with HTTP-Basic authentication. If `username` is provided, a `password` must also be provided.
+ * `password`: a password to use to log in with HTTP-Basic authentication. If `password` is provided, a `username` must also be provided.
+ * `ssl_verify`: if `false`, SSL certificate validation will be disabled. Default: `true`
+
+In addition, the `elasticsearch` resource allows for filtering the nodes returned by property before executing the tests:
+
+    describe elasticsearch.where { node_name == 'one-off-node' } do
+      its('version') { should eq '1.2.3' }
+    end
+
+    describe elasticsearch.where { process.mlockall == false } do
+      its('count') { should cmp 0 }
+    end
+
+To simply check if nodes exist that match the criteria, use the `exist` matcher:
+
+    describe elasticsearch.where { cluster_name == 'my_cluster' } do
+      it { should exist }
+    end
+
+## Supported Properties
+
+The following properties are provided:
+
+* build_hash
+* cluster_name
+* host
+* http
+* ingest
+* ip
+* jvm
+* module_list
+* modules
+* node_name
+* node_id
+* os
+* plugin_list
+* plugins
+* process
+* roles
+* settings
+* total_indexing_buffer
+* transport
+* transport_address
+* version
+
+Since the `elasticsearch` resource is meant for use on a cluster, each property will return an array of the values for each node that matches any provided search criteria. Using InSpec's `cmp` matcher will help avoid any issues when trying to compare values for when a single match is returned (i.e. when the cluster only contains a single node, or the `where` filter criteria provided only returns a single node).
+
+## Property Examples
+
+### build_hash
+
+Returns the build hash for each of the nodes.
+
+    describe elasticsearch do
+      its('build_hash') { should cmp 'b2f0c09' }
+    end
+
+### cluster_name
+
+Returns the cluster names of each of the nodes.
+
+    describe elasticsearch do
+      its('cluster_name') { should cmp 'my_cluster' }
+    end
+
+### host
+
+Returns the hostname of each of the nodes. This may return an IP address of the node is not properly performing DNS resolution or has no hostname set.
+
+    describe elasticsearch do
+      its('host') { should cmp 'my.hostname.mycompany.biz' }
+    end
+
+### http
+
+Returns a hash of HTTP-related settings for each of the nodes. In this example, the `first` method is used to grab only the first node's HTTP-related info and is a way of removing the item from the Array if only one node is being queried.
+
+    describe elasticsearch do
+      its('http.first.max_content_length_in_bytes') { should cmp 123456 }
+    end
+
+### ingest
+
+Returns ingest-related settings and capabilities, such as available processors.
+
+    describe elasticsearch do
+      its('ingest.first.processors.count') { should be >= 1 }
+    end
+
+### ip
+
+Returns the IP address of each of the nodes.
+
+    describe elasticsearch do
+      its('ip') { should cmp '192.168.1.100' }
+    end
+
+### jvm
+
+Returns Java Virtual Machine related parameters for each of the nodes.
+
+    describe elasticsearch do
+      its('jvm.first.version') { should cmp '1.8.0_141' }
+    end
+
+### module_list
+
+Returns a list of enabled modules for each node in the cluster. For more additional information about each module, use the `modules` property.
+
+    describe elasticsearch do
+      its('module_list.first') { should include 'my_module' }
+    end
+
+### modules
+
+Returns detailed information about each enabled module for each node in the cluster. For a succint list of the names of each of the modules enabled, use the `module_list` property. This example uses a bit of additional Ruby to find a specific module and assert a value.
+
+    modules = elasticsearch.modules.first
+    lang_groovy_module = modules.find { |mod| mod.name == 'lang-groovy' }
+
+    describe 'lang-groovy module version' do
+      subject { lang_groovy_module }
+      its('version') { should cmp '5.5.2' }
+    end
+
+### node_name
+
+Returns the node name for each node in the cluster.
+
+    describe elasticsearch do
+      its('node_name') { should cmp 'node1' }
+    end
+
+### node_id
+
+Returns the node IDs of each of the nodes in the cluster.
+
+    describe elasticsearch do
+      its('node_id') { should include 'my_node_id' }
+    end
+
+### os
+
+Returns OS-related information about each node in the cluster.
+
+    describe elasticsearch do
+      its('os.first.arch') { should cmp 'amd64' }
+    end
+
+### plugin_list
+
+Returns a list of enabled plugins for each node in the cluster. For more additional information about each plugin, use the `plugins` property.
+
+    describe elasticsearch do
+      its('plugin_list.first') { should include 'my_plugin' }
+    end
+
+### plugins
+
+Returns detailed information about each enabled plugin for each node in the cluster. For a succint list of the names of each of the plugins enabled, use the `plugin_list` property. This example uses a bit of additional Ruby to find a specific plugin and assert a value.
+
+    plugins = elasticsearch.plugins.first
+    my_plugin = plugins.find { |plugin| plugin.name == 'my_plugin' }
+
+    describe 'my_plugin plugin version' do
+      subject { my_plugin }
+      its('version') { should cmp '1.2.3' }
+    end
+
+### process
+
+Returns process information for each node in the cluster, such as the process ID.
+
+    describe elasticsearch do
+      its('process.first.mlockall') { should cmp true }
+    end
+
+### roles
+
+Returns the role for each of the nodes in the cluster.
+
+    describe elasticsearch.where { node_name == 'my_master_node' } do
+      it { should include 'master' }
+    end
+
+### settings
+
+Returns all the configuration settings for each node in the cluster. These settings usually include those set in the elasticsearch.yml as well as those set via `-Des.` or `-E` flags at startup. Use the `inspec shell` to explore the various setting keys that are available.
+
+    describe elasticsearch do
+      its('settings.first.path.home') { should cmp '/usr/share/elasticsearch' }
+    end
+
+### total_indexing_buffer
+
+Returns the total indexing buffer for each node in the cluster.
+
+    describe elasticsearch do
+      its('total_indexing_buffer') { should cmp 123456 }
+    end
+
+### transport
+
+Returns transport-related settings for each node in the cluster, such as the bound and published addresses.
+
+    describe elasticsearch do
+      its('transport.first.bound_address') { should cmp '1.2.3.4:9200' }
+    end
+
+### transport_address
+
+Returns the bound transport address for each node in the cluster.
+
+    describe elasticsearch do
+      its('transport_address') { should cmp '1.2.3.4:9200' }
+    end
+
+### version
+
+Returns the version of Elasticsearch running on each node of the cluster.
+
+    describe elasticsearch do
+      its('version') { should cmp '5.5.2' }
+    end

data/docs/resources/etc_fstab.md.erb

@@ -0,0 +1,120 @@
+---
+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.
+
+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
+      its('mount_point') { should cmp 'hostname' }
+      its('file_system_type') { should cmp 'list' }
+      its('mount_options') { should cmp 'list' }
+      its('dump_options') { should cmp 'list' }
+      its('file_system_options') { should cmp 'list' }
+    end
+
+Use the optional constructor parameter to give an alternative path to fstab file
+
+    describe etc_fstab(hosts_path).where { device_name == 'value' } do
+      its('mount_point') { should cmp 'hostname' }
+      its('file_system_type') { should cmp 'list' }
+      its('mount_options') { should cmp 'list' }
+      its('dump_options') { should cmp 'list' }
+      its('file_system_options') { should cmp 'list ' }
+    end
+
+where
+
+* `device_name` is the name associated with the device.
+* `mount_point` is the directory at which the filesystem is configured to be mounted.
+* `file_system_type` is the type of file system of the device or partition.
+* `mount_options` is the options for the device or partition.
+* `dump_options` is a number used by dump to decide if a file system should be backed up.
+* `file_system_options` is a number that specifies the order the file system should be checked.
+
+## Property Examples and Return Types
+
+### device_name
+
+`device_name` returns a string array of device names mounted on the system.
+
+    describe etc_fstab.where { mount_point == '/mnt/sr0' } do
+      its('device_name') { should cmp '/dev/sr0' }
+    end
+
+### mount_point
+
+`mount_point` returns a string array of directorys at which filesystems are configured to be mounted.
+
+    describe etc_fstab.where { device_name == '/dev/sr0' } do
+      its('mount_point') { should cmp '/mnt/sr0' }
+    end
+
+### file_system_type
+
+`file_system_type` returns a String array of each partitions file system type.
+
+    describe etc_fstab.where { device_name == '/dev/sr0' } do
+      its('file_system_type') { should cmp 'iso9660' }
+    end
+
+### mount_options
+
+`mount_options` returns a two dimensional array of each partitions mount options.
+
+    describe etc_fstab.where { mount_point == '/' } do
+      its('mount_options') { should eq [['defaults', 'x-systemd.device-timeout=0']] }
+    end
+
+### dump_options
+
+`dump_options` returns a integer array of each partitions dump option.
+
+    describe etc_fstab.where { device_name == '/dev/sr0' } do
+      its('dump_options') { should cmp 0 }
+    end
+
+### file_system_options
+
+`file_system_options` returns a integer array of each partitions file system option.
+
+    describe etc_fstab.where { device_name == '/dev/sr0' } do
+      its('file_system_options') { should cmp 0 }
+    end
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec resource.
+
+### Check all partitions that have type of 'nfs'.
+
+    nfs_systems = etc_fstab.nfs_file_systems.entries
+    nfs_systems.each do |partition|
+      describe partition do
+        its('mount_options') { should include 'nosuid' }
+      end
+    end
+
+### Check the partition mounted at /home contains 'nosuid' in its mount_options.
+
+    describe etc_fstab do
+      its('home_mount_options') { should include 'nosuid' }
+    end
+
+### Check if a partition is mounted at a point.
+
+    describe etc_fstab.where { mount_point == '/home' } do
+      it { should be_configured }
+    end

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

@@ -0,0 +1,68 @@
+---
+title: About the etc_hosts Resource
+---
+
+# etc_hosts
+
+Use the `etc_hosts` InSpec audit resource to test rules set to match IP addresses with hostnames.
+## Syntax
+
+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.
+
+    describe etc_hosts.where { ip_address == 'value' } do
+      its('primary_name') { should cmp 'hostname' }
+      its('all_host_names') { should cmp 'list' }
+    end
+
+Use the optional constructor parameter to give an alternative path to hosts file
+
+    describe etc_hosts('path/to/hosts').where { ip_address == 'value' } do
+      its('primary_name') { should cmp 'hostname' }
+      its('all_host_names') { should cmp 'list' }
+    end
+
+where
+
+* `ip_address` is the ip address of the hostname in either ipv4 or ipv6 format.
+* `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
+
+`ip_address` returns a string array of ip addresses specified in the etc/hosts file.
+
+    describe etc_hosts.where { primary_name == 'localhost' } do
+      its('ip_address') { should cmp '127.0.1.154' }
+    end
+
+### primary_name
+
+`primary_name` returns a string array of primary_names specified in the etc/hosts file.
+
+    describe etc_hosts.where { ip_address == '::1' } do
+      its('primary_name') { should cmp 'localhost' }
+    end
+
+### all_host_names
+
+`all_host_names` returns a two dimensional string array where each entry has the primary_name first followed by any aliases.
+
+    describe etc_hosts.where { ip_address == '127.0.1.154' } do
+      its('all_host_names') { should eq [['localhost', 'localhost.localdomain', 'localhost4', 'localhost4.localdomain4'],  ['localhost', 'localhost.localdomain', 'localhost6', 'localhost6.localdomain6']] }
+    end

data/docs/resources/etc_hosts_allow.md.erb

@@ -0,0 +1,68 @@
+---
+title: About the etc_hosts_allow Resource
+---
+
+# etc_hosts_allow
+
+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.
+
+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
+      its ('client_list') { should include ['values'] }
+      its ('options') { should include ['values'] }
+    end
+
+Use the optional constructor parameter to give an alternative path to hosts.allow
+
+    describe etc_hosts_allow(hosts_path).where { daemon == 'value' } do
+      its ('client_list') { should include ['values'] }
+      its ('options') { should include ['values'] }
+    end
+
+where
+
+* `daemon` is a daemon that will be allowed to pass traffic in.
+* `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
+
+`daemon` returns a string containing the daemon that is allowed in the rule.
+
+    describe etc_hosts_allow.where { client_list == ['127.0.1.154',  '[:fff:fAb0::]'] } do
+      its('daemon') { should eq ['vsftpd', 'sshd'] }
+    end
+
+### client_list
+
+`client_list` returns a 2d string array where each entry contains the clients specified for the rule.
+
+    describe etc_hosts_allow.where { daemon == 'sshd' } do
+      its('client_list') { should include ['192.168.0.0/16', '[abcd::0000:1234]'] }
+    end
+
+### options
+
+`options` returns a 2d string array where each entry contains any options specified for the rule.
+
+    describe etc_hosts_allow.where { daemon == 'sshd' } do
+      its('options') { should include ['deny', 'echo "REJECTED"'] }
+    end

data/docs/resources/etc_hosts_deny.md.erb

@@ -0,0 +1,68 @@
+---
+title: About the etc_hosts_deny Resource
+---
+
+# etc_hosts_deny
+
+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.
+
+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
+      its ('client_list') { should include ['values'] }
+      its ('options') { should include ['values'] }
+    end
+
+Use the optional constructor parameter to give an alternative path to hosts.deny
+
+    describe etc_hosts_deny(hosts_path).where { daemon == 'value' } do
+      its ('client_list') { should include ['values'] }
+      its ('options') { should include ['values'] }
+    end
+
+where
+
+* `daemon` is a daemon that will be rejected to pass traffic in.
+* `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
+
+`daemon` returns a string containing the daemon that is allowed in the rule.
+
+    describe etc_hosts_deny.where { client_list == ['127.0.1.154',  '[:fff:fAb0::]'] } do
+      its('daemon') { should eq ['vsftpd', 'sshd'] }
+    end
+
+### client_list
+
+`client_list` returns a 2d string array where each entry contains the clients specified for the rule.
+
+    describe etc_hosts_deny.where { daemon == 'sshd' } do
+      its('client_list') { should include ['192.168.0.0/16', '[abcd::0000:1234]'] }
+    end
+
+### options
+
+`options` returns a 2d string array where each entry contains any options specified for the rule.
+
+    describe etc_hosts_deny.where { daemon == 'sshd' } do
+      its('options') { should include ['deny', 'echo "REJECTED"'] }
+    end