Mirrors/inspec
2
0
Fork 0
mirror of https://github.com/inspec/inspec synced 2024-11-10 15:14:23 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #5677 from inspec/vasundhara/docs-update-for-resource-properties

Browse source 
Fix docs to make property listing in the website docs more useful.
This commit is contained in:
Clinton Wolfe 2021-11-20 01:59:35 -05:00 committed by GitHub
commit f6d4272da1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
20 changed files with 452 additions and 346 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
docs-chef-io/content/inspec/resources/aide_conf.md
View file

@ -49,13 +49,29 @@ Use the where clause to match a selection_line to one rule or a particular set o
## Properties
- `conf_path`, `content`, `rules`, `all_have_rule`
### `rules`
## Property Examples
The `rules` property returns the list of rules set in the `aide.conf` file.
its('rules') { should include ['r', 'sha512'] }
### `all_have_rule`
The `all_have_rule` property returns the all selected lines from `aide.conf` file e.g. 'p', 'i' etc.
aide_conf.all_have_rule('sha512')
### `selection_lines`
The `selection_lines` property returns the list of lines from `aide.conf` file.
its('selection_lines') { should include '/sbin' }
## Examples
The following examples show how to use this Chef InSpec audit resource.
### Test if all selection lines contain the xattr rule
### Test if all selection lines contain the `xattr` rule
describe aide_conf.all_have_rule('xattr') do
it { should eq true }
@ -67,7 +83,7 @@ The following examples show how to use this Chef InSpec audit resource.
its('rules.flatten') { should include 'r' }
end
### Test whether selection line for /sbin consists of a particular set of rules
### Test whether the selection line for `/sbin` consists of a particular set of rules
describe aide_conf.where { selection_line == '/sbin' } do
its('rules') { should include ['r', 'sha512'] }

12
docs-chef-io/content/inspec/resources/bash.md
View file

@ -48,27 +48,21 @@ For example:
## Properties
- `exit_status`
- `stderr`
- `stdout`
## Property Examples
### exit_status
The `exit_status` property tests the exit status for the command:
The `exit_status` property returns the exit status for the command.
its('exit_status') { should eq 0 }
### stderr
The `stderr` property tests results of the command as returned in standard error (stderr):
The `stderr` property returns results of the command as returned in standard error (stderr).
its('stderr') { should eq '' }
### stdout
The `stdout` property tests results of the command as returned in standard output (stdout).
The `stdout` property returns the results of the command as returned in standard output (stdout).
its('stdout') { should match /bin/ }

14
docs-chef-io/content/inspec/resources/bond.md
View file

@ -36,34 +36,34 @@ where
- `'name'` is the name of the bonded network interface
- `{ should exist }` is a valid matcher for this resource
## Property Examples
The following examples show how to use this Chef InSpec audit resource.
## Properties
### content
The `content` matcher tests if contents in the file that defines the bonded network interface match the value specified in the test. The values of the `content` matcher are arbitrary.
The `content` property returns the contents in the file that defines the bonded network interface. The values of the `content` property are arbitrary.
its('content') { should match('value') }
### interfaces
The `interfaces` matcher tests if the named secondary interfaces are available.
The `interfaces` property tests if the named secondary interfaces are available.
its('interfaces') { should eq ['eth0', 'eth1', ...] }
### mode
The `mode` matcher tests the Bonding Mode.
The `mode` property returns the Bonding Mode.
its('mode') { should eq 'IEEE 802.3ad Dynamic link aggregation' }
### params
The `params` matcher tests arbitrary parameters for the bonded network interface.
The `params` property returns arbitrary parameters for the bonded network interface.
its('params') { should eq 'value' }
## Examples
### Test if eth0 is a secondary interface for bond0
describe bond('bond0') do

10
docs-chef-io/content/inspec/resources/bridge.md
View file

@ -11,7 +11,7 @@ platform = "linux"
parent = "inspec/resources/os"
+++
Use the `bridge` Chef InSpec audit resource to test basic network bridge properties, such as name, if an interface is defined, and the associations for any defined interface.
Use the `bridge` Chef InSpec audit resource to test basic network bridge properties, such as `name`, if an interface is defined, and the associations for any defined interface.
## Availability
@ -32,19 +32,15 @@ A `bridge` resource block declares the bridge to be tested and what interface it
it { should have_interface 'eth0' }
end
## Properties
- On Linux platforms, any value in the `/sys/class/net/{interface}/bridge` directory may be tested
- On the Windows platform, the `Get-NetAdapter` cmdlet is associated with the `Get-NetAdapterBinding` cmdlet and returns the `ComponentID ms_bridge` value as a JSON object
## Property Examples
## Properties
### interfaces
The `interfaces` property tests if the named interface is present:
The `interfaces` property returns the named interfaces.
its('interfaces') { should eq 'foo' }
its('interfaces') { should eq 'bar' }
its('interfaces') { should include('foo') }
## Matchers

