beaker-windows 0.6.2

data/Rakefile

@@ -0,0 +1,13 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+
+task :default do
+  system 'rake --tasks'
+end
+
+desc "Run spec tests"
+RSpec::Core::RakeTask.new(:test) do |t|
+  t.rspec_opts = ['--color']
+  t.pattern = 'spec/'
+end

data/lib/beaker-windows.rb

@@ -0,0 +1,12 @@
+%w( path powershell registry windows_feature).each do |lib|
+  require "beaker-windows/#{lib}"
+end
+
+module Beaker
+  class TestCase
+    include BeakerWindows::Path
+    include BeakerWindows::Powershell
+    include BeakerWindows::Registry
+    include BeakerWindows::WindowsFeature
+  end
+end

data/lib/beaker-windows/path.rb

@@ -0,0 +1,111 @@
+module BeakerWindows
+  module Path
+
+    # Combine string containing paths with mixed separators. Coerce the path
+    # to Windows style automatically. (Configurable)
+    #
+    # ==== Attributes
+    #
+    # * +*paths+ - Two or more strings containing paths to be joined.
+    # * +opts+ - An options hash - not required
+    #   * +:path_sep+ - The desired path separator to use. (Default: "\")
+    #   * +:strip_drive+ - A boolean flag indicating of the drive letter should be stripped.
+    #
+    # ==== Returns
+    #
+    # +string+ - An absolute path to the manifests for an environment on the master host.
+    #
+    # ==== Raises
+    #
+    # +ArgumentError+ - Too few arguments.
+    #
+    # ==== Example
+    #
+    # join_path('c:\meow', 'cats/', 'bats\')
+    # join_path('c:\dog', 'bark', :strip_drive => true)
+    def join_path(*args)
+      # Init
+      opts = args.last.is_a?(Hash) ? args.pop : {}
+      opts[:path_sep] ||= "\\"
+      opts[:strip_drive] ||= false
+
+      combined_path = ''
+
+      # Verify that the user provided at least two paths to combine
+      raise(ArgumentError, "Too few arguments") if args.length < 2
+
+      # Combine the paths
+      args.each do |path|
+        # Verify that the provided args are strings
+        raise(ArgumentError, "Non-string provided as path") unless path.is_a?(String)
+
+        combined_path << opts[:path_sep].to_s unless combined_path.empty?
+        combined_path << path.gsub(/(\\|\/)/, opts[:path_sep].to_s)
+      end
+
+      # Remove duplicate path separators
+      combined_path.gsub!(/(\\|\/){2,}/, opts[:path_sep].to_s)
+
+      # Strip the drive letter if needed
+      combined_path.sub!(/^\w:/, '') if opts[:strip_drive]
+
+      return combined_path
+    end
+
+  end
+end
+
+module Beaker
+  module DSL
+    module Assertions
+
+      # Assert that a Windows file/registry path is valid on a host.
+      #
+      # ==== Attributes
+      #
+      # * +host+ - A Windows Beaker host running PowerShell.
+      # * +path+ - A path representing either a file system or registry path.
+      #     If asserting registry paths they must be perpended with the correct hive.
+      # * +path_type+ - The type of path expected.
+      #   * +:any+ - Can be a container or leaf. (Default)
+      #   * +:container+ - Path must be a file system folder or registry key.
+      #   * +:leaf+ - Path must be a file system file or registry value.
+      #
+      # ==== Raises
+      #
+      # +ArgumentError+ - An invalid path type specified.
+      # +Minitest::Assertion+ - Path does not exist or is the wrong type.
+      #
+      # ==== Example
+      #
+      # assert_win_path_on(host, 'C:\Windows')
+      # assert_win_path_on(host, 'C:\Windows\System32', :container)
+      # assert_win_path_on(host, 'C:\Windows\System32\kernel32.dll', :leaf)
+      # assert_win_path_on(host, 'HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion\SystemRoot')
+      def assert_win_path_on(host, path, path_type=:any)
+        # Init
+        ps_cmd = "Test-Path -Path '#{path}' -Type "
+
+        # Expected path type
+        case path_type
+          when :any
+            ps_cmd << 'Any'
+          when :container
+            ps_cmd << 'Container'
+          when :leaf
+            ps_cmd << 'Leaf'
+          else
+            raise(ArgumentError, 'An invalid path type specified!')
+        end
+
+        # Test path
+        result = on(host, exec_ps_cmd(ps_cmd,
+                                      :verify_cmd => true,
+                                      :EncodedCommand => true),
+                    :accept_all_exit_codes => true)
+        assert(0 == result.exit_code, 'Path does not exist or is the wrong type!')
+      end
+
+    end
+  end
+end

