inspec-vault Plugin

This is a plugin for Chef InSpec that allows Inputs to be read from HashiCorp Vault.

• Project State: Active (but EXPERIMENTAL)
• Issues Response SLA: 3 business days
• Pull Request Response SLA: 3 business days

For more information on project states and SLAs, see this documentation.

This Chef InSpec plugin is in the early stages of research and development. Functionality may be defective, incomplete, or be withdrawn in the future. If you are interested in helping this project mature, please join the conversation or contribute code at the inspec-vault project.

Assuming it has been published to RubyGems, you can install this gem using:

you@machine $ inspec plugin install inspec-vault

A full introduction to Vault is beyond the scope of this document, but begin by downloading a recent version from https://www.vaultproject.io . Then, start a Vault dev-mode server with the following command:

$ vault server -dev

From there, you can then store an input. For example, look at the command below to store an input named my_input with the value of 2, for the my_profile profile. Once entered, Vault responds with metadata about the entry.

[cwolfe@lodi inspec-vault]$ vault kv put secret/inspec/my_profile my_input=2
Key              Value
---              -----
created_time     2019-09-10T17:54:16.237055Z
deletion_time    n/a
destroyed        false
version          1

With that value stored, Chef InSpec will now be able to retrieve the value.

With the inspec-vault plugin enabled, whenever an input() DSL call appears in profile control code, Chef InSpec contacts the Vault server. If the secret is located in Vault, Chef InSpec uses this value. Otherwise, it searches for other sources to resolve the input, such as other plugins, profile metadata, or CLI values, as described in the Chef InSpec input precedence documentation.

The default mode allows you to use profile-specific secrets.

For example, whenever profile code like this is encountered:

# In profile "my_profile"
describe input("some_input") do
  it { should cmp "some_expected_value" }
end

With no other settings, Chef InSpec looks for a Vault secret located at secret/inspec/my_profile with a key named some_input, where inspec is derived from the path_prefix setting and my_profile is the name of this InSpec profile.

To access global information instead of a value related to a specific profile, qualify the path in absolute syntax with a starting /. For example:

describe input("/configuration/webserver/password")
 it { should cmp "some_expected_value" }
end

In this case, Chef InSpec searches the secret/configuration/webserver document and returns the value of the password key.

Each plugin option may be set either as an environment variable, or as a plugin option in your Chef InSpec configuration file at ~/.inspec/config.json. For example, to set the prefix_path option in the config file, lay out the config file as follows:

{
  "version": "1.2",
  "plugins":{
    "inspec-vault":{
      "prefix_path":"my-profiles"
    }
  }
}

Config file option names are always lowercase.

This plugin supports the following options:

A string that indicates where the key-value path should begin; default value is "secret". The path is constructed as <mount_point>/data/<path_prefix>/<profile_name>.

A string that indicates the latter portion of the key-value path; default value is "inspec". The path is constructed as <mount_point>/data/<path_prefix>/<profile_name>.

A number between 0 and 100, default 60. When two input provides both provide a value for the same input name, the priority determines which providers' value is used, with the higher priority prevailing. Core Chef InSpec providers only range up to 50, so inspec-vault will (by default) override any other input provider.

This environment variable is the URL and port of your Vault installation. Default is http://127.0.0.1:8200.

This value is the secret used to authenticate to Vault. Required, no default provided.

Please have a look at our CONTRIBUTING.md for general guidelines.

Run bundle exec rake test:lint for linting, bundle exec rake test:unit for unit tests, and bundle exec rake test:integration for integration tests.

Note that integration tests will download and run Vault server locally.