inspec 0.34.1 → 1.0.0

data/docs/inspec_and_friends.md

@@ -0,0 +1,105 @@
+---
+title: InSpec and friends
+---
+
+# InSpec and friends
+
+This page looks at projects that are similar to InSpec to explain how they
+relate to each other.
+
+## 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:
+
+```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.
+
+```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.md

@@ -0,0 +1,136 @@
+---
+title: InSpec Matchers Reference
+---
+
+# 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.
+
+```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.
+
+```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
+
+    ```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
+
+    ```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
+
+    ```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
+
+    ```ruby
+    describe auditd_conf do
+      its('log_format') { should cmp /raw/i }
+    end
+    ```
+
+* Improved printing of octal comparisons
+
+    ```ruby
+    describe file('/proc/cpuinfo') do
+      its('mode') { should cmp '0345' }
+    end
+
+    expected: 0345
+    got: 0444
+    ```
+
+## eq
+
+Test for exact equality of two values.
+
+```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:
+
+```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.
+
+```ruby
+describe passwd do
+  its('users') { should include 'my_user' }
+end
+```
+
+## match
+
+Check if a string matches a regular expression.
+
+```ruby
+describe sshd_config do
+  its('Ciphers') { should_not match /cbc/ }
+end
+```

data/docs/plugin_kitchen_inspec.html.md

@@ -0,0 +1,55 @@
+---
+title: About kitchen-inspec
+---
+
+# kitchen-inspec
+
+The `kitchen-inspec` driver enables InSpec to be used as a verifier within Kitchen.
+
+To use InSpec as a verifier, add it to the kitchen.yml file:
+
+    verifier:
+      name: inspec
+
+To define a suite that pulls its run-list from the Chef Compliance server:
+
+    suites:
+      - name: compliance
+        run_list:
+          - recipe[ssh-hardening]
+        verifier:
+          inspec_tests:
+            - compliance://base/ssh
+
+and then run the following command:
+
+    $ inspec compliance login https://compliance.test --user admin --insecure --token ''
+
+where `--insecure` is required when using self-signed certificates.
+
+To define a suite that pulls its run-list from the Chef Supermarket:
+
+    suites:
+      - name: supermarket
+        run_list:
+          - recipe[ssh-hardening]
+        verifier:
+          inspec_tests:
+            - supermarket://hardening/ssh-hardening
+
+The `kitchen-inspec` driver expects tests to be located in the `test/integration` directory in a cookbook. For example::
+
+    .
+    ├── Berksfile
+    ├── Gemfile
+    ├── README.md
+    ├── metadata.rb
+    ├── recipes
+    │   ├── default.rb
+    │   └── nginx.rb
+    └── test
+        └── integration
+            └── default
+                ├── controls
+                ├── inspec.yml
+                └── libraries

data/docs/profiles.md

@@ -0,0 +1,285 @@
+---
+title: About InSpec Profiles
+---
+
+# InSpec Profiles
+
+InSpec supports the creation of complex test and compliance profiles, which organize controls to support dependency management and code reuse. Each profile is a standalone structure with its own distribution and execution flow.
+
+# Profile Structure
+
+A profile should have the following structure::
+
+    examples/profile
+    ├── README.md
+    ├── controls
+    │   ├── example.rb
+    │   └── control_etc.rb
+    ├── libraries
+    │   └── extension.rb
+    └── inspec.yml
+
+where:
+
+* `inspec.yml` includes the profile description (required)
+* `controls` is the directory in which all tests are located (required)
+* `libraries` is the directory in which all InSpec resource extensions are located (optional)
+* `README.md` should be used to explain the profile, its scope, and usage
+
+See a complete example profile in the InSpec open source repository: https://github.com/chef/inspec/tree/master/examples/profile
+
+## inspec.yml
+
+Each profile must have an `inspec.yml` file that defines the following information:
+
+ * Use `name` to specify a unique name for the profile. Required.
+ * Use `title` to specify a human-readable name for the profile.
+ * Use `maintainer` to specify the profile maintainer.
+ * Use `copyright` to specify the copyright holder.
+ * Use `copyright_email` to specify support contact information for the profile, typically an email address.
+ * Use `license` to specify the license for the profile.
+ * Use `summary` to specify a one line summary for the profile.
+ * Use `description` to specify a multiple line description of the profile.
+ * Use `version` to specify the profile version.
+ * Use `supports` to specify a list of supported platform targets.
+ * Use `depends` to define a list of profiles on which this profile depends.
+
+`name` is required; all other profile settings are optional. For example:
+
+    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
+    depends:
+      - name: profile
+        path: ../path/to/profile
+
+## Verify Profiles
+
+Use the `inspec check` command to verify the implementation of a profile:
+
+    $ inspec check examples/profile
+
+# Platform Support
+
+Use the `supports` setting in the `inspec.yml` file to specify one (or more) platforms for which a profile is targeting. The list of supported platforms may contain simple names, names and versions, or detailed flags, and may be combined arbitrarily. For example, to target anything running Debian Linux:
+
+    name: ssh
+    supports:
+      - os-name: debian
+
+and to target only Ubuntu version 14.04
+
+    name: ssh
+    supports:
+      - os-name: ubuntu
+        release: 14.04
+
+and to target the entire RedHat platform (including CentOS and Oracle Linux):
+
+    name: ssh
+    supports:
+      - os-family: redhat
+
+and to target anything running on Amazon AWS:
+
+    name: ssh
+    supports:
+      - platform: aws
+
+and to target all of these examples in a single `inspec.yml` file:
+
+    name: ssh
+    supports:
+      - os-name: debian
+    supports:
+      - os-name: ubuntu
+        release: 14.04
+    supports:
+      - os-family: redhat
+    supports:
+      - platform: aws
+
+
+# Profile Dependencies
+
+Use the `depends` setting in the `inspec.yml` file to specify one (or more) profiles on which this profile depends. A profile dependency may be sourced from a path, URL, a git repo, a cookbook located on Chef Supermarket or on GitHub, or a profile located on the Chef Compliance server.
+
+## Path
+
+The `path` setting defines a profile that is located on disk. This setting is typically used during development of profiles and when debugging profiles. This setting does not support version constraints. If the location of the profile does not exist, an error is returned.
+
+For example:
+
+    depends:
+    - name: my-profile
+      path: /absolute/path
+    - name: another
+      path: ../relative/path
+
+## URL
+
+The `url` setting specifies a profile that is located at an HTTP- or HTTPS-based URL. The profile must be accessible via a HTTP GET operation and must be a valid profile archive (zip, tar, tar.gz format). If the download fails, the profile is inaccessible, or not in the correct format, an error is returned.
+
+For example:
+
+    depends:
+    - name: my-profile
+      url: https://my.domain/path/to/profile.tgz
+
+## git
+
+A `git` setting specifies a profile that is located in a git repository, with optional settings for branch, tag, commit, and version. The source location is translated into a URL upon resolution. This type of dependency supports version indexing via semantic versioning as git tags.
+
+For example:
+
+    depends:
+    - name: git-profile
+      git: http://url/to/repo
+      branch:  desired_branch
+      tag:     desired_version
+      commit:  pinned_commit
+      version: semver_via_tags
+
+## Chef Supermarket
+
+A `supermarket` setting specifies a profile that is located in a cookbook hosted on Chef Supermarket, with optional settings for branch, tag, commit, and version. The source location is translated into a URL upon resolution. This type of dependency supports version indexing via semantic versioning as git tags.
+
+For example:
+
+    depends:
+    - name: supermarket-profile
+      git: username/profile
+      branch:  desired_branch
+      tag:     desired_version
+      commit:  pinned_commit
+      version: semver_via_tags
+
+## GitHub
+
+A `github` setting specifies a profile that is located in a repository hosted on GitHub, with optional settings for branch, tag, commit, and version. The source location is translated into a URL upon resolution. This type of dependency supports version indexing via semantic versioning as git tags.
+
+For example:
+
+    depends:
+    - name: gh-profile
+      git: username/project
+      branch:  desired_branch
+      tag:     desired_version
+      commit:  pinned_commit
+      version: semver_via_tags
+
+## Chef Compliance
+
+A `compliance` setting specifies a profile that is located on the Chef Compliance server.
+
+For example:
+
+    depends:
+      - name: linux
+        compliance: base/linux
+
+
+## Define in inspec.yml
+
+Use the `depends` setting in the `inspec.yml` file to define any combination of profile dependencies. For example:
+
+    depends:
+      - name: ssh-hardening
+        supermarket: hardening/ssh-hardening
+      - name: os-hardening
+        url: https://github.com/dev-sec/tests-os-hardening/archive/master.zip
+      - name: ssl-benchmark
+        git: https://github.com/dev-sec/ssl-benchmark.git
+      - name: windows-patch-benchmark
+        git: https://github.com/chris-rock/windows-patch-benchmark.git
+      - name: linux
+        compliance: base/linux
+
+# Profile Inheritance
+
+When a profile is run, it may include controls that are defined in other profiles. Controls may also be required.
+
+## include_controls
+
+The `include_controls` keyword may be used in a profile to import all rules from the named profile.
+
+For example, to include controls from the `cis-level-1` profile when running the `cis-fs-2.7` profile:
+
+    include_controls 'cis-level-1' do
+
+      control "cis-fs-2.7" do
+        impact 1.0
+      ...
+
+    end
+
+To include controls from the `cis-level-1` profile, but skipping two controls within that profile:
+
+    include_controls 'cis-level-1' do
+
+      skip_control "cis-fs-2.1"
+      skip_control "cis-fs-2.2"
+
+    end
+
+## require_controls
+
+The `require_controls` keyword may be used to load only specific controls from the named profile.
+
+For example, to require that controls `cis-fs-2.1` and `cis-fs-2.2` be loaded from the `cis-level-1` profile:
+
+    require_controls 'cis-level-1' do
+
+      control "cis-fs-2.1"
+      control "cis-fs-2.2"
+
+    end
+
+
+## require_resource
+
+By default, all of the resources from a listed dependency are available
+for use in your profile. If two of your dependencies provide a resource with
+the same name, you can use the `require_resource` DSL function to
+disambiguate the two:
+
+    require_resource(profile: 'my_dep', resource: 'my_res',
+                     as: 'my_res2')
+
+This will allow you to reference the resource `my_res` from the
+profile `my_dep` using the name `my_res2`.
+
+# Profile Attributes
+
+Attributes may be used in profiles to define secrets, such as user names and passwords, that should not otherwise be stored in plain-text in a cookbook. First specify a variable in the control for each secret, then add the secret to a Yaml file located on the local machine, and then run `inspec exec` and specify the path to that Yaml file using the `--attrs` attribute.
+
+For example, a control:
+
+    val_user = attribute('user', default: 'alice', description: 'An identification for the user')
+    val_password = attribute('password', description: 'A value for the password')
+
+    describe val_user do
+      it { should eq 'bob' }
+    end
+
+    describe val_password do
+      it { should eq 'secret' }
+    end
+
+And a Yaml file named `profile-attribute.yml`:
+
+    user: bob
+    password: secret
+
+The following command runs the tests and applies the secrets specified in `profile-attribute.yml`:
+
+    $ inspec exec examples/profile-attribute --attrs examples/profile-attribute.yml
+
+See the full example in the InSpec open source repository: https://github.com/chef/inspec/tree/master/examples/profile-attribute

data/docs/resources/apache_conf.md.erb

@@ -0,0 +1,75 @@
+---
+title: About the apache_conf Resource
+---
+
+# apache_conf
+
+Use the `apache_conf` InSpec audit resource to test the configuration settings for Apache. This file is typically located under `/etc/apache2` on the Debian and Ubuntu platforms and under `/etc/httpd` on the Fedora, CentOS, RedHat Enterprise Linux, and ArchLinux platforms. The configuration settings may vary significantly from platform to platform.
+
+# Syntax
+
+An `apache_conf` InSpec audit resource block declares configuration settings that should be tested:
+
+    describe apache_conf('path') do
+      its('setting_name') { should eq 'value' }
+    end
+
+where
+
+* `'setting_name'` is a configuration setting defined in the Apache configuration file
+* `('path')` is the non-default path to the Apache configuration file
+* `{ should eq 'value' }` is the value that is expected
+
+# Matchers
+
+This InSpec audit resource matches any service that is listed in the Apache configuration file:
+
+    its('PidFile') { should_not eq '/var/run/httpd.pid' }
+
+or:
+
+    its('Timeout') { should eq 300 }
+
+For example:
+
+    describe apache_conf do
+      its('MaxClients') { should eq 100 }
+      its('Listen') { should eq '443'}
+    end
+
+
+## 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" %>
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test for blocking .htaccess files on CentOS
+
+    describe apache_conf do
+      its('AllowOverride') { should eq 'None' }
+    end
+
+## Test ports for SSL
+
+    describe apache_conf do
+      its('Listen') { should eq '443'}
+    end