inspec-core 2.1.67

data/docs/glossary.md

@@ -0,0 +1,99 @@
+# InSpec Glossary
+
+## Basic Syntax
+```
+describe foo('/path/to/foo.txt') do
+    its('blah') { should cmp '123' }
+    it { should exist }
+    it { should be_reasonable }
+    it { should_not be_ridiculous }
+end
+```
+## Basic Elements:
+
+### describe **foo**, where
+
+  * `foo` is the _resource_
+
+### describe foo **('/path/to/foo.txt')**, where
+
+  * `'/path/to/foo.txt'` is the _resource parameter_
+
+## Tests:
+
+### **its('blah') { should cmp '123' }** is an _individual test_, where
+
+  * `blah` is a _property_
+  * { should cmp '123' } is a _condition statement_
+  * `should`  is the _condition_
+  * `cmp`  is the _matcher_
+  * `'123'`  is the _expected result_
+
+### **{ should exist }** is a _condition statement_, where
+
+  * `should`  is the _condition_
+  * `exist`  is the _matcher_
+
+### **{ should be\_reasonable }** is a _condition statement_, where
+    
+  * `should`  is the _condition_
+  * `be_reasonable`  is the _matcher_
+
+### **{ should\_not be\_ridiculous }** is a _negative condition statement_, where
+
+  * `should_not`  is the _negative condition_
+  * `be_ridiculous`  is the _matcher_
+
+## Advanced Syntax
+
+```
+describe foos('/path/to/foo.txt', ssl_verify: true).where { names == 'blah' } do
+    its('jared') { should cmp >= 123 }
+    its('jared.sort.first.monkey') { should be `loud` }
+    its(['jared', 'monkey.with.dots']) { should be `loud` }
+end
+```
+
+## Advanced Elements:
+
+### describe **foos**, where
+
+  * `foos` is a _plural resource_
+
+### describe foos **('/path/to/foo.txt', ssl_verify: true)**, where
+
+  * `'/path/to/foo.txt'` and `ssl_verify: true` are the _resource parameters_. Resources take one or more parameters.
+
+## Filters:
+
+### describe foos ('/path/to/foo.txt', ssl_verify: true)**.where { names == 'blah' }** 
+
+  * `.where  { names == 'blah' }` is an example of a **filter**. 
+  * `{ names == 'blah' }` is an example of a _filter clause_ 
+  * Some resources support one or more filters.
+  * Filters are used on plural resources. 
+  * Some resources, such as `etc_hosts` are explicitly plural, while others, such as `passwd` are implicitly plural. 
+
+### **{ names == 'my-name' && spots == true }** are filter criteria
+
+  * `names` compares output to `blah`
+  * `has spots` evaluates to `true` or `false`
+
+## Properties:
+
+### **its('jared') { should cmp >= 123 }**
+
+  * `jared` is the _property_
+  
+### **{ should cmp >= 123 }** is a conditional statement that uses a matcher with an operator and expected value.
+
+  * `cmp`  is the _matcher_
+  * `>=` is the operator (some matchers accept operators)
+  * `123` is the expected value
+
+## Properties with advanced usage:
+
+### Some properties may have advanced usage:
+#### **its `('jared.sort.first.monkey') { should be `loud` }`**
+
+  * `jared.sort.first.monkey` is an example of the `jared` property with an advanced usage

data/docs/habitat.md