8
docs-chef-io/content/inspec/resources/bsd_service.md
View file

@ -36,11 +36,11 @@ A `bsd_service` resource block declares the name of a service and then one (or m
where
- `('service_name')` must specify a service name
- `be_installed`, `be_enabled`, and `be_running` are valid matchers for this resource.
- `be_installed`, `be_enabled`, and `be_running` are the different [matchers](#matchers) for this resource.
### Using `bsd_service` resource parameters
## Parameters
#### Path
### Path
The path to the service manager's control may be specified for situations where the path isn't available in the current `PATH`. For example:
@ -52,7 +52,7 @@ The path to the service manager's control may be specified for situations where
## Properties
All properties available to the `service` resource may be used.
All properties available to the [`service`](/inspec/resources/service/) resource may be used.
## Matchers

142
docs-chef-io/content/inspec/resources/dh_params.md
View file

@ -39,31 +39,51 @@ A `dh_params` resource block declares a parameter file to be tested.
## Properties
- `generator`
- `modulus`
- `prime_length`
- `pem`
- `text`
## Property Examples
### generator (Integer)
Verify generator used for the Diffie-Hellman operation:
The `generator` property returns generator used for the Diffie-Hellman operation.
its('generator') { should eq 2 }
### modulus (String)
The `modulus` property returns the prime modulus used for the Diffie-Hellman operation.
its('modulus') { should eq '00:91:a0:15:89:e5:bc:38:93:12:02:fc:...' }
### prime_length (Integer)
The `prime_length` property returns the length of prime modulus used for the Diffie-Hellman operation.
its('prime_length') { should eq 2048 }
### pem (String)
The `pem` property returns the pem formatted value of DH parameters.
its('pem') { should eq '-----BEGIN DH PARAMETERS...' }
### text (String)
The `text` property returns the value of DH parameters in text format.
its('text') { should eq 'PKCS#3 DH Parameters: (2048 bit)...' }
## Examples
### Test generator used for the Diffie-Hellman operation:
describe dh_params('/path/to/file.dh_pem') do
its('generator') { should eq 2 }
end
### modulus (String)
Verify prime modulus used for the Diffie-Hellman operation:
### Test prime modulus used for the Diffie-Hellman operation:
describe dh_params('/path/to/file.dh_pem') do
its('modulus') { should eq '00:91:a0:15:89:e5:bc:38:93:12:02:fc:...' }
end
Example using multi-line string:
### Test example using multi-line string:
```ruby
describe dh_params('/path/to/file.dh_pem') do
@ -93,41 +113,40 @@ describe dh_params('/path/to/file.dh_pem') do
end
```
### prime_length (Integer)
Verify length of prime modulus used for the Diffie-Hellman operation:
### Test length of prime modulus used for the Diffie-Hellman operation:
describe dh_params('/path/to/file.dh_pem') do
its('prime_length') { should eq 2048 }
end
### pem (String)
Verify `pem` output of DH parameters:
### Test `pem` output of DH parameters:
describe dh_params('/path/to/file.dh_pem') do
its('pem') { should eq '-----BEGIN DH PARAMETERS...' }
end
Example using multi-line string:
### Test example using multi-line string:
```ruby
its('pem') do
# regex removes all leading spaces
should eq <<-EOF.gsub(/^[[:blank:]]+/, '')
-----BEGIN DH PARAMETERS-----
MIIBCAKCAQEAkaAVieW8OJMSAvyRooX39yljLtNOeob37oT+QtBIvJyR1VT4eB3A
QXiixKwaJIudiFWYC6ynI+vCqisuqfmv1I5OEbx/NaKs2jrv8CVsmqT9ACh2hixX
h2cwXbHWWyKPcqHq3ovvnjMaQJJohQJUAgn6wGDBPE4oJtvtJY44IVZA3MDAZh8r
MsO0eKkmlOr3QSiy9VsBOAxGCYUmTWkSjZUPNeLmTkc6ht2Ksv5FFSfYWcI89GL/
X3Tpd5JQRzYrBVdg7nuhYMwceit3GIo398cxPhXLFX97Zpb7xr591gNeDWB1K1ti
KqM3tjT5/pZM9sXjoVKvAcFPx0Kgvu3NEwIBAg==
-----END DH PARAMETERS-----
EOF
describe dh_params('/path/to/file.dh_pem') do
its('pem') do
# regex removes all leading spaces
should eq <<-EOF.gsub(/^[[:blank:]]+/, '')
-----BEGIN DH PARAMETERS-----
MIIBCAKCAQEAkaAVieW8OJMSAvyRooX39yljLtNOeob37oT+QtBIvJyR1VT4eB3A
QXiixKwaJIudiFWYC6ynI+vCqisuqfmv1I5OEbx/NaKs2jrv8CVsmqT9ACh2hixX
h2cwXbHWWyKPcqHq3ovvnjMaQJJohQJUAgn6wGDBPE4oJtvtJY44IVZA3MDAZh8r
MsO0eKkmlOr3QSiy9VsBOAxGCYUmTWkSjZUPNeLmTkc6ht2Ksv5FFSfYWcI89GL/
X3Tpd5JQRzYrBVdg7nuhYMwceit3GIo398cxPhXLFX97Zpb7xr591gNeDWB1K1ti
KqM3tjT5/pZM9sXjoVKvAcFPx0Kgvu3NEwIBAg==
-----END DH PARAMETERS-----
EOF
end
end
```
Verify via `openssl dhparam` command:
### Test via `openssl dhparam` command:
$ openssl dhparam -in /path/to/file.dh_pem
-----BEGIN DH PARAMETERS-----
@ -139,46 +158,47 @@ Verify via `openssl dhparam` command:
KqM3tjT5/pZM9sXjoVKvAcFPx0Kgvu3NEwIBAg==
-----END DH PARAMETERS-----
### text (String)
Verify human-readable text output of DH parameters:
### Test human-readable text output of DH parameters:
describe dh_params('/path/to/file.dh_pem') do
its('text') { should eq 'PKCS#3 DH Parameters: (2048 bit)...' }
end
Example using multi-line string:
### Test example using multi-line string:
```ruby
its('text') do
# regex removes 2 leading spaces
should eq <<-EOF.gsub(/^[[:blank:]]{2}/, '')
PKCS#3 DH Parameters: (2048 bit)
prime:
00:91:a0:15:89:e5:bc:38:93:12:02:fc:91:a2:85:
f7:f7:29:63:2e:d3:4e:7a:86:f7:ee:84:fe:42:d0:
48:bc:9c:91:d5:54:f8:78:1d:c0:41:78:a2:c4:ac:
1a:24:8b:9d:88:55:98:0b:ac:a7:23:eb:c2:aa:2b:
2e:a9:f9:af:d4:8e:4e:11:bc:7f:35:a2:ac:da:3a:
ef:f0:25:6c:9a:a4:fd:00:28:76:86:2c:57:87:67:
30:5d:b1:d6:5b:22:8f:72:a1:ea:de:8b:ef:9e:33:
1a:40:92:68:85:02:54:02:09:fa:c0:60:c1:3c:4e:
28:26:db:ed:25:8e:38:21:56:40:dc:c0:c0:66:1f:
2b:32:c3:b4:78:a9:26:94:ea:f7:41:28:b2:f5:5b:
01:38:0c:46:09:85:26:4d:69:12:8d:95:0f:35:e2:
e6:4e:47:3a:86:dd:8a:b2:fe:45:15:27:d8:59:c2:
3c:f4:62:ff:5f:74:e9:77:92:50:47:36:2b:05:57:
60:ee:7b:a1:60:cc:1c:7a:2b:77:18:8a:37:f7:c7:
31:3e:15:cb:15:7f:7b:66:96:fb:c6:be:7d:d6:03:
5e:0d:60:75:2b:5b:62:2a:a3:37:b6:34:f9:fe:96:
4c:f6:c5:e3:a1:52:af:01:c1:4f:c7:42:a0:be:ed:
cd:13
generator: 2 (0x2)
EOF
describe dh_params('/path/to/file.dh_pem') do
its('text') do
# regex removes 2 leading spaces
should eq <<-EOF.gsub(/^[[:blank:]]{2}/, '')
PKCS#3 DH Parameters: (2048 bit)
prime:
00:91:a0:15:89:e5:bc:38:93:12:02:fc:91:a2:85:
f7:f7:29:63:2e:d3:4e:7a:86:f7:ee:84:fe:42:d0:
48:bc:9c:91:d5:54:f8:78:1d:c0:41:78:a2:c4:ac:
1a:24:8b:9d:88:55:98:0b:ac:a7:23:eb:c2:aa:2b:
2e:a9:f9:af:d4:8e:4e:11:bc:7f:35:a2:ac:da:3a:
ef:f0:25:6c:9a:a4:fd:00:28:76:86:2c:57:87:67:
30:5d:b1:d6:5b:22:8f:72:a1:ea:de:8b:ef:9e:33:
1a:40:92:68:85:02:54:02:09:fa:c0:60:c1:3c:4e:
28:26:db:ed:25:8e:38:21:56:40:dc:c0:c0:66:1f:
2b:32:c3:b4:78:a9:26:94:ea:f7:41:28:b2:f5:5b:
01:38:0c:46:09:85:26:4d:69:12:8d:95:0f:35:e2:
e6:4e:47:3a:86:dd:8a:b2:fe:45:15:27:d8:59:c2:
3c:f4:62:ff:5f:74:e9:77:92:50:47:36:2b:05:57:
60:ee:7b:a1:60:cc:1c:7a:2b:77:18:8a:37:f7:c7:
31:3e:15:cb:15:7f:7b:66:96:fb:c6:be:7d:d6:03:
5e:0d:60:75:2b:5b:62:2a:a3:37:b6:34:f9:fe:96:
4c:f6:c5:e3:a1:52:af:01:c1:4f:c7:42:a0:be:ed:
cd:13
generator: 2 (0x2)
EOF
end
end
```
Verify via `openssl dhparam` command:
### Test via `openssl dhparam` command:
$ openssl dhparam -in /path/to/file.dh_pem -noout -text
PKCS#3 DH Parameters: (2048 bit)

8
docs-chef-io/content/inspec/resources/docker_plugin.md
View file

@ -38,17 +38,13 @@ The resource allows you to pass in an plugin id:
The `id` property returns the full plugin id:
describe docker_plugin('cloudstor/aws') do
its('id') { should eq '0ac30b93ad40' }
end
its('id') { should eq '0ac30b93ad40' }
### version
The `version` property tests the value of plugin version:
describe docker_plugin('cloudstor/aws') do
its('version') { should eq '0.11.0' }
end
its('version') { should eq '0.11.0' }
## Examples

232
docs-chef-io/content/inspec/resources/elasticsearch.md
View file

@ -34,10 +34,10 @@ This resource first became available in v1.43.5 of InSpec.
## Supported Resource Parameters
The `elasticsearch` resource accepts a number of optional resource parameters:
The `elasticsearch` resource accepts several optional resource parameters:
`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`
: 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 specify 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.
@ -66,81 +66,139 @@ To simply check if nodes exist that match the criteria, use the `exist` matcher:
## Properties
The following properties are provided:
The following are the different properties of the resource:
- 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 helps avoid issues when comparing values when there is only a single match (i.e. when the cluster only contains a single node, or the `where` filter criteria provided only returns a single node).
## Property Examples
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 helps avoid issues when comparing values when there is only a single match (i.e. when the cluster only contains a single node or the `where` filter criteria provided only returns a single node).
### build_hash
Returns the build hash for each of the nodes.
The `build hash` property returns the build hash for each of the nodes.
describe elasticsearch do
its('build_hash') { should cmp 'b2f0c09' }
end
its('build_hash') { should cmp 'b2f0c09' }
### cluster_name
Returns the cluster names of each of the nodes.
The `cluster_name` property returns the cluster names of each of the nodes.
describe elasticsearch do
its('cluster_name') { should cmp 'my_cluster' }
end
its('cluster_name') { should cmp 'my_cluster' }
### host
Returns the hostname of each of the nodes. This may return an IP address, if the node is improperly performing DNS resolution or has no hostname set.
The `host` property returns the hostname of each of the nodes. This may return an IP address if the node is improperly performing DNS resolution or has no hostname set.
describe elasticsearch do
its('host') { should cmp 'my.hostname.mycompany.biz' }
end
its('host') { should cmp 'my.hostname.mycompany.biz' }
### 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.
The `http` property 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
its('http.first.max_content_length_in_bytes') { should cmp 123456 }
### ingest
Returns ingest-related settings and capabilities, such as available processors.
The `ingest` property returns ingest-related settings and capabilities, such as available processors.
describe elasticsearch do
its('ingest.first.processors.count') { should be >= 1 }
end
its('ingest.first.processors.count') { should be >= 1 }
### ip
Returns the IP address of each of the nodes.
The `ip` property returns the IP address of each of the nodes.
describe elasticsearch do
its('ip') { should cmp '192.168.1.100' }
end
its('ip') { should cmp '192.168.1.100' }
### jvm
Returns Java Virtual Machine related parameters for each of the nodes.
The `jvm` property 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
its('jvm.first.version') { should cmp '1.8.0_141' }
### 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.
The `module_list` property returns a list of enabled modules for each node in the cluster.
describe elasticsearch do
its('module_list.first') { should include 'my_module' }
end
its('module_list.first') { should include 'my_module' }
### modules
Returns detailed information about each enabled module for each node in the cluster. For a succinct list of the names of each of the modules enabled, use the `module_list` property. This example uses additional Ruby to find a specific module and assert a value.
The `modules` property returns detailed information about each enabled module for each node in the cluster.
its('modules.first') { should include 'lang-groovy' }
### node_name
The `node_name` property returns the node name for each node in the cluster.
its('node_name') { should cmp 'node1' }
### node_id
The `node_id` property returns the node IDs of each of the nodes in the cluster.
its('node_id') { should include 'my_node_id' }
### os
The `os` property returns OS-related information about each node in the cluster.
its('os.first.arch') { should cmp 'amd64' }
### plugin_list
The `plugin_list` property returns a list of enabled plugins for each node in the cluster. For more additional information about each plugin, use the `plugins` property.
its('plugin_list.first') { should include 'my_plugin' }
### plugins
The `plugins` property returns detailed information about each enabled plugin for each node in the cluster.
its('plugins.first') { should include 'my_plugin' }
### process
The `process` property returns process information for each node in the cluster, such as the process ID.
its('process.first.mlockall') { should cmp true }
### roles
The `roles` property returns the role for each of the nodes in the cluster.
its('roles') { should include 'master' }
### settings
The `settings` property 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.
its('settings.first.path.home') { should cmp '/usr/share/elasticsearch' }
### total_indexing_buffer
The `total_indexing_buffer` property returns the total indexing buffer for each node in the cluster.
its('total_indexing_buffer') { should cmp 123456 }
### transport
The `transport` property returns transport-related settings for each node in the cluster, such as the bound and published addresses.
its('transport.first.bound_address') { should cmp '1.2.3.4:9200' }
### transport_address
The `transport_address` property returns the bound transport address for each node in the cluster.
its('transport_address') { should cmp '1.2.3.4:9200' }
### version
The `version` property returns the version of Elasticsearch running on each node of the cluster.
its('version') { should cmp '5.5.2' }
## Examples
### Test to verify the specific module. Uses additional Ruby to find a specific module and assert a value. For a succinct list of the names of each of the modules enabled, use the `module_list` property.
modules = elasticsearch.modules.first
lang_groovy_module = modules.find { |mod| mod.name == 'lang-groovy' }
@ -150,41 +208,7 @@ Returns detailed information about each enabled module for each node in the clus
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 succinct list of the names of each of the plugins enabled, use the `plugin_list` property. This example uses additional Ruby to find a specific plugin and assert a value.
### Tests to verify the specific plugin. Uses additional Ruby to find a specific plugin and assert a value. For a succinct list of the names of each of the plugins enabled, use the `plugin_list` property.
plugins = elasticsearch.plugins.first
my_plugin = plugins.find { |plugin| plugin.name == 'my_plugin' }
@ -194,62 +218,6 @@ Returns detailed information about each enabled plugin for each node in the clus
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
## Matchers
For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).

29
docs-chef-io/content/inspec/resources/etc_fstab.md
View file

@ -25,8 +25,8 @@ This resource first became available in v1.37.6 of InSpec.
## 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.
An etc_fstab rule specifies a device name, its mount point, its mount type, the options it mounted with,
its dump options and the files system options should be checked.
Use the where clause to match a property to one or more rules in the fstab file:
@ -50,18 +50,9 @@ Use the optional constructor parameter to give an alternative path to fstab file
## Properties
- `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
### device_name
`device_name` returns a string array of device names mounted on the system.
The `device_name` property returns a string array including the device names mounted on the system.
describe etc_fstab.where { mount_point == '/mnt/sr0' } do
its('device_name') { should cmp '/dev/sr0' }
@ -69,7 +60,7 @@ Use the optional constructor parameter to give an alternative path to fstab file
### mount_point
`mount_point` returns a string array of directories at which filesystems are configured to be mounted.
The `mount_point` property returns a string array including the path of directories at which filesystems are configured to be mounted.
describe etc_fstab.where { device_name == '/dev/sr0' } do
its('mount_point') { should cmp '/mnt/sr0' }
@ -77,7 +68,7 @@ Use the optional constructor parameter to give an alternative path to fstab file
### file_system_type
`file_system_type` returns a String array of each partitions file system type.
The `file_system_type` property returns a string array including each device or partitions file system type.
describe etc_fstab.where { device_name == '/dev/sr0' } do
its('file_system_type') { should cmp 'iso9660' }
@ -85,7 +76,7 @@ Use the optional constructor parameter to give an alternative path to fstab file
### mount_options
`mount_options` returns a two dimensional array of each partitions mount options.
The `mount_options` property returns a two dimensional array of each partition's mount options.
describe etc_fstab.where { mount_point == '/' } do
its('mount_options') { should eq [['defaults', 'x-systemd.device-timeout=0']] }
@ -93,7 +84,7 @@ Use the optional constructor parameter to give an alternative path to fstab file
### dump_options
`dump_options` returns a integer array of each partitions dump option.
The `dump_options` property returns an integer array of each partitions dump option. This is a number used by dump to decide if a file system should be backed up.
describe etc_fstab.where { device_name == '/dev/sr0' } do
its('dump_options') { should cmp 0 }
@ -101,13 +92,15 @@ Use the optional constructor parameter to give an alternative path to fstab file
### file_system_options
`file_system_options` returns a integer array of each partitions file system option.
The `file_system_options` property returns an integer array of each partitions file system option. This is a number that specifies the order in which the file system should be checked.
describe etc_fstab.where { device_name == '/dev/sr0' } do
its('file_system_options') { should cmp 0 }
end
### Check all partitions that have type of 'nfs'
## Examples
### Check all partitions that have a type of 'nfs'
nfs_systems = etc_fstab.nfs_file_systems.entries
nfs_systems.each do |partition|

22
docs-chef-io/content/inspec/resources/etc_group.md
View file

@ -11,7 +11,7 @@ platform = "linux"
parent = "inspec/resources/os"
+++
Use the `etc_group` Chef 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.
Use the `etc_group` Chef 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-separated list of users that belong to the group.
## Availability
@ -41,14 +41,30 @@ or:
where
- `('path')` is the non-default path to the `inetd.conf` file
- `('path')` is the non-default path to the `\etc\group` file
- `.where()` filters for a specific item and value, to which the parameter are compared
- `.where` filter may be one or more of:
- `name: 'name'`, `group_name: 'group_name'`, `password: 'password'`, `gid: 'gid'`, `group_id: 'gid'`, `users: 'user_name'`, `members: 'member_name'`
## Properties
- `'gids'`, `'groups'`, and `'users'` are valid resource parameters for this resource.
### gids
The `gids` property returns the list of gids from `/etc/group` file.
its('gids') { should include 'gid' }
### groups
The `groups` property returns the list of groups from `/etc/group` file.
its('groups') { should include 'my_group' }
### users
The `users` property returns the list of users from `/etc/group `file.
its('users') { should include 'my_user' }
## Examples

37
docs-chef-io/content/inspec/resources/etc_hosts.md
View file

@ -45,35 +45,44 @@ Use the optional resource parameter to give an alternative path to the hosts fil
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.
- `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 alias names the host has.
## Properties
'ip_address', 'primary_name', 'all_host_names'
## Property Examples
### ip_address
`ip_address` returns a string array of ip addresses specified in the etc/hosts file.
The `ip_address` property returns a string array of ip addresses specified in the etc/hosts file.
its('ip_address') { should cmp '127.0.1.154' }
### primary_name
The `primary_name` property returns a string array of primary_names specified in the etc/hosts file.
its('primary_name') { should cmp 'localhost' }
### all_host_names
The `all_host_names` property returns a two-dimensional string array where each entry has the primary_name first followed by any aliases.
its('all_host_names') { should cmp 'list' }
##Examples
### Test the IP address of the given primary name 'localhost'.
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.
### Test the primay name for where ip address is '::1'
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.
### Test the list of primary names and their aliases for the given IP address.
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']] }

25
docs-chef-io/content/inspec/resources/etc_hosts_allow.md
View file

@ -25,16 +25,16 @@ This resource first became available in v1.39.1 of InSpec.
## Syntax
An etc/hosts.allow rule specifies one or more daemons mapped to one or more clients, with zero or more options to for accepting traffic when found.
An etc/hosts.allow rule specifies one or more daemons mapped to one or more clients, with zero or more options for accepting traffic when found.
Use the where clause to match a property to one or more rules in the hosts.allow file.
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'] }
its ('options') { should include ['values'] }p
end
Use the optional constructor parameter to give an alternative path to hosts.allow
Use the optional constructor parameter to give an alternative path to `hosts.allow` file.
describe etc_hosts_allow(hosts_path).where { daemon == 'value' } do
its ('client_list') { should include ['values'] }
@ -43,21 +43,14 @@ Use the optional constructor parameter to give an alternative path to hosts.allo
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.
- `daemon` is a filter that will be allowed to pass traffic in.
- `client_list`, `options` are the valid resource properties that test the list of clients who will be allowed to pass traffic in, and a list of tasks that are to be done with the rule when traffic is found respectively.
## Properties
- `daemon`
- `client_list`
- `options`
## Property Examples
### daemon
`daemon` returns a string containing the daemon that is allowed in the rule.
The `daemon` property 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'] }
@ -65,7 +58,7 @@ where
### client_list
`client_list` returns a 2d string array where each entry contains the clients specified for the rule.
The `client_list` property 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]'] }
@ -73,7 +66,7 @@ where
### options
`options` returns a 2d string array where each entry contains any options specified for the rule.
The `options` property 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"'] }

