inspec-vault 0.0.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 7afd48c6772df42d77ed99c42c5492030ec90610
-  data.tar.gz: e8f71d4de6c89af85203da46215bca95fb5a1766
+SHA256:
+  metadata.gz: cfbbbb425fb095bdf5a4124f20a3475f87f6d983074339889156e70eccb1cbc7
+  data.tar.gz: c45dcca2381837fbb2380467ac66eae9321fce02ef23d5ab8cea27403ce9ca21
 SHA512:
-  metadata.gz: 422c66def196ccc63ed1cffbd1f6f52e16c2259b89b89d43c67a28d04a441bde0fcb816c985ab7fb739e49045d36b5d97cdc912e93607e4430e676f3adb14370
-  data.tar.gz: 6569769e23f6fd1320f9228e6f4cd2630d10bf0d6e5f8ca17640e516e11bd73d17600e2300a40a843c844179c68e8d049dabd354b5fae127817556e16110ccf2
+  metadata.gz: fe1329781eca561a3788ed933bc5a46729447819be483e047095217caf4ae53d233e23936bf0201729e99b5c3cfc3a7096b7b9586c58a52908dec34fdaa88684
+  data.tar.gz: 803e458ad47d5f518691b0e265c997689ffa045c3c144be241361436e342669f4fc4229f3c888c411b1c97657b19f2f01a391ca6e5601d277fffcb6cbb3bbbe6

data/Gemfile

@@ -0,0 +1,16 @@
+# encoding: utf-8
+source "https://rubygems.org"
+
+gemspec
+
+gem "inspec-bin"
+
+group :development do
+  gem "chefstyle", "0.13.0"
+  gem "m"
+  gem "bundler"
+  gem "byebug"
+  gem "minitest"
+  gem "rake"
+  gem "rubocop"
+end

data/README.md

