train-winrm 0.1.0 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 12bed665790e51bd23cbe569c27f6a93c0300e8c
-  data.tar.gz: 599a6d141eb447d549ca3b511c15929401dea19d
+SHA256:
+  metadata.gz: 8bedb30ef9245e5953c85b86be962be97d177335bdc3ec5714f5eb4a3a83e407
+  data.tar.gz: 4a0beebeea34e8db4b989beac547d67d88cf57b915ae372d6ccf48689c1b74c3
 SHA512:
-  metadata.gz: b12889e4dc8845c34c911e3856213eee6a8993d1d1e93488bd838a0ff0421722cba9256641b3c23bda1a7df9982e5c0ed3fdd805ee787f161edf57e34129f5a6
-  data.tar.gz: 82873a1ed8096c63b6c56f8a8acf0981168429af31fcb63f421af272664d8822142f7fab0e7627d6aa413f1639201c84c8e91b076f1cd7cd551c88d0d38cef37
+  metadata.gz: 07d7e9550cf28e75d4f7c16fc266ccdb7a4a81d16438554fc6a6bb964dddd8a4cac4fea13efeb3551dfea2cab3bf148c86f20af982b7b5caa10ee59aabf382da
+  data.tar.gz: 79ef8219d7655d87cb58706c037dae54e6b67063d2b20b4bce459148c27a9f91d35beb8afb7185b91c4deb8020d492b4947cec302595703341b0ab39ee285352

data/Gemfile

@@ -1,6 +1,6 @@
 # encoding: utf-8
 
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
 # This is a Gemfile, which is used by bundler
 # to ensure a coherent set of gems is installed.
@@ -12,12 +12,15 @@ 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
+  # Depend on this here, not in the gemspec - to avoid having to have
+  # client applications induce circular dependencies
+  gem "train-core", "~> 3.0"
+  gem "bundler"
+  gem "byebug"
+  gem "m"
+  gem "minitest"
+  gem "mocha"
+  gem "pry"
+  gem "rake"
+  gem "chefstyle"
 end

data/README.md

@@ -1,8 +1,12 @@
 # train-winrm - Train Plugin for connecting to Windows via Remote Management
 
+* **Project State: Active**
+* **Issues Response SLA: 3 business days**
+* **Pull Request Response SLA: 3 business days**
+
 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
+This plugin relies on the `winrm` and `winrm-fs` gems for implementation.
 
 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.
 
@@ -10,6 +14,12 @@ Train plugins may be developed without a Chef InSpec installation.
 
 ## To Install this as a User
 
+### ChefDK Installation
+
+After August 2019, this plugin will be distributed with ChefDK; you do not need to install it separately.
+
+### Manual Installation using `inspec plugin install`
+
 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.
@@ -20,15 +30,53 @@ Simply run:
 $ inspec plugin install train-winrm
 ```
 
-You can then run:
+You can then run, using Chef InSpec as an example:
+
+```
+you@home $ inspec some-profile winrm://someuser@somehost --password somepassword
+```
 
+From Ruby code, you may use this plugin as follows:
 ```