@@ -0,0 +1,192 @@
+---
+title: InSpec Integration with Habitat
+---
+
+# Habitat Integration
+
+InSpec provides an easy method to create an executable Habitat package for an InSpec profile. When run via the Habitat Supervisor, the package will run InSpec with your profile and write out its findings to a JSON file. This provides the ability to ship your compliance controls alongside your Habitat-packaged application and continuously run InSpec, providing you *Continuous Compliance.*
+
+## What is Habitat?
+
+Habitat by Chef is our new Application Automation tool that aims to make it easy, safe, and fast to build, deploy, and manage applications. From build dependencies, runtime dependencies, dynamic configuration, and service discovery (just to name a few), Habitat packages the automation with the application instead of relying on an underlying platform.
+
+To learn more about Habitat and try our demos and tutorials, visit [https://www.habitat.sh](https://www.habitat.sh).
+
+## Using the Habitat Integration
+
+After creating a Habitat package for an InSpec profile (see CLI commands below) and uploading the package to a Habitat Depot or manually distributing to a host, start the Habitat Supervisor with your package:
+
+```bash
+hab start adamleff/inspec-profile-frontend1
+```
+
+The Habitat Supervisor will install InSpec and execute your profile in a loop. By default, the loop runs every 300 seconds but can be changed via the `sleep_time` configuration value:
+
+```bash
+HAB_INSPEC_PROFILE_FRONTEND1="sleep_time = 60" hab start adamleff/inspec-profile-frontend1
+```
+
+The Habitat Supervisor will display output like this:
+
+```
+hab start adamleff/inspec-profile-frontend1
+∵ Missing package for core/hab-sup/0.17.0
+» Installing core/hab-sup/0.17.0
+↓ Downloading core/hab-sup/0.17.0/20170214235450
+    1.68 MB / 1.68 MB - [=========================================================================] 100.00 % 7.43 MB/s
+
+... more Habitat output here ...
+
+hab-sup(MN): Starting adamleff/inspec-profile-frontend1/0.1.0/20170328173005
+hab-sup(CS): adamleff/inspec-profile-frontend1/0.1.0/20170328173005 is not installed
+↓ Downloading adamleff-20160617201047 public origin key
+    79 B / 79 B | [===============================================================================] 100.00 % 2.64 MB/s
+☑ Cached adamleff-20160617201047 public origin key
+↓ Downloading chef/inspec/1.17.0/20170321214949
+    16.93 MB / 16.93 MB / [======================================================================] 100.00 % 10.49 MB/s
+
+... more Habitat output here ...
+
+★ Install of adamleff/inspec-profile-frontend1/0.1.0/20170328173005 complete with 9 new packages installed.
+hab-sup(MR): Butterfly Member ID d9bd761e18c144469d755b1b97406eb2
+hab-sup(MR): Starting butterfly on 0.0.0.0:9638
+hab-sup(MR): Starting http-gateway on 0.0.0.0:9631
+inspec-profile-frontend1.default(SR): Initializing
+inspec-profile-frontend1.default(SV): Starting process as user=hab, group=hab
+inspec-profile-frontend1.default(O): Executing InSpec for adamleff/inspec-profile-frontend1
+inspec-profile-frontend1.default(O): InSpec run completed successfully.
+inspec-profile-frontend1.default(O): sleeping for 300 seconds
+```
+
+The above sample output shows the supervisor starting, downloading the necessary dependencies for the supervisor and the InSpec profile, and then shows the supervisor running InSpec successfully.
+
+InSpec will write a JSON file in the `${svc_var_path}/inspec_results` directory containing the results of the last InSpec run. For example, for the `adamleff/inspec-profile-frontend1` package, the InSpec results will be at:
+
+```
+/hab/svc/inspec-profile-frontend1/var/inspec_results/inspec-profile-frontend1.json
+```
+
+## InSpec Habitat CLI Commands
+
+### inspec habitat profile create
+
+Create a Habitat package for an InSpec profile. InSpec will validate the profile, fetch and vendor any dependencies (if necessary), and build the Habitat package with a dependency on the latest InSpec. The resulting package will be saved to the current working directory.
+
+The package file will be named:
+
+```
+HABITAT_ORIGIN-inspec-profile-PROFILE_NAME-PROFILE_VERSION-BUILD_ID-x86_64-linux.hart
+```
+
+For example:
+
+```
+adamleff-inspec-profile-frontend1-0.1.0-20170328173005-x86_64-linux.hart
+```
+
+#### Syntax
+
+```bash
+inspec habitat profile create PROFILE_DIRECTORY
+```
+
+Example:
+
+```bash
+inspec habitat profile create ~/profiles/frontend1
+```
+
+### inspec habitat profile create
+
+Create a Habitat package for an InSpec profile. InSpec will validate the profile, fetch and vendor any dependencies (if necessary), and build the Habitat package with a dependency on the latest InSpec. The resulting package will be saved to the current working directory.
+
+The package can then be manually uploaded to a Habitat Depot or manually distributed to a host and installed via `hab pkg install`.
+
+The package file will be named:
+
+```
+HABITAT_ORIGIN-inspec-profile-PROFILE_NAME-PROFILE_VERSION-BUILD_ID-x86_64-linux.hart
+```
+
+For example:
+
+```
+adamleff-inspec-profile-frontend1-0.1.0-20170328173005-x86_64-linux.hart
+```
+
+#### Syntax
+
+```bash
+inspec habitat profile create PROFILE_DIRECTORY
+```
+
+#### Example
+
+```bash
+inspec habitat profile create ~/profiles/frontend1
+```
+
+#### Example Output
+
+```
+$ habitat profile create ~/profiles/frontend1
+[2017-03-28T13:29:32-04:00] INFO: Creating a Habitat artifact for profile: /Users/aleff/profiles/frontend1
+[2017-03-28T13:29:32-04:00] INFO: Checking to see if Habitat is installed...
+[2017-03-28T13:29:32-04:00] INFO: Copying profile contents to the work directory...
+[2017-03-28T13:29:32-04:00] INFO: Generating Habitat plan at /var/folders/v5/z54gb76j2rs3wrn65hmtyf1r0000gp/T/inspec-habitat-exporter20170328-4932-kg2ltd/habitat/plan.sh...
+[2017-03-28T13:29:32-04:00] INFO: Generating a Habitat run hook at /var/folders/v5/z54gb76j2rs3wrn65hmtyf1r0000gp/T/inspec-habitat-exporter20170328-4932-kg2ltd/habitat/hooks/run...
+[2017-03-28T13:29:32-04:00] INFO: Generating Habitat's default.toml configuration...
+[2017-03-28T13:29:32-04:00] INFO: Building our Habitat artifact...
+   hab-studio: Destroying Studio at /hab/studios/src (default)
+   hab-studio: Creating Studio at /hab/studios/src (default)
+   hab-studio: Importing adamleff secret origin key
+» Importing origin key from standard input
+★ Imported secret origin key adamleff-20160617201047.
+» Installing core/hab-backline
+↓ Downloading core/hab-backline/0.19.0/20170311034116
+    2.17 KB / 2.17 KB / [=========================================================================] 100.00 % 4.33 MB/s
+
+... more Habitat output here...
+
+[2017-03-28T13:30:18-04:00] INFO: Copying artifact to /Users/aleff...
+```
+
+### inspec habitat profile upload
+
+Create and then upload a Habitat package for an InSpec profile. Like the `inspec habitat profile create` command, InSpec will validate the profile, fetch and vendor any dependencies (if necessary), and build the Habitat package with a dependency on the latest InSpec. However, instead of saving the package locally to the workstation, InSpec will upload it to the depot defined in the `HAB_DEPOT` environment variable. If `HAB_DEPOT` is not defined, the package will be uploaded to the public Habitat depot at [https://app.habitat.sh](https://app.habitat.sh).
+
+#### Syntax
+
+```bash
+inspec habitat profile upload PROFILE_DIRECTORY
+```
+
+#### Example
+
+```bash
+inspec habitat profile upload ~/profiles/frontend1
+```
+
+#### Example Output
+```
+[2017-03-28T13:29:32-04:00] INFO: Creating a Habitat artifact for profile: /Users/aleff/profiles/frontend1
+[2017-03-28T13:29:32-04:00] INFO: Checking to see if Habitat is installed...
+[2017-03-28T13:29:32-04:00] INFO: Copying profile contents to the work directory...
+[2017-03-28T13:29:32-04:00] INFO: Generating Habitat plan at /var/folders/v5/z54gb76j2rs3wrn65hmtyf1r0000gp/T/inspec-habitat-exporter20170328-4932-kg2ltd/habitat/plan.sh...
+[2017-03-28T13:29:32-04:00] INFO: Generating a Habitat run hook at /var/folders/v5/z54gb76j2rs3wrn65hmtyf1r0000gp/T/inspec-habitat-exporter20170328-4932-kg2ltd/habitat/hooks/run...
+[2017-03-28T13:29:32-04:00] INFO: Generating Habitat's default.toml configuration...
+[2017-03-28T13:29:32-04:00] INFO: Building our Habitat artifact...
+   hab-studio: Destroying Studio at /hab/studios/src (default)
+   hab-studio: Creating Studio at /hab/studios/src (default)
+   hab-studio: Importing adamleff secret origin key
+» Importing origin key from standard input
+★ Imported secret origin key adamleff-20160617201047.
+» Installing core/hab-backline
+↓ Downloading core/hab-backline/0.19.0/20170311034116
+    2.17 KB / 2.17 KB / [=========================================================================] 100.00 % 4.33 MB/s
+
+... more Habitat output here...
+
+[2017-03-28T13:30:18-04:00] INFO: Uploading the Habitat artifact to our Depot...
+[2017-03-28T13:30:23-04:00] INFO: Upload complete!
+```

data/docs/inspec_and_friends.md

@@ -0,0 +1,114 @@
+---
+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 by software engineers 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
+```
+
+That said, InSpec is not RSpec. Some key differences:
+
+ * In InSpec, `describe` blocks should not be nested; instead use `control` blocks to describe a higher-level grouping of tests.
+ * The RSpec `shared_example` construct is not supported.  Instead, create a simple custom resource that executes repetitious tasks.
+ * InSpec is aimed at compliance practitioners and infrastructure testers, so our focus is providing a few, well-supported, easy-to-use [universal matchers](https://www.inspec.io/docs/reference/matchers/), such as `cmp`. In contrast, RSpec is a tool designed for software engineers. It thus supports a very large range of matchers, to enable testing of software engineering constructs such as exceptions, Object Oriented Programming relationships, and so on. 
+ * While InSpec uses parts of the RSpec project and codebase, it is a separate project from InSpec. Rspec's release schedule and feature set are beyond the control of the InSpec team. While it is possible to use many of the RSpec core features within InSpec profiles, InSpec can only guarantee that the features described at [docs.inspec.io](https://docs.inspec.io) will function correctly. Some RSpec core functionality may be removed in future versions of InSpec as needed to ensure stability in the InSpec project.
+
+## Serverspec
+
+Serverspec is 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.
+
+You can also watch this [podcast](http://foodfightshow.org/2016/02/inspec.html) to find out more on the relationship of InSpec and Serverspec.
+
+### How is InSpec different from 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,169 @@
+---
+title: InSpec Universal Matchers Reference
+---
+
+# InSpec Universal Matchers Reference
+
+InSpec uses matchers to help compare resource values to expectations.
+The following matchers are available:
+
+You may also use any matcher provided by [RSpec::Expectations](https://relishapp.com/rspec/rspec-expectations/docs), but those matchers are outside of InSpec's [scope of support](https://www.inspec.io/docs/reference/inspec_and_friends/#rspec).
+
+The following InSpec-supported universal matchers are available:
+
+* [`be`](#be) - make numeric comparisons
+* [`be_in`](#be_in) - look for the property value in a list
+* [`cmp`](#cmp) - general-use equality (try this first)
+* [`eq`](#eq) - type-specific equality
+* [`include`](#include) - look for an expected value in a list-valued property
+* [`match`](#match) - look for patterns in text using regular expressions
+
+See [Explore InSpec resources](https://learn.chef.io/modules/explore-inspec-resources#/) on Learn Chef Rally to learn more about InSpec's built-in matchers.
+
+## 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
+```
+
+<br>
+
+## 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
+    ```
+* Recognize versions embedded in strings
+
+    ```ruby
+    describe package(curl) do
+      its('version') { should cmp > '7.35.0-1ubuntu2.10' }
+    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
+    ```
+<br>
+
+## 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
+```
+
+`eq` 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`.
+
+<br>
+
+## include
+
+Verifies if a value is included in a list.
+
+```ruby
+describe passwd do
+  its('users') { should include 'my_user' }
+end
+```
+
+<br>
+
+## be_in
+
+Verifies that an item is included in a list.
+
+```ruby
+describe resource do
+  its('item') { should be_in LIST }
+end
+```
+
+<br>
+
+## match
+
+Check if a string matches a regular expression.
+
+```ruby
+describe sshd_config do
+  its('Ciphers') { should_not match /cbc/ }
+end
+```