18
docs-chef-io/content/inspec/resources/etc_hosts_deny.md
View file

@ -25,7 +25,7 @@ This resource first became available in v1.39.1 of InSpec.
## Syntax
An etc/hosts.deny rule specifies one or more daemons mapped to one or more clients, with zero or more options for rejecting traffic when found.
An `etc_hosts_deny` rule specifies one or more daemons mapped to one or more clients, with zero or more options for rejecting traffic when found.
Use the where clause to match a property to one or more rules in the hosts.deny file:
@ -44,20 +44,14 @@ Use the optional constructor parameter to give an alternative path to hosts.deny
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.
- `client_list` is a list of clients that will be rejected to pass traffic in.
- `options` is a list of tasks that are to be done with the rule when traffic is found.
## Properties
- `daemon`
- `client_list`
- `options`
## Parameter Examples
### daemon
`daemon` returns a string containing the daemon that is allowed in the rule.
The `daemon` property 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'] }
@ -65,7 +59,7 @@ where
### client_list
`client_list` returns a 2d string array where each entry contains the clients specified for the rule.
The `client_list` property 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]'] }
@ -73,7 +67,7 @@ where
### options
`options` returns a 2d string array where each entry contains any options specified for the rule.
The `options` property 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"'] }

28
docs-chef-io/content/inspec/resources/filesystem.md
View file

