inspec 2.2.112 → 2.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed479c2bc17fad9ab4aefa69f119d6448332b4e2f5befac16f427fa589a8cef8
-  data.tar.gz: 6e055c297017f08684d15780060e2a9bf528f1f1579e0f8224a35202aad73c66
+  metadata.gz: 1e9a4bdc61290bace400878278ede4c09824a0edc8c14c2f3f9b6d2737f46058
+  data.tar.gz: 0ee613addabeb1b49e304e4d35fb87a5134f9e66ccfec913f188d987444516f5
 SHA512:
-  metadata.gz: b3be7a2eb3219f1ceabad6ce163ae24f644475a67a3825f9163c7a572be3a54db5dad11dc5765d28f5330fa5fea5ce7b535e887e56aa86749dcf3c6453c8b9e2
-  data.tar.gz: bab90ce890a5973fc24d8d02be94c88673553a0164dd0d6f5675247223244d232fd6f6a253ff0d3141549fb0f5f4857bdd984ab60ab03d2a5620f5325927f818
+  metadata.gz: 9869319175d8a4769cbf7a540e4c4d2c383e87ea8ed1c06656e933473e8e50224bcc321be65e0bf8dd6a45eadd1700826bef341dad4de6f9cf834d2c35688251
+  data.tar.gz: 486383709c684ee46d1b7ad16e7475fe0cd286a13ea6738554a5d05ea3db08b725a1f663d2b6a4532262521729797a1146ec6d24748df0f100c32daa47b7b8fa

data/.rubocop.yml

@@ -5,9 +5,15 @@ AllCops:
   - Gemfile
   - Rakefile
   - 'test/**/*'
-  - 'examples/**/*'
+  - 'lib/plugins/*/test/**/*'
+  # This is delicate; we want to include examples/plugins/*/lib
+  # but not anything else.
+  - 'examples/*profile*/**/*'
+  - 'examples/kitchen*/**/*'
+  - 'examples/inheritance/**/*'
+  - 'examples/custom-resource/**/*'
+  - 'examples/plugins/*/test/**/*'
   - 'vendor/**/*'
-  - 'lib/plugins/inspec-*/test/**/*'
   - 'lib/bundles/inspec-init/templates/**/*'
   - 'www/demo/**/*'
 AlignParameters:

data/CHANGELOG.md

@@ -1,38 +1,61 @@
 # Change Log
 <!-- usage documentation: http://expeditor-docs.es.chef.io/configuration/changelog/ -->
-<!-- latest_release 2.2.112 -->
-## [v2.2.112](https://github.com/inspec/inspec/tree/v2.2.112) (2018-09-19)
+<!-- latest_release 2.3.4 -->
+## [v2.3.4](https://github.com/inspec/inspec/tree/v2.3.4) (2018-09-27)
 
