inspec-core 2.2.112 → 2.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08e8c25f0f329b43923160911ebafc36bebe17e7f7a09d5f4254a3534849429e'
-  data.tar.gz: 9238855161cf160af08a51119847757864374c75f6dfcbef2a2abec6e8033358
+  metadata.gz: e8f9909b462e77ca666275bb82308ea451a68ead2f5498aa111d74a55f5a6f64
+  data.tar.gz: 002c18ea92f6c1879f5e8abdc53231a673b0bac7b66ce9042363a10504ebb424
 SHA512:
-  metadata.gz: 648d001c2eea839d426543d34f80da62928abe93a9ffbf6de4838a1e100b4aaa16475dc16bf93fb647f8f0e41f2db02eab834678a0f88c628d358dfdfbd6bbf8
-  data.tar.gz: c170162f6a199addb3fb8595e6e265a2e14efb715ec8eb890cc827cbe248d07bd516b83f81b0f431b28e18f1a645a1586cabf7d4177043fa7e55339bdd8c543d
+  metadata.gz: 642c43b3305289773a3fe75d286c5c0eaae10fa2ff869541aed3eb683a0e04bbf2d839bf3665e11eca1f87fcdf909de99885c3822035c37db2e7b5ffc876da8a
+  data.tar.gz: 7df8c80861da7a4a252a47d02f50a1d3f138abf1cd4021c78462d3174176a623a81a0f1071ad8031b73dfd32f5f41eb3224c982a667a132d2ffefc569078a443

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/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/style.md

@@ -0,0 +1,178 @@
+# InSpec profile style guide
+
+This is a set of recommended InSpec rules you should use when writing controls.
+
+## Control files
+
+### 1. All controls should be located in the "controls" directory and end in ".rb"
+
+Reason: Most syntax highlighters will render InSpec files correctly across a wide list of tools.
+
+Avoid: `controls/ssh_config`
+Use: `controls/ssh_config.rb`
+
+Avoid: `controls/ssh/config.rb`
+Use: `controls/ssh_config.rb`
+
+### 2. Avoid using "controls" or "control" in the name of your control files
+
+Reason: Using `controls` in the filename again duplicates it and creates unnecessary clutter when reading it. Keep the names short and concise.
+
+Avoid: `controls/ssh_controls.rb`
+Use: `controls/ssh.rb`
+
+
+## Code style
+
+### 3. Avoid unnecessary parentheses in matchers
+
+Adding additional parentheses is not required and provides more readability if it is not used:
+
+Avoid: `it { should eq(value) }`
+Use: `it { should eq value }`
+
+The exception are matchers that require additional arguments or named arguments.
+
+
+## Controls
+
+### 4. Do not wrap controls in conditional statements
+
+Reason: This will create dynamic profiles whose controls depend on the execution. The problem here is that we cannot render the profile or provide its information before scanning a system. We want to be able to inform users of the contents of their profiles before they run them. It is valid to skip controls that are not necessary for a system, as long as you do it via `only_if` conditions. Ruby's internal conditionals will hide parts of the profile to static analysis and should thus be avoided.
+
+Avoid:
+```ruby
+if package('..').installed?
+  control "package-test1" do
+    ..
+  end
+end
+```
+
+Use:
+```ruby
+control "package-test1" do
+  only_if { package('..').installed? }
+end
+```
+
+Avoid:
+```ruby
+case inspec.platform.name
+when /centos/
+  include_controls 'centos-profile'
+...
+```
+
+Use: The `supports` attribute in `inspec.yml` files of the profile you want to include:
+
+```ruby
+supports:
+- platform-name: centos
+```
+
+Now whenever you run the base profile you can just `include_controls 'centos-profile'`.
+It will only run the included profiles is the platform matches the supported platform.
+
+
+### 5. Do not include dynamic elements in the control IDs
+
+Reason: Control IDs are used to map test results to the tests and profiles. Dynamic control IDs make it impossible to map results back, since the identifier which connects tests and results may change in the process.
+
+Avoid:
+```ruby
+control "test-file-#{name}" do
+  ..
+end
+```
+
+Use:
+```ruby
+control "test-all-files" do
+  ..
+end
+```
+
+Sometimes you may create controls from a static list of elements. If this list stays the same no matter what system is scanned, it may be ok to do so and use it as a generator for static controls.
+
+
+### 6. Avoid Ruby system calls
+
+Reason: Ruby code is executed on the system that runs InSpec. This allows
+InSpec to work without Ruby and rubygems being required on remote
+targets (servers or containers). System calls are often used to interact with
+the local OS or remote endpoints from a local installation.
+InSpec tests, however, are designed to be universally executable on all
+types of runtimes, including local and remote execution. We want to give
+users the ability to take an OS profile and execute it remotely or locally.
+
+**Avoid shelling out**
+
+Avoid: `` `ls``\`
+Avoid: `system("ls")`
+Avoid: `IO.popen("ls")`
+Use: `command("ls")` or `powershell("..")`
+
+Ruby's command executors will only run localy. Imagine a test like this:
+
+```ruby
+describe `whoami` do
+  it { should eq "bob\n" }
+end
+```
+
+If you run this test on your local system and happen to be using Bob's account
+it will succeed. But if you were to run it against `--target alice@remote-host.com`
+it will still report that the user is bob instead of alice.
+
+Instead, do this:
+
+```ruby
+describe command('whoami') do
+  its('stdout') { should eq "bob\n" }
+end
+```
+
+If the profile is pointed to a remote endpoint using the `command` resource
+will run it on the remote OS.
+
+**Avoid Ruby IO on files**
+
+Avoid: `File.new("filename").read`
+Avoid: `File.read("filename")`
+Avoid: `IO.read("filename")`
+Use: `file("filename")`
+
+Similar to the command interactions these files will only be read localy
+with Ruby's internal calls. If you run this test against a remote target it won't
+read the file from the remote endpoint, but from the local OS instead.
+Use the `file` resource to read files on the target system.
+
+In general, try to avoid Ruby's IO calls from within InSpec controls and
+use InSpec resources instead.
+
+
+### 7. Avoid Ruby gem dependencies in controls
+
+In addition to avoiding system-level gems and modules you should also limit
+the use of external dependencies to resource packs or plugins. Gems need to be
+resolved, installed, vendored, and protected from conflicts. We aim to avoid
+exposing this complexity to users of InSpec, to make it a great tool even if
+you are not a developer.
+
+Developers may still use external gem dependencies but should vendor it
+with their plugins or resource packs.
+
+
+### 8. Avoid debugging calls (in production)
+
+Reason: One of the best way to develop and explore tests is the interactive debugging shell `pry` (see the section on "Interactive Debugging with Pry" at the end of this page). However, after you finish your profile make sure you have no interactive statements included anymore. Sometimes interactive calls are hidden behind conditionals (`if` statements) that are harder to reach. These calls can easily cause trouble when an automated profiles runs into an interactive `pry` call that stops the execution and waits for user input.
+
+Avoid: `binding.pry` in production profiles
+Use: Use debugging calls during development only
+
+Also you may find it helpful to use the inspec logging interface:
+
+```ruby
+Inspec::Log.info('Hi')
+```