inspec/docs/resources.rst

=====================================================
InSpec Resources Reference
=====================================================

The following InSpec resources are available:

* ``apt``
* ``bond``
* ``bridge``
* ``command``
* ``directory``
* ``file``
* ``gem``
* ``group``
* ``host``
* ``interface``
* ``kernel_module``
* ``kernel_parameter``
* ``npm``
* ``oneget``
* ``os``
* ``os_env``
* ``package``
* ``pip``
* ``port``
* ``processes``
* ``registry_key``
* ``script``
* ``service``
* ``user``
* ``windows_feature``
* ``yum``

In addition to the open source resources, Chef Compliance ships with additional resources:

* ``apache_conf``
* ``audit_policy``
* ``audit_daemon_conf``
* ``audit_daemon_rules``
* ``csv``
* ``etc_group``
* ``group_policy``
* ``inetd_config``
* ``json``
* ``limits_conf``
* ``login_defs``
* ``mysql``
* ``mysql_conf``
* ``mysql_session``
* ``ntp_conf``
* ``parse_config``
* ``parse_config_file``
* ``passwd``
* ``postgres``
* ``postgres_conf``
* ``postgres_session``
* ``security_policy``
* ``ssh_config``
* ``sshd_config``
* ``yaml``

See below for more information about each InSpec resource, its related matchers, and examples of how to use it in a recipe.

apache_conf
=====================================================
Use the ``apache_conf`` InSpec resource to xxxxx.

IN_PROGRESS

apt
=====================================================
Use the ``apt`` InSpec resource to verify |apt| repositories on the |debian| and |ubuntu| platforms, and also |ppa| repositories on the |ubuntu| platform.

Syntax
-----------------------------------------------------
A ``apt`` InSpec resource block verifies apt and ppa repositories. For example:

.. code-block:: ruby

    describe apt('http://ppa.launchpad.net/juju/stable/ubuntu') do
      it { should exist }
      it { should be_enabled }
    end

    describe apt('ppa:nginx/stable') do
      it { should exist }
      it { should be_enabled }
    end

where

