inspec 1.0.0 → 1.35.1

data/docs/resources/x509_certificate.md.erb

@@ -0,0 +1,146 @@
+---
+title: The x509_certificate Resource
+---
+
+# x509_certificate
+
+Use the `x509_certificate` InSpec audit resource to test the fields and validity of an x.509 certificate.
+
+X.509 certificates use public/private key pairs to sign and encrypt documents
+or communications over a network. They may also be used for authentication.
+
+Examples include SSL certificates, S/MIME certificates and VPN authentication
+certificates.
+
+## Syntax
+
+An `x509_certificate` resource block declares a certificate `key file` to be tested.
+
+    describe x509_certificate('mycertificate.pem') do
+      its('validity_in_days') { should be > 30 }
+    end
+
+## Supported Properties
+
+### subject.XX
+
+`subject` property makes it easier to access individual subject elements.
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      its('subject.CN') { should eq "www.mywebsite.com" }
+    end
+
+### subject_dn (String)
+
+The `subject_dn` string returns the distinguished name of the subject field. It contains several fields separated by forward slashes. The field identifiers are the same ones used by OpenSSL to generate CSR's and certs. Use `subject.XX` instead to access the parsed version.
+
+e.g. `/C=US/L=Seattle/O=Chef Software Inc/OU=Chefs/CN=Richard Nixon`
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      its('subject_dn') { should match "CN=www.mywebsite.com" }
+    end
+
+### issuer.XX
+
+`issuer` makes it easier to access individual issuer elements.
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      its('issuer.CN') { should eq "Acme Trust CA" }
+    end
+
+### issuer_dn (String)
+
+The `issuer_dn` is the distinguished name from a CA (certificate authority) during the
+certificate signing process. It describes which authority is guaranteeing the
+identity of our certificate.
+
+e.g. `/C=US/L=Seattle/CN=Acme Trust CA/emailAddress=support@acmetrust.org`
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      its('issuer_cn') { should match "CN=Acme Trust CA" }
+    end
+
+### public_key (String)
+
+The `public_key` property returns a base64 encoded public key in PEM format.
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      its('public_key') { should match "-----BEGIN PUBLIC KEY-----\nblah blah blah..." }
+    end
+
+### key_length (Integer)
+
+The `key_length` property calculates the number of bits in the public key.
+More bits increase security, but at the cost of speed and in extreme cases, compatibility.
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      its('key_length') { should be 2048 }
+    end
+
+### signature_algorithm (String)
+
+The `signature_algorithm` property describes which hash function was used by the CA to
+sign the certificate.
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      its('signature_algorithm') { should be 'sha256WithRSAEncryption' }
+    end
+
+
+### validity_in_days (Float)
+
+The `validity_in_days` property can be used to check that certificates are not in
+danger of expiring soon.
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      its('validity_in_days') { should be > 30 }
+    end
+
+### not_before and not_after (Time)
+
+The `not_before` and `not_after` properties expose the start and end dates of certificate
+validity. They are exposed as ruby Time class so that date arithmetic can be easily performed.
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      its('not_before') { should be <= Time.utc.now }
+      its('not_after')  { should be >= Time.utc.now }
+    end
+
+### serial (Integer)
+
+The `serial` property exposes the serial number of the certificate. The serial number is set by the CA during the signing process and should be unique within that CA.
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      its('serial') { should eq 9623283588743302433 }
+    end
+
+### version (Integer)
+
+The `version` property exposes the certificate version.
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      its('version') { should eq 2 }
+    end
+
+### extensions (Hash)
+
+The `extensions` hash property is mainly used to determine what the certificate can be used for.
+
+    describe x509_certificate('/etc/pki/www.mywebsite.com.pem') do
+      # Check what extension categories we have
+      its('extensions') { should include 'keyUsage' }
+      its('extensions') { should include 'extendedKeyUsage' }
+      its('extensions') { should include 'subjectAltName' }
+
+      # Check examples of basic 'keyUsage'
+      its('extensions.keyUsage') { should include 'Digital Signature' }
+      its('extensions.keyUsage') { should include 'Non Repudiation' }
+      its('extensions.keyUsage') { should include 'Data Encipherment' }
+
+      # Check examples of newer 'extendedKeyUsage'
+      its('extensions.extendedKeyUsage') { should include 'TLS Web Server Authentication' }
+      its('extensions.extendedKeyUsage') { should include 'Code Signing' }
+
+      # Check examples of 'subjectAltName'
+      its('extensions.subjectAltName') { should include 'email:support@chef.io' }
+    end

