train-winrm 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 12bed665790e51bd23cbe569c27f6a93c0300e8c
+  data.tar.gz: 599a6d141eb447d549ca3b511c15929401dea19d
+SHA512:
+  metadata.gz: b12889e4dc8845c34c911e3856213eee6a8993d1d1e93488bd838a0ff0421722cba9256641b3c23bda1a7df9982e5c0ed3fdd805ee787f161edf57e34129f5a6
+  data.tar.gz: 82873a1ed8096c63b6c56f8a8acf0981168429af31fcb63f421af272664d8822142f7fab0e7627d6aa413f1639201c84c8e91b076f1cd7cd551c88d0d38cef37

data/Gemfile

@@ -0,0 +1,23 @@
+# encoding: utf-8
+
+source 'https://rubygems.org'
+
+# This is a Gemfile, which is used by bundler
+# to ensure a coherent set of gems is installed.
+# This file lists dependencies needed when outside
+# of a gem (the gemspec lists deps for gem deployment)
+
+# Bundler should refer to the gemspec for any dependencies.
+gemspec
+
+# Remaining group is only used for development.
+group :development do
+  gem 'bundler'
+  gem 'byebug'
+  gem 'm'
+  gem 'minitest'
+  gem 'mocha'
+  gem 'pry'
+  gem 'rake'
+  gem 'rubocop', '= 0.49.1' # Need to keep in sync with main InSpec project, so config files will work
+end

data/README.md

