inspec/docs/profiles.rst

=====================================================
InSpec Profiles
=====================================================

InSpec supports the creation of complex test and compliance profiles, which organize controls to support dependency management and code re-use. These profiles are standalone structures with their own distribution and execution flow.

InSpec profile structure
-----------------------------------------------------

To create a new profile just place the files according to the following structure:

.. code-block:: bash

  $ tree examples/profile
  examples/profile
  ├── README.md
  ├── controls
  │   ├── example.rb
  │   └── gordon.rb
  ├── libraries
  │   └── gordon_config.rb
  └── inspec.yml


 * `inspec.yml` - includes the profile description (required)
 * `controls` - a folder which contains  all tests (required)
 * `libraries` - a folder which contains InSpec resource extensions (optional)
 * `README.md` - a best-practice readme to each explain the profile and its scope

For a full example, see our `example profile`_.

.. _example profile: ../examples/profile

InSpec profile manifest
-----------------------------------------------------

Each profile has a manifest file `inspec.yml`. It looks as follows

.. code-block:: yaml

  name: ssh
  title: Basic SSH
  maintainer: Chef Software, Inc.
  copyright: Chef Software, Inc.
  copyright_email: support@chef.io
  license: Proprietary, All rights reserved
  summary: Verify that SSH Server and SSH Client are configured securely
  version: 1.0.0
  supports:
    - os-family: linux


A manifest description may contain the following values:

 * `name` - Identifier of the profile (required)
 * `title` - Human-readable name of the profile (optional)
 * `maintainer` - Name of the profile maintainer (optional)
 * `copyright` - Copyright holder (optional)
 * `copyright_email` - Support contact for profile (optional)
 * `license` - License of the profile (optional)
 * `summary` - One-line summary of the profile (optional)
 * `description` - Description of the profile (optional)
 * `version` - Version of the profile (optional)
 * `supports` - A list of supported targets (optional)

Supported targets
-----------------------------------------------------

The manifest contains the `supports` flag, which specifies operating systems or even cloud systems that the profile is targeting.

This list can contain simple names, names and versions, or detailed flags for the targeted system. These can freely be combined:

.. code-block:: yaml

  name: ssh
  supports:
    // Runs on any version of Debian Linux
    - os-name: debian

    // Only runs on Ubuntu 14.04
    - os-name: ubuntu
      release: 14.04

    // Targets RedHat, CentOS, Oracle Linux ...
    - os-family: redhat

    // Or even broader
    - platform: aws


InSpec profile verification
-----------------------------------------------------

InSpec ships with a verification command that verifies the implementation of a profile

$ inspec check examples/profile


InSpec profile archive
-----------------------------------------------------

Profiles are composed of multiple files. This hinders easy distribution of a profile. InSpec solves the problem by offering to collect all files in one archive.

The InSpec profile archive format aims for flexibility and reuse of standard and common technologies:

 * tar and gzip (default)
 * zip
 * HTTP

This should enable third-parties to easily build InSpec profile archives:

 * InSpec archives MUST be named with the stanard suffix
 * InSpec archives MUST be a tar.gz or zip formatted file
 * InSpec archives MUST have no duplicate entries
 * InSpec archives MAY be compressed with gzip, bzip2, or xz.

InSpec is able to create profile archive for you. By default it generates a tar-file on Unix and zip on Windows or Mac.

.. code-block:: bash

  # will generate a example-profile.tar.gz
  $ inspec archive examples/profile

  # will generate a example-profile.zip
  $ inspec archive examples/profile --zip


Profile inheritance
-----------------------------------------------------

**Include controls of existing profile**

The `include_controls` keyword allows you to import all rules from an existing profile. This can be easily extended with additional rules.

.. code-block:: bash

  include_controls 'cis-level-1' do

    control "cis-fs-2.7" do
      impact 1.0
    ...

  end

**Inherit from a profile, but skip some rules**

Sometimes, not all requirements can be fullfiled for a legacy application. To manage the derivation, you can skip certain controls with `skip_control`.

.. code-block:: bash

  include_controls 'cis-level-1' do

    skip_control "cis-fs-2.1"
    skip_control "cis-fs-2.2"

  end

**Load specific controls from another profile**

.. code-block:: bash

  require_controls 'cis-level-1' do

    control "cis-fs-2.1"
    control "cis-fs-2.2"

  end