train-core 1.4.4

data/lib/train/platforms/detect/uuid.rb

@@ -0,0 +1,34 @@
+# encoding: utf-8
+
+require 'digest/sha1'
+require 'securerandom'
+require 'json'
+
+module Train::Platforms::Detect
+  class UUID
+    include Train::Platforms::Detect::Helpers::OSCommon
+
+    def initialize(platform)
+      @platform = platform
+      @backend = @platform.backend
+    end
+
+    def find_or_create_uuid
+      # for api transports uuid is defined on the connection
+      if defined?(@backend.unique_identifier)
+        uuid_from_string(@backend.unique_identifier)
+      elsif @platform.unix?
+        unix_uuid
+      elsif @platform.windows?
+        windows_uuid
+      else
+        if @platform[:uuid_command]
+          result = @backend.run_command(@platform[:uuid_command])
+          return uuid_from_string(result.stdout.chomp) if result.exit_status.zero? && !result.stdout.empty?
+        end
+
+        raise 'Could not find platform uuid! Please set a uuid_command for your platform.'
+      end
+    end
+  end
+end

data/lib/train/platforms/family.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+
+module Train::Platforms
+  class Family
+    include Train::Platforms::Common
+    attr_accessor :children, :condition, :families, :name
+
+    def initialize(name, condition)
+      @name = name
+      @condition = condition
+      @families = {}
+      @children = {}
+      @detect = nil
+      @title = "#{name.to_s.capitalize} Family"
+
+      # add itself to the families list
+      Train::Platforms.families[@name.to_s] = self
+    end
+
+    def title(title = nil)
+      return @title if title.nil?
+      @title = title
+      self
+    end
+  end
+end

data/lib/train/platforms/platform.rb

@@ -0,0 +1,101 @@
+# encoding: utf-8
+
+module Train::Platforms
+  class Platform
+    include Train::Platforms::Common
+    attr_accessor :backend, :condition, :families, :family_hierarchy, :platform
+
+    def initialize(name, condition = {})
+      @name = name
+      @condition = condition
+      @families = {}
+      @family_hierarchy = []
+      @platform = {}
+      @detect = nil
+      @title = name.to_s.capitalize
+
+      # add itself to the platform list
+      Train::Platforms.list[name] = self
+    end
+
+    def direct_families
+      @families.collect { |k, _v| k.name }
+    end
+
+    def family
+      @platform[:family] || @family_hierarchy[0]
+    end
+
+    def name
+      # Override here incase a updated name was set
+      # during the detect logic
+      clean_name
+    end
+
+    def clean_name(force: false)
+      @cleaned_name = nil if force
+      @cleaned_name ||= begin
+                          name = (@platform[:name] || @name)
+                          name.downcase!.tr!(' ', '_') if name =~ /[A-Z ]/
+                          name
+                        end
+    end
+
+    def uuid
+      @uuid ||= Train::Platforms::Detect::UUID.new(self).find_or_create_uuid.downcase
+    end
+
+    # This is for backwords compatability with
+    # the current inspec os resource.
+    def[](name)
+      if respond_to?(name)
+        send(name)
+      else
+        'unknown'
+      end
+    end
+
+    def title(title = nil)
+      return @title if title.nil?
+      @title = title
+      self
+    end
+
+    def to_hash
+      @platform
+    end
+
+    # Add generic family? and platform methods to an existing platform
+    #
+    # This is done later to add any custom
+    # families/properties that were created
+    def add_platform_methods
+      # Redo clean name if there is a detect override
+      clean_name(force: true) unless @platform[:name].nil?
+
+      # Add in family methods
+      family_list = Train::Platforms.families
+      family_list.each_value do |k|
+        next if respond_to?(k.name + '?')
+        define_singleton_method(k.name + '?') do
+          family_hierarchy.include?(k.name)
+        end
+      end
+
+      # Helper methods for direct platform info
+      @platform.each_key do |m|
+        next if respond_to?(m)
+        define_singleton_method(m) do
+          @platform[m]
+        end
+      end
+
+      # Create method for name if its not already true
+      m = name + '?'
+      return if respond_to?(m)
+      define_singleton_method(m) do
+        true
+      end
+    end
+  end
+end