data/docs/resources/xinetd_conf.md.erb

@@ -6,7 +6,7 @@ title: About the xinetd_conf Resource
 
 Use the `xinetd_conf` InSpec audit resource to test services under `/etc/xinet.d` on Linux and Unix platforms. xinetd---the extended Internet service daemon---listens on all ports, and then loads the appropriate program based on a request. The `xinetd.conf` file is typically located at `/etc/xinetd.conf` and contains a list of Internet services associated to the ports on which that service will listen. Only enabled services may handle a request; only services that are required by the system should be enabled.
 
-# Syntax
+## Syntax
 
 An `xinetd_conf` resource block declares settings found in a `xinetd.conf` file for the named service:
 
@@ -22,29 +22,29 @@ where
 * `should eq 'value'` is the value that is expected
 
 
-# Matchers
+## Matchers
 
 This InSpec audit resource has the following matchers:
 
-## be
+### be
 
 <%= partial "/shared/matcher_be" %>
 
-## be_enabed
+### be_enabed
 
 The `be_enabled` matcher tests if a service listed under `/etc/xinet.d` is enabled:
 
     it { should be_enabled }
 
-## cmp
+### cmp
 
 <%= partial "/shared/matcher_cmp" %>
 
-## eq
+### eq
 
 <%= partial "/shared/matcher_eq" %>
 
-## ids
+### ids
 
 The `ids` matcher tests if the named service is located under `/etc/xinet.d`:
 
@@ -54,21 +54,21 @@ For example:
 
     its('ids') { should include 'chargen-stream chargen-dgram'}
 
-## include
+### include
 
 <%= partial "/shared/matcher_include" %>
 
-## match
+### match
 
 <%= partial "/shared/matcher_match" %>
 
-## services
+### services
 
 The `services` matcher tests if the named service is listed under `/etc/xinet.d`:
 
     its('services') { should include 'service_name' }
 
-## socket_types
+### socket_types
 
 The `socket_types` matcher tests if a service listed under `/etc/xinet.d` is configured to use the named socket type:
 
@@ -86,7 +86,7 @@ For a TCP-based service:
 
     its('socket_types') { should eq 'stream' }
 
-## types
+### types
 
 The `types` matcher tests the service type:
 
@@ -94,7 +94,7 @@ The `types` matcher tests the service type:
 
 where `'TYPE'` is `INTERNAL` (for a service provided by xinetd), `RPC` (for a service based on remote procedure call), or `UNLISTED` (for services not under `/etc/services` or `/etc/rpc`).
 
-## wait
+### wait
 
 The `wait` matcher tests how a service handles incoming connections.
 
@@ -108,11 +108,11 @@ For TCP (`stream`) socket types the `wait` matcher should test for `no`:
     its('socket_types') { should eq 'stream' }
     its('wait') { should eq 'no' }
 
-# Examples
+## Examples
 
 The following examples show how to use this InSpec audit resource.
 
-## Test a socket_type
+### Test a socket_type
 
 The network socket type: `dgram` (a datagram-based service), `raw` (a service that requires direct access to an IP address), `stream` (a stream-based service), or `seqpacket` (a service that requires a sequenced packet).
 