@ -47,9 +47,33 @@ where
- `free_kb` is the available space on the partition and is measured in kilobytes (KB).
- `percent_free` is the percentage of available free space, and ranges from 0 to 100.
## Resource Property Examples
## Properties
The following examples show how to use this Chef InSpec audit resource.
## size_kb (Integer)
The `size_kb` property returns the total partition size in kb.
its('size_kb') { should be >= 32000 }
## free_kb (Integer)
The `free_kb` property returns the size of available space on the partition in kb.
its('size_kb') { should be >= 32000 }
## percent_free (Integrer)
The `percent_free` property returns the available free space on the partition, ranges from 0 to 100.
its('percent_free') { should be >= 20 }
## type (String)
The `type` property returns the type of the file system.
its('type') { should cmp 'NTFS' }
## Examples
### Test if the root partition is greater than 32000 KB

10
docs-chef-io/content/inspec/resources/firewalld.md
View file

@ -34,7 +34,7 @@ This resource first became available in v1.40.0 of InSpec.
it { should have_rule_enabled('family=ipv4 source address=192.168.0.14 accept', 'public') }
end
Use the where clause to test open interfaces, sources, and services in active zones.
Use the where clause to test open interfaces, sources, and services that are in active zones.
describe firewalld.where { zone == 'public' } do
its('interfaces') { should cmp ['enp0s3', 'eno2'] }
@ -44,7 +44,7 @@ Use the where clause to test open interfaces, sources, and services in active zo
## Properties
### interfaces
### `interfaces`
The `interfaces` property is used in conjunction with the where class to display open interfaces in an active zone.
@ -52,7 +52,7 @@ The `interfaces` property is used in conjunction with the where class to display
its('interfaces') { should cmp ['enp0s3', 'eno2'] }
end
### sources
### `sources`
The `sources` property is used in conjunction with the where class to display open sources in an active zone.
@ -60,7 +60,7 @@ The `sources` property is used in conjunction with the where class to display op
its('sources') { should cmp ['192.168.1.0/24', '192.168.1.2'] }
end
### services
### `services`
The `services` property is used in conjunction with the where class to display open services in an active zone.
@ -68,7 +68,7 @@ The `services` property is used in conjunction with the where class to display o
its('services') { should cmp ['ssh', 'icmp'] }
end
### default_zone
### `default_zone`
The `default_zone` property displays the default active zone to be used.