data/lib/train/plugins.rb

@@ -0,0 +1,40 @@
+# encoding: utf-8
+#
+# Author:: Dominik Richter (<dominik.richter@gmail.com>)
+# Author:: Christoph Hartmann (<chris@lollyrock.com>)
+
+require 'train/errors'
+
+module Train
+  class Plugins
+    require 'train/plugins/transport'
+
+    class << self
+      # Retrieve the current plugin registry, containing all plugin names
+      # and their transport handlers.
+      #
+      # @return [Hash] map with plugin names and plugins
+      def registry
+        @registry ||= {}
+      end
+    end
+  end
+
+  # Create a new plugin by inheriting from the class returned by this method.
+  # Create a versioned plugin by providing the transport layer plugin version
+  # to this method. It will then select the correct class to inherit from.
+  #
+  # The plugin version determins what methods will be available to your plugin.
+  #
+  # @param [Int] version = 1 the plugin version to use
+  # @return [Transport] the versioned transport base class
+  def self.plugin(version = 1)
+    if version != 1
+      fail ClientError,
+           'Only understand train plugin version 1. You are trying to '\
+           "initialize a train plugin #{version}, which is not supported "\
+           'in the current release of train.'
+    end
+    ::Train::Plugins::Transport
+  end
+end

data/lib/train/plugins/base_connection.rb