@@ -0,0 +1,114 @@
+# inspec-vault Plugin
+
+This is a plugin for [Chef InSpec](https://www.inspec.io/) that allows [Inputs](https://www.inspec.io/docs/reference/inputs/) to be read from [HashiCorp Vault](https://www.vaultproject.io/).
+
+* **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](https://github.com/chef/chef-oss-practices/blob/master/repo-management/repo-states.md).
+
+## Notice - Experimental Project
+
+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](https://github.com/inspec/inspec-vault).
+
+## To Install This Plugin
+
+Assuming it has been published to RubyGems, you can install this gem using:
+
+```
+you@machine $ inspec plugin install inspec-vault
+```
+
+## Loading Secrets into 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.
+
+## What This Plugin Does
+
+With the inspec-vault plugin enabled, Chef InSpec will contact the Vault server whenever an `input()` DSL call appears in profile control code. For example, whenever profile code like this is encountered:
+
+```ruby
+# In profile "my_profile"
+describe input("some_input") do
+  it { should cmp "some_expected_value" }
+end
+```
+
+Chef InSpec will determine a secret lookup path and access Vault. With no other settings, Chef InSpec will look for a Vault secret located at `secret/inspec/my_profile` with a key named "some_input". Chef InSpec will use the Vault secret if found, but otherwise it will fall back to other means of resolving the input, such as the profile metadata or CLI values.
+
+## Configuring the Plugin
+
+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:
+
+```json
+{
+  "version": "1.2",
+  "plugins":{
+    "inspec-vault":{
+      "prefix_path":"my-profiles"
+    }
+  }
+}
+```
+
+Config file option names are always lowercase.
+
+This plugin supports the following options:
+
+### INSPEC_VAULT_MOUNT_POINT
+
+### mount_point
+
+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>`.
+
+### INSPEC_VAULT_PATH_PREFIX
+
+### path_prefix
+
+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>`.
+
+### INSPEC_VAULT_PRIORITY
+
+### priority
+
+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.
+
+### VAULT_ADDR
+
+### vault_addr
+
+This environment variable is the URL and port of your Vault installation. Default is http://127.0.0.1:8200.
+
+### VAULT_TOKEN
+
+This value is the secret used to authenticate to Vault. Required, no default provided.
+
+## Developing This Plugin
+
+Please have a look at our CONTRIBUTING.md for general guidelines.
+
+### Testing
+
+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.
+

data/inspec-vault.gemspec

@@ -0,0 +1,40 @@
+# coding: utf-8
+
+# As plugins are usually packaged and distributed as a RubyGem,
+# we have to provide a .gemspec file, which controls the gembuild
+# and publish process.  This is a fairly generic gemspec.
+
+# It is traditional in a gemspec to dynamically load the current version
+# from a file in the source tree.  The next three lines make that happen.
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "inspec-vault/version"
+
+Gem::Specification.new do |spec|
+  # Importantly, all InSpec plugins must be prefixed with `inspec-` (most
+  # plugins) or `train-` (plugins which add new connectivity features).
+  spec.name          = "inspec-vault"
+
+  # It is polite to namespace your plugin under InspecPlugins::YourPluginInCamelCase
+  spec.version       = InspecPlugins::Vault::VERSION
+  spec.authors       = ["InSpec Core Engineering"]
+  spec.email         = ["inspec@chef.io"]
+  spec.summary       = "Use HashiCorp Vault data in your InSpec profiles"
+  spec.description   = "This plugin allows InSpec 'inputs' to be provided by a HashiCorp Vault installation.  This enables you to unify your secrets management with your compliance automation."
+  spec.homepage      = "https://github.com/inspec/inspec-vault"
+  spec.license       = "Apache-2.0"
+
+  # Though complicated-looking, this is pretty standard for a gemspec.
+  # It just filters what will actually be packaged in the gem (leaving
+  # out tests, etc)
+  spec.files = %w{
+    README.md inspec-vault.gemspec Gemfile
+  } + Dir.glob(
+    "lib/**/*", File::FNM_DOTMATCH
+  ).reject { |f| File.directory?(f) }
+  spec.require_paths = ["lib"]
+
+  # If you rely on any other gems, list them here with any constraints.
+  # This is how `inspec plugin install` is able to manage your dependencies.
+  spec.add_dependency "vault", "~> 0.12"
+end

data/lib/inspec-vault.rb

@@ -0,0 +1,16 @@
+# encoding: utf-8
+
+# This file is known as the "entry point."
+# This is the file InSpec will try to load if it
+# thinks your plugin is installed.
+
+# The *only* thing this file should do is setup the
+# load path, then load the plugin definition file.
+
+# Next two lines simply add the path of the gem to the load path.
+# This is not needed when being loaded as a gem; but when doing
+# plugin development, you may need it.  Either way, it's harmless.
+libdir = File.dirname(__FILE__)
+$LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
+
+require "inspec-vault/plugin"

data/lib/inspec-vault/input.rb

@@ -0,0 +1,79 @@
+require "vault"
+
+# See https://github.com/inspec/inspec/blob/master/docs/dev/plugins.md#implementing-input-plugins
+
+module InspecPlugins::Vault
+  class Input < Inspec.plugin(2, :input)
+
+    attr_reader :plugin_conf
+    attr_reader :mount_point
+    attr_reader :path_prefix
+    attr_reader :vault
+    attr_reader :priority
+
+    def initialize
+      @plugin_conf = Inspec::Config.cached.fetch_plugin_config("inspec-vault")
+
+      @mount_point = fetch_plugin_setting("mount_point", "secret")
+      @path_prefix = fetch_plugin_setting("path_prefix", "inspec")
+
+      # We need priority to be numeric; even though env vars or JSON may present it as string - hence the to_i
+      @priority = fetch_plugin_setting("priority", 60).to_i
+
+      @vault = Vault::Client.new(
+        address: fetch_vault_setting("vault_addr"),
+        token: fetch_vault_setting("vault_token")
+      )
+    end
+
+    # What priority should an input value recieve from us?
+    # This plgin does not currently allow setting this on a per-input basis,
+    # so they all recieve the same "default" value.
+    # Implements https://github.com/inspec/inspec/blob/master/docs/dev/plugins.md#default_priority
+    def default_priority
+      priority
+    end
+
+    # returns Array of input names as strings
+    def list_inputs(profile_name)
+      vault.with_retries(Vault::HTTPConnectionError) do
+        path = logical_path_for_profile(profile_name)
+        doc = vault.logical.read(path)
+        return [] unless doc
+        return doc.data[:data].keys.map(&:to_s)
+      end
+    end
+
+    # Fetch a value of a single input from Vault
+    # Assumption: inputs have been stored on documents named for their
+    # profiles, and each input has a key-value pair in the document.
+    # TODO we should probably cache these - https://github.com/inspec/inspec-vault/issues/15
+    def fetch(profile_name, input_name)
+      path = logical_path_for_profile(profile_name)
+      vault.with_retries(Vault::HTTPConnectionError) do
+        doc = vault.logical.read(path)
+        # Keys from vault are always symbolized
+        return doc.data[:data][input_name.to_sym] if doc
+      end
+    end
+
+    private
+
+    def logical_path_for_profile(profile_name)
+      # When you actually read a value, on the KV2 backend you must
+      # read secret/data/path, not secret/path (as on the CLI)
+      # https://www.vaultproject.io/api/secret/kv/kv-v2.html#read-secret-version
+      # Is this true for all backends?
+      "#{mount_point}/data/#{path_prefix}/#{profile_name}"
+    end
+
+    def fetch_plugin_setting(setting_name, default = nil)
+      env_var_name = "INSPEC_VAULT_#{setting_name.upcase}"
+      ENV[env_var_name] || plugin_conf[setting_name] || default
+    end
+
+    def fetch_vault_setting(setting_name)
+      ENV[setting_name.upcase] || plugin_conf[setting_name]
+    end
+  end
+end

data/lib/inspec-vault/plugin.rb

@@ -0,0 +1,27 @@
+# encoding: UTF-8
+
+# Plugin Definition file
+# The purpose of this file is to declare to InSpec what plugin_types (capabilities)
+# are included in this plugin, and provide hooks that will load them as needed.
+
+# It is important that this file load successfully and *quickly*.
+# Your plugin's functionality may never be used on this InSpec run; so we keep things
+# fast and light by only loading heavy things when they are needed.
+
+# Presumably this is light
+require "inspec-vault/version"
+module InspecPlugins
+  module Vault
+    class Plugin < ::Inspec.plugin(2)
+      # Internal machine name of the plugin. InSpec will use this in errors, etc.
+      plugin_name :'inspec-vault'
+
+      # Define an Input plugin type.
+      input :vault do
+        require_relative "input.rb"
+        InspecPlugins::Vault::Input
+      end
+
+    end
+  end
+end

data/lib/inspec-vault/version.rb

@@ -0,0 +1,10 @@
+# encoding: UTF-8
+
+# This file simply makes it easier for CI engines to update
+# the version stamp, and provide a clean way for the gemspec
+# to learn the current version.
+module InspecPlugins
+  module Vault
+    VERSION = "0.3.2".freeze
+  end
+end

metadata

@@ -1,23 +1,46 @@
 --- !ruby/object:Gem::Specification
 name: inspec-vault
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.3.2
 platform: ruby
 authors:
-- Jared Quick
+- InSpec Core Engineering
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-10-19 00:00:00.000000000 Z
-dependencies: []
-description: 
+date: 2019-09-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: vault
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+description: This plugin allows InSpec 'inputs' to be provided by a HashiCorp Vault
+  installation.  This enables you to unify your secrets management with your compliance
+  automation.
 email:
-- jquick@chef.io
+- inspec@chef.io
 executables: []
 extensions: []
 extra_rdoc_files: []
-files: []
-homepage: https://github.com/inspec/inspec
+files:
+- Gemfile
+- README.md
+- inspec-vault.gemspec
+- lib/inspec-vault.rb
+- lib/inspec-vault/input.rb
+- lib/inspec-vault/plugin.rb
+- lib/inspec-vault/version.rb
+homepage: https://github.com/inspec/inspec-vault
 licenses:
 - Apache-2.0
 metadata: {}
@@ -36,9 +59,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.14
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
-summary: inspec-vault plugin UNDER CONSTRUCTION
+summary: Use HashiCorp Vault data in your InSpec profiles
 test_files: []