16
docs-chef-io/content/inspec/resources/gem.md
View file

@ -37,7 +37,21 @@ where
- `('gem_binary')` can specify the path to a non-default gem binary, defaults to `'gem'`
- `be_installed` is a valid matcher for this resource
## Resource Property Examples
## Properties
### `version (String)`
The `version` property returns a string of the default version on the system:
its('version') { should eq '0.33.0' }
### `versions`
The `versions` property returns an array of strings of all the versions of the gem installed on the system:
its('versions') { should include /0.33/ }
## Examples
The following examples show how to use this Chef InSpec audit resource.

30
docs-chef-io/content/inspec/resources/group.md
View file

@ -44,28 +44,17 @@ where
- `'group_name'` must specify the name of a group to be tested on the system
- `exist` and `'gid'` are valid matchers for this resource
## Examples
The following examples show how to use this Chef InSpec audit resource.
### Test the group identifier for the root group
describe group('root') do
it { should exist }
its('gid') { should eq 0 }
end
## Properties
### gid
The `gid` property tests the named group identifier:
The `gid` property returns the named group identifier:
its('gid') { should eq 1234 }
### members
The `members` property tests the members that belong to the group:
The `members` property returns the members that belong to the group:
its('members') { should include 'root' }
@ -79,15 +68,26 @@ where `members` returns:
Example: `"member1,member2"`
### members_array
The `members_array` property tests the members that belong to a group just like the
The `members_array` property returns the members that belong to a group just like the
`members` property,
but the value returned by this property is always an array of group members.
its('members_array') { should include 'root' }
## Examples
The following examples show how to use this Chef InSpec audit resource.
### Test the group identifier for the root group
describe group('root') do
it { should exist }
its('gid') { should eq 0 }
end
## Matchers
For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).