@@ -0,0 +1,169 @@
+# encoding: utf-8
+
+require 'train/errors'
+require 'train/extras'
+require 'train/file'
+require 'logger'
+
+class Train::Plugins::Transport
+  # A Connection instance can be generated and re-generated, given new
+  # connection details such as connection port, hostname, credentials, etc.
+  # This object is responsible for carrying out the actions on the remote
+  # host such as executing commands, transferring files, etc.
+  #
+  # @author Fletcher Nichol <fnichol@nichol.ca>
+  class BaseConnection
+    include Train::Extras
+
+    # Create a new Connection instance.
+    #
+    # @param options [Hash] connection options
+    # @yield [self] yields itself for block-style invocation
+    def initialize(options = nil)
+      @options = options || {}
+      @logger = @options.delete(:logger) || Logger.new(STDOUT)
+      Train::Platforms::Detect::Specifications::OS.load
+      Train::Platforms::Detect::Specifications::Api.load
+
+      # default caching options
+      @cache_enabled = {
+        file: true,
+        command: false,
+      }
+
+      @cache = {}
+      @cache_enabled.each_key do |type|
+        clear_cache(type)
+      end
+    end
+
+    def cache_enabled?(type)
+      @cache_enabled[type.to_sym]
+    end
+
+    # Enable caching types for Train. Currently we support
+    # :file and :command types
+    def enable_cache(type)
+      fail Train::UnknownCacheType, "#{type} is not a valid cache type" unless @cache_enabled.keys.include?(type.to_sym)
+      @cache_enabled[type.to_sym] = true
+    end
+
+    def disable_cache(type)
+      fail Train::UnknownCacheType, "#{type} is not a valid cache type" unless @cache_enabled.keys.include?(type.to_sym)
+      @cache_enabled[type.to_sym] = false
+      clear_cache(type.to_sym)
+    end
+
+    # Closes the session connection, if it is still active.
+    def close
+      # this method may be left unimplemented if that is applicable
+    end
+
+    def to_json
+      {
+        'files' => Hash[@cache[:file].map { |x, y| [x, y.to_json] }],
+      }
+    end
+
+    def load_json(j)
+      require 'train/transports/mock'
+      j['files'].each do |path, jf|
+        @cache[:file][path] = Train::Transports::Mock::Connection::File.from_json(jf)
+      end
+    end
+
+    # Is this a local transport?
+    def local?
+      false
+    end
+
+    def direct_platform(name, platform_details = nil)
+      plat = Train::Platforms.name(name)
+      plat.backend = self
+      plat.platform = platform_details unless platform_details.nil?
+      plat.family_hierarchy = family_hierarchy(plat).flatten
+      plat.add_platform_methods
+      plat
+    end
+
+    def family_hierarchy(plat)
+      plat.families.each_with_object([]) do |(k, _v), memo|
+        memo << k.name
+        memo << family_hierarchy(k) unless k.families.empty?
+      end
+    end
+
+    # Get information on the operating system which this transport connects to.
+    #
+    # @return [Platform] system information
+    def platform
+      @platform ||= Train::Platforms::Detect.scan(self)
+    end
+    # we need to keep os as a method for backwards compatibility with inspec
+    alias os platform
+
+    # This is the main command call for all connections. This will call the private
+    # run_command_via_connection on the connection with optional caching
+    def run_command(cmd)
+      return run_command_via_connection(cmd) unless cache_enabled?(:command)
+
+      @cache[:command][cmd] ||= run_command_via_connection(cmd)
+    end
+
+    # This is the main file call for all connections. This will call the private
+    # file_via_connection on the connection with optional caching
+    def file(path, *args)
+      return file_via_connection(path, *args) unless cache_enabled?(:file)
+
+      @cache[:file][path] ||= file_via_connection(path, *args)
+    end
+
+    # Builds a LoginCommand which can be used to open an interactive
+    # session on the remote host.
+    #
+    # @return [LoginCommand] array of command line tokens
+    def login_command
+      fail NotImplementedError, "#{self.class} does not implement #login_command()"
+    end
+
+    # Block and return only when the remote host is prepared and ready to
+    # execute command and upload files. The semantics and details will
+    # vary by implementation, but a round trip through the hosted
+    # service is preferred to simply waiting on a socket to become
+    # available.
+    def wait_until_ready
+      # this method may be left unimplemented if that is applicablelog
+    end
+
+    private
+
+    # Execute a command using this connection.
+    #
+    # @param command [String] command string to execute
+    # @return [CommandResult] contains the result of running the command
+    def run_command_via_connection(_command)
+      fail NotImplementedError, "#{self.class} does not implement #run_command_via_connection()"
+    end
+
+    # Interact with files on the target. Read, write, and get metadata
+    # from files via the transport.
+    #
+    # @param [String] path which is being inspected
+    # @return [FileCommon] file object that allows for interaction
+    def file_via_connection(_path, *_args)
+      fail NotImplementedError, "#{self.class} does not implement #file_via_connection(...)"
+    end
+
+    def clear_cache(type)
+      @cache[type.to_sym] = {}
+    end
+
+    # @return [Logger] logger for reporting information
+    # @api private
+    attr_reader :logger
+
+    # @return [Hash] connection options
+    # @api private
+    attr_reader :options
+  end
+end

data/lib/train/plugins/transport.rb

@@ -0,0 +1,49 @@
+# encoding: utf-8
+#
+# Author:: Dominik Richter (<dominik.richter@gmail.com>)
+# Author:: Christoph Hartmann (<chris@lollyrock.com>)
+
+require 'logger'
+require 'train/errors'
+require 'train/extras'
+require 'train/options'
+
+class Train::Plugins
+  class Transport
+    include Train::Extras
+    Train::Options.attach(self)
+
+    require 'train/plugins/base_connection'
+
+    # Initialize a new Transport object
+    #
+    # @param [Hash] config = nil the configuration for this transport
+    # @return [Transport] the transport object
+    def initialize(options = {})
+      @options = merge_options({}, options || {})
+      @logger = @options[:logger] || Logger.new(STDOUT)
+    end
+
+    # Create a connection to the target. Options may be provided
+    # for additional configuration.
+    #
+    # @param [Hash] _options = nil provide optional configuration params
+    # @return [Connection] the connection for this configuration
+    def connection(_options = nil)
+      fail Train::ClientError, "#{self.class} does not implement #connection()"
+    end
+
+    # Register the inheriting class with as a train plugin using the
+    # provided name.
+    #
+    # @param [String] name of the plugin, by which it will be found
+    def self.name(name)
+      Train::Plugins.registry[name] = self
+    end
+
+    private
+
+    # @return [Logger] logger for reporting information
+    attr_reader :logger
+  end
+end