data/lib/beaker-windows/powershell.rb

@@ -0,0 +1,111 @@
+module BeakerWindows
+  module Powershell
+
+    # Executes a PowerShell command on a host. Allow validation of command execution and fail if
+    # PowerShell command throws an exception. Note: if quotes are required then the single quote
+    # should be preferred. If double quotes are required you will need to double escape the quotes!
+    #
+    # ==== Attributes
+    #
+    # * +command+ - The PowerShell command to execute on the host.
+    # * +opts+ - Either command-line options to pass to PowerShell or the following:
+    #   * +:excep_fail+ - Command will return exit code 1 if an exception is caught.
+    #     (Default: true)
+    #   * +:verify_cmd+ - Command will return exit code 1 if the outcome of the command
+    #     is "$false". (Default: false)
+    #   * +:EncodedCommand+ - Will encode the command in base64. Useful for commands
+    #      with nested quoting or containing Unicode characters. (Default: false)
+    #
+    # ==== Returns
+    #
+    # +Beaker::Command+ - An object for executing powershell commands on a host
+    #
+    # ==== Raises
+    #
+    # +nil+
+    #
+    # ==== Example
+    #
+    # on(hosts, exec_ps_cmd("Set-Content -path 'fu.txt' -value 'fu'"))
+    # on(hosts, exec_ps_cmd("Set-Content -path 'fu.txt' -value 'fu'", :ExecutionPolicy => 'Unrestricted')
+    # on(hosts, exec_ps_cmd("Set Content -path 'fu.txt', -value 'fu'", :EncodedCommand => true))
+    # on(hosts, exec_ps_cmd("1 -eq 2", :verify_cmd => true))
+    # on(hosts, exec_ps_cmd("does.not.exist", :excep_fail => true))
+    def exec_ps_cmd(command, opts={})
+      # Init
+      opts[:verify_cmd] ||= false
+      opts[:excep_fail] = true if opts[:excep_fail].nil?
+
+      ps_opts = {} # Command-line options to pass to PowerShell
+
+      # Determine how the command should be wrapped for execution
+      if opts[:verify_cmd]
+        command = "if ( #{command} ) { exit 0 } else { exit 1 }"
+      end
+
+      if opts[:excep_fail]
+        # Only prefix escape character if not encoded
+        var_accessor = opts[:EncodedCommand] ? '$_' : '\$_'
+
+        command = "try { #{command} } catch { Write-Host #{var_accessor}.Exception.Message; exit 1 }"
+      end
+
+      # Wrap the command in quotes when not encoded
+      command = "\"#{command}\"" unless opts[:EncodedCommand]
+
+      # Coerce all keys to be strings.
+      opts.each do |k, v|
+        ps_opts[k.to_s] = v unless (k == :verify_cmd) || (k == :excep_fail)
+      end
+
+      return powershell(command, ps_opts)
+    end
+
+    # Execute a PowerShell script on a remote machine. (This method support native Unicode)
+    # Note: This method fails on Windows 2008 R2! See BKR-293 for more details.
+    #
+    # ==== Attributes
+    #
+    # * +hosts+ - A Windows Beaker host(s) running PowerShell.
+    # * +ps_script+ - A PowerShell script to execute on the remote host.
+    #
+    # ==== Returns
+    #
+    # +Beaker::Result+
+    #
+    # ==== Raises
+    #
+    # +nil+
+    #
+    # ==== Examples
+    #
+    # exec_ps_script_on(host, 'Write-Host Hello')
+    def exec_ps_script_on(hosts, ps_script, &block)
+      #Init
+      script_path = "C:/Windows/Temp/beaker_powershell_script_#{Time.now.to_i}.ps1"
+      utf8_ps_script = "\xEF\xBB\xBF".force_encoding('UTF-8') + ps_script.force_encoding('UTF-8')
+
+      block_on(hosts) do |host|
+        #Create remote file with UTF-8 BOM
+        create_remote_file(host, script_path, utf8_ps_script)
+
+        #Execute PowerShell script on host
+        @result = on(host, powershell('', {'File' => script_path}), :accept_all_exit_codes => true)
+
+        #Also, let additional checking be performed by the caller.
+        if block_given?
+          case block.arity
+            #block with arity of 0, just hand back yourself
+            when 0
+              yield self
+            #block with arity of 1 or greater, hand back the result object
+            else
+              yield @result
+          end
+        end
+        @result
+      end
+    end
+
+  end
+end