-TODO - example
+require 'train'
+transport = Train.create(
+  'winrm',
+  host: '1.2.3.4',
+  user: 'Administrator',
+  password: '...',
+  ssl: true,
+  self_signed: true
+)
+conn = transport.connection
 ```
 
 ## Target Options for Train-WinRM
 
-TODO
+### host
+
+Required `String`. The hostname or IP address used for connection.
+
+#### port
+
+Optional `Integer`, default 5985 (plain) or 5896 (SSL). The port number to which the connection should be made.
+
+### user
+
+Optional `String`, username used for sign in.  Default `Administrator`.
+
+### password
+
+Optional `String`, password used for sign in. None sent if not provided.
+
+### ssl
+
+Optional `Boolean`. Defaults to `false`. Determines whether to use SSL to encrypt communications.
+
+Several other options exist. To see these options, run:
+
+```
+puts Train.options('winrm')
+```
 
 ## Reporting Issues
 
@@ -46,6 +94,12 @@ If you wish to contribute to this plugin, please use the usual fork-branch-push-
 
 [Plugin Development](https://github.com/inspec/train/blob/master/docs/dev/plugins.md) is documented on the `train` project on GitHub.
 
+### Unit tests
+
+Run `bundle exec rake test:unit` to run the unit tests.
+
 ### Testing changes against a Windows Machine
 
-TODO
+Install Vagrant and VirtualBox. Check the Vagrantfile to verify that it references a Windows 2016 evaluation VagrantBox to which you have access.
+
+Then, run `bundle exec rake test:integration`. There are sub-tasks you can use to run only the integration tests; to see a list of all tasks, run `rake -aT`.

data/lib/train-winrm.rb

@@ -12,9 +12,9 @@ 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'
+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'
+require "train-winrm/transport"
+require "train-winrm/connection"

data/lib/train-winrm/connection.rb

@@ -33,8 +33,8 @@
 # * marshalling to / from JSON
 # You don't have to worry about most of this.
 
-require 'train'
-require 'train/plugins'
+require "train"
+require "train/plugins"
 
 module TrainPlugins
   module WinRM
@@ -54,6 +54,7 @@ module TrainPlugins
       # (see Base::Connection#close)
       def close
         return if @session.nil?
+
         session.close
       ensure
         @session = nil
@@ -61,7 +62,7 @@ module TrainPlugins
 
       # (see Base::Connection#login_command)
       def login_command
-        case RbConfig::CONFIG['host_os']
+        case RbConfig::CONFIG["host_os"]
         when /darwin/
           login_command_for_mac
         when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
@@ -69,9 +70,9 @@ module TrainPlugins
         when /linux/
           login_command_for_linux
         else
-          fail ActionFailed,
-               "Remote login not supported in #{self.class} " \
-               "from host OS '#{RbConfig::CONFIG['host_os']}'."
+          raise ActionFailed,
+            "Remote login not supported in #{self.class} " \
+            "from host OS '#{RbConfig::CONFIG["host_os"]}'."
         end
       end
 
@@ -91,7 +92,7 @@ module TrainPlugins
         delay = 3
         session(
           retry_limit: @max_wait_until_ready / delay,
-          retry_delay: delay,
+          retry_delay: delay
         )
         run_command_via_connection(PING_COMMAND.dup)
       end
@@ -110,8 +111,9 @@ module TrainPlugins
 
       def run_command_via_connection(command, &data_handler)
         return if command.nil?
+
         logger.debug("[WinRM] #{self} (#{command})")
-        out = ''
+        out = ""
 
         response = session.run(command) do |stdout, _|
           yield(stdout) if data_handler && stdout
@@ -131,7 +133,7 @@ module TrainPlugins
         host = URI.parse(options[:endpoint]).host
         content = [
           "full address:s:#{host}:#{@rdp_port}",
-          'prompt for credentials:i:1',
+          "prompt for credentials:i:1",
           "username:s:#{options[:user]}",
         ].join("\n")
 
@@ -157,10 +159,10 @@ module TrainPlugins
       # @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)
+        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.
@@ -168,7 +170,7 @@ module TrainPlugins
       # @return [LoginCommand] a login command
       # @api private
       def login_command_for_mac
-        LoginCommand.new('open', rdp_doc(mac: true))
+        LoginCommand.new("open", rdp_doc(mac: true))
       end
 
       # Builds a `LoginCommand` for use by Windows-based platforms.
@@ -176,7 +178,7 @@ module TrainPlugins
       # @return [LoginCommand] a login command
       # @api private
       def login_command_for_windows
-        LoginCommand.new('mstsc', rdp_doc)
+        LoginCommand.new("mstsc", rdp_doc)
       end
 
       # Establishes a remote shell session, or establishes one when invoked
@@ -205,7 +207,7 @@ module TrainPlugins
       # @api private
       def to_s
         options_to_print = @options.clone
-        options_to_print[:password] = '<hidden>' if options_to_print.key?(:password)
+        options_to_print[:password] = "<hidden>" if options_to_print.key?(:password)
         "#{@username}@#{@hostname}<#{options_to_print.inspect}>"
       end
     end

data/lib/train-winrm/transport.rb

@@ -21,11 +21,11 @@
 # 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'
+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.
@@ -44,22 +44,22 @@ module TrainPlugins
     # @author Salim Afiune <salim@afiunemaya.com.mx>
     # @author Fletcher Nichol <fnichol@nichol.ca>
     class Transport < Train.plugin(1) # rubocop:disable Metrics/ClassLength
-      name 'winrm'
+      name "winrm"
 
-      require 'train-winrm/connection'
+      require "train-winrm/connection"
 
       # ref: https://github.com/winrb/winrm#transports
-      SUPPORTED_WINRM_TRANSPORTS = %i(negotiate ssl plaintext kerberos).freeze
+      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 :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 :path, default: "/wsman"
       option :ssl, default: false
       option :self_signed, default: false
 
@@ -101,21 +101,21 @@ module TrainPlugins
         super(opts)
 
         # set scheme and port based on ssl activation
-        scheme = opts[:ssl] ? 'https' : 'http'
+        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}"
+          raise Train::ClientError, "Unsupported transport type: #{winrm_transport.inspect}"
         end
 
         # remove leading '/'
-        path = (opts[:path] || '').sub(%r{^/+}, '')
+        path = (opts[:path] || "").sub(%r{^/+}, "")
 
         opts[:endpoint] = "#{scheme}://#{opts[:host]}:#{port}/#{path}"
       end
 
-      WINRM_FS_SPEC_VERSION = '~> 1.0'.freeze
+      WINRM_FS_SPEC_VERSION = "~> 1.0".freeze
 
       # Builds the hash of options needed by the Connection object on
       # construction.
@@ -125,23 +125,23 @@ module TrainPlugins
       # @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],
+          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],
+          realm: opts[:kerberos_realm],
+          service: opts[:kerberos_service],
+          ca_trust_file: opts[:ca_trust_file],
+          ssl_peer_fingerprint: opts[:ssl_peer_fingerprint],
         }
       end
 
@@ -164,34 +164,34 @@ module TrainPlugins
       # (see Base#load_needed_dependencies!)
       def load_needed_dependencies!
         spec_version = WINRM_FS_SPEC_VERSION.dup
-        logger.debug('winrm-fs requested,' \
+        logger.debug("winrm-fs requested," \
           " loading WinRM::FS gem (#{spec_version})")
-        gem 'winrm-fs', spec_version
-        first_load = require 'winrm-fs'
+        gem "winrm-fs", spec_version
+        first_load = require "winrm-fs"
         load_winrm_transport!
 
         if first_load
-          logger.debug('WinRM::FS library loaded')
+          logger.debug("WinRM::FS library loaded")
         else
-          logger.debug('WinRM::FS previously loaded')
+          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' \
+          " 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}'`.",
+          " 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})"
+          "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' }
+        silence_warnings { require "winrm-fs" }
       end
 
       # Return the last saved WinRM connection instance.