* ``apt()`` must specify a repository
* ``http://ppa.launchpad.net/juju/stable/ubuntu`` is the repository, it understands **urls**
   (``http://ppa.launchpad.net/juju/stable/ubuntu``), **ppa** (``ppa:ubuntu-wine/ppa``), or **short ppa**
   (``ubuntu-wine/ppa``)
* ``exist`` and ``be_enabled`` are a valid matcher for this InSpec resource

Matchers
-----------------------------------------------------
This InSpec resource has the following matchers:

exist
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The `exist` matcher tests if the repository is installed configured, but may be commented out. For example:

.. code-block:: ruby

   it { should exist }

be_enabled
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The `be_enabled` matcher tests if the repository is enabled in your `/etc/apt/*.list files`. For example:

.. code-block:: ruby

   it { should be_enabled }

Examples
-----------------------------------------------------
The following example shows how to use this InSpec resource in a compliance profile.

**Verify that a repository exists and is enabled**

.. code-block:: ruby

  describe apt('ppa:nginx/stable') do
    it { should exist }
    it { should be_enabled }
  end

**Verify that a repository is not present**

.. code-block:: ruby

  describe apt('ubuntu-wine/ppa') do
    it { should_not exist }
    it { should_not be_enabled }
  end

Compatability with ServerSpec
-----------------------------------------------------

This resource provides an ``ppa`` alias to be compatible with ServerSpec. This will be removed in future releases.


Supported Operating Systems
-----------------------------------------------------

* Debian 6, 7, 8
* Ubuntu 12.04, 14.04


audit_policy
=====================================================
Use the ``audit_policy`` InSpec resource to xxxxx.

IN_PROGRESS



audit_daemon_conf
=====================================================
Use the ``audit_daemon_conf`` InSpec resource to xxxxx.

IN_PROGRESS



audit_daemon_rules
=====================================================
Use the ``audit_daemon_rules`` InSpec resource to xxxxx.

IN_PROGRESS



bond
=====================================================
Use the ``bond`` InSpec resource to test a logical, bonded network interface (i.e. "two or more network interfaces aggregated into a single, logical network interface"). On |unix| and |linux| platforms, any value in the ``/proc/net/bonding`` directory may be tested.

IN_PROGRESS



bridge -- DONE
=====================================================
Use the ``bridge`` InSpec resource to test basic network bridge properties, such as name, if an interface is defined, and the associations for any defined interface.

* On |unix| and |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

.. not sure the previous two bullet items are actually true, but keeping there for reference for now, just in case

Syntax -- DONE
-----------------------------------------------------
A ``bridge`` InSpec resource block declares xxxxx. For example:

.. code-block:: ruby

   describe bridge('br0') do
     it { should exist }
     it { should have_interface 'eth0' }
   end

..
.. where
..
.. * ``xxxxx`` must specify xxxxx
.. * xxxxx
.. * ``xxxxx`` is a valid matcher for this InSpec resource
..

Matchers -- DONE
-----------------------------------------------------
This InSpec resource has the following matchers.

exist -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``exist`` matcher tests if the network bridge is available. For example:

.. code-block:: ruby

   it { should exist }

have_interface -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``have_interface`` matcher tests if the named interface is defined for the network bridge. For example:

.. code-block:: ruby

   it { should have_interface 'eth0' }

interfaces -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``interfaces`` matcher tests if the named interface is present. For example:

.. code-block:: ruby

   its(:interfaces) { should eq foo }
   its(:interfaces) { should eq bar }
   its(:interfaces) { should include foo, bar }

.. wild guessing ^^^

..
.. Examples
.. -----------------------------------------------------
.. The following examples show how to use this InSpec resource in a recipe.
..
.. **xxxxx**
..
.. xxxxx
..
.. **xxxxx**
..
.. xxxxx
..



command
=====================================================
Use the ``command`` InSpec resource to test an arbitrary command.

IN_PROGRESS



csv
=====================================================
Use the ``csv`` InSpec resource to xxxxx.

IN_PROGRESS


directory
=====================================================
Use the ``directory`` InSpec resource to xxxxx.

IN_PROGRESS



etc_group
-----------------------------------------------------
Use the ``etc_group`` InSpec resource to test the contents of the ``/etc/group`` file on |linux| and |unix| platforms. The ``/etc/group`` file stores details about each group---group name, password, group identifier, and a comma-separate list of users that belong to the group.

IN_PROGRESS



file
=====================================================
Use the ``file`` InSpec resource to xxxxx.

IN_PROGRESS


gem
=====================================================
Use the ``gem`` InSpec resource to xxxxx.

IN_PROGRESS



group
=====================================================
Use the ``group`` InSpec resource to xxxxx.

IN_PROGRESS



group_policy
=====================================================
Use the ``group_policy`` InSpec resource to xxxxx.

IN_PROGRESS



host -- DONE
=====================================================
Use the ``host`` InSpec resource to test the name used to refer to a specific host and its availability, including the Internet protocols and ports over which that host name should be available.

Syntax -- DONE
-----------------------------------------------------
A ``host`` InSpec resource block declares a host name, and then (depending on what is to be tested) a port and/or a protocol. For example:

.. code-block:: ruby

   describe host('example.com', port: 80, proto: 'udp') do
     it { should be_reachable }
   end

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
* ``proto: 'name'`` is the Internet protocol: |icmp| (``proto: 'icmp'``), |tcp| (``proto: 'tcp'``), or |udp| (``proto: 'udp'``)
* ``be_reachable`` is a valid matcher for this InSpec resource

Matchers -- DONE
-----------------------------------------------------
This InSpec resource has the following matchers.

be_reachable -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``be_reachable`` matcher tests if the host name is available. For example:

.. code-block:: ruby

     it { should be_reachable }


be_resolvable -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``be_resolvable`` matcher tests for host name resolution, i.e. "resolvable to an IP address". For example:

.. code-block:: ruby

     it { should be_resolvable }


ipaddress -- DONE
-----------------------------------------------------
The ``ipaddress`` matcher tests if a host name is resolvable to a specific IP address. For example:

.. code-block:: ruby

     its(:ipaddress) { should include '93.184.216.34' }


Examples -- DONE
-----------------------------------------------------
The following examples show how to use this InSpec resource in a recipe.

**Verify host name s reachable over a specific protocol and port number**

.. code-block:: ruby

   describe host('example.com', port: 53, proto: 'udp') do
     it { should be_reachable }
   end

**Verify that a specific IP address can be resolved**

.. code-block:: ruby

   describe host('example.com', port: 80, proto: 'tcp') do
     it { should be_resolvable }
     its(:ipaddress) { should include '192.168.1.1' }
   end




inetd_config -- DONE
=====================================================
Use the ``inetd_config`` InSpec resource to test if a service is enabled in the ``inetd.conf`` file on |linux| and |unix| platforms. |inetd|---the Internet service daemon---listens on dedicated ports, and then loads the appropriate program based on a request. The ``inetd.conf`` file is typically located at ``/etc/inetd.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 -- DONE
-----------------------------------------------------
A ``inetd_config`` InSpec resource block declares the list of services that should be disabled in the ``inetd.conf`` file. For example:

.. code-block:: ruby

   describe inetd_config('path') do
     its(:service_name) { should eq nil }
   end

where

* ``'service_name'`` is a service listed in the ``inetd.conf`` file
* ``('path')`` is the non-default path to the ``inetd.conf`` file
* ``should eq 'value'`` is the value that is expected
inetd_conf('/path/to/inetd.conf')
* ``{ should eq nil }`` tests if the service is disabled (will return ``true`` if the service is disabled); use an ``its`` block for each service to be tested

Matchers -- DONE
-----------------------------------------------------
This InSpec resource matches any service that is listed in the ``inetd.conf`` file. For example:

.. code-block:: ruby

     its(:shell) { should eq nil }

or:

.. code-block:: ruby

     its(:netstat) { should eq nil }

or:

.. code-block:: ruby

     its(:systat) { should eq nil }

For example:

.. code-block:: ruby

   describe inetd_conf do
     its(:shell) { should eq nil }
     its(:login) { should eq nil }
     its(:exec) { should eq nil }
   end

Examples -- DONE
-----------------------------------------------------
The following examples show how to use this InSpec resource in a recipe.

**Verify that FTP is disabled**

The contents if the ``inetd.conf`` file contain the following:

.. code-block:: text

   #ftp      stream   tcp   nowait   root   /usr/sbin/tcpd   in.ftpd -l -a
   #telnet   stream   tcp   nowait   root   /usr/sbin/tcpd   in.telnetd

and the following test is defined:

.. code-block:: ruby

   describe inetd_config do
     its(:ftp) { should eq nil }
     its(:telnet) { should eq nil }
   end

Because both the ``ftp`` and ``telnet`` Internet services are commented out (``#``), both services are disabled. Consequently, both tests will return ``true``. However, if the ``inetd.conf`` file is set as follows:

.. code-block:: text

   ftp       stream   tcp   nowait   root   /usr/sbin/tcpd   in.ftpd -l -a
   #telnet   stream   tcp   nowait   root   /usr/sbin/tcpd   in.telnetd

then the same test will return ``false`` for ``ftp`` and the entire test will fail.


interface -- DONE
=====================================================
Use the ``interface`` InSpec resource to test basic network adapter properties, such as name, status, state, address, and link speed (in MB/sec).

* On |unix| and |linux| platforms, any value in the ``/sys/class/net/#{iface}`` directory may be tested.
* On the |windows| platform, the ``Get-NetAdapter`` cmdlet returns the following values: ``Property Name``, ``InterfaceDescription``, ``Status``, ``State``, ``MacAddress``, ``LinkSpeed``, ``ReceiveLinkSpeed``, ``TransmitLinkSpeed``, and ``Virtual``, returned as a |json| object.

.. not sure the previous two bullet items are actually true, but keeping there for reference for now, just in case

Syntax -- DONE
-----------------------------------------------------
A ``interface`` InSpec resource block declares network interface properties to be tested. For example:

.. code-block:: ruby

   describe interface do
     it { should be_up }
     its(:speed) { should eq 1000 }
     its('name') { should eq eth0 }
   end

..
.. where
..
.. * ``xxxxx`` must specify xxxxx
.. * xxxxx
.. * ``xxxxx`` is a valid matcher for this InSpec resource
..

Matchers -- DONE
-----------------------------------------------------
This InSpec resource has the following matchers.

be_up -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``be_up`` matcher tests if the network interface is available. For example:

.. code-block:: ruby

   it { should be_up }

name -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``name`` matcher tests if the named network interface exists. For example:

.. code-block:: ruby

   its('name') { should eq eth0 }

speed -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``speed`` matcher tests the speed of the network interface, in MB/sec. For example:

.. code-block:: ruby

   its(:speed) { should eq 1000 }

..
.. Examples
.. -----------------------------------------------------
.. The following examples show how to use this InSpec resource in a recipe.
..
.. **xxxxx**
..
.. xxxxx
..
.. **xxxxx**
..
.. xxxxx
..



json -- DONE
=====================================================
Use the ``json`` InSpec resource to test data in a |json| file.

Syntax -- DONE
-----------------------------------------------------
A ``json`` InSpec resource block declares the data to be tested. For example:

.. code-block:: ruby

   describe json do
     its('name') { should eq 'foo' }
   end

where

* ``name`` is a configuration setting in a |json| file
* ``should eq 'foo'`` tests a value of ``name`` as read from a |json| file versus the value declared in the test

Matchers -- DONE
-----------------------------------------------------
This InSpec resource has the following matchers.

name -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``name`` matcher tests the value of ``name`` as read from a |json| file versus the value declared in the test. For example:

.. code-block:: ruby

   its('name') { should eq 'foo' }

Examples -- DONE
-----------------------------------------------------
The following examples show how to use this InSpec resource in a recipe.

**Test a cookbook version in a policyfile.lock.json file**

.. code-block:: ruby

   describe json('policyfile.lock.json') do
     its('cookbook_locks.omnibus.version') { should eq('2.2.0') }
   end



kernel_module
=====================================================
Use the ``kernel_module`` InSpec resource to xxxxx.

IN_PROGRESS



kernel_parameter
=====================================================
Use the ``kernel_parameter`` InSpec resource to xxxxx.

IN_PROGRESS



limits_conf
=====================================================
Use the ``limits_conf`` InSpec resource to xxxxx.

IN_PROGRESS



login_defs -- DONE
=====================================================
Use the ``login_defs`` InSpec resource to test configuration settings in the ``/etc/login.defs`` file. The ``logins.defs`` file defines site-specific configuration for the shadow password suite on |linux| and |unix| platforms, such as password expiration ranges, minimum/maximum values for automatic selection of user and group identifiers, or the method with which passwords are encrypted.

Syntax -- DONE
-----------------------------------------------------
A ``login_defs`` InSpec resource block declares the ``login.defs`` configuration data to be tested. For example:

.. code-block:: ruby

   describe login_defs do
     its('name') { should include('foo') }
   end

where

* ``name`` is a configuration setting in ``login.defs``
* ``{ should include('foo') }`` tests the value of ``name`` as read from ``login.defs`` versus the value declared in the test

Matchers -- DONE
-----------------------------------------------------
This InSpec resource has the following matchers.

name -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``name`` matcher tests the value of ``name`` as read from ``login.defs`` versus the value declared in the test. For example:

.. code-block:: ruby

   its('name') { should eq 'foo' }

Examples -- DONE
-----------------------------------------------------
The following examples show how to use this InSpec resource in a recipe.

**Test password expiration settings**

.. code-block:: ruby

   describe login_defs do
     its('PASS_MAX_DAYS') { should eq '180' }
     its('PASS_MIN_DAYS') { should eq '1' }
     its('PASS_MIN_LEN') { should eq '15' }
     its('PASS_WARN_AGE') { should eq '30' }
   end

**Test the encryption method**

.. code-block:: ruby

   describe login_defs do
     its('ENCRYPT_METHOD') { should eq 'SHA512' }
   end

**Test xxxxx** <<< what does this test?

.. code-block:: ruby

   describe login_def do
     its('UMASK') { should eq '077' }
     its('PASS_MAX_DAYS.to_i') { should be <= 90 }
   end



mysql
=====================================================
Use the ``mysql`` InSpec resource to xxxxx.

IN_PROGRESS



mysql_conf
=====================================================
Use the ``mysql_conf`` InSpec resource to xxxxx.


IN_PROGRESS



mysql_session
=====================================================
Use the ``mysql_session`` InSpec resource to xxxxx.

IN_PROGRESS



npm
=====================================================
Use the ``npm`` InSpec resource to xxxxx.

IN_PROGRESS



ntp_conf
=====================================================
Use the ``ntp_conf`` InSpec resource to xxxxx.

IN_PROGRESS



oneget
=====================================================
Use the ``oneget`` InSpec resource to xxxxx.

IN_PROGRESS



os
=====================================================
Use the ``os`` InSpec resource to xxxxx.

IN_PROGRESS



os_env
=====================================================
Use the ``os_env`` InSpec resource to test environment variables.

IN_PROGRESS



package
=====================================================
Use the ``package`` InSpec resource to xxxxx.

IN_PROGRESS



parse_config
=====================================================
Use the ``parse_config`` InSpec resource to test arbitrary configuration files.

IN_PROGRESS



parse_config_file
=====================================================
Use the ``parse_config_file`` InSpec resource to test arbitrary configuration files.

IN_PROGRESS



passwd -- DONE
=====================================================
Use the ``passwd`` InSpec resource to test the contents of ``/etc/passwd``, which contains the following information for users that may log into the system and/or as users that own running processes. The format for ``/etc/passwd`` includes:

* A username
* The password for that user
* The user identifier (UID) assigned to that user
* The group identifier (GID) assigned to that user
* Additional information about that user
* That user's home directory
* That user's default command shell

defined as a colon-delimited row in the file, one row per user. For example:

.. code-block:: bash

   root:x:1234:5678:additional_info:/home/dir/:/bin/bash

Syntax -- DONE
-----------------------------------------------------
A ``passwd`` InSpec resource block declares one (or more) users and associated user information to be tested. For example:

.. code-block:: ruby

   describe passwd do
     its(:matcher) { should eq 0 }
   end

where

* ``count``, ``gids``, ``passwords``, ``uid``, ``uids``, ``username``, ``usernames``, and ``users`` are valid matchers for this InSpec resource

Matchers -- DONE
-----------------------------------------------------
This InSpec resource has the following matchers.

count -- ?????
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``count`` matcher tests if xxxxx. For example:

.. code-block:: ruby

   its(:count) { should eq 1 }

gids -- ?????
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``gids`` matcher tests if xxxxx. For example:

.. code-block:: ruby

   its(:gids) { should eq 1234 }

passwords -- ?????
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``passwords`` matcher tests if xxxxx. For example:

.. code-block:: ruby

   its(:passwords) { should eq xxxxx }

uid -- ?????
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``uid`` matcher tests if xxxxx. For example:

.. code-block:: ruby

   its(:uid) { should eq xxxxx }

uids -- ?????
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``uids`` matcher tests if xxxxx. For example:

.. code-block:: ruby

   its(:uids) { should eq 1 }

username -- ?????
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``username`` matcher tests if xxxxx. For example:

.. code-block:: ruby

   its(:username) { should eq 'root' }

usernames -- ?????
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``usernames`` matcher tests if xxxxx. For example:

.. code-block:: ruby

   its(:usernames) { should eq 'root' }

users -- ?????
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``users`` matcher tests if xxxxx. For example:

.. code-block:: ruby

   its(:users) { should eq 'root' }

Examples -- DONE
-----------------------------------------------------
The following examples show how to use this InSpec resource in a recipe.

**xxxxx**

.. code-block:: ruby

   describe passwd do
     its(:usernames) { should eq 'root' }
     its(:uids) { should eq 1 }
   end

**xxxxx**

.. code-block:: ruby

   describe passwd.uid(0) do
     its(:username) { should eq 'root' }
     its(:count) { should eq 1 }
   end



pip -- DONE
=====================================================
Use the ``pip`` InSpec resource to test packages that are installed using the |pip| installer.

Syntax -- DONE
-----------------------------------------------------
A ``pip`` InSpec resource block declares a package and (optionally) a package version. For example:

.. code-block:: ruby

   describe pip('Jinja2') do
     it { should be_installed }
   end

where

* ``'Jinja2'`` is the name of the package
* ``be_installed`` tests to see if the ``Jinja2`` package is installed

Matchers -- DONE
-----------------------------------------------------
This InSpec resource has the following matchers.

be_installed -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``be_installed`` matcher tests if the named package is installed on the system. For example:

.. code-block:: ruby

   it { should be_installed }

version -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``version`` matcher tests if the named package version is on the system. For example:

.. code-block:: ruby

   its(:version) { should eq 1.2.3 }

Examples -- DONE
-----------------------------------------------------
The following examples show how to use this InSpec resource in a recipe.

**Test if Jinja2 is installed on the system**

.. code-block:: ruby

   describe pip('Jinja2') do
     it { should be_installed }
   end

**Test if Jinja2 2.8 is installed on the system**

.. code-block:: ruby

   describe pip('Jinja2') do
     it { should be_installed }
     its(:version) { should eq '2.8' }
   end


port -- DONE
=====================================================
Use the ``port`` InSpec resource to test basic port properties, such as port, process, if it's listening.

Syntax -- DONE
-----------------------------------------------------
A ``port`` InSpec resource block declares a port, and then depending on what needs to be tested, a process, protocol, process identifier, and its state (is it listening?). For example:

.. code-block:: ruby

   describe port(514) do
     it { should be_listening }
     its(:process) {should eq 'syslog'}
   end

where the ``syslog`` process is tested to see if it's listening on port 514.

Matchers -- DONE
-----------------------------------------------------
This InSpec resource has the following matchers.

be_listening -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``be_listening`` matcher tests if the port is listening for traffic. For example:

.. code-block:: ruby

   it { should be_listening }

be_listening.with() -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``be_listening`` matcher can also test if the port is listening for traffic over a specific protocol or on local binding address. Use ``.with()`` to specify a protocol or local binding address. For example, a protocol:

.. code-block:: ruby

   it { should be_listening.with('tcp') }

A local binding address:

   it { should be_listening.with('127.0.0.1:631') }

A protocol and a local binding address:

   it { should be_listening.with('tcp', '127.0.0.1:631') }

pid -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``pid`` matcher tests the process identifier (PID). For example:

.. code-block:: ruby

   its(:pid) { should eq '27808' }

process -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``process`` matcher tests if the named process is running on the system. For example:

.. code-block:: ruby

   its(:process) { should eq 'syslog' }

protocol -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``protocol`` matcher tests the Internet protocol: |icmp| (``'icmp'``), |tcp| (``'tcp'`` or ``'tcp6'``), or |udp| (``'udp'`` or ``'udp6'``). For example:

.. code-block:: ruby

   its(:protocol) { should eq 'tcp' }

or for the |ipv6| protocol:

.. code-block:: ruby

   its(:protocol) { should eq 'tcp6' }

Examples -- DONE
-----------------------------------------------------
The following examples show how to use this InSpec resource in a recipe.

**Test port 80, listening with the TCP protocol**

.. code-block:: ruby

   describe port(80) do
     it { should be_listening }
     its('protocol') {should eq 'tcp'}
   end

**Test port 80, listening with TCP version IPv6 protocol**

.. code-block:: ruby

   describe port(80) do
     it { should be_listening }
     its('protocol') {should eq 'tcp6'}
   end



postgres -- NOT AN AUDIT RESOURCE?
=====================================================
TBD

.. This one seems like it's just loading some postgresql information on behalf of the postgres_conf and postgres_session InSpec resources. Right?


postgres_conf -- DONE
=====================================================
Use the ``postgres_conf`` InSpec resource to test the contents of the configuration file for |postgresql|, typically located at ``/etc/postgresql/<version>/main/postgresql.conf`` or ``/var/lib/postgres/data/postgresql.conf``, depending on the platform.

Syntax -- DONE
-----------------------------------------------------
A ``postgres_conf`` InSpec resource block declares one (or more) settings in the ``postgresql.conf`` file, and then compares the setting in the configuration file to the value stated in the test. For example:

.. code-block:: ruby

   describe postgres_conf('path') do
     its('setting') { should eq 'value' }
   end

where

* ``'setting'`` specifies a setting in the ``postgresql.conf`` file
* ``('path')`` is the non-default path to the ``postgresql.conf`` file
* ``should eq 'value'`` is the value that is expected

Matchers -- DONE
-----------------------------------------------------
This InSpec resource has the following matchers.

setting -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``setting`` matcher tests specific, named settings in the ``postgresql.conf`` file. For example:

.. code-block:: ruby

   its('setting') { should eq 'value' }

Use a ``setting`` matcher for each setting to be tested.

Examples -- DONE
-----------------------------------------------------
The following examples show how to use this InSpec resource in a recipe.

**Test the maximum number of allowed client connections**

.. code-block:: ruby

   describe postgres_conf do
     its('max_connections') { should eq '5' }
   end

**Test system logging**

.. code-block:: ruby

   describe postgres_conf do
     its('logging_collector') { should eq 'on' }
     its('log_connections') { should eq 'on' }
     its('log_disconnections') { should eq 'on' }
     its('log_duration') { should eq 'on' }
     its('log_hostname') { should eq 'on' }
     its('log_line_prefix') { should eq '%t %u %d %h' }
   end

**Test the port on which PostgreSQL listens**

.. code-block:: ruby

   describe postgres_conf do
     its('port') { should eq '5432' }
   end

**Test the Unix socket settings**

.. code-block:: ruby

   describe postgres_conf do
     its('unix_socket_directories') { should eq '.s.PGSQL.5432' }
     its('unix_socket_group') { should eq nil }
     its('unix_socket_permissions') { should eq '0770' }
   end

where ``unix_socket_group`` is set to the |postgresql| default setting (the group to which the server user belongs).



postgres_session -- DONE
=====================================================
Use the ``postgres_session`` InSpec resource to test SQL commands run against a |postgresql| database.

Syntax -- DONE
-----------------------------------------------------
A ``postgres_session`` InSpec resource block declares the username and password to use for the session, and then the command to be run. For example:

.. code-block:: ruby

   sql = postgres_session('username', 'password')

   sql.describe('SELECT * FROM pg_shadow WHERE passwd IS NULL;') do
     its('output') { should eq('') }
   end


where

* ``sql = postgres_session`` declares a username and password with permission to run the query
* ``describe('')`` contains the query to be run
* ``its('output') { should eq('') }`` compares the results of the query against the expected result in the test

Matchers -- DONE
-----------------------------------------------------
This InSpec resource has the following matchers.

output -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``output`` matcher tests the results of the query. For example:

.. code-block:: ruby

   its(:output) { should eq(/^0/) }

Examples -- DONE
-----------------------------------------------------
The following examples show how to use this InSpec resource in a recipe.

**Test the PostgreSQL shadow password**

.. code-block:: ruby

   sql = postgres_session('my_user', 'password')

   sql.describe('SELECT * FROM pg_shadow WHERE passwd IS NULL;') do
     its(:output) { should eq('') }
   end

**Test for risky database entries**

.. code-block:: ruby

   sql = postgres_session('my_user', 'password')

   sql.describe('SELECT count (*)
                 FROM pg_language
                 WHERE lanpltrusted = 'f'
                 AND lanname!='internal'
                 AND lanname!='c';') do
     its(:output) { should eq(/^0/) }
   end



processes -- DONE
=====================================================
Use the ``processes`` InSpec resource to test properties for running programs a system.

Syntax -- DONE
-----------------------------------------------------
A ``processes`` InSpec resource block declares the name of the process to be tested, and then declares one (or more) property/value pairs. For example:

.. code-block:: ruby

   describe processes('process_name') do
     its('property_name') { should eq 'property_value' }
   end

where

* ``processes('process_name')`` must specify the name of a process that is running on the system
* Multiple properties may be tested; for each property to be tested, use an ``its('property_name')`` statement

Matchers -- DONE
-----------------------------------------------------
This InSpec resource has the following matchers.

property_name -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``property_name`` matcher tests the named property for the specified value. For example:

.. code-block:: ruby

   its('property_name') { should eq 'property_value' }

Examples -- DONE
-----------------------------------------------------
The following examples show how to use this InSpec resource in a recipe.

**Test if the list length for the mysqld process is 1**

.. code-block:: ruby

   describe processes('mysqld') do
     its('list.length') { should eq '1' }
   end

**Test if the init process is owned by the root user**

.. code-block:: ruby

   describe processes('init') do
     its('user') { should eq 'root' }
   end

**Test if a high-priority process is running**

.. code-block:: ruby

   describe processes('some_process') do
     its('state') { should eq 'R<' }
   end


registry_key -- DONE
=====================================================
Use the ``registry_key`` InSpec resource to test key values in the |windows| registry.

Syntax -- DONE
-----------------------------------------------------
A ``registry_key`` InSpec resource block declares the item in the |windows| registry, the path to a setting under that item, and then one (or more) name/value pairs to be tested. For example:

.. code-block:: ruby

   describe registry_key('registry_item', 'path\to\key') do
     its('name') { should eq 'value' }
   end

where

* ``'registry_item'`` is a key in the |windows| registry
* ``'path\to\key'`` is the path in the |windows| registry
* ``('name')`` and ``'value'`` represent the name of the key and the value assigned to that key

Matchers -- DONE
-----------------------------------------------------
This InSpec resource has the following matchers.

name -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``name`` matcher tests the value for the specified registry setting. For example:

.. code-block:: ruby

   its('name') { should eq 'value' }

Examples -- DONE
-----------------------------------------------------
The following examples show how to use this InSpec resource in a recipe.

**Test the start time for the Schedule service**

.. code-block:: ruby

   describe registry_key('Task Scheduler','HKEY_LOCAL_MACHINE\...\Schedule') do
     its('Start') { should eq 2 }
   end

where ``'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\Schedule'`` is the full path to the setting.


script -- DONE
=====================================================
Use the ``script`` InSpec resource to test a |powershell| script on the |windows| platform.

.. this one is a bit of a wild guess.

Syntax -- DONE
-----------------------------------------------------
A ``script`` InSpec resource block declares xxxxx. For example:

.. code-block:: ruby

   describe script do
     its('script_name') { should include 'total_wild_guess' }
   end

..
.. where
..
.. * ``xxxxx`` must specify xxxxx
.. * xxxxx
.. * ``xxxxx`` is a valid matcher for this InSpec resource
..

Matchers -- DONE
-----------------------------------------------------
This InSpec resource has the following matchers.

script_name -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``script_name`` matcher tests the named script against the value specified by the test. For example:

.. code-block:: ruby

   its('script_name') { should include 'total_wild_guess' }

Examples -- DONE
-----------------------------------------------------
The following examples show how to use this InSpec resource in a recipe.

.. stoopid test below; probably need a better one

**Test that user Grantmc belongs to the Active Directory object**

.. code-block:: ruby

   describe script do
     its('ADObject') { should include 'Get-ADPermission -Identity Grantmc' }
   end

..
.. **xxxxx**
..
.. xxxxx
..


security_policy -- DONE
=====================================================
Use the ``security_policy`` InSpec resource to test security policies on the |windows| platform.

Syntax -- DONE
-----------------------------------------------------
A ``security_policy`` InSpec resource block declares the name of a security policy and the value to be tested. For example:

.. code-block:: ruby

   describe security_policy do
     its('policy_name') { should eq 'value' }
   end

where

* ``'policy_name'`` must specify a security policy
* ``{ should eq 'value' }`` tests the value of ``policy_name`` against the value declared in the test

Matchers -- DONE
-----------------------------------------------------
This InSpec resource has the following matchers.

policy_name -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``policy_name`` matcher must be the name of a security policy. For example:

.. code-block:: ruby

   its('SeNetworkLogonRight') { should eq '*S-1-5-11' }

Examples -- DONE
-----------------------------------------------------
The following examples show how to use this InSpec resource in a recipe.

**Verify that only the Administrators group has remote access**

.. code-block:: ruby

   describe security_policy do
     its('SeRemoteInteractiveLogonRight') { should eq '*S-1-5-32-544' }
   end


service -- DONE
=====================================================
Use the ``service`` InSpec resource to test if the named service is installed, running and/or enabled.

Syntax -- DONE
-----------------------------------------------------
A ``service`` InSpec resource block declares the name of a service and then one (or more) matchers to test the state of the service. For example:

.. code-block:: ruby

   describe service('service_name') do
     it { should be_installed }
     it { should be_enabled }
     it { should be_running }
   end

..
.. where
..
.. * ``xxxxx`` must specify xxxxx
.. * xxxxx
.. * ``xxxxx`` is a valid matcher for this InSpec resource
..

Matchers -- DONE
-----------------------------------------------------
This InSpec resource has the following matchers.

be_enabled -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``be_enabled`` matcher tests if the named service is enabled. For example:

.. code-block:: ruby

   it { should be_enabled }

be_installed -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``be_installed`` matcher tests if the named service is installed. For example:

.. code-block:: ruby

   it { should be_installed }

be_running -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``be_running`` matcher tests if the named service is running. For example:

.. code-block:: ruby

   it { should be_running }

Examples -- DONE
-----------------------------------------------------
The following examples show how to use this InSpec resource in a recipe.

**Test if the postgresql service is both running and enabled**

.. code-block:: ruby

   describe service('postgresql') do
     it { should be_enabled }
     it { should be_running }
   end

**Test if the mysql service is both running and enabled**

.. code-block:: ruby

   describe service('mysqld') do
     it { should be_enabled }
     it { should be_running }
   end


ssh_config -- DONE
=====================================================
Use the ``ssh_config`` InSpec resource to test |openssh| |ssh| client configuration data located at ``etc/ssh/ssh_config`` on |linux| and |unix| platforms.

Syntax -- DONE
-----------------------------------------------------
A ``ssh_config`` InSpec resource block declares the client |openssh| configuration data to be tested. For example:

.. code-block:: ruby

   describe ssh_config('path') do
     its('name') { should include('foo') }
   end

where

* ``name`` is a configuration setting in ``ssh_config``
* ``('path')`` is the non-default ``/path/to/ssh_config``
* ``{ should include('foo') }`` tests the value of ``name`` as read from ``ssh_config`` versus the value declared in the test

Matchers -- DONE
-----------------------------------------------------
This InSpec resource has the following matchers.

name -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``name`` matcher tests the value of ``name`` as read from ``ssh_config`` versus the value declared in the test. For example:

.. code-block:: ruby

   its('name') { should eq 'foo' }

or:

.. code-block:: ruby

   it's('name') {should include('bar') }

Examples -- DONE
-----------------------------------------------------
The following examples show how to use this InSpec resource in a recipe.

**Test SSH configuration settings**

.. code-block:: ruby

   describe ssh_config do
     its('cipher') { should eq '3des' }
     its('port') { should '22' }
     its('hostname') { should include('example.com') }
   end

**Test which variables from the local environment are sent to the server**

.. code-block:: ruby

   return unless command('ssh').exist?

   describe ssh_config do
     its('SendEnv') { should include('GORDON_CLIENT') }
   end

**Test owner and group permissions**

.. code-block:: ruby

  describe ssh_config do
    its('owner') { should eq 'root' }
    its('mode') { should eq 644 }
  end


sshd_config -- DONE
=====================================================
Use the ``sshd_config`` InSpec resource to test configuration data for the |openssh| daemon located at ``etc/ssh/sshd_config`` on |linux| and |unix| platforms. sshd---the |openssh| daemon---listens on dedicated ports, starts a daemon for each incoming connection, and then handles encryption, authentication, key exchanges, command executation, and data exchanges.

Syntax -- DONE
-----------------------------------------------------
A ``sshd_config`` InSpec resource block declares the client |openssh| configuration data to be tested. For example:

.. code-block:: ruby

   describe sshd_config('path') do
     its('name') { should include('foo') }
   end

where

* ``name`` is a configuration setting in ``sshd_config``
* ``('path')`` is the non-default ``/path/to/sshd_config``
* ``{ should include('foo') }`` tests the value of ``name`` as read from ``ssh_config`` versus the value declared in the test

Matchers -- DONE
-----------------------------------------------------
This InSpec resource has the following matchers.

name -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``name`` matcher tests the value of ``name`` as read from ``sshd_config`` versus the value declared in the test. For example:

.. code-block:: ruby

   its('name') { should eq 'foo' }

or:

.. code-block:: ruby

   it's('name') {should include('bar') }

Examples -- DONE
-----------------------------------------------------
The following examples show how to use this InSpec resource in a recipe.

**Test which variables may be sent to the server**

.. code-block:: ruby

   return unless command('sshd').exist?

   describe sshd_config do
     its('AcceptEnv') { should include('GORDON_SERVER') }
   end

**Test for IPv6-only addresses**

.. code-block:: ruby

   return unless command('sshd').exist?

   describe sshd_config do
     its('AddressFamily') { should eq 'inet6' }
   end

**Test protocols**

.. code-block:: ruby

   describe sshd_config do
     its('Protocol') { should eq '2' }
   end


user -- DONE
=====================================================
Use the ``user`` InSpec resource to test user profiles, including the groups to which they belong, the frequency of required password changes, the directory paths to home and shell.

Syntax -- DONE
-----------------------------------------------------
A ``user`` InSpec resource block declares a user name, and then one (or more) matchers. For example:

.. code-block:: ruby

   describe user('root') do
     it { should exist }
     its('uid') { should eq 1234 }
     its('gid') { should eq 1234 }
     its('group') { should eq 'root' }
     its('groups') { should eq ['root', 'other']}
     its('home') { should eq '/root' }
     its('shell') { should eq '/bin/bash' }
     its('mindays') { should eq 0 }
     its('maxdays') { should eq 90 }
     its('warndays') { should eq 8 }
   end

where

* ``('root')`` is the user to be tested
* ``it { should exist }`` tests if the user exists
* ``gid``, ``group``, ``groups``, ``home``, ``maxdays``, ``mindays``, ``shell``, ``uid``, and ``warndays`` are valid matchers for this InSpec resource

Matchers -- DONE
-----------------------------------------------------
This InSpec resource has the following matchers.

exist -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``exist`` matcher tests if the named user exists. For example:

.. code-block:: ruby

   it { should exist }

gid -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``gid`` matcher tests the group identifier. For example:

.. code-block:: ruby

   its('gid') { should eq 1234 } }

where ``1234`` represents the user identifier.

group -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``group`` matcher tests the group to which the user belongs. For example:

.. code-block:: ruby

   its('group') { should eq 'root' }

where ``root`` represents the group.

groups -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``groups`` matcher tests two (or more) groups to which the user belongs. For example:

.. code-block:: ruby

   its('groups') { should eq ['root', 'other']}

home -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``home`` matcher tests the home directory path for the user. For example:

.. code-block:: ruby

   its('home') { should eq '/root' }

maxdays -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``maxdays`` matcher tests the maximum number of days between password changes. For example:

.. code-block:: ruby

   its('maxdays') { should eq 99 }

where ``99`` represents the maximum number of days.

mindays -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``mindays`` matcher tests the minimum number of days between password changes. For example:

.. code-block:: ruby

   its('mindays') { should eq 0 }

where ``0`` represents the maximum number of days.

shell -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``shell`` matcher tests the path to the default shell for the user. For example:

.. code-block:: ruby

   its('shell') { should eq '/bin/bash' }

uid -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``uid`` matcher tests the user identifier. For example:

.. code-block:: ruby

   its('uid') { should eq 1234 } }

where ``1234`` represents the user identifier.

warndays -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``warndays`` matcher tests the number of days a user is warned before a password must be changed. For example:

.. code-block:: ruby

   its('warndays') { should eq 5 }

where ``5`` represents the number of days a user is warned.

Examples -- DONE
-----------------------------------------------------
The following examples show how to use this InSpec resource in a recipe.

..
.. **xxxxx**
..
.. xxxxx
..
.. **xxxxx**
..
.. xxxxx
..


windows_feature -- DONE
=====================================================
Use the ``windows_feature`` InSpec resource to test features on |windows|. The ``Get-WindowsFeature`` cmdlet returns the following values: ``Property Name``, ``DisplayName``, ``Description``, ``Installed``, and ``InstallState``, returned as a |json| object similar to:

.. code-block:: javascript

   {
     "Name": "XPS-Viewer",
     "DisplayName": "XPS Viewer",
     "Description": "The XPS Viewer reads, sets permissions, and digitally signs XPS documents.",
     "Installed": false,
     "InstallState": 0
   }

Syntax -- DONE
-----------------------------------------------------
A ``windows_feature`` InSpec resource block declares the name of the |windows| feature, tests if that feature is installed, and then returns information about that feature. For example:

.. code-block:: ruby

   describe windows_feature('feature_name') do
     it { should be_installed }
   end

where

* ``('feature_name')`` must specify a |windows| feature name, such as ``DHCP Server`` or ``IIS-Webserver``
* ``be_installed`` is a valid matcher for this InSpec resource

Matchers -- DONE
-----------------------------------------------------
This InSpec resource has the following matchers.

be_installed -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``be_installed`` matcher tests if the named |windows| feature is installed. For example:

.. code-block:: ruby

   it { should be_installed }

If the feature is installed, the ``Get-WindowsFeature`` cmdlet is run and the name, display name, description, and install state is returned as a |json| object.

Examples -- DONE
-----------------------------------------------------
The following examples show how to use this InSpec resource in a recipe.

**Test the DHCP Server feature **

.. code-block:: ruby

   describe windows_feature('DHCP Server') do
     it{ should be_installed }
   end


yaml -- DONE
=====================================================
Use the ``yaml`` InSpec resource to test configuration data in a |yaml| file.

Syntax -- DONE
-----------------------------------------------------
A ``yaml`` InSpec resource block declares the configuration data to be tested. For example:

.. code-block:: ruby

   describe yaml do
     its('name') { should eq 'foo' }
   end

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

Matchers -- DONE
-----------------------------------------------------
This InSpec resource has the following matchers.

name -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``name`` matcher tests the value of ``name`` as read from a |yaml| file versus the value declared in the test. For example:

.. code-block:: ruby

   its('name') { should eq 'foo' }

Examples -- DONE
-----------------------------------------------------
The following examples show how to use this InSpec resource in a recipe.

**Test a kitchen.yml file driver**

.. code-block:: ruby

   describe yaml('.kitchen.yaml') do
     its('driver.name') { should eq('vagrant') }
   end

yum -- DONE
=====================================================
Use the ``yum`` InSpec resource to test packages in the |yum| repository.

Syntax -- DONE
-----------------------------------------------------
A ``yum`` InSpec 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"). For example:

.. code-block:: ruby

   describe yum.repo('name') do
     it { should exist }
     it { should be_enabled }
   end

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 -- DONE
-----------------------------------------------------
This InSpec resource has the following matchers.

be_enabled -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``be_enabled`` matcher tests if the package repository is a valid package source. For example:

.. code-block:: ruby

   it { should be_enabled }

exist -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``exist`` matcher tests if the package repository exists. For example:

.. code-block:: ruby

   it { should exist }

repo('name') -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The ``repo('name')`` matcher names a specific package repository. For example:

.. code-block:: ruby

   describe yum.repo('epel') do
     ...
   end

repos -- DONE
+++++++++++++++++++++++++++++++++++++++++++++++++++++
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:

.. code-block:: ruby

   its('repos') { should include 'some_repo' }

Examples -- DONE
-----------------------------------------------------
The following examples show how to use this InSpec resource in a recipe.

**Test if the yum repo exists**

.. code-block:: ruby

   describe yum do
     its('repos') { should exist }
   end

**Test if the 'base/7/x86_64' repo exists and is enabled**

.. code-block:: ruby

   describe yum do
     its('repos') { should include 'base/7/x86_64' }
     its('epel') { should exist }
     its('epel') { should be_enabled }
   end

**Test if a specific yum repo exists**

.. code-block:: ruby

   describe yum.repo('epel') do
     it { should exist }
     it { should be_enabled }
   end