@@ -0,0 +1,51 @@
+# train-winrm - Train Plugin for connecting to Windows via Remote Management
+
+This plugin allows applications that rely on Train to communicate with the WinRM API.  For example, you could use this to audit Windows Server 2016 machines.
+
+TODO - details about underlying library
+
+Train itself has no CLI, nor a sophisticated test harness.  Chef InSpec does have such facilities, so installing Train plugins will require a Chef InSpec installation.  You do not need to use or understand Chef InSpec.
+
+Train plugins may be developed without a Chef InSpec installation.
+
+## To Install this as a User
+
+Train plugins are distributed as gems.  You may choose to manage the gem yourself, but if you are an Chef InSpec user, Chef InSpec can handle it for you.
+
+You will need Chef InSpec v2.3 or later.
+
+Simply run:
+
+```
+$ inspec plugin install train-winrm
+```
+
+You can then run:
+
+```
+TODO - example
+```
+
+## Target Options for Train-WinRM
+
+TODO
+
+## Reporting Issues
+
+Bugs, typos, limitations, and frustrations are welcome to be reported through the [GitHub issues page for the train-winrm project](https://github.com/inspec/train-winrm/issues).
+
+You may also ask questions in the #inspec channel of the Chef Community Slack team.  However, for an issue to get traction, please report it as a github issue.
+
+## Development on this Plugin
+
+### Development Process
+
+If you wish to contribute to this plugin, please use the usual fork-branch-push-PR cycle.  All functional changes need new tests, and bugfixes are expected to include a new test that demonstrates the bug.
+
+### Reference Information
+
+[Plugin Development](https://github.com/inspec/train/blob/master/docs/dev/plugins.md) is documented on the `train` project on GitHub.
+
+### Testing changes against a Windows Machine
+
+TODO

data/lib/train-winrm.rb

@@ -0,0 +1,20 @@
+# This file is known as the "entry point."
+# This is the file Train will try to load if it
+# thinks your plugin is needed.
+
+# The *only* thing this file should do is setup the
+# load path, then load plugin files.
+
+# 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)
+
+# It's traditonal to keep your gem version in a separate file, so CI can find it easier.
+require 'train-winrm/version'
+
+# A train plugin has three components: Transport, Connection, and (optionally) Platform.
+# Transport acts as the glue.
+require 'train-winrm/transport'
+require 'train-winrm/connection'

data/lib/train-winrm/connection.rb

@@ -0,0 +1,213 @@
+# encoding: utf-8
+
+#
+# Author:: Salim Afiune (<salim@afiunemaya.com.mx>)
+# Author:: Matt Wrock (<matt@mattwrock.com>)
+# Author:: Fletcher Nichol (<fnichol@nichol.ca>)
+# Author:: Dominik Richter (<dominik.richter@gmail.com>)
+# Author:: Christoph Hartmann (<chris@lollyrock.com>)
+#
+# Copyright (C) 2014, Salim Afiune
+#
+# 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.
+
+# Most of the work of a Train plugin happens in this file.
+# Connections derive from Train::Plugins::Transport::BaseConnection,
+# and provide a variety of services.  Later generations of the plugin
+# API will likely separate out these responsibilities, but for now,
+# some of the responsibilities include:
+# * authentication to the target
+# * platform / release /family detection
+# * caching
+# * API execution
+# * marshalling to / from JSON
+# You don't have to worry about most of this.
+
+require 'train'
+require 'train/plugins'
+
+module TrainPlugins
+  module WinRM
+    # @author Fletcher Nichol <fnichol@nichol.ca>
+    class Connection < Train::Plugins::Transport::BaseConnection # rubocop:disable Metrics/ClassLength
+      attr_reader :hostname
+      def initialize(options)
+        super(options)
+        @hostname               = @options.delete(:hostname)
+        @rdp_port               = @options.delete(:rdp_port)
+        @connection_retries     = @options.delete(:connection_retries)
+        @connection_retry_sleep = @options.delete(:connection_retry_sleep)
+        @max_wait_until_ready   = @options.delete(:max_wait_until_ready)
+        @operation_timeout      = @options.delete(:operation_timeout)
+      end
+
+      # (see Base::Connection#close)
+      def close
+        return if @session.nil?
+        session.close
+      ensure
+        @session = nil
+      end
+
+      # (see Base::Connection#login_command)
+      def login_command
+        case RbConfig::CONFIG['host_os']
+        when /darwin/
+          login_command_for_mac
+        when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
+          login_command_for_windows
+        when /linux/
+          login_command_for_linux
+        else
+          fail ActionFailed,
+               "Remote login not supported in #{self.class} " \
+               "from host OS '#{RbConfig::CONFIG['host_os']}'."
+        end
+      end
+
+      # (see Base::Connection#upload)
+      def upload(locals, remote)
+        file_manager.upload(locals, remote)
+      end
+
+      def download(remotes, local)
+        Array(remotes).each do |remote|
+          file_manager.download(remote, local)
+        end
+      end
+
+      # (see Base::Connection#wait_until_ready)
+      def wait_until_ready
+        delay = 3
+        session(
+          retry_limit: @max_wait_until_ready / delay,
+          retry_delay: delay,
+        )
+        run_command_via_connection(PING_COMMAND.dup)
+      end
+
+      def uri
+        "winrm://#{options[:user]}@#{options[:endpoint]}:#{@rdp_port}"
+      end
+
+      private
+
+      PING_COMMAND = "Write-Host '[WinRM] Established\n'".freeze
+
+      def file_via_connection(path)
+        Train::File::Remote::Windows.new(self, path)
+      end
+
+      def run_command_via_connection(command, &data_handler)
+        return if command.nil?
+        logger.debug("[WinRM] #{self} (#{command})")
+        out = ''
+
+        response = session.run(command) do |stdout, _|
+          yield(stdout) if data_handler && stdout
+          out << stdout if stdout
+        end
+
+        CommandResult.new(out, response.stderr, response.exitcode)
+      end
+
+      # Create a local RDP document and return it
+      #
+      # @param opts [Hash] configuration options
+      # @option opts [true,false] :mac whether or not the document is for a
+      #   Mac system
+      # @api private
+      def rdp_doc(opts = {})
+        host = URI.parse(options[:endpoint]).host
+        content = [
+          "full address:s:#{host}:#{@rdp_port}",
+          'prompt for credentials:i:1',
+          "username:s:#{options[:user]}",
+        ].join("\n")
+
+        content.prepend("drivestoredirect:s:*\n") if opts[:mac]
+
+        content
+      end
+
+      # @return [Winrm::FileManager] a file transporter
+      # @api private
+      def file_manager
+        @file_manager ||= begin
+          # Ensure @service is available:
+          wait_until_ready
+          WinRM::FS::FileManager.new(@service)
+        end
+      end
+
+      # Builds a `LoginCommand` for use by Linux-based platforms.
+      #
+      # TODO: determine whether or not `desktop` exists
+      #
+      # @return [LoginCommand] a login command
+      # @api private
+      def login_command_for_linux
+        args  = %W(-u #{options[:user]})
+        args += %W(-p #{options[:pass]}) if options.key?(:pass)
+        args += %W(#{URI.parse(options[:endpoint]).host}:#{@rdp_port})
+        LoginCommand.new('rdesktop', args)
+      end
+
+      # Builds a `LoginCommand` for use by Mac-based platforms.
+      #
+      # @return [LoginCommand] a login command
+      # @api private
+      def login_command_for_mac
+        LoginCommand.new('open', rdp_doc(mac: true))
+      end
+
+      # Builds a `LoginCommand` for use by Windows-based platforms.
+      #
+      # @return [LoginCommand] a login command
+      # @api private
+      def login_command_for_windows
+        LoginCommand.new('mstsc', rdp_doc)
+      end
+
+      # Establishes a remote shell session, or establishes one when invoked
+      # the first time.
+      #
+      # @param retry_options [Hash] retry options for the initial connection
+      # @return [Winrm::CommandExecutor] the command executor session
+      # @api private
+      def session(retry_options = {})
+        @session ||= begin
+          opts = {
+            retry_limit: @connection_retries.to_i,
+            retry_delay: @connection_retry_sleep.to_i,
+          }.merge(retry_options)
+
+          opts[:operation_timeout] = @operation_timeout unless @operation_timeout.nil?
+          @service = ::WinRM::Connection.new(options.merge(opts))
+          @service.logger = logger
+          @service.shell(:powershell)
+        end
+      end
+
+      # String representation of object, reporting its connection details and
+      # configuration.
+      #
+      # @api private
+      def to_s
+        options_to_print = @options.clone
+        options_to_print[:password] = '<hidden>' if options_to_print.key?(:password)
+        "#{@username}@#{@hostname}<#{options_to_print.inspect}>"
+      end
+    end
+  end
+end

data/lib/train-winrm/transport.rb

@@ -0,0 +1,216 @@
+# encoding: utf-8
+
+#
+# Author:: Salim Afiune (<salim@afiunemaya.com.mx>)
+# Author:: Matt Wrock (<matt@mattwrock.com>)
+# Author:: Fletcher Nichol (<fnichol@nichol.ca>)
+# Author:: Dominik Richter (<dominik.richter@gmail.com>)
+# Author:: Christoph Hartmann (<chris@lollyrock.com>)
+#
+# Copyright (C) 2014, Salim Afiune
+#
+# 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.
+
+require 'rbconfig'
+require 'uri'
+require 'train'
+require 'train/errors'
+require 'train/plugins'
+
+# Train Plugins v1 are usually declared under the TrainPlugins namespace.
+# Each plugin has three components: Transport, Connection, and (optionally) Platform.
+# We'll only define the Transport here, but we'll refer to the others.
+
+module TrainPlugins
+  module WinRM
+    # Wrapped exception for any internally raised WinRM-related errors.
+    #
+    # @author Fletcher Nichol <fnichol@nichol.ca>
+    class WinRMFailed < Train::TransportError; end
+
+    # A Transport which uses WinRM to execute commands and transfer files.
+    #
+    # @author Matt Wrock <matt@mattwrock.com>
+    # @author Salim Afiune <salim@afiunemaya.com.mx>
+    # @author Fletcher Nichol <fnichol@nichol.ca>
+    class Transport < Train.plugin(1) # rubocop:disable Metrics/ClassLength
+      name 'winrm'
+
+      require 'train-winrm/connection'
+
+      # ref: https://github.com/winrb/winrm#transports
+      SUPPORTED_WINRM_TRANSPORTS = %i(negotiate ssl plaintext kerberos).freeze
+
+      # common target configuration
+      option :host, required: true
+      option :port
+      option :user, default: 'administrator', required: true
+      option :password, nil
+      option :winrm_transport, default: :negotiate
+      option :winrm_disable_sspi, default: false
+      option :winrm_basic_auth_only, default: false
+      option :path, default: '/wsman'
+      option :ssl, default: false
+      option :self_signed, default: false
+
+      # additional winrm options
+      option :rdp_port, default: 3389
+      option :connection_retries, default: 5
+      option :connection_retry_sleep, default: 1
+      option :max_wait_until_ready, default: 600
+      option :ssl_peer_fingerprint, default: nil
+      option :kerberos_realm, default: nil
+      option :kerberos_service, default: nil
+      option :ca_trust_file, default: nil
+      # The amount of time in SECONDS for which each operation must get an ack
+      # from the winrm endpoint. Does not mean that the command has
+      # completed in this time, only that the server has ack'd the request.
+      option :operation_timeout, default: nil
+
+      def initialize(opts)
+        super(opts)
+        load_needed_dependencies!
+      end
+
+      # (see Base#connection)
+      def connection(state = nil, &block)
+        opts = merge_options(options, state || {})
+        validate_options(opts)
+        conn_opts = connection_options(opts)
+
+        if @connection && @connection_options == conn_opts
+          reuse_connection(&block)
+        else
+          create_new_connection(conn_opts, &block)
+        end
+      end
+
+      private
+
+      def validate_options(opts)
+        super(opts)
+
+        # set scheme and port based on ssl activation
+        scheme = opts[:ssl] ? 'https' : 'http'
+        port = opts[:port]
+        port = (opts[:ssl] ? 5986 : 5985) if port.nil?
+        winrm_transport = opts[:winrm_transport].to_sym
+        unless SUPPORTED_WINRM_TRANSPORTS.include?(winrm_transport)
+          fail Train::ClientError, "Unsupported transport type: #{winrm_transport.inspect}"
+        end
+
+        # remove leading '/'
+        path = (opts[:path] || '').sub(%r{^/+}, '')
+
+        opts[:endpoint] = "#{scheme}://#{opts[:host]}:#{port}/#{path}"
+      end
+
+      WINRM_FS_SPEC_VERSION = '~> 1.0'.freeze
+
+      # Builds the hash of options needed by the Connection object on
+      # construction.
+      #
+      # @param data [Hash] merged configuration and mutable state data
+      # @return [Hash] hash of connection options
+      # @api private
+      def connection_options(opts)
+        {
+          logger:                   logger,
+          transport:                opts[:winrm_transport].to_sym,
+          disable_sspi:             opts[:winrm_disable_sspi],
+          basic_auth_only:          opts[:winrm_basic_auth_only],
+          hostname:                 opts[:host],
+          endpoint:                 opts[:endpoint],
+          user:                     opts[:user],
+          password:                 opts[:password],
+          rdp_port:                 opts[:rdp_port],
+          connection_retries:       opts[:connection_retries],
+          connection_retry_sleep:   opts[:connection_retry_sleep],
+          max_wait_until_ready:     opts[:max_wait_until_ready],
+          no_ssl_peer_verification: opts[:self_signed],
+          realm:                    opts[:kerberos_realm],
+          service:                  opts[:kerberos_service],
+          ca_trust_file:            opts[:ca_trust_file],
+          ssl_peer_fingerprint:     opts[:ssl_peer_fingerprint],
+        }
+      end
+
+      # Creates a new WinRM Connection instance and save it for potential
+      # future reuse.
+      #
+      # @param options [Hash] conneciton options
+      # @return [WinRM::Connection] a WinRM Connection instance
+      # @api private
+      def create_new_connection(options, &block)
+        if @connection
+          logger.debug("[WinRM] shutting previous connection #{@connection}")
+          @connection.close
+        end
+
+        @connection_options = options
+        @connection = Connection.new(options, &block)
+      end
+
+      # (see Base#load_needed_dependencies!)
+      def load_needed_dependencies!
+        spec_version = WINRM_FS_SPEC_VERSION.dup
+        logger.debug('winrm-fs requested,' \
+          " loading WinRM::FS gem (#{spec_version})")
+        gem 'winrm-fs', spec_version
+        first_load = require 'winrm-fs'
+        load_winrm_transport!
+
+        if first_load
+          logger.debug('WinRM::FS library loaded')
+        else
+          logger.debug('WinRM::FS previously loaded')
+        end
+      rescue LoadError => e
+        logger.fatal(
+          "The `winrm-fs' gem is missing and must" \
+          ' be installed or cannot be properly activated. Run' \
+          " `gem install winrm-fs --version '#{spec_version}'`" \
+          ' or add the following to your Gemfile if you are using Bundler:' \
+          " `gem 'winrm-fs', '#{spec_version}'`.",
+        )
+        raise Train::UserError,
+              "Could not load or activate WinRM::FS (#{e.message})"
+      end
+
+      # Load WinRM::Transport code.
+      #
+      # @api private
+      def load_winrm_transport!
+        silence_warnings { require 'winrm-fs' }
+      end
+
+      # Return the last saved WinRM connection instance.
+      #
+      # @return [Winrm::Connection] a WinRM Connection instance
+      # @api private
+      def reuse_connection
+        logger.debug("[WinRM] reusing existing connection #{@connection}")
+        yield @connection if block_given?
+        @connection
+      end
+
+      def silence_warnings
+        old_verbose = $VERBOSE
+        $VERBOSE = nil
+        yield
+      ensure
+        $VERBOSE = old_verbose
+      end
+    end
+  end
+end

data/lib/train-winrm/version.rb

@@ -0,0 +1,10 @@
+# This file exists simply to record the version number of the plugin.
+# It is kept in a separate file, so that your gemspec can load it and
+# learn the current version without loading the whole plugin.  Also,
+# many CI servers can update this file when "version bumping".
+
+module TrainPlugins
+  module WinRM
+    VERSION = '0.1.0'.freeze
+  end
+end

data/train-winrm.gemspec

@@ -0,0 +1,45 @@
+# 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 'train-winrm/version'
+
+Gem::Specification.new do |spec|
+  # Importantly, all Train plugins must be prefixed with `train-`
+  spec.name = 'train-winrm'
+
+  # It is polite to namespace your plugin under InspecPlugins::YourPluginInCamelCase
+  spec.version       = TrainPlugins::WinRM::VERSION
+  spec.authors       = ['Chef InSpec Team']
+  spec.email         = ['inspec@chef.io']
+  spec.summary       = 'Windows WinRM API Transport for Train'
+  spec.description   = 'Allows applictaions using Train to speak to Windows using Remote Management; handles authentication, cacheing, and SDK dependency management.'
+  spec.homepage      = 'https://github.com/inspec/train-winrm'
+  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 train-winrm.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.
+
+  # If you only need certain gems during development or testing, list
+  # them in Gemfile, not here.
+
+  # Do not list inspec as a dependency of a train plugin.
+
+  spec.add_dependency 'train', '~> 2.0'
+  spec.add_dependency 'winrm', '~> 2.0'
+  spec.add_dependency 'winrm-fs', '~> 1.0'
+end

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: train-winrm
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chef InSpec Team
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-05-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: train
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: winrm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: winrm-fs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Allows applictaions using Train to speak to Windows using Remote Management;
+  handles authentication, cacheing, and SDK dependency management.
+email:
+- inspec@chef.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- README.md
+- lib/train-winrm.rb
+- lib/train-winrm/connection.rb
+- lib/train-winrm/transport.rb
+- lib/train-winrm/version.rb
+- train-winrm.gemspec
+homepage: https://github.com/inspec/train-winrm
+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: Windows WinRM API Transport for Train
+test_files: []