34
docs-chef-io/content/inspec/resources/host.md
View file

@ -38,19 +38,35 @@ 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
- `protocol: 'name'` is the Internet protocol: TCP (`protocol: 'tcp'`), UDP (`protocol: 'udp'` or ICMP (`protocol: 'icmp'`))
- `protocol:` is the Internet protocol: TCP (`protocol: 'tcp'`), UDP (`protocol: 'udp'` or ICMP (`protocol: 'icmp'`))
## Resource Properties
- `connection`, `ipaddress`, `protocol`, `socket`
## Resource Examples
The following examples show how to use this Chef InSpec audit resource.
## Properties
### ipaddress
The `ipaddress` matcher tests if a host name is resolvable to a specific IP address:
The `ipaddress` property returns the ipaddress of the host.
its('ipaddress') { should include '93.184.216.34' }
### connection
The `connection` property returns the connection string.
its('connection') { should match /connection refused/ }
### `protocol`
The `protocol` property returns the protocol that given host is using.
its('protocol') { should eq 'tcp' }
### `socket`property returns the socket for the given host.
its('socket') { should match /STATUS_OK/ }
## Examples
### Verify that host name is resolvable to specific IP address.
describe host('example.com') do
its('ipaddress') { should include '93.184.216.34' }

59
docs-chef-io/content/inspec/resources/http.md
View file

