inspec 0.34.1 → 1.0.0

data/docs/dsl_inspec.rst

@@ -1,259 +0,0 @@
-=====================================================
-InSpec DSL
-=====================================================
-
-|inspec| is a run-time framework and rule language used to specify compliance, security, and policy requirements. It includes a collection of resources that help you write auditing controls quickly and easily. The syntax used by both open source and |chef compliance| auditing is the same. The open source |inspec resource| framework is compatible with |chef compliance|.
-
-The InSpec DSL is a Ruby DSL for writing audit controls, which includes audit resources that you can invoke.
-
-The following sections describe the syntax and show some simple examples of using the |inspec resources| to define
-
-Syntax
-=====================================================
-
-The following resource tests |ssh| server configuration. For example, a simple control may described as:
-
-.. code-block:: ruby
-
-  describe sshd_config do
-    its('Port') { should eq('22') }
-  end
-
-In various use cases like implementing IT compliance across different departments, it becomes handy to extend the control with metadata. Each control may define an additional ``impact``, ``title`` or ``desc``. An example looks like:
-
-.. code-block:: ruby
-
-   control 'sshd-8' do
-     impact 0.6
-     title 'Server: Configure the service port'
-     desc '
-       Always specify which port the SSH server should listen to.
-       Prevent unexpected settings.
-     '
-     tag 'ssh','sshd','openssh-server'
-     tag cce: 'CCE-27072-8'
-     ref 'NSA-RH6-STIG - Section 3.5.2.1', url: 'https://www.nsa.gov/ia/_files/os/redhat/rhel5-guide-i731.pdf'
-
-     describe sshd_config do
-       its('Port') { should eq('22') }
-     end
-   end
-
-
-where
-
-* ``'sshd-8'`` is the name of the control
-* ``impact``, ``title``, and ``desc`` define metadata that fully describes the importance of the control, its purpose, with a succinct and complete description
-* ``impact`` is an float that measures the importance of the compliance results and must be a value between ``0.0`` and ``1.0``.
-* ``tag`` is optional meta-information with with key or key-value pairs
-* ``ref`` is a reference to an external document
-* ``describe`` is a block that contains at least one test. A ``control`` block must contain at least one ``describe`` block, but may contain as many as required
-* ``sshd_config`` is an |inspec| resource. For the full list of InSpec resources, see |inspec| resource documentation
-* ``its('Port')`` is the matcher; ``{ should eq('22') }`` is the test. A ``describe`` block must contain at least one matcher, but may contain as many as required
-
-
-Advanced concepts
-=====================================================
-
-With inspec it is possible to check if at least one of a collection of checks is true. For example: If a setting is configured in two different locations, you may want to test if either configuration A or configuration B have been set. This is accomplished via ``describe.one``. It defines a block of tests with at least one valid check.
-
-.. code-block:: ruby
-
-   describe.one do
-     describe ConfigurationA do
-       its('setting_1') { should eq true }
-     end
-
-     describe ConfigurationB do
-       its('setting_2') { should eq true }
-     end
-   end
-
-Examples
-=====================================================
-The following examples show simple compliance tests using a single ``control`` block.
-
-Test System Event Log
------------------------------------------------------
-The following test shows how to audit machines running |windows| 2012 R2 that pwassword complexity is enabled:
-
-.. code-block:: ruby
-
-  control 'windows-account-102' do
-    impact 1.0
-    title 'Windows Password Complexity is Enabled'
-    desc 'Password must meet complexity requirement'
-    describe security_policy do
-      its('PasswordComplexity') { should eq 1 }
-    end
-  end
-
-Are PosgtreSQL passwords empty?
------------------------------------------------------
-The following test shows how to audit machines running |postgresql| to ensure that passwords are not empty.
-
-.. code-block:: ruby
-
-   control 'postgres-7' do
-     impact 1.0
-     title 'Don't allow empty passwords'
-     describe postgres_session('user', 'pass').query("SELECT * FROM pg_shadow WHERE passwd IS NULL;") do
-       its('output') { should eq('') }
-     end
-   end
-
-
-Are MySQL passwords in ENV?
------------------------------------------------------
-The following test shows how to audit machines running |mysql| to ensure that passwords are not stored in ``ENV``:
-
-.. code-block:: ruby
-
-   control 'mysql-3' do
-     impact 1.0
-     title 'Do not store your MySQL password in your ENV'
-     desc '
-       Storing credentials in your ENV may easily expose
-       them to an attacker. Prevent this at all costs.
-     '
-     describe command('env') do
-       its('stdout') { should_not match(/^MYSQL_PWD=/) }
-     end
-   end
-
-Is /etc/ssh a Directory?
------------------------------------------------------
-The following test shows how to audit machines to ensure that ``/etc/ssh`` is a directory:
-
-.. code-block:: ruby
-
-   control 'basic-1' do
-     impact 1.0
-     title '/etc/ssh should be a directory'
-     desc '
-       In order for OpenSSH to function correctly, its
-       configuration path must be a folder.
-     '
-     describe file('/etc/ssh') do
-       it { should be_directory }
-     end
-   end
-
-Is Apache running?
------------------------------------------------------
-The following test shows how to audit machines to ensure that |apache| is enabled and running:
-
-.. code-block:: ruby
-
-   control 'apache-1' do
-     impact 0.3
-     title 'Apache2 should be configured and running'
-     describe service(apache.service) do
-       it { should be_enabled }
-       it { should be_running }
-     end
-   end
-
-Are insecure packages installed ?
------------------------------------------------------
-The following test shows how to audit machines for insecure packages:
-
-.. code-block:: ruby
-
-  control 'cis-os-services-5.1.3' do
-    impact 0.7
-    title '5.1.3 Ensure rsh client is not installed'
-
-    describe package('rsh') do
-      it { should_not be_installed }
-    end
-
-    describe package('rsh-redone-client') do
-      it { should_not be_installed }
-    end
-  end
-
-
-Test Windows Registry Keys
------------------------------------------------------
-The following test shows how to audit machines to ensure Safe DLL Seach Mode is enabled:
-
-.. code-block:: ruby
-
-  control 'windows-base-101' do
-    impact 1.0
-    title 'Safe DLL Search Mode is Enabled'
-    desc '
-      @link: https://msdn.microsoft.com/en-us/library/ms682586(v=vs.85).aspx
-    '
-    describe registry_key('HKLM\\System\\CurrentControlSet\\Control\\Session Manager') do
-      it { should exist }
-      it { should_not have_property_value('SafeDllSearchMode', :type_dword, '0') }
-    end
-  end
-
-Exclude specific test
------------------------------------------------------
-This shows how to allow skipping certain tests if conditions are not met, by using ``only_if``.
-In this example the test will not be performed if ``redis-cli`` command does not exist, because for example package on remote host was not installed.
-
-.. code-block:: ruby
-
-  control 'nutcracker-connect-redis-001' do
-    impact 1.0
-    title 'Check if nutcracker can pass commands to redis'
-    desc 'execute redis-cli set key command, to check connectivity of the service'
-
-    only_if do
-      command('redis-cli').exist?
-    end
-
-    describe command('redis-cli SET test_inspec "HELLO"') do
-      its(:stdout) { should match(/OK/) }
-    end
-  end
-
-Mixing this with other conditionals (like checking existence of the files etc.) can help to test different test paths using inspec. This way you can skip certain tests which would 100% fail due to the way servers are prepared, but you know that the same test suites are reused later in different circumstances by different teams.
-
-Additional metadata for controls
------------------------------------------------------
-
-The following example illustrates various ways to add tags and references to `control`
-
-.. code-block:: ruby
-
-  control 'ssh-1' do
-      impact 1.0
-
-      title 'Allow only SSH Protocol 2'
-      desc 'Only SSH protocol version 2 connections should be permitted.
-            The default setting in /etc/ssh/sshd_config is correct, and can be
-            verified by ensuring that the following line appears: Protocol 2'
-
-      tag 'production','development'
-      tag 'ssh','sshd','openssh-server'
-
-      tag cce: 'CCE-27072-8'
-      tag disa: 'RHEL-06-000227'
-
-      tag remediation: 'stig_rhel6/recipes/sshd-config.rb'
-      tag remediation: 'https://supermarket.chef.io/cookbooks/ssh-hardening'
-
-      ref 'NSA-RH6-STIG - Section 3.5.2.1', url: 'https://www.nsa.gov/ia/_files/os/redhat/rhel5-guide-i731.pdf'
-      ref 'http://people.redhat.com/swells/scap-security-guide/RHEL/6/output/ssg-centos6-guide-C2S.html'
-
-      describe ssh_config do
-          its ('Protocol') { should eq '2'}
-      end
-   end`
-
-
-
-.. |inspec| replace:: InSpec
-.. |inspec resource| replace:: InSpec Resource
-.. |chef compliance| replace:: Chef Compliance
-.. |ruby| replace:: Ruby
-.. |ssh| replace:: SSH
-.. |windows| replace:: Microsoft Windows
-.. |postgresql| replace:: PostgreSQL
-.. |apache| replace:: Apache

data/docs/dsl_resource.rst

@@ -1,90 +0,0 @@
-=====================================================
-Resource DSL
-=====================================================
-
-InSpec provides a mechanism for defining custom resources. These become available with their respective names and provide easy functionality to profiles.
-
-Resource location
------------------------------------------------------
-
-Resources may be added to profiles in the `libraries` folder:
-
-.. code-block:: bash
-
-  $ tree examples/profile
-  examples/profile
-  ...
-  ├── libraries
-  │   └── gordon_config.rb
-
-
-Resource structure
------------------------------------------------------
-
-The smallest possible resource takes this form:
-
-.. code-block:: ruby
-
-  class Tiny < Inspec.resource(1)
-    name 'tiny'
-  end
-
-Resources are written as a regular Ruby `class` which inherits from `Inspec.resource`. The number (`1`) specifies the version this resource plugin targets. As InSpec evolves, this interface may change and may require a higher version.
-
-The following attributes can be configured:
-
-* `name` - Identifier of the resource (required)
-* `desc` - Description of the resource (optional)
-* `example` - Example usage of the resource (optional)
-
-The following methods are available to the resource:
-
-* `inspec` - Contains a registry of all other resources to interact with the operating system or target in general.
-* `skip_resource` - A resource may call this method to indicate, that requirements aren't met. All tests that use this resource will be marked as `skipped`.
-
-The following example shows a full resource using attributes and methods to provide simple access to a configuration file:
-
-.. code-block:: ruby
-
-  class GordonConfig < Inspec.resource(1)
-    name 'gordon_config'
-
-    desc '
-      Resource description ...
-    '
-
-    example '
-      describe gordon_config do
-        its("signal") { should eq "on" }
-      end
-    '
-
-    # Load the configuration file on initialization
-    def initialize(path = nil)
-      @path = path || '/etc/gordon.conf'
-      @params = SimpleConfig.new( read_content )
-    end
-
-    # Expose all parameters of the configuration file.
-    def method_missing(name)
-      @params[name]
-    end
-
-    private
-
-    def read_content
-      f = inspec.file(@path)
-      # Test if the path exist and that it's a file
-      if f.file?
-        # Retrieve the file's contents
-        f.content
-      else
-        # If the file doesn't exist, skip all tests that use gordon_config
-        skip_resource "Can't read config from #{@path}."
-      end
-    end
-  end
-
-For a full example, see our `example resource`_.
-
-.. _example resource: ../examples/profile/libraries/gordon_config.rb

data/docs/inspec_and_friends.rst

@@ -1,85 +0,0 @@
-=====================================================
-InSpec and friends
-=====================================================
-
-RSpec
-=====================================================
-
-RSpec is an awesome framework that is widely used to test Ruby code. It enables test-driven development (TDD) and helps developers to write better code every day.
-
-InSpec is built on top of RSpec and uses it as the underlying foundation to execute tests. It uses the key strengths of RSpec, easily execute tests and a DSL to write tests, but extends the functionality for use as compliance audits. InSpec ships with custom audit resources that make it easy to write audit checks and with the ability to run those checks on remote servers. These audit resources provided know the differences between operating systems and help you abstract from the local operating system, similar to other resources you might use in your Chef recipes.
-
-A complete InSpec rule looks like:
-
-.. code-block:: ruby
-
-  control "sshd-11" do
-    impact 1.0
-    title "Server: Set protocol version to SSHv2"
-    desc "Set the SSH protocol version to 2. Don't use legacy
-          insecure SSHv1 connections anymore."
-    tag security: "level-1"
-    tag "openssh-server"
-    ref "Server Security Guide v.1.0", url: "http://..."
-
-    describe sshd_config do
-      its('Protocol') { should eq('2') }
-    end
-  end
-
-
-
-Serverspec
-=====================================================
-
-Serverspec can be credited as the first extension of RSpec that enabled users to run RSpec tests on servers to verify deployed artifacts. It was created in March 2013 by Gosuke Miyashita and has been widely adopted. It is also one of the core test frameworks within test-kitchen and has been widely used within the Chef ecosystem.  InSpec takes lessons learned implementing and using Serverspec and builds on them to make auditing and compliance easier.
-
-Lessons learned from Serverspec include:
-
-* IT, compliance, and security professional require metadata beyond what Serverspec offers, such as criticality, to fully describe controls.
-
-* Setting up and running the same tests across multiple machines must be easy.
-
-* It must be easy to locate, debug, and extend operating system-dependent code.
-
-* It must be easy to extend the language and create custom resources.
-
-* It must run multiple tests simultaneously.
-
-* Support for Windows is a first-class requirement.
-
-* A command line interface (CLI) is required for faster iteration of test code.
-
-
-How is InSpec different than Serverspec
------------------------------------------------------
-
-One of the key differences is that InSpec targets more user groups. It is optimized for DevOps, Security, and Compliance professionals. Additional metadata, such as impact, title, and description, make it easier to fully describe the controls which makes it easier to share the controls with other departments. This enables Security departments to prioritize rules. DevOps teams use this information to focus on the most critical issues to remediate.
-
-.. code-block:: ruby
-
-  control "sshd-11" do
-    impact 1.0
-    title "Server: Set protocol version to SSHv2"
-    desc "Set the SSH protocol version to 2. Don't use legacy
-          insecure SSHv1 connections anymore."
-    tag security: "level-1"
-    tag "openssh-server"
-    ref "Server Security Guide v.1.0" url: "http://..."
-
-    describe sshd_config do
-      its('Protocol') { should cmp 2 }
-    end
-  end
-
-**Why not fork Serverspec?**
-
-InSpec started as an extension of Serverspec. As the extension grew, it became clear that a new library was required.  Creating and maintaining a fork was not practical so a new project was born.
-
-**Will InSpec only work on machines managed by Chef?**
-
-No, InSpec can be used on any machine.  It doesn’t matter if that machine was configured by Chef or configured lovingly by the hands of your local System Administrator.
-
-**Is InSpec a replacement of Serverspec?**
-
-InSpec is intended to be a drop-in replacement of Serverspec. Popular Serverspec resources have been ported to InSpec. It changed some behaviour as documented in our migration guide.

data/docs/matchers.rst

@@ -1,137 +0,0 @@
-=====================================================
-InSpec Matchers Reference
-=====================================================
-
-
-Inspec uses matchers to help compare resource values to expectations. The following matchers are available:
-
-* `be`
-* `cmp`
-* `eq`
-* `include`
-* `match`
-
-
-be
-=====================================================
-
-This matcher can be followed by many different comparison operators. Always make sure to use numbers, not strings, for these comparisons.
-
-.. code-block:: ruby
-
-  describe file('/proc/cpuinfo') do
-    its('size') { should be >= 10 }
-    its('size') { should be < 1000 }
-  end
-
-cmp
-=====================================================
-
-Unlike ``eq``, cmp is a matcher for less-restrictive comparisons. It will try to fit the actual value to the type you are comparing it to. This is meant to relieve the user from having to write type-casts and resolutions.
-
-.. code-block:: ruby
-
-  describe sshd_config do
-    its('Protocol') { should cmp 2 }
-  end
-
-  describe passwd.uid(0) do
-    its('users') { should cmp 'root' }
-  end
-
-``cmp`` behaves in the following way:
-
-* Compare strings to numbers
-
-  .. code-block:: ruby
-
-    describe sshd_config do
-      its('Protocol') { should eq '2' }
-
-      its('Protocol') { should cmp '2' }
-      its('Protocol') { should cmp 2 }
-    end
-
-* String comparisons are not case-sensitive
-
-  .. code-block:: ruby
-
-    describe auditd_conf do
-      its('log_format') { should cmp 'raw' }
-      its('log_format') { should cmp 'RAW' }
-    end
-
-* Compare arrays with only one entry to a value
-
-  .. code-block:: ruby
-
-    describe passwd.uids(0) do
-      its('users') { should cmp 'root' }
-      its('users') { should cmp ['root'] }
-    end
-
-* Single-value arrays of strings may also be compared to a regex
-
-  .. code-block:: ruby
-
-    describe auditd_conf do
-      its('log_format') { should cmp /raw/i }
-    end
-
-* Improved printing of octal comparisons
-
-  .. code-block:: ruby
-
-    describe file('/proc/cpuinfo') do
-      its('mode') { should cmp '0345' }
-    end
-
-    expected: 0345
-    got: 0444
-
-eq
-=====================================================
-
-Test for exact equality of two values.
-
-.. code-block:: ruby
-
-  describe sshd_config do
-    its('RSAAuthentication') { should_not eq 'no' }
-    its('Protocol') { should eq '2' }
-  end
-
-It fails if types don't match. Please keep this in mind, when comparing configuration
-entries that are numbers:
-
-.. code-block:: ruby
-
-  its('Port') { should eq '22' } # ok
-
-  its('Port') { should eq 22 }
-  # fails: '2' != 2 (string vs int)
-
-For less restrictive comparisons, please use ``cmp``.
-
-include
-=====================================================
-
-Verifies if a value is included in a list.
-
-.. code-block:: ruby
-
-  describe passwd do
-    its('users') { should include 'my_user' }
-  end
-
-
-match
-=====================================================
-
-Check if a string matches a regular expression.
-
-.. code-block:: ruby
-
-  describe sshd_config do
-    its('Ciphers') { should_not match /cbc/ }
-  end