data/lib/train-winrm/version.rb

@@ -5,6 +5,6 @@
 
 module TrainPlugins
   module WinRM
-    VERSION = '0.1.0'.freeze
+    VERSION = "0.2.3".freeze
   end
 end

data/train-winrm.gemspec

@@ -4,22 +4,22 @@
 
 # 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__)
+lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'train-winrm/version'
+require "train-winrm/version"
 
 Gem::Specification.new do |spec|
   # Importantly, all Train plugins must be prefixed with `train-`
-  spec.name = 'train-winrm'
+  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'
+  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
@@ -27,9 +27,9 @@ Gem::Specification.new do |spec|
   spec.files = %w{
     README.md train-winrm.gemspec Gemfile
   } + Dir.glob(
-    'lib/**/*', File::FNM_DOTMATCH
+    "lib/**/*", File::FNM_DOTMATCH
   ).reject { |f| File.directory?(f) }
-  spec.require_paths = ['lib']
+  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.
@@ -38,8 +38,7 @@ Gem::Specification.new do |spec|
   # 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'
+  # Do not list train or train-core as a dependency of a train plugin.
+  spec.add_dependency "winrm", "~> 2.0"
+  spec.add_dependency "winrm-fs", "~> 1.0"
 end

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: train-winrm
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.3
 platform: ruby
 authors:
 - Chef InSpec Team
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-05-09 00:00:00.000000000 Z
+date: 2019-08-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
@@ -86,8 +72,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.14.3
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Windows WinRM API Transport for Train