data/lib/train/transports/local.rb

@@ -0,0 +1,232 @@
+# encoding: utf-8
+#
+# author: Dominik Richter
+# author: Christoph Hartmann
+
+require 'train/plugins'
+require 'train/errors'
+require 'mixlib/shellout'
+
+module Train::Transports
+  class Local < Train.plugin(1)
+    name 'local'
+
+    class PipeError < Train::TransportError; end
+
+    def connection(_ = nil)
+      @connection ||= Connection.new(@options)
+    end
+
+    class Connection < BaseConnection
+      def initialize(options)
+        super(options)
+
+        @runner = if options[:command_runner]
+                    force_runner(options[:command_runner])
+                  else
+                    select_runner(options)
+                  end
+      end
+
+      def local?
+        true
+      end
+
+      def login_command
+        nil # none, open your shell
+      end
+
+      def uri
+        'local://'
+      end
+
+      private
+
+      def select_runner(options)
+        if os.windows?
+          # Force a 64 bit poweshell if needed
+          if RUBY_PLATFORM == 'i386-mingw32' && os.arch == 'x86_64'
+            powershell_cmd = "#{ENV['SystemRoot']}\\sysnative\\WindowsPowerShell\\v1.0\\powershell.exe"
+          else
+            powershell_cmd = 'powershell'
+          end
+
+          # Attempt to use a named pipe but fallback to ShellOut if that fails
+          begin
+            WindowsPipeRunner.new(powershell_cmd)
+          rescue PipeError
+            WindowsShellRunner.new(powershell_cmd)
+          end
+        else
+          GenericRunner.new(self, options)
+        end
+      end
+
+      def force_runner(command_runner)
+        case command_runner
+        when :generic
+          GenericRunner.new(self, options)
+        when :windows_pipe
+          WindowsPipeRunner.new
+        when :windows_shell
+          WindowsShellRunner.new
+        else
+          fail "Runner type `#{command_runner}` not supported"
+        end
+      end
+
+      def run_command_via_connection(cmd)
+        # Use the runner if it is available
+        return @runner.run_command(cmd) if defined?(@runner)
+
+        # If we don't have a runner, such as at the beginning of setting up the
+        # transport and performing the first few steps of OS detection, fall
+        # back to shelling out.
+        res = Mixlib::ShellOut.new(cmd)
+        res.run_command
+        Local::CommandResult.new(res.stdout, res.stderr, res.exitstatus)
+      rescue Errno::ENOENT => _
+        CommandResult.new('', '', 1)
+      end
+
+      def file_via_connection(path)
+        if os.windows?
+          Train::File::Local::Windows.new(self, path)
+        else
+          Train::File::Local::Unix.new(self, path)
+        end
+      end
+
+      class GenericRunner
+        include_options Train::Extras::CommandWrapper
+
+        def initialize(connection, options)
+          @cmd_wrapper = Local::CommandWrapper.load(connection, options)
+        end
+
+        def run_command(cmd)
+          if defined?(@cmd_wrapper) && !@cmd_wrapper.nil?
+            cmd = @cmd_wrapper.run(cmd)
+          end
+
+          res = Mixlib::ShellOut.new(cmd)
+          res.run_command
+          Local::CommandResult.new(res.stdout, res.stderr, res.exitstatus)
+        end
+      end
+
+      class WindowsShellRunner
+        require 'json'
+        require 'base64'
+
+        def initialize(powershell_cmd = 'powershell')
+          @powershell_cmd = powershell_cmd
+        end
+
+        def run_command(script)
+          # Prevent progress stream from leaking into stderr
+          script = "$ProgressPreference='SilentlyContinue';" + script
+
+          # Encode script so PowerShell can use it
+          script = script.encode('UTF-16LE', 'UTF-8')
+          base64_script = Base64.strict_encode64(script)
+
+          cmd = "#{@powershell_cmd} -NoProfile -EncodedCommand #{base64_script}"
+
+          res = Mixlib::ShellOut.new(cmd)
+          res.run_command
+          Local::CommandResult.new(res.stdout, res.stderr, res.exitstatus)
+        end
+      end
+
+      class WindowsPipeRunner
+        require 'json'
+        require 'base64'
+        require 'securerandom'
+
+        def initialize(powershell_cmd = 'powershell')
+          @powershell_cmd = powershell_cmd
+          @pipe = acquire_pipe
+          fail PipeError if @pipe.nil?
+        end
+
+        def run_command(cmd)
+          script = "$ProgressPreference='SilentlyContinue';" + cmd
+          encoded_script = Base64.strict_encode64(script)
+          @pipe.puts(encoded_script)
+          @pipe.flush
+          res = OpenStruct.new(JSON.parse(Base64.decode64(@pipe.readline)))
+          Local::CommandResult.new(res.stdout, res.stderr, res.exitstatus)
+        end
+
+        private
+
+        def acquire_pipe
+          pipe_name = "inspec_#{SecureRandom.hex}"
+
+          start_pipe_server(pipe_name)
+
+          pipe = nil
+
+          # PowerShell needs time to create pipe.
+          100.times do
+            begin
+              pipe = open("//./pipe/#{pipe_name}", 'r+')
+              break
+            rescue
+              sleep 0.1
+            end
+          end
+
+          pipe
+        end
+
+        def start_pipe_server(pipe_name)
+          require 'win32/process'
+
+          script = <<-EOF
+            $ErrorActionPreference = 'Stop'
+
+            $pipeServer = New-Object System.IO.Pipes.NamedPipeServerStream('#{pipe_name}')
+            $pipeReader = New-Object System.IO.StreamReader($pipeServer)
+            $pipeWriter = New-Object System.IO.StreamWriter($pipeServer)
+
+            $pipeServer.WaitForConnection()
+
+            # Create loop to receive and process user commands/scripts
+            $clientConnected = $true
+            while($clientConnected) {
+              $input = $pipeReader.ReadLine()
+              $command = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($input))
+
+              # Execute user command/script and convert result to JSON
+              $scriptBlock = $ExecutionContext.InvokeCommand.NewScriptBlock($command)
+              try {
+                $stdout = & $scriptBlock | Out-String
+                $result = @{ 'stdout' = $stdout ; 'stderr' = ''; 'exitstatus' = 0 }
+              } catch {
+                $stderr = $_ | Out-String
+                $result = @{ 'stdout' = ''; 'stderr' = $_; 'exitstatus' = 1 }
+              }
+              $resultJSON = $result | ConvertTo-JSON
+
+              # Encode JSON in Base64 and write to pipe
+              $encodedResult = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($resultJSON))
+              $pipeWriter.WriteLine($encodedResult)
+              $pipeWriter.Flush()
+            }
+          EOF
+
+          utf8_script = script.encode('UTF-16LE', 'UTF-8')
+          base64_script = Base64.strict_encode64(utf8_script)
+          cmd = "#{@powershell_cmd} -NoProfile -ExecutionPolicy bypass -NonInteractive -EncodedCommand #{base64_script}"
+
+          server_pid = Process.create(command_line: cmd).process_id
+
+          # Ensure process is killed when the Train process exits
+          at_exit { Process.kill('KILL', server_pid) }
+        end
+      end
+    end
+  end
+end