-#### Merged Pull Requests
-- Move artifact to v2 plugin  [#3406](https://github.com/inspec/inspec/pull/3406) ([jquick](https://github.com/jquick))
+#### New Features
+- Plugins: Support for Train Plugins in InSpec [#3444](https://github.com/inspec/inspec/pull/3444) ([clintoncwolfe](https://github.com/clintoncwolfe))
 <!-- latest_release -->
 
-<!-- release_rollup since=2.2.102 -->
-### Changes since 2.2.102 release
+<!-- release_rollup since=2.2.112 -->
+### Changes since 2.2.112 release
 
 #### Enhancements
-- adding `versions` to the `gem` resource [#3398](https://github.com/inspec/inspec/pull/3398) ([majormoses](https://github.com/majormoses)) <!-- 2.2.107 -->
-- Plugins: Add support for &#39;bundles&#39; migration [#3384](https://github.com/inspec/inspec/pull/3384) ([clintoncwolfe](https://github.com/clintoncwolfe)) <!-- 2.2.105 -->
-
-#### New Features
-- Update AWS Security Group to work with IPV6 rules. [#3394](https://github.com/inspec/inspec/pull/3394) ([MartinLogan](https://github.com/MartinLogan)) <!-- 2.2.111 -->
-- Added db_name flag [#3383](https://github.com/inspec/inspec/pull/3383) ([kdoores](https://github.com/kdoores)) <!-- 2.2.104 -->
+- Support the Busybox variant of netstat in the port resource [#3425](https://github.com/inspec/inspec/pull/3425) ([RoboticCheese](https://github.com/RoboticCheese)) <!-- 2.2.119 -->
 
 #### Merged Pull Requests
-- Move artifact to v2 plugin  [#3406](https://github.com/inspec/inspec/pull/3406) ([jquick](https://github.com/jquick)) <!-- 2.2.112 -->
-- Move inspec init to v2 plugins [#3407](https://github.com/inspec/inspec/pull/3407) ([jquick](https://github.com/jquick)) <!-- 2.2.110 -->
-- Fix gem tests from recent merge [#3409](https://github.com/inspec/inspec/pull/3409) ([jquick](https://github.com/jquick)) <!-- 2.2.109 -->
-- Fix json automate tests and render call [#3408](https://github.com/inspec/inspec/pull/3408) ([jquick](https://github.com/jquick)) <!-- 2.2.108 -->
-- Move habitat to v2 plugin [#3404](https://github.com/inspec/inspec/pull/3404) ([jquick](https://github.com/jquick)) <!-- 2.2.106 -->
-- Fix rendering of profiles docs [#3393](https://github.com/inspec/inspec/pull/3393) ([jquick](https://github.com/jquick)) <!-- 2.2.103 -->
+- Plugins: Example CLI Plugin, a Resource Lister [#3421](https://github.com/inspec/inspec/pull/3421) ([clintoncwolfe](https://github.com/clintoncwolfe)) <!-- 2.3.3 -->
+- Pin postgresql to a lower cookbook version [#3449](https://github.com/inspec/inspec/pull/3449) ([jquick](https://github.com/jquick)) <!-- 2.3.2 -->
+- RFC inspec style guide [#3356](https://github.com/inspec/inspec/pull/3356) ([arlimus](https://github.com/arlimus)) <!-- 2.3.1 -->
+- Bump minor version [#3448](https://github.com/inspec/inspec/pull/3448) ([jquick](https://github.com/jquick)) <!-- 2.3.0 -->
+- Add support for multiple descriptions for controls [#3424](https://github.com/inspec/inspec/pull/3424) ([jerryaldrichiii](https://github.com/jerryaldrichiii)) <!-- 2.2.120 -->
+- Plugins: Load all CLI commands on usage on empty invocation [#3428](https://github.com/inspec/inspec/pull/3428) ([clintoncwolfe](https://github.com/clintoncwolfe)) <!-- 2.2.118 -->
+- Fix v2 loader appveyor issue [#3434](https://github.com/inspec/inspec/pull/3434) ([jquick](https://github.com/jquick)) <!-- 2.2.116 -->
+- Add new resource: aws_ebs_volume [#3381](https://github.com/inspec/inspec/pull/3381) ([jmassardo](https://github.com/jmassardo)) <!-- 2.2.115 -->
+
+#### Bug Fixes
+- Grammar correction in error message: use &quot;an&quot; with attribute and unknown [#3439](https://github.com/inspec/inspec/pull/3439) ([alexpop](https://github.com/alexpop)) <!-- 2.2.117 -->
+- Remove load locks for cloud resources [#3420](https://github.com/inspec/inspec/pull/3420) ([jquick](https://github.com/jquick)) <!-- 2.2.114 -->
+
+#### New Features
+- Plugins: Support for Train Plugins in InSpec [#3444](https://github.com/inspec/inspec/pull/3444) ([clintoncwolfe](https://github.com/clintoncwolfe)) <!-- 2.3.4 -->
+- Plugins Installer API [#3352](https://github.com/inspec/inspec/pull/3352) ([clintoncwolfe](https://github.com/clintoncwolfe)) <!-- 2.2.113 -->
 <!-- release_rollup -->
 
 <!-- latest_stable_release -->
+## [v2.2.112](https://github.com/inspec/inspec/tree/v2.2.112) (2018-09-19)
+
+#### New Features
+- Added db_name flag [#3383](https://github.com/inspec/inspec/pull/3383) ([kdoores](https://github.com/kdoores))
+- Update AWS Security Group to work with IPV6 rules. [#3394](https://github.com/inspec/inspec/pull/3394) ([MartinLogan](https://github.com/MartinLogan))
+
+#### Enhancements
+- Plugins: Add support for &#39;bundles&#39; migration [#3384](https://github.com/inspec/inspec/pull/3384) ([clintoncwolfe](https://github.com/clintoncwolfe))
+- adding `versions` to the `gem` resource [#3398](https://github.com/inspec/inspec/pull/3398) ([majormoses](https://github.com/majormoses))
+
+#### Merged Pull Requests
+- Fix rendering of profiles docs [#3393](https://github.com/inspec/inspec/pull/3393) ([jquick](https://github.com/jquick))
+- Move habitat to v2 plugin [#3404](https://github.com/inspec/inspec/pull/3404) ([jquick](https://github.com/jquick))
+- Fix json automate tests and render call [#3408](https://github.com/inspec/inspec/pull/3408) ([jquick](https://github.com/jquick))
+- Fix gem tests from recent merge [#3409](https://github.com/inspec/inspec/pull/3409) ([jquick](https://github.com/jquick))
+- Move inspec init to v2 plugins [#3407](https://github.com/inspec/inspec/pull/3407) ([jquick](https://github.com/jquick))
+- Move artifact to v2 plugin  [#3406](https://github.com/inspec/inspec/pull/3406) ([jquick](https://github.com/jquick))
+<!-- latest_stable_release -->
+
 ## [v2.2.102](https://github.com/inspec/inspec/tree/v2.2.102) (2018-09-17)
 
 #### Merged Pull Requests
 - Add json-automate to the report method [#3401](https://github.com/inspec/inspec/pull/3401) ([jquick](https://github.com/jquick))
-<!-- latest_stable_release -->
 
 ## [v2.2.101](https://github.com/inspec/inspec/tree/v2.2.101) (2018-09-14)
 

data/README.md

@@ -452,4 +452,4 @@ Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
-limitations under the License. 
+limitations under the License.

data/Rakefile

@@ -106,10 +106,23 @@ namespace :test do
     sh(Gem.ruby, 'test/docker_test.rb', *tests)
   end
 
-  task :integration do
+  task :integration, [:os] do |task, args|
     concurrency = ENV['CONCURRENCY'] || 1
-    os = ENV['OS'] || ''
-    sh("bundle exec kitchen test -c #{concurrency} #{os}")
+    os = args[:os] || ENV['OS'] || ''
+    ENV['DOCKER'] = 'true' if ENV['docker'].nil?
+    puts "Building current InSpec gem for audit cookbook testing..."
+    output = %x[gem build inspec-core.gemspec]
+    puts output
+    gem_name = output.split("\n")[-1].split(':')[1].strip
+    path = File.dirname(__FILE__)
+    File.rename(File.join(path, gem_name), File.join(path, 'inspec-core-local.gem'))
+    destination = File.join(path, 'test', 'cookbooks', 'os_prepare', 'files', 'inspec-core-local.gem')
+    begin
+      FileUtils.cp(File.join(path, 'inspec-core-local.gem'), destination)
+      sh("bundle exec kitchen test -c #{concurrency} #{os}")
+    ensure
+      FileUtils.rm(destination)
+    end
   end
 
   task :ssh, [:target] do |_t, args|

data/docs/dev/integration-testing.md

@@ -0,0 +1,31 @@
+# Integration Testing with InSpec
+
+## Introduction
+
+Inspec uses Test Kitchen for its integration testing. Our current testing uses Docker as our backend. You should install and have Docker running befor you run any tests.
+
+### How to run specific integrations
+
+To run a specific integration test use the following:
+
+```bash
+bundle exec rake test:integration[OS_NAME]
+```
+
+Example:
+```bash
+bundle exec rake test:integration[default-ubuntu-1604]
+```
+
+# Inspec Integrations
+
+### Test Kitchen
+
+We run the test/integration/default profile at the end of each integration test in the verify stage. This confirms that our current code is compatible with test kitchen.
+
+### Audit Testing
+
+For Audit cookbook testing InSpec sets up some special hooks. The integration rake command will bundle up the current checkout into a gem which is passed along to test kitchen in the os_prepare cookbook. When this cookbook is ran it will install the local inspec gem. Audit will then use this gem accordingly when running in the post chef-client validators. The .kitchen.yml is setup to export the audit report to a json file which we look for and confirm the structure in the test/integration/default/controls/audit_spec.rb file.
+
+In the validation file we confirm that the file was created from audit and that the structure looks correct. We also validate that the inspec ran with audit is the same that the current branch is using. This validates that audit did not use a older version for some reason.
+

data/docs/dev/plugins.md

@@ -26,9 +26,11 @@ The software design of the InSpec Plugin v2 API is deeply inspired by the Vagran
 
 The normal distribution and installation method is via gems, handled by the `inspec plugin` command.
 
-TODO: give basic overview of `inspec plugin` and link to docs
+`inspec plugin install inspec-myplugin` will fetch `inspec-myplugin` from rubygems.org, and install it and its gemspec dependencies under the user's `.inspec` directory.  You may also provide a local gemfile.  For local development, however, path-to-source is usually most convenient.
 
-### Plugins may also be found by path
+For more on the `plugin` CLI command, run `inspec plugin help`.
+
+### Plugins may also be found by path to a source tree
 
 For local development or site-specific installations, you can also 'install' a plugin by path using `inspec plugin`, or edit `~/.inspec/plugins.json` directly to add a plugin.
 

data/docs/dsl_inspec.md

@@ -26,10 +26,8 @@ In various use cases like implementing IT compliance across different department
 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.
-  '
+  desc 'Always specify which port the SSH server should listen.'
+  desc 'rationale', 'This ensures that there are no 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'
@@ -44,6 +42,7 @@ 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
+* `desc` when given only one argument it sets the default description. When given 2 arguments (see: `'rationale'`) it will use the first argument as a header when rendering in Automate
 * `impact` is an float that measures the importance of the compliance results and must be a value between `0.0` and `1.0`. The value ranges are:
   * `0.0 to <0.4` these are controls with minor criticality
   * `0.4 to <0.7` these are controls with major criticality
@@ -252,3 +251,104 @@ control 'ssh-1' do
   end
 end
 ```
+
+# Using Ruby in InSpec
+
+The InSpec DSL is a Ruby based language. This allows you to be flexible with
+Ruby code in controls:
+
+```ruby
+json_obj = json('/file.json')
+json_obj['keys'].each do |value|
+  ..
+end
+```
+
+Ruby allows a lot of freedoms, but should be limited in controls so that they
+remain portable and easy to understand. Please see our [profile style guide](./style).
+
+Core and custom resources are written as regular Ruby classes which inherit from
+`Inspec.resource`.
+
+
+## Interactive Debugging with Pry
+
+Here's a sample InSpec control that users Ruby variables to instantiate
+an InSpec resource once and use the content in multiple tests.
+
+```ruby
+control 'check-perl' do
+  impact 0.3
+  title 'Check perl compiled options and permissions'
+  perl_out = command('perl -V')
+  #require 'pry'; binding.pry;
+  describe perl_out do
+    its('exit_status') { should eq 0 }
+    its('stdout') { should match /USE_64_BIT_ALL/ }
+    its('stdout') { should match /useposix=true/ }
+    its('stdout') { should match /-fstack-protector/ }
+  end
+
+  # extract an array of include directories
+  perl_inc = perl_out.stdout.partition('@INC:').last.strip.split("\n")
+  # ensure include directories are only writable by 'owner'
+  perl_inc.each do |path|
+    describe directory(path.strip) do
+      it { should_not be_writable.by 'group' }
+      it { should_not be_writable.by 'other' }
+    end
+  end
+end
+```
+
+An **advanced** but very useful Ruby tip. In the previous example, I
+commented out the `require 'pry'; binding.pry;` line. If you remove the
+`#` prefix and run the control, the execution will stop at that line and
+give you a `pry` shell. Use that to troubleshoot, print variables, see
+methods available, etc. For the above example:
+
+```ruby
+[1] pry> perl_out.exit_status
+=> 0
+[2] pry> perl_out.stderr
+=> ""
+[3] pry> ls perl_out
+Inspec::Plugins::Resource#methods: inspect
+Inspec::Resources::Cmd#methods: command  exist?  exit_status  result  stderr  stdout  to_s
+Inspec::Resource::Registry::Command#methods: inspec
+instance variables: @__backend_runner__  @__resource_name__  @command  @result
+[4] pry> perl_out.stdout.partition('@INC:').last.strip.split("\n")
+=> ["/Library/Perl/5.18/darwin-thread-multi-2level",
+ "    /Library/Perl/5.18",
+...REDACTED...
+[5] pry> exit    # or abort
+```
+
+You can use `pry` inside both the controls DSL and resources. Similarly,
+for dev and test, you can use `inspec shell` which is based on `pry`,
+for example:
+
+```ruby
+$ inspec shell
+Welcome to the interactive InSpec Shell
+To find out how to use it, type: help
+
+inspec> command('ls /home/gordon/git/inspec/docs').stdout
+=> "ctl_inspec.rst\ndsl_inspec.rst\ndsl_resource.rst\n"
+inspec> command('ls').stdout.split("\n")
+=> ["ctl_inspec.rst", "dsl_inspec.rst", "dsl_resource.rst"]
+
+inspec> help command
+Name: command
+
+Description:
+Use the command InSpec audit resource to test an arbitrary command that is run on the system.
+
+Example:
+describe command('ls -al /') do
+  it { should exist }
+  its('stdout') { should match /bin/ }
+  its('stderr') { should eq '' }
+  its('exit_status') { should eq 0 }
+end
+```

data/docs/plugins.md

@@ -0,0 +1,57 @@
+---
+title: About InSpec and Train Plugins
+---
+
+# InSpec and Train Plugins
+
+## What are InSpec Plugins?
+
+InSpec Plugins are optional software components that extend the capabilities of InSpec. For example, [`inspec-iggy`](https://github.com/inspec/inspec-iggy) is a Plugin project that aims to generate InSpec controls from infrastructure-as-code files.  Plugins are distributed as RubyGems, and InSpec manages their installation. InSpec Plugins always begin with the prefix 'inspec-'.
+
+## What are Train Plugins?
+
+Train Plugins allow InSpec to speak to new kinds of targets (typically new remote targets or APIs, but you could treat the local system in a new way if you wished to).  For example, if you wanted to audit a Kubernetes cluster, you might want a transport that can talk to the supervisor API.  You'd develop a Train Plugin for that, and install it using the InSpec command line. Train Plugins always begin with the prefix 'train-'.
+
+## What can plugins do?
+
+Currently, each plugin can offer one or more of these capabilities:
+
+ * define a new command-line-interface (CLI) command suite
+ * connectivity to new types of hosts or cloud providers (`train` plugins)
+
+Future work might include new capability types, such as:
+
+ * reporters (output generators)
+ * DSL extensions at the file, control, or test level
+ * attribute fetchers to allow reading InSpec attributes from new sources (for example, a remote, encrypted key-value store)
+
+## How do I find out which plugins are available?
+
+The InSpec CLI can tell you which plugins are available:
+
+```bash
+$ inspec plugin search
+```
+
+## How do I install and manage plugins?
+
+The InSpec command line now offers a new subcommand just for managing plugins.
+
+You can install a plugin by running:
+
+```bash
+$ inspec plugin install inspec-some-plugin
+$ inspec plugin install train-some-plugin
+```
+
+For more details on what the `plugin` command can do, see the [online help](https://www.inspec.io/docs/reference/cli/#plugin), or run `inspec plugin help`.
+
+## How do I write a plugin?
+
+### InSpec Plugins
+
+For details on how to author an InSpec Plugin, see the [developer documentation](https://github.com/inspec/inspec/blob/master/docs/dev/plugins.md)
+
+### Train Plugins
+
+For details on how to author a Train Plugin, see the [developer documentation](https://github.com/inspec/train/blob/master/docs/dev/plugins.md)

data/docs/resources/aws_ebs_volume.md.erb

@@ -0,0 +1,76 @@
+---
+title: About the aws_ebs_volume Resource
+platform: aws
+---
+
+# aws\_ebs\_volume
+
+Use the `aws_ebs_volume` InSpec audit resource to test properties of a single AWS EBS volume.
+
+<br>
+
+## Availability
+
+### Installation
+
+This resource is distributed along with InSpec itself. You can use it automatically.
+
+## Syntax
+
+An `aws_ebs_volume` resource block declares the tests for a single AWS EBS volume by either name or id.
+
+    describe aws_ebs_volume('vol-01a2349e94458a507') do
+      it { should exist }
+    end
+
+    describe aws_ebs_volume(name: 'data-vol') do
+      it { should be_encrypted }
+    end
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test that an EBS Volume does not exist
+
+    describe aws_ebs_volume(name: 'data_vol') do
+      it { should_not exist }
+    end
+
+### Test that an EBS Volume is encrypted
+
+    describe aws_ebs_volume(name: 'secure_data_vol') do
+      it { should be_encrypted }
+    end
+
+### Test that an EBS Volume the correct size
+
+    describe aws_ebs_volume(name: 'data_vol') do
+      its('size') { should cmp 32 }
+    end
+
+<br>
+
+## Properties
+
+* `availability_zone`, `encrypted`, `iops`, `kms_key_id`, `size`, `snapshot_id`, `state`, `volume_type`
+
+<br>
+
+## Matchers
+
+This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### be\_encrypted
+
+The `be_encrypted` matcher tests if the described EBS Volume is encrypted.
+
+    it { should be_encrypted }
+
+## AWS Permissions
+
+Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `ec2:DescribeVolumes`, and `iam:GetInstanceProfile` actions set to allow.
+
+You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon EC2](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonec2.html), and [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).