data/lib/beaker-windows/registry.rb

@@ -0,0 +1,251 @@
+module BeakerWindows
+  module Registry
+
+    # Get the data from a registry value.
+    #
+    # ==== Attributes
+    #
+    # * +hive+ - A symbol representing the following hives:
+    #   * +:hklm+ - HKEY_LOCAL_MACHINE.
+    #   * +:hkcu+ - HKEY_CURRENT_USER.
+    #   * +:hku+ - HKEY_USERS.
+    #
+    # ==== Returns
+    #
+    # +String+ - A string representing the PowerShell hive path.
+    #
+    # ==== Raises
+    #
+    # +ArgumentError+ - Invalid registry hive specified!
+    #
+    # ==== Example
+    #
+    # get_registry_value_on(host, :hklm, "SOFTWARE\Microsoft\Windows NT\CurrentVersion", "SystemRoot")
+    def _get_hive(hive)
+      # Translate hives.
+      case hive
+        when :hklm
+          return "HKLM:\\"
+        when :hkcu
+          return "HKCU:\\"
+        when :hku
+          return "HKU:\\"
+        else
+          raise(ArgumentError, 'Invalid registry hive specified!')
+      end
+    end
+
+    # Get the data from a registry value.
+    #
+    # ==== Attributes
+    #
+    # * +host+ - A Windows Beaker host.
+    # * +hive+ - The hive containing the registry value. Allowed values:
+    #   * +:hklm+ - HKEY_LOCAL_MACHINE.
+    #   * +:hkcu+ - HKEY_CURRENT_USER.
+    #   * +:hku+ - HKEY_USERS.
+    # * +path+ - The key containing the desired registry value.
+    # * +value+ - The name of the registry value.
+    #
+    # ==== Returns
+    #
+    # +String+ - A string representing the registry value data. (Always returns a string
+    #    even for DWORD/QWORD and Binary value types.)
+    #
+    # ==== Raises
+    #
+    # +ArgumentError+ - Invalid registry hive specified!
+    # +RuntimeError+ - The specified key or path does not exist.
+    #
+    # ==== Example
+    #
+    # get_registry_value_on(host, :hklm, "SOFTWARE\Microsoft\Windows NT\CurrentVersion", "SystemRoot")
+    def get_registry_value_on(host, hive, path, value)
+      # Init
+      ps_cmd = "(Get-Item -Path '#{_get_hive(hive)}#{path}').GetValue('#{value}')"
+
+      # Parse output
+      result = on(host, exec_ps_cmd(ps_cmd, :EncodedCommand => true), :accept_all_exit_codes => true)
+
+      raise(RuntimeError, 'Registry path or value does not exist!') if result.exit_code == 1
+
+      return result.stdout.rstrip
+    end
+
+    # Create or update the data for a registry value.
+    #
+    # ==== Attributes
+    #
+    # * +host+ - A Windows Beaker host.
+    # * +hive+ - The hive containing the registry value. Allowed values:
+    #   * +:hklm+ - HKEY_LOCAL_MACHINE.
+    #   * +:hkcu+ - HKEY_CURRENT_USER.
+    #   * +:hku+ - HKEY_USERS.
+    # * +path+ - The key containing the desired registry value.
+    # * +value+ - The name of the registry value.
+    # * +data+ - The data for the specified registry value.
+    # * +data_type+ - The data type for the specified registry value:
+    #   * +:string+ - REG_SZ .
+    #   * +:multi+ - REG_MULTI_SZ.
+    #   * +:expand+ - REG_EXPAND_SZ.
+    #   * +:dword+ - REG_DWORD.
+    #   * +:qword+ - REG_QWORD.
+    #   * +:bin+ - REG_BINARY. This needs to be a string of comma-separated hex values.
+    #       (example: "be,ef,f0,0d")
+    #
+    # ==== Raises
+    #
+    # +ArgumentError+ - Invalid registry hive specified!
+    # +ArgumentError+ - Invalid format for binary data!
+    # +ArgumentError+ - Invalid data type specified!
+    # +RuntimeError+ - The specified key or path does not exist.
+    #
+    # ==== Example
+    #
+    # set_registry_value_on(host, :hkcu, 'SOFTWARE\test_key', 'string_value', 'test_data')
+    # set_registry_value_on(host, :hkcu, 'SOFTWARE\test_key', 'dword_value', 255, :dword)
+    # set_registry_value_on(host, :hkcu, 'SOFTWARE\test_key', 'bin_value', 'be,ef,f0,0d', :bin)
+    def set_registry_value_on(host, hive, path, value, data, data_type=:string)
+      # Init
+      ps_cmd = "New-ItemProperty -Force -Path '#{_get_hive(hive)}#{path}' -Name '#{value}'"
+
+      # Data type coercion.
+      case data_type
+        when :string
+          ps_cmd << " -Value '#{data.to_s}' -PropertyType String"
+        when :multi
+          ps_cmd << " -Value '#{data.to_s}' -PropertyType MultiString"
+        when :expand
+          ps_cmd << " -Value '#{data.to_s}' -PropertyType ExpandString"
+        when :dword
+          ps_cmd << " -Value #{data.to_s} -PropertyType DWord"
+        when :qword
+          ps_cmd << " -Value #{data.to_s} -PropertyType QWord"
+        when :bin
+          raise(ArgumentError, 'Invalid format for binary data!') unless data =~ /^(,?[\da-f]{2})+$/
+
+          hexified = ''
+          data.split(',').each do |hex|
+            hexified << ',' unless hexified.empty?
+            hexified << "0x#{hex}"
+          end
+
+          ps_cmd << " -Value ([byte[]](#{hexified})) -PropertyType Binary"
+        else
+          raise(ArgumentError, 'Invalid data type specified!')
+      end
+
+      # Parse output
+      result = on(host, exec_ps_cmd(ps_cmd, :EncodedCommand => true), :accept_all_exit_codes => true)
+
+      raise(RuntimeError, 'Registry path or value does not exist!') if result.exit_code == 1
+    end
+
+    # Remove a registry value.
+    #
+    # ==== Attributes
+    #
+    # * +host+ - A Windows Beaker host.
+    # * +hive+ - The hive containing the registry value. Allowed values:
+    #   * +:hklm+ - HKEY_LOCAL_MACHINE.
+    #   * +:hkcu+ - HKEY_CURRENT_USER.
+    #   * +:hku+ - HKEY_USERS.
+    # * +path+ - The key containing the desired registry value.
+    # * +value+ - The name of the registry value.
+    #
+    # ==== Returns
+    #
+    # +String+ - A string representing the registry value data. (Always returns a string
+    #    even for DWORD/QWORD and Binary value types.)
+    #
+    # ==== Raises
+    #
+    # +ArgumentError+ - Invalid registry hive specified!
+    # +RuntimeError+ - The specified key or path does not exist.
+    #
+    # ==== Example
+    #
+    # remove_registry_value_on(host, :hkcu, 'SOFTWARE\test_key', 'string_value')
+    def remove_registry_value_on(host, hive, path, value)
+      # Init
+      ps_cmd = "Remove-ItemProperty -Force -Path '#{_get_hive(hive)}#{path}' -Name '#{value}'"
+
+      # Parse output
+      result = on(host, exec_ps_cmd(ps_cmd, :EncodedCommand => true), :accept_all_exit_codes => true)
+
+      raise(RuntimeError, 'Registry path or value does not exist!') if result.exit_code == 1
+    end
+
+    # Create a new registry key. If the key already exists then this method will
+    # silently fail. This method will create parent intermediate parent keys if they
+    # do not exist.
+    #
+    # ==== Attributes
+    #
+    # * +host+ - A Windows Beaker host.
+    # * +hive+ - The hive containing the registry value. Allowed values:
+    #   * +:hklm+ - HKEY_LOCAL_MACHINE.
+    #   * +:hkcu+ - HKEY_CURRENT_USER.
+    #   * +:hku+ - HKEY_USERS.
+    # * +path+ - The path of the registry key to create.
+    #
+    # ==== Raises
+    #
+    # +ArgumentError+ - Invalid registry hive specified!
+    # +RuntimeError+ - The specified key or path does not exist.
+    #
+    # ==== Example
+    #
+    # new_registry_key_on(host, :hkcu, 'SOFTWARE\some_new_key')
+    def new_registry_key_on(host, hive, path)
+      # Init
+      ps_cmd = "New-Item -Force -Path '#{_get_hive(hive)}#{path}'"
+
+      # Parse output
+      result = on(host, exec_ps_cmd(ps_cmd, :EncodedCommand => true), :accept_all_exit_codes => true)
+
+      raise(RuntimeError, 'Registry path or value does not exist!') if result.exit_code == 1
+    end
+
+    # Remove a registry key. The method will not remove a registry key if the key contains
+    # nested subkeys and values. Use the "recurse" argument to force deletion of nested
+    # registry keys.
+    #
+    # ==== Attributes
+    #
+    # * +host+ - A Windows Beaker host.
+    # * +hive+ - The hive containing the registry value. Allowed values:
+    #   * +:hklm+ - HKEY_LOCAL_MACHINE.
+    #   * +:hkcu+ - HKEY_CURRENT_USER.
+    #   * +:hku+ - HKEY_USERS.
+    # * +path+ - The key containing the desired registry value.
+    # * +recurse+ - Recursively delete nested subkeys and values. (Default: false)
+    #
+    # ==== Returns
+    #
+    # +String+ - A string representing the registry value data. (Always returns a string
+    #    even for DWORD/QWORD and Binary value types.)
+    #
+    # ==== Raises
+    #
+    # +ArgumentError+ - Invalid registry hive specified!
+    # +RuntimeError+ - The specified key or path does not exist.
+    #
+    # ==== Example
+    #
+    # remove_registry_key_on(host, :hkcu, 'SOFTWARE\test_key')
+    def remove_registry_key_on(host, hive, path, recurse=false)
+      # Init
+      ps_cmd = "Remove-Item -Force -Path '#{_get_hive(hive)}#{path}'"
+
+      # Recursively delete key if requested
+      ps_cmd << " -Recurse" if recurse
+
+      # Parse output
+      result = on(host, exec_ps_cmd(ps_cmd, :EncodedCommand => true), :accept_all_exit_codes => true)
+
+      raise(RuntimeError, 'Registry path or value does not exist!') if result.exit_code == 1
+    end
+
+  end
+end