@@ -120,7 +120,7 @@ The network socket type: `dgram` (a datagram-based service), `raw` (a service th
        its('socket_types') { should include 'dgram' }
     end
 
-## Test a service type
+### Test a service type
 
 The type of service: `INTERNAL` (a service provided by xinetd), `RPC` (an RPC-based service), `TCPMUX` (a service that is started on a well-known TPCMUX port), or `UNLISTED` (a service that is not listed in a standard system file location).
 
@@ -128,7 +128,7 @@ The type of service: `INTERNAL` (a service provided by xinetd), `RPC` (an RPC-ba
        its('type') { should include 'RPC' }
     end
 
-## Test the telnet service
+### Test the telnet service
 
 For example, a `telnet` file under `/etc/xinet.d` contains the following settings:
 

data/docs/resources/xml.md.erb

@@ -0,0 +1,75 @@
+---
+title: About the xml Resource
+---
+
+# xml
+
+Use the `xml` InSpec audit resource to test data in an XML file.
+
+## Syntax
+
+An `xml` resource block declares the data to be tested. Assume the following XML file:
+
+    <root>
+      <name>hello</name>
+      <meta>
+        <creator>John Doe</creator>
+      </meta>
+      <array>
+        <element>one</element>
+        <element>two</element>
+      </array>
+    </root>
+
+This file can be queried using:
+
+    describe xml('/path/to/name.xml') do
+      its('root/name') { should eq ['hello'] }
+      its('root/meta/creator') { should eq ['John Doe'] }
+      its('root/array[2]/element]) { should eq ['two'] }
+    end
+
+where
+
+* `root/name` is an XPath expression
+* `should eq ['foo']` tests a value of `root/name` as read from an XML file versus the value declared in the test
+
+## Matchers
+
+This InSpec audit resource has the following matchers:
+
+### be
+
+<%= partial "/shared/matcher_be" %>
+
+### cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+### eq
+
+<%= partial "/shared/matcher_eq" %>
+
+### include
+
+<%= partial "/shared/matcher_include" %>
+
+### match
+
+<%= partial "/shared/matcher_match" %>
+
+### name
+
+The `name` matcher tests the value of `name` as read from a JSON file versus the value declared in the test:
+
+    its('name') { should eq 'foo' }
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test an AppPool's presence in an applicationHost.config file
+
+    describe xml('applicationHost.config') do
+      its('configuration/system.applicationHost/applicationPools/add@name') { should contain('my_pool') }
+    end

data/docs/resources/yaml.md.erb

@@ -6,7 +6,7 @@ title: About the yaml Resource
 
 Use the `yaml` InSpec audit resource to test configuration data in a Yaml file.
 
-# Syntax
+## Syntax
 
 A `yaml` resource block declares the configuration data to be tested. Assume the following Yaml file:
 
@@ -17,7 +17,7 @@ A `yaml` resource block declares the configuration data to be tested. Assume the
 
 This file can be queried using:
 
-    describe yaml do
+    describe yaml('filename.yml') do
       its('name') { should eq 'foo' }
       its(['array', 1]) { should eq 'one' }
     end
@@ -27,42 +27,56 @@ where
 * `name` is a configuration setting in a Yaml file
 * `should eq 'foo'` tests a value of `name` as read from a Yaml file versus the value declared in the test
 
+Like the `json` resource, the `yaml` resource can read a file, run a command, or accept content inline:
 
-# Matchers
+    describe yaml('config.yaml') do
+      its(['driver', 'name']) { should eq 'vagrant' }
+    end
+
+    describe yaml({ command: 'retrieve_data.py --yaml' }) do
+      its('state') { should eq 'open' }
+    end
+
+    describe yaml({ content: \"key1: value1\nkey2: value2\" }) do
+      its('key2') { should cmp 'value2' }
+    end
+
+
+## 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" %>
 
-## name
+### name
 
 The `name` matcher tests the value of `name` as read from a Yaml file versus the value declared in the test:
 
     its('name') { should eq 'foo' }
 
-# Examples
+## Examples
 
 The following examples show how to use this InSpec audit resource.
 
-## Test a kitchen.yml file driver
+### Test a kitchen.yml file driver
 
     describe yaml('.kitchen.yaml') do
       its('driver.name') { should eq('vagrant') }

data/docs/resources/yum.md.erb

@@ -6,7 +6,7 @@ title: About the yum Resource
 
 Use the `yum` InSpec audit resource to test packages in the Yum repository.
 
-# Syntax
+## Syntax
 
 A `yum` resource block declares a package repo, tests if the package repository is present, and if it that package repository is a valid package source (i.e. "is enabled"):
 
@@ -19,43 +19,43 @@ where
 
 * `repo('name')` is the (optional) name of a package repo, using either a full identifier (`'updates/7/x86_64'`) or a short identifier (`'updates'`)
 
-# Matchers
+## Matchers
 
 This InSpec audit resource has the following matchers:
 
-## be
+### be
 
 <%= partial "/shared/matcher_be" %>
 
-## be_enabled
+### be_enabled
 
 The `be_enabled` matcher tests if the package repository is a valid package source:
 
     it { should be_enabled }
 
-## cmp
+### cmp
 
 <%= partial "/shared/matcher_cmp" %>
 
-## eq
+### eq
 
 <%= partial "/shared/matcher_eq" %>
 
-## exist
+### exist
 
 The `exist` matcher tests if the package repository exists:
 
     it { should exist }
 
-## include
+### include
 
 <%= partial "/shared/matcher_include" %>
 
-## match
+### match
 
 <%= partial "/shared/matcher_match" %>
 
-## repo('name')
+### repo('name')
 
 The `repo('name')` matcher names a specific package repository:
 
@@ -63,13 +63,13 @@ The `repo('name')` matcher names a specific package repository:
       ...
     end
 
-## repos
+### repos
 
 The `repos` matcher tests if a named repo, using either a full identifier (`'updates/7/x86_64'`) or a short identifier (`'updates'`), is included in the Yum repo:
 
     its('repos') { should include 'some_repo' }
 
-## shortname
+### shortname
 
 The `shortname` matcher names a specific package repository's group identifier. For example, if a repository's group name is "Directory Server", the corresponding group idenfier is typically "directory-server":
 
@@ -77,17 +77,17 @@ The `shortname` matcher names a specific package repository's group identifier.
       its('shortname') { should eq 'directory-server' }
     end
 
-# Examples
+## Examples
 
 The following examples show how to use this InSpec audit resource.
 
-## Test if the yum repo exists
+### Test if the yum repo exists
 
     describe yum do
       its('repos') { should exist }
     end
 
-## Test if the 'base/7/x86_64' repo exists and is enabled
+### Test if the 'base/7/x86_64' repo exists and is enabled
 
     describe yum do
       its('repos') { should include 'base/7/x86_64' }
@@ -95,9 +95,17 @@ The following examples show how to use this InSpec audit resource.
       its('epel') { should be_enabled }
     end
 
-## Test if a specific yum repo exists
+### Test if a specific yum repo exists
 
     describe yum.repo('epel') do
       it { should exist }
       it { should be_enabled }
     end
+
+### Test a particular repository configuration, such as its Base URL
+
+    describe yum.repo('mycompany-artifacts') do
+      it { should exist }
+      it { should be_enabled }
+      its('baseurl') { should include 'mycompany.biz' }
+    end

data/docs/resources/zfs_dataset.md.erb

@@ -0,0 +1,63 @@
+---
+title: About the zfs_dataset Resource
+---
+
+# zfs_dataset
+
+Use the `zfs_dataset` InSpec audit resource to test the ZFS datasets on FreeBSD systems.
+
+## Syntax
+
+A `zfs_dataset` resource block declares the ZFS dataset properties that should be tested:
+
+    describe zfs_dataset('dataset') do
+      it { should MATCHER 'value' }
+    end
+
+where
+
+* `('dataset')` is the name of the ZFS dataset (eg: `'tank/tmp'`)
+* `MATCHER` is a valid matcher for this resource
+* `'value'` is the value to be tested
+
+
+## Matchers
+
+This InSpec audit resource has the matchers listed below, in addition to dynamically exposing all ZFS dataset properties available (see: `man zfs` for the list of supported properties.)
+
+### be
+
+<%= partial "/shared/matcher_be" %>
+
+### be_mounted
+
+The `be_mounted` matcher tests if the dataset is accessible from the file system:
+
+    it { should be_mounted }
+
+### cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+### eq
+
+<%= partial "/shared/matcher_eq" %>
+
+### match
+
+<%= partial "/shared/matcher_match" %>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test a dataset of 'tank/tmp'
+
+    describe zfs_dataset('tank/tmp') do
+      it { should be_mounted }
+      its('atime') { should eq  'on' }
+      its('compression') { should eq  'lz4' }
+      its('exec') { should eq  'off' }
+      its('readonly') { should eq  'off' }
+      its('setuid') { should eq  'off' }
+    end

data/docs/resources/zfs_pool.md.erb

@@ -0,0 +1,57 @@
+---
+title: About the zfs_pool Resource
+---
+
+# zfs_pool
+
+Use the `zfs_pool` InSpec audit resource to test the ZFS pools on FreeBSD systems.
+
+## Syntax
+
+A `zfs_pool` resource block declares the ZFS pool properties that should be tested:
+
+    describe zfs_pool('pool') do
+      it { should MATCHER 'value' }
+    end
+
+where
+
+* `('pool')` is the name of the ZFS pool (eg: `'tank'`)
+* `MATCHER` is a valid matcher for this resource
+* `'value'` is the value to be tested
+
+
+## Matchers
+
+This InSpec audit resource has the matchers listed below, in addition to dynamically exposing all ZFS pool properties available (see: `man zpool` for the list of supported properties.)
+
+### be
+
+<%= partial "/shared/matcher_be" %>
+
+### cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+### eq
+
+<%= partial "/shared/matcher_eq" %>
+
+### match
+
+<%= partial "/shared/matcher_match" %>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test a pool of 'tank'
+
+    describe zfs_pool('tank') do
+      its('autoexpand') { should eq  'off' }
+      its('failmode') { should eq  'continue' }
+      its('feature@lz4_compress') { should eq  'active' }
+      its('health') { should eq  'ONLINE' }
+      its('listsnapshots') { should eq  'off' }
+      its('readonly') { should eq  'off' }
+    end