train-habitat 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: eac163fde458b35d8ca76275c7855ffa74a85cdc
+  data.tar.gz: be696afb0d1f2bbb6562c030fe88b566e3004ae9
+SHA512:
+  metadata.gz: fa6c53f04316c25a25a0a393a789abe030f11dbb6097a240a630fe0667b5ed44be447f29306e98e60e03bc9ff41bdca50278712c8829ad53083f43e5e32cc2ed
+  data.tar.gz: a4e3061e4a97b64e57e60408327f09707f7630a02b639c6e6ea4f943d01fdb72563770afd0e37c0eff921e7430edd24372c09ae4e902e72c5804c6d053247ff8

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'byebug', '~> 11.0'
+  gem 'm', '~> 1.5'
+  gem 'minitest', '~> 5.11'
+  gem 'mocha', '~> 1.8'
+  gem 'pry', '~> 0.11'
+  gem 'rake', '~> 12.3'
+  gem 'rubocop', '~> 0.59'
+end

data/README.md

@@ -0,0 +1,163 @@
+# Train-Habitat
+
+`train-habitat` is a Train plugin and is used as a Train Transport to connect to Habitat installations.
+
+## To Install this as a User
+
+You will need InSpec v2.3 or later.
+
+Simply run:
+
+```
+$ inspec plugin install train-habitat
+```
+
+## Using train-habitat from InSpec
+
+As `train-habitat` takes potentially many options, it is simplest to list the options in your `~/.inspec/config.json` file, then used the named set of options with `-t`.
+
+For example, if your config file contains:
+
+```
+{
+  "file_version": "1.1",
+  "credentials": {
+    "habitat": {
+      "dev-hab": {
+        "api_url": "http://dev-hab.my-corp.io",
+        "cli_ssh_host": "dev-hab.my-corp.io"
+      },
+      "prod-hab": {
+        "api_url": "https://prod-hab.my-corp.io",
+        "api_auth_token": "opensesame"
+      },
+    }
+  }
+}
+```
+
+Using this configuration, you could execute:
+
+```
+$ inspec exec some-profile -t habitat://dev-hab
+# Or
+$ inspec exec some-profile -t habitat://prod-hab
+```
+
+You may also pass `--config some-file.json` to use a config file at a different location.
+
+See the next section for the full list of options you may use with a `habitat` credential set in your configuration.
+
+## Using train-habitat from Ruby
+
+The options that may be passed to `Train.create` are listed below.
+
+### Dual-mode transport
+
+Because Habitat exposes some facts by its HTTP Gateway API, and some facts by its CLI tool `hab`, this Train Transport has three modes of operation:
+
+ * Using only the HTTP API (no ability to query packages, but rich ability to query rings)
+ * Using only the `hab` CLI command (limitations TBD)
+ * Using both (full capabilities)
+
+When creating a `train-habitat` Connection, there are thus two sets of options, prefixed with `api_` and `cli_` respectively. You must provide at least one set.
+
+### API-Mode options
+
+API-mode options are used to connect to a Habitat Supervisor running with an exposed HTTP Gateway. They are prefixed with `api_`.
+
+```ruby
+Train.create(:habitat, api_url: 'http://my-hab.my-company.io:9631')
+```
+
+#### api_url
+
+Required for API-mode use. This is an HTTP or HTTPS URL that identifies a Supervisor HTTP Gateway.  If the port is omitted from the URL, the API standard port of 9631 is assumed; to use port 80, specify it explicitly.
+
+#### api_auth_token
+
+The supervisor may be configured to require a [Bearer Token Authorization](https://www.habitat.sh/docs/using-habitat/#monitor-services-through-the-http-api), in which the client and the gateway use a pre-shared secret. Use this option to specify the secret.
+
+### CLI Mode options
+
+CLI options are more varied, and are entirely dependent on the underlying transport chosen to reach the CLI. For example, if there were a supported transport named 'radio' that took options 'channel' and 'band', specify them to train-habitat like this:
+
+```ruby
+Train.create(:habitat, {cli_radio_band: 'VHF', cli_radio_channel: 23})
+```
+
+`train-habitat` identifies the underlying "sub-transport" using the prefixes of the provided options. For example, if you pass an option named `cli_ssh_host`, `train-habitat` will recognize that you intend to use the SSH transport to connect to a location that has access to the `hab` CLI tool.
+
+You may specify many options referring to the same sub-transport (such as credentials), but it is an error to specify more than one CLI sub-transport.
+
+Currently supported CLI transports include:
+ * SSH
+
+Plans for future support include (in approximate order):
+ * WinRM
+ * Local
+ * Docker
+
+#### General Options
+
+Any options not prefixed with `cli_` or `api_` are also passed to the CLI transport. This means you can use generic Train connection options such as the `sudo` and `shell` sets of options (see [train source code](https://github.com/inspec/train/blob/71679307903fc8853e09abd93f3901c83800e019/lib/train/extras/command_wrapper.rb#L31)), as well as `logger`.
+
+#### SSH Options
+
+`train-habitat` can accept any option that the Train SSH Transport accepts if the prefix `cli_ssh_` is added. This includes:
+
+ * `cli_ssh_host` - String hostname or IP address
+ * `cli_ssh_user` - String user to connect as
+ * `cli_ssh_key_files` - Array of paths to private key files to use
+
+Other options are available; see [train source code](https://github.com/inspec/train/blob/71679307903fc8853e09abd93f3901c83800e019/lib/train/transports/ssh.rb#L45) for details.
+
+## Development
+
+### Testing
+```
+# Install development tools
+$ gem install bundler
+$ bundle install
+
+# Running style checker
+bundle exec rake lint
+
+# Running unit tests
+bundle exec rake test:unit
+
+# Running integration tests (requires Vagrant and VirtualBox)
+bundle exec rake test:integration
+```
+
+## Contributing
+
+1. Fork it
+1. Create your feature branch (git checkout -b my-new-feature)
+1. Commit your changes (git commit -sam 'Add some feature')
+1. Push to the branch (git push origin my-new-feature)
+1. Create new Pull Request
+
+## License
+
+| **Author:**          | Paul Welch
+
+| **Author:**          | David McCown
+
+| **Author:**          | Clinton Wolfe
+
+| **Copyright:**       | Copyright (c) 2018-2019 Chef Software Inc.
+
+| **License:**         | Apache License, Version 2.0
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+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.

data/lib/train-habitat.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+libdir = File.dirname(__FILE__)
+$LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
+
+require 'train-habitat/version'
+require 'train-habitat/transport'
+require 'train-habitat/platform'
+require 'train-habitat/connection'

data/lib/train-habitat/connection.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'train-habitat/httpgateway'
+require 'train-habitat/platform'
+require 'train-habitat/transport'
+
+module TrainPlugins
+  module Habitat
+    class Connection < Train::Plugins::Transport::BaseConnection
+      include TrainPlugins::Habitat::Platform
+
+      attr_reader :cli_transport_name, :cli_connection, :cli_transport, :transport_options
+
+      def initialize(options = {})
+        @transport_options = options
+        validate_transport_options!
+
+        super(transport_options)
+        initialize_cli_connection! if cli_options_provided?
+        enable_cache :api_call
+      end
+
+      def uri
+        "habitat://#{@options[:host]}"
+      end
+
+      def api_options_provided?
+        have_transport_options_with_prefix?('api')
+      end
+
+      def cli_options_provided?
+        TrainPlugins::Habitat::Transport.cli_transport_prefixes.keys.map(&:to_s).any? do |prefix|
+          have_transport_options_with_prefix?(prefix)
+        end
+      end
+
+      # Use this to execute a `hab` command. Do not include the `hab` executable in the invocation.
+      def run_hab_cli(command, _exec_options = {})
+        raise CliNotAvailableError(cli_tranport_names) unless cli_options_provided?
+
+        # TODO: - leverage exec_options to add things like JSON parsing, ENV setting, etc.
+        cli_connection.run_command(hab_path + ' ' + command)
+      end
+
+      def hab_path
+        '/bin/hab'
+      end
+
+      def habitat_api_client
+        cached_client(:api_call, :HTTPGateway) do
+          # Send all options beginning with api_ to the HTTPGateway, stripping the prefix
+          api_options = {}
+          transport_options.each do |option_name, option_value|
+            next unless option_name.to_s.start_with? 'api_'
+
+            api_options[option_name.to_s.sub(/^api_/, '').to_sym] = option_value
+          end
+          HTTPGateway.new(api_options)
+        end
+      end
+
+      private
+
+      def validate_transport_options!
+        unless api_options_provided? || cli_options_provided?
+          raise Train::TransportError, "Habitat connection options that begin with either 'cli' or 'api' required"
+        end
+
+        valid_cli_prefixes = TrainPlugins::Habitat::Transport.cli_transport_prefixes.keys.map(&:to_s)
+        seen_cli_options = transport_options.keys.map(&:to_s).select { |n| n.start_with?('cli_') }
+
+        # All seen CLI options must start with a recognized prefix
+        options_by_prefix = {}
+        seen_cli_options.each do |option|
+          prefix = valid_cli_prefixes.detect { |p| option.start_with?(p) }
+          unless prefix
+            raise Train::TransportError, "All Habitat CLI connection options must begin with a recognized prefix (#{valid_cli_prefixes.join(', ')}) - saw #{option}"
+          end
+
+          options_by_prefix[prefix] ||= []
+          options_by_prefix[prefix] << option
+        end
+
+        # Only one prefix may be used (don't mix and match)
+        if options_by_prefix.count > 1
+          raise Train::TransportError, "Only one set of Habitat CLI connection options may be used - saw #{options_by_prefix.keys.join(', ')}"
+        end
+      end
+
+      def cli_transport_names
+        TrainPlugins::Habitat::Transport.cli_transport_prefixes.values
+      end
+
+      def have_transport_options_with_prefix?(prefix)
+        transport_options.keys.map(&:to_s).any? { |option_name| option_name.start_with? prefix }
+      end
+
+      def initialize_cli_connection! # rubocop:disable Metrics/AbcSize
+        return if @cli_connection
+        raise CliNotAvailableError(cli_tranport_names) unless cli_options_provided?
+
+        # group cli connection options by prefix
+        # Our incoming connection options have prefixes, so we see things like 'cli_ssh_host'.
+        # The ssh transport wants just 'host'. So identify which transports we have
+        # options for, and trim them down.
+        known_prefixes = TrainPlugins::Habitat::Transport.cli_transport_prefixes.keys.map(&:to_s)
+
+        seen_cli_transports = {}
+        non_specific_options = {} # Things like :logger, :sudo, etc
+        transport_options.each do |xport_option_name, xport_option_value|
+          unless xport_option_name.to_s.start_with?('cli_')
+            non_specific_options[xport_option_name] = xport_option_value
+            next
+          end
+          known_prefixes.each do |prefix|
+            next unless xport_option_name.to_s.start_with?(prefix)
+
+            xport_name = TrainPlugins::Habitat::Transport.cli_transport_prefixes[prefix.to_sym]
+
+            seen_cli_transports[xport_name] ||= {}
+            # Remove the prefix from the option and store under transport name
+            seen_cli_transports[xport_name][xport_option_name.to_s.sub(/^#{prefix}_/, '').to_sym] = xport_option_value
+          end
+        end
+
+        raise MultipleCliTransportsError, seen_cli_tranports.keys if seen_cli_transports.count > 1
+
+        # If no specific logger was passed in, re-use ours.
+        non_specific_options[:logger] = logger
+
+        @cli_transport_name = seen_cli_transports.keys.first
+        final_train_options = seen_cli_transports[cli_transport_name].merge(non_specific_options)
+        @cli_transport = Train.create(cli_transport_name, final_train_options)
+        @cli_connection = cli_transport.connection
+      end
+    end
+  end
+end

data/lib/train-habitat/httpgateway.rb

@@ -0,0 +1,46 @@
+require 'uri'
+require 'net/http'
+
+module TrainPlugins
+  module Habitat
+    class HTTPGateway
+      Response = Struct.new(:code, :body, :raw_response)
+
+      attr_reader :base_uri
+
+      def initialize(opts)
+        @base_uri = URI(opts[:url])
+        # check for provided port and default if not provided
+        if base_uri.port == 80 && opts[:url] !~ %r{\w+:\d+(\/|$)}
+          base_uri.port = 9631
+        end
+
+        @auth_token = opts[:auth_token]
+      end
+
+      def get_path(path)
+        uri = base_uri.dup
+        uri.path = path
+        headers = {}
+        unless auth_token.nil?
+          headers['Authorization'] = 'Bearer ' + auth_token # Set bearer token, see https://www.habitat.sh/docs/using-habitat/#authentication
+        end
+
+        conn = Net::HTTP.start(uri.host, uri.port)
+        conn.read_timeout = 5
+
+        resp = Response.new
+        resp.raw_response = conn.get(uri, headers)
+
+        resp.code = resp.raw_response.code.to_i
+        if resp.code == 200
+          resp.body = JSON.parse(resp.raw_response.body, symbolize_names: true)
+        end
+        resp
+      end
+
+      # Private accessor
+      attr_reader :auth_token
+    end
+  end
+end

data/lib/train-habitat/illegal_state_error.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class IllegalStateError < StandardError
+  def initialize(msg = nil)
+    super
+  end
+end
+
+class NoServicesFoundError < IllegalStateError
+  def initialize(origin, name)
+    super("Expected one service '#{origin}/#{name}', but found none.")
+  end
+end
+
+class MultipleServicesFoundError < IllegalStateError
+  def initialize(origin, name)
+    super("Expected one service '#{origin}/#{name}', but found multiple.")
+  end
+end
+
+class CliNotAvailableError < IllegalStateError
+  def initialize(_cli_tranport_names)
+    super("No CLI-capable connection options passed - use one of #{cli_transport_names.join(', ')} option sets")
+  end
+end
+
+class MultipleCliTransportsError < IllegalStateError
+  def initialize(_cli_tranport_names)
+    super("Too many CLI-capable transports specified - only one may be used at a time.  Saw: #{cli_transport_names.join(', ')}.")
+  end
+end

data/lib/train-habitat/platform.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module TrainPlugins
+  module Habitat
+    module Platform
+      def platform
+        Train::Platforms.name('habitat').in_family('api')
+        force_platform!('habitat', release: TrainPlugins::Habitat::VERSION)
+      end
+    end
+  end
+end

data/lib/train-habitat/transport.rb

@@ -0,0 +1,33 @@
+require 'train'
+require 'train/plugins'
+require 'train-habitat/connection'
+
+module TrainPlugins
+  module Habitat
+    class Transport < Train.plugin(1)
+      name 'habitat'
+
+      # The train-habitat plugins is a chimeric plugin, meaning it uses
+      # multiple ways of connecting to its target. A user must specifiy
+      # at least one set, but they can use multiple sets of connecting
+      # information to get a full experience.
+
+      # For service listings and health, specify supervisor api options.
+      # https://www.habitat.sh/docs/using-habitat/#monitor-services-through-the-http-api
+      option :api_url, required: false, desc: 'The url at which a Habitat Supervisor exposes its HTTP Gateway API'
+      option :api_auth_token, required: false, desc: 'A bearer token which may be used to authenticate to the Supervisor HTTP Gateway'
+
+      def self.cli_transport_prefixes
+        {
+          # add transports here, prefix => transport name
+          cli_ssh: :ssh,
+        }
+      end
+
+      # inspec -t habitat://credset
+      def connection(_instance_opts = nil)
+        @connection ||= TrainPlugins::Habitat::Connection.new(@options)
+      end
+    end
+  end
+end

data/lib/train-habitat/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module TrainPlugins
+  module Habitat
+    VERSION = '0.1.0'
+  end
+end

data/train-habitat.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'train-habitat/version'
+
+Gem::Specification.new do |spec|
+  spec.name        = 'train-habitat'
+  spec.version     = TrainPlugins::Habitat::VERSION
+  spec.authors     = ['Chef InSpec Team']
+  spec.email       = ['inspec@chef.io']
+  spec.summary     = 'Habitat API Transport for Train'
+  spec.description = 'Allows applications using Train to speak to Habitat.'
+  spec.homepage    = 'https://github.com/inspec/train-habitat'
+  spec.license     = 'Apache-2.0'
+
+  spec.files = %w{
+    README.md train-habitat.gemspec Gemfile
+  } + Dir.glob(
+    'lib/**/*', File::FNM_DOTMATCH
+  ).reject { |f| File.directory?(f) }
+  spec.require_paths = ['lib']
+
+  # All plugins should mention train, > 1.4
+  spec.add_dependency 'train', '>= 1.7.8', '< 3.0'
+
+  spec.add_development_dependency 'minitest', '~> 5.0'
+  spec.add_development_dependency 'rake', '~> 10.0'
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: train-habitat
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chef InSpec Team
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-03-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: train
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.7.8
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.7.8
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+description: Allows applications using Train to speak to Habitat.
+email:
+- inspec@chef.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- README.md
+- lib/train-habitat.rb
+- lib/train-habitat/connection.rb
+- lib/train-habitat/httpgateway.rb
+- lib/train-habitat/illegal_state_error.rb
+- lib/train-habitat/platform.rb
+- lib/train-habitat/transport.rb
+- lib/train-habitat/version.rb
+- train-habitat.gemspec
+homepage: https://github.com/inspec/train-habitat
+licenses:
+- Apache-2.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.14.3
+signing_key: 
+specification_version: 4
+summary: Habitat API Transport for Train
+test_files: []