@ -75,16 +75,8 @@ For example, a service is listening on default http port can be tested like this
Beginning with Chef InSpec 1.41, you can enable the ability to have the HTTP test execute on the remote target:
describe http('http://www.example.com', enable_remote_worker: true) do
its('body') { should cmp 'awesome' }
end
In Chef InSpec 2.0, the HTTP test will automatically execute remotely whenever Chef InSpec is testing a remote node.
## Parameters
- `url`, `auth`, `params`, `method`, `headers`, `data`, `open_timeout`, `read_timeout`, `ssl_verify`, `max_redirects`
## Parameter Examples
### url
@ -178,19 +170,17 @@ In Chef InSpec 2.0, the HTTP test will automatically execute remotely whenever C
## Properties
- `body`, `headers`, `http_method`, `status`,
## Property Examples
- `body`, `headers`, `http_method`, `status`
### body
The `body` matcher tests body content of http response:
The `body` property tests body content of http response:
its('body') { should eq 'hello\n' }
### headers
The `headers` matcher returns an hash of all http headers:
The `headers` property returns an hash of all http headers:
its('headers') { should eq {} }
@ -198,12 +188,53 @@ Individual headers can be tested via:
its('headers.Content-Type') { should cmp 'text/html' }
### http_method
The `http_method` property returns the http method of the http request.
its('http_method') { should eq 'GET'}
### status
The `status` matcher tests status of the http response:
The `status` property tests status of the http response:
its('status') { should eq 200 }
## Example
The following examples show how to use this Chef InSpec audit resource. An `http` resource block declares the configuration settings to be tested:
### Simple http test
For example, a service is listening on default http port can be tested like this:
describe http('http://localhost') do
its('status') { should cmp 200 }
end
### Complex http test
describe http('http://localhost:8080/ping',
auth: {user: 'user', pass: 'test'},
params: {format: 'html'},
method: 'POST',
headers: {'Content-Type' => 'application/json'},
data: '{"data":{"a":"1","b":"five"}}') do
its('status') { should cmp 200 }
its('body') { should cmp 'pong' }
its('headers.Content-Type') { should cmp 'text/html' }
end
## Local vs. Remote
Beginning with Chef InSpec 1.41, you can enable the ability to have the HTTP test execute on the remote target:
describe http('http://www.example.com', enable_remote_worker: true) do
its('body') { should cmp 'awesome' }
end
In Chef InSpec 2.0, the HTTP test will automatically execute remotely whenever Chef InSpec is testing a remote node.
## Matchers
For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).

