inspec 2.2.61 → 2.2.64

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d165544705d8d7d1532d3490b651106922bd12a39bcd086dea86dfa184830939
-  data.tar.gz: bdb0c2273998ad9dd3bf2846755fa60db0522713f8937f31922a26ba52e98391
+  metadata.gz: 8ae8178b1be1a7d13be61e1a281b95fed49be3fae45f26aff9eb435113e5c1f2
+  data.tar.gz: 9c224166b801afc788f73bb01a33cbb86e6189d4e0d1edeaf4ea984774185a5a
 SHA512:
-  metadata.gz: 0547572d06d433e4c32f68006300aac09a5b37d85110d501a4a4fb73c966c1faec898e078e7ad5f7f69ef2fac034f94881fcb4c4b8a5fb54f8a0fc6c2c0a6817
-  data.tar.gz: a1d656a0ebd2288ecdbf4f8060bededba27a6af94d17fe0643f803456739370b1399f4ed7ccd3fac9fd48181b65d5f3d7d89467e0166db42a097fbb48cb1d806
+  metadata.gz: 7e3fe1c9405ad49d9f06f478b6bfbd954cc2cb7256eff64d8f79ff09319a4bcb50e86d7a020562abec492be7d8423372e4f3ca2317ae84bc73de8b31ed8f8c46
+  data.tar.gz: 74eea6f7ada2d8b4f0492a450ed7243b7b9b590acd186bdda472e0c436bb7d6ed5cc4bba6f9f2955f6f077760fbd7c1b0a08492a33b340da8bc45b7eb50c9845

data/CHANGELOG.md

@@ -1,36 +1,43 @@
 # Change Log
 <!-- usage documentation: http://expeditor-docs.es.chef.io/configuration/changelog/ -->
-<!-- latest_release 2.2.61 -->
-## [v2.2.61](https://github.com/inspec/inspec/tree/v2.2.61) (2018-08-09)
+<!-- latest_release 2.2.64 -->
+## [v2.2.64](https://github.com/inspec/inspec/tree/v2.2.64) (2018-08-17)
 