40
docs-chef-io/content/inspec/resources/iis_app.md
View file

@ -39,10 +39,7 @@ An `iis_app` resource block declares details about the named site:
where
- `'application_path'` is the path to the application, such as `'/myapp'`
- `'site_name'` is the name of the site, such as `'Default Web Site'`
- `('application_pool')` is the name of the application pool in which the site's root application is run, such as `'DefaultAppPool'`
- `('protocols')` is a binding for the site, such as `'http'`. A site may have multiple bindings; therefore, use a `have_protocol` matcher for each site protocol to be tested
- `('physical_path')` is the physical path to the application, such as `'C:\\inetpub\\wwwroot\\myapp'`
- `have_application_pool`, `have_protocol`, `have_site_name`, `have_physical_path` and `have_path` are the different [matchers](#matchers) for this resource.
For example:
@ -57,11 +54,40 @@ For example:
## Properties
application_pool, path, physical_path, protocols, site_name
## Examples
## Resource Examples
### application pool
The following examples show how to use this Chef InSpec audit resource.
`application_pool` property returns the name of the application pool in which the site's root application is run, such as `DefaultAppPool`.
its('application_pool') { should eq 'root' }
### path
`path` property returns the path to the application.
its('path') { should eq '\my_app' }
### physical_path
`physical_path` property returns the physical path of the application, such as `'C:\\inetpub\\wwwroot\\myapp'`.
its('phyiscal_path') { should eq 'C:\\inetpub\\wwwroot\\myapp' }
### protocols
`protocols` property returns an array of protocols i.e. the binding for the site, such as `'http'`. A site may have multiple bindings.
its('protocols') { should include 'http' }
### site_name
`site_name` property returns the name of the site, such as `'Default Web Site'`
its('site_name') { should eq 'Default Web Site' }
## Examples
### Test a default IIS web application