-#### New Resources
-- add iis_app_pool resource [#2400](https://github.com/inspec/inspec/pull/2400) ([strocknar](https://github.com/strocknar))
+#### Merged Pull Requests
+- Dummy PR to bump expeditor version. [#3298](https://github.com/inspec/inspec/pull/3298) ([jquick](https://github.com/jquick))
 <!-- latest_release -->
 
-<!-- release_rollup since=2.2.55 -->
-### Changes since 2.2.55 release
+<!-- release_rollup since=2.2.61 -->
+### Changes since 2.2.61 release
+
+#### Merged Pull Requests
+- Dummy PR to bump expeditor version. [#3298](https://github.com/inspec/inspec/pull/3298) ([jquick](https://github.com/jquick)) <!-- 2.2.64 -->
+- Allow the jsonAutomate report to be executed from cli [#3285](https://github.com/inspec/inspec/pull/3285) ([jquick](https://github.com/jquick)) <!-- 2.2.63 -->
+- Update `only_if` to allow user specified messages. [#3267](https://github.com/inspec/inspec/pull/3267) ([miah](https://github.com/miah)) <!-- 2.2.62 -->
+<!-- release_rollup -->
+
+<!-- latest_stable_release -->
+## [v2.2.61](https://github.com/inspec/inspec/tree/v2.2.61) (2018-08-09)
 
 #### New Resources
-- add iis_app_pool resource [#2400](https://github.com/inspec/inspec/pull/2400) ([strocknar](https://github.com/strocknar)) <!-- 2.2.61 -->
-- Add new resource: aws_ecs_cluster [#3213](https://github.com/inspec/inspec/pull/3213) ([meringu](https://github.com/meringu)) <!-- 2.2.60 -->
+- Add new resource: aws_ecs_cluster [#3213](https://github.com/inspec/inspec/pull/3213) ([meringu](https://github.com/meringu))
+- add iis_app_pool resource [#2400](https://github.com/inspec/inspec/pull/2400) ([strocknar](https://github.com/strocknar))
 
 #### Enhancements
-- Adding docker plugin support [#3074](https://github.com/inspec/inspec/pull/3074) ([frezbo](https://github.com/frezbo)) <!-- 2.2.58 -->
+- Adding docker plugin support [#3074](https://github.com/inspec/inspec/pull/3074) ([frezbo](https://github.com/frezbo))
 
 #### Bug Fixes
-- Error cleanly if a reporter errors while rendering [#3280](https://github.com/inspec/inspec/pull/3280) ([jquick](https://github.com/jquick)) <!-- 2.2.59 -->
-- Add support in aws_route_table to allow 17 hexadecimal characters [#3277](https://github.com/inspec/inspec/pull/3277) ([kchistova](https://github.com/kchistova)) <!-- 2.2.57 -->
+- Add support in aws_route_table to allow 17 hexadecimal characters [#3277](https://github.com/inspec/inspec/pull/3277) ([kchistova](https://github.com/kchistova))
+- Error cleanly if a reporter errors while rendering [#3280](https://github.com/inspec/inspec/pull/3280) ([jquick](https://github.com/jquick))
 
 #### Merged Pull Requests
-- Enable inspec archive, check, and json to run as unpriveleged user [#3263](https://github.com/inspec/inspec/pull/3263) ([phiggins](https://github.com/phiggins)) <!-- 2.2.56 -->
-<!-- release_rollup -->
-
+- Enable inspec archive, check, and json to run as unpriveleged user [#3263](https://github.com/inspec/inspec/pull/3263) ([phiggins](https://github.com/phiggins))
 <!-- latest_stable_release -->
+
 ## [v2.2.55](https://github.com/inspec/inspec/tree/v2.2.55) (2018-08-03)
 
 #### Enhancements
 - Add a merged json report for A2 [#3261](https://github.com/inspec/inspec/pull/3261) ([jquick](https://github.com/jquick))
-<!-- latest_stable_release -->
 
 ## [v2.2.54](https://github.com/inspec/inspec/tree/v2.2.54) (2018-08-02)
 

data/README.md

@@ -453,4 +453,3 @@ 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.
-

data/docs/dev/plugins.md

@@ -0,0 +1,321 @@
+# Developing InSpec Plugins for the v2 plugin API
+
+## Introduction
+
+### Inspiration
+
+The software design of the InSpec Plugin v2 API is deeply inspired by the Vagrant plugin v2 system.  While the InSpec Plugin v2 system is an independent implementation, acknowledgements are due to the Hashicorp team for such a well-thought-out design.
+
+### Note About versions
+
+"v2" refers to the second major version of the Plugin API.  It doesn't refer to the InSpec release number.
+
+### Design Goals
+
+* Load-on-demand. Improve `inspec` startup time by making plugins load heavy libraries only if they are being used.
+* Independent velocity. Enable passionate community members to contribute at their own pace by shifting core development into plugin development
+* Increase dogfooding. Convert internal components into plugins to reduce core complexity and allow testing in isolation
+
+### Design Anti-goals
+
+* Don't implement resources in plugins; use resource packs for that.
+
+## How Plugins are Located and Loaded
+
+### Plugins are usually gems
+
+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
+
+### Plugins may also be found by path
+
+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.
+
+### The plugins.json file
+
+InSpec stores its list of known plugins in a file, `~/.inspec/plugins.json`. The purpose of this file is avoid having to do a gem path filesystem scan to locate plugins.  When you install, update, or uninstall a plugin using `inspec plugin`, InSpec updates this file.
+
+You can tell inspec to use a different config directory using the INSPEC_CONFIG_DIR environment variable.
+
+Top-level entries in the JSON file:
+
+ * `plugins_config_version` - must have the value "1.0.0". Reserved for future format changes.
+ * `plugins` - an Array of Hashes, each containing information about plugins that are expected to be installed
+
+Each plugin entry may have the following keys:
+
+ * `name` - Required.  String name of the plugin.  Internal machine name of the plugin. Must match `plugin_name` DSL call (see Plugin class below).
+ * `installation_type` - Optional, default "gem".  Selects a loading mechanism, may be either "path" or "gem"
+ * `installation_path` - Required if installation_type is "path".  A `require` will be attempted against this path.  It may be absolute or relative; InSpec adds both the process current working directory as well as the InSpec installation root to the load path.
+
+TODO: keys for gem installations
+
+Putting this all together, here is a plugins.json file from the InSpec test suite:
+
+```json
+{
+  "plugins_config_version" : "1.0.0",
+  "plugins": [
+    {
+      "name": "inspec-meaning-of-life",
+      "installation_type": "path",
+      "installation_path": "test/unit/mock/plugins/meaning_of_life_path_mode/inspec-meaning-of-life"
+    }
+  ]
+}
+```
+
+## Plugin Parts
+
+### A Typical Plugin File Layout
+
+```
+inspec-my-plugin.gemspec
+lib/
+  inspec-my-plugin.rb  # Entry point
+  inspec-my-plugin/
+    cli.rb             # An implementation file
+    plugin.rb          # Plugin definition file
+    heavyweight.rb     # A support file
+```
+
+Generally, except for the entry point, you may name these files anything you like; however, the above example is the typical convention.
+
+### Gemspec and Plugin Dependencies
+
+This is a normal Gem specification file. When you release your plugin as a gem, you can declare dependencies here, and InSpec will automatically install them along with your plugin.
+
+If you are using a path-based install, InSpec will not manage your dependencies.
+
+### Entry Point
+
+The entry point is the file that will be `require`d at load time (*not* activation time; see Plugin Lifecycle, below).  You should load the bare minimum here - only the plugin definition file. Do not load any plugin dependencies in this file.
+
+```ruby
+# lib/inspec-my-plugin.rb
+require_relative 'inspec-my-plugin/plugin'
+```
+
+### Plugin Definition File
+
+The plugin definition file uses the plugin DSL to declare a small amount of metadata, followed by as many activation hooks as your plugin needs.
+
+While you may use any valid Ruby module name, we encourage you to namespace your plugin under `InspecPlugins::YOUR_PLUGIN`.
+
+```ruby
+# lib/inspec-my-plugin/plugin.rb
+module InspecPlugins
+  module MyPlugin
+    # Class name doesn't matter, but this is a reasonable default name
+    class PluginDefinition < Inspec.plugin(2)
+
+      # Metadata
+      # Must match entry in plugins.json
+      plugin_name :'inspec-my-plugin'
+
+      # Activation hooks (CliCommand as an example)
+      cli_command :'my-command' do
+        require_relative 'cli'
+        InspecPlugins::MyPlugin::CliCommand
+      end
+
+    end
+  end
+end
+```
+
+Note that the block passed to `cli_command` is not executed when the plugin definition is loaded.  It will only be executed if inspec decides it needs to activate that plugin component.
+
+Every activation hook is expected to return a `Class` which will be used in post-activation or execution phases. The behavior, duck typing, and superclass of that Class vary depending on the plugin type; see below for details.
+
+### Implementation Files
+
+Inside the implementation files, you should be sure to do three things:
+
+1. Load any heavyweight libraries your plugin needs
+2. Create a class (which you will return from the activator hook)
+3. Within the class, implement your functionality, as dictated by the plugin type API
+
+```ruby
+# lib/inspec-my-plugin/cli.rb
+
+# Load enormous dependencies
+require_relative 'heavyweight'
+
+module InspecPlugin::MyPlugin
+  # Class name doesn't matter, but this is a reasonable default name
+  class CliCommand < Inspec.plugin(2, :cli_command) # Note two-arg form
+    # Implement API or use DSL as dictated by cli_command plugin type
+    # ...
+  end
+end
+```
+
+## Plugin Lifecycle
+
+All queries regarding plugin state should be directed to `Inspec::Plugin::V2::Registry.instance`, a singleton object.
+
+```ruby
+registry = Inspec::Plugin::V2::Registry.instance
+plugin_status = registry[:'inspec-meaning-of-life']
+```
+
+### Discovery (Known Plugins)
+
+If a plugin is mentioned in `plugins.json` or is a plugin distributed with InSpec itself, it is *known*.  You can get its status, a `Inspec::Plugin::V2::Status` object.
+
+Reading the plugins.json file is handled by the Loader when Loader.new is called; at that point the registry should know about plugins.
+
+### Loading
+
+Next, we load plugins.  Loading means that we `require` the entry point determined from the plugins.json. Your plugin definition file will thus execute.
+
+If things go right, the Status now has a bunch of Activators, each with a block that has not yet executed.
+
+If things go wrong, have a look at `status.load_exception`.
+
+### Activation and Execution
+
+Depending on the plugin type, activation may be triggered by a number of different events. For example, CliCommand plugin types are activated when their activation name is mentioned in the command line arguments.
+
+After activation, code for that aspect of the plugin is loaded and ready to execute. Execution may be triggered by a number of different events. For example, the CliCommand plugin types are implicitly executed by Thor when `Inspec::CLI` calls `start()`.
+
+Refer to the sections below for details about activation and execution timing.
+
+## Implementing a CLI Command Plugin
+
+The CliCommand plugin_type allows you to extend the InSpec command line interface by adding a namespace of new commands. InSpec is based on [Thor](http://whatisthor.com/) ([docs](https://www.rubydoc.info/github/wycats/thor/Thor)), and the plugin system exposes Thor directly.
+
+CliCommand can do things like:
+
+```bash
+# A namespaced custom command with options
+you@machine$ inspec sweeten add --kind sugar --teaspoons 2
+# A namespaced custom command with short options
+you@machine$ inspec sweeten add -k agave
+# Mix global and namespace options
+you@machine$ inspec --debug sweeten add -k aspartame
+# Namespace included in help
+you@machine$ inspec help
+Commands:
+  inspec archive PATH      # archive a profile to tar.gz (default) or zip
+  inspec sweeten ...       # Add spoonfuls til the medicine goes down
+# Detailed help
+[cwolfe@lodi inspec-plugins]$ inspec help sweeten
+Commands:
+  inspec sweeten add [opts]       # Adds sweetener to your beverage
+  inspec sweeten count            # Reports on teaspoons in your beverage, always bad news
+```
+
+Currently, it cannot create a direct (non-namespaced) command, such as `inspec mycommand` with no subcommands.
+
+### Declare your plugin activators
+
+In your `plugin.rb`, include one or more `cli_command` activation blocks.  The activation block name will be matched against the command line arguments; if the name is present, your activator will fire (in which case it should load any needed libraries) and should return your implementation class.
+
+#### CliCommand Activator Example
+
+```ruby
+
+# In plugin.rb
+module InspecPlugins::Sweeten
+  class Plugin < Inspec.plugin(2)
+    # ... other plugin stuff
+
+    cli_command :sweeten do
+      require_relative 'cli.rb'
+      InspecPlugins::Sweeten::CliCommand
+    end
+  end
+end
+```
+
+Like any activator, the block above will only be called if needed. For CliCommand plugins, the plugin system naively scans through ARGV, looking for the activation name as a whole element.  Multiple CliCommand activations may occur if several different names match, though each activation will only occur once.
+
+```bash
+you@machine $ inspec sweeten ... # Your CliCommand implementation is activated and executed
+you@machine $ inspec exec ... # Your CliCommand implementation is not activated
+```
+
+Execution occurs implicitly via `Thor.start()`, which is handled by `bin/inspec`. Keep reading.
+
+You should also be aware of one other activation event: if the CLI is invoked as `inspec help`, *all* CliCommand plugins will activate (but will not be executed). This is so that each plugin's help information can be registered with Thor.
+
+### Implementation class for CLI Commands
+
+In your `cli.rb`, you should begin by requesting the superclass from `Inspec.plugin`:
+
+```ruby
+module InspecPlugins::Sweeten
+  class CliCommand < Inspec.plugin(2, :cli_command)
+    # ...
+  end
+end
+```
+
+The Inspec plugin v2 system promises the following:
+
+* The superclass will be an (indirect) subclass of Thor
+* The plugin system will handle registering the subcommand with Thor for you
+* The plugin system will handle setup of the subcommand help message for you
+
+### Implementing your command
+
+Within your `cli.rb`, you need to do two things:
+
+* Inform Inspec of your subcommand's usage and description, so the `help` commands will work properly
+* Implement your subcommands and options using the Thor DSL
+
+See also: [Thor homepage](http://whatisthor.com/) and [Thor docs](https://www.rubydoc.info/github/wycats/thor/Thor).
+
+#### Call subcommand_desc
+
+Within your implementation, make a call like this:
+
+```ruby
+# Class declaration as above
+subcommand_desc 'sweeten ...', 'Add spoonfuls til the medicine goes down'
+```
+
+The first argument is the usage message; it will be displayed whenever you execute `inspec help`, or when Thor tries to parse a malformed `inspec sweeten ...` command.
+
+The second is the command groups description, and is displayed with `inspec help`.
+
+Both arguments are free-form Strings intended for humans; the usage message should begin with your subcommand name to prevent user confusion.
+
+If you neglect to call this DSL method, Thor will not register your command.
+
+#### Adding Subcommands
+
+The minimum needed for a command is a call to `desc` to set the help message, and a method definition named after the command.
+
+```ruby
+desc 'Reports on teaspoons in your beverage, always bad news'
+def count
+  # Someone has executed `inspec sweeten count` - do whatever that entails
+  case beverage_type
+  when :soda
+    puts 12
+  when :tea_two_lumps
+    puts 2
+  end
+end
+```
+
+There is a great deal more you can do with Thor, especially concerning handling options. Refer to the Thor docs for more examples and details.
+
+#### Using no_command
+
+One common surprise seen with Thor is that every public instance method of your CliCommand implementation class is expected to be a CLI command definition. Thor will issue a warning if it encounters a public method definition without a `desc` call preceding it.  Two ways around this include:
+
+* Make your helper methods private
+* Enclose your non-command methods in a no_command block (a feature of Thor just for this circumstance)
+
+```ruby
+no_command do
+  def beverage_type
+    @bevvy
+  end
+end
+```

data/docs/profiles.md

@@ -81,12 +81,23 @@ $ 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:
+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 the following:
+
+* Use `platform-family` to restrict to a specific platform family.
+* Use `platform-name` to restrict on a specific platform name.
+* Use `release` to restrict to a specific platform version (used with platform-name).
+* Use `platform` to restrict on either platform-name or platform-family.
+
+For compatibility we support `os-name` and `os-family`. We recommend all users to change `os-name` to `platform-name` and `os-family` to `platform-family`.
+
+With InSpec 2.0, we introduced new families to help distinguish the cloud platforms. The new families can restrict the platform family to `os`, `aws`, `azure` or `gcp`.
+
+For example, to target anything running Debian Linux:
 
 ```YAML
 name: ssh
 supports:
-  - os-name: debian
+  - platform-name: debian
 ```
 
 and to target only Ubuntu version 14.04
@@ -94,7 +105,7 @@ and to target only Ubuntu version 14.04
 ```YAML
 name: ssh
 supports:
-  - os-name: ubuntu
+  - platform-name: ubuntu
     release: 14.04
 ```
 
@@ -103,7 +114,7 @@ and to target the entire RedHat platform (including CentOS and Oracle Linux):
 ```YAML
 name: ssh
 supports:
-  - os-family: redhat
+  - platform-family: redhat
 ```
 
 and to target anything running on Amazon AWS:
@@ -119,10 +130,10 @@ and to target all of these examples in a single `inspec.yml` file:
 ```YAML
 name: ssh
 supports:
-  - os-name: debian
-  - os-name: ubuntu
+  - platform-name: debian
+  - platform-name: ubuntu
     release: 14.04
-  - os-family: redhat
+  - platform-family: redhat
   - platform: aws
 ```
 
@@ -226,9 +237,7 @@ Once defined in the `inspec.yml`, controls from the included profiles can be use
 
 With the `include_controls` command in a profile, all controls from the named profile will be executed every time the including profile is executed.
 
-```YAML
 ![Include Controls](/images/profile_inheritance/include_controls.png)
-```
 
 In the example above, every time `my-app-profile` is executed, all the controls from `my-baseline` are also executed. Therefore, the following controls would be executed:
 
@@ -245,9 +254,8 @@ including controls from other profiles!
 
 What if one of the controls from the included profile does not apply to your environment? Luckily, it is not necessary to maintain a slightly-modified copy of the included profile just to delete a control. The `skip_control` command tells InSpec to not run a particular control.
 
-```YAML
 ![Include Controls with Skip](/images/profile_inheritance/include_controls_with_skip.png)
-```
+
 
 In the above example, all controls from `my-app-profile` and `my-baseline` profile will be executed every time `my-app-profile` is executed **except** for control `baseline-2` from the `my-baseline` profile.
 
@@ -257,9 +265,7 @@ Let's say a particular control from an included profile should still be run, but
 
 When a control is included, it can also be modified!
 
-```YAML
 ![Include Controls with Modification](/images/profile_inheritance/include_controls_with_mod.png)
-```
 
 In the above example, all controls from `my-baseline` are executed along with all the controls from the including profile, `my-app-profile`. However, should control `baseline-1` fail, it will be raised with an impact of `0.5` instead of the originally-intended impact of `1.0`.
 
@@ -267,9 +273,7 @@ In the above example, all controls from `my-baseline` are executed along with al
 
 If there are only a handful of controls that should be executed from an included profile, it's not necessarily to skip all the unneeded controls, or worse, copy/paste those controls bit-for-bit into your profile. Instead, use the `require_controls` command.
 
-```YAML
 ![Require Controls](/images/profile_inheritance/require_controls.png)
-```
 
 Whenever `my-app-profile` is executed, in addition to its own controls, it will run only the controls specified in the `require_controls` block. In the case, the following controls would be executed:
 
@@ -283,9 +287,7 @@ Controls `baseline-1`, `baseline-3`, and `baseline-5` would not be run, just as
 
 And, just the way its possible to modify controls when using `include_controls`, controls can be modified as well.
 
-```YAML
 ![Require Controls with Modification](/images/profile_inheritance/require_controls_with_mod.png)
-```
 
 As with the prior example, only `baseline-2` and `baseline-4` are executed, but if `baseline-2` fails, it will report with an impact of `0.5` instead of the originally-intended `1.0` impact.
 
@@ -436,4 +438,4 @@ end
 ```text
 test file
   ✔  should be a file
-```
+```