chef-powershell 1.0.0

data/chef-powershell.gemspec

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+bin = File.expand_path("bin", __dir__)
+$LOAD_PATH.unshift(bin) unless $LOAD_PATH.include?(bin)
+require "chef-powershell/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "chef-powershell"
+  spec.version       = ChefPowerShell::VERSION
+  spec.authors       = ["Chef Software, Inc"]
+  spec.email         = ["oss@chef.io"]
+
+  spec.summary       = %q{Extneral module for accessing and utilizing PowerShell}
+  spec.homepage      = "https://github.com/chef/chef/tree/main/chef-powershell"
+  spec.license       = "Apache-2.0"
+
+  spec.required_ruby_version = ">= 2.6"
+
+  spec.add_runtime_dependency "ffi"
+  spec.add_runtime_dependency "ffi-yajl"
+
+  spec.metadata = {
+    "bug_tracker_uri" => "https://github.com/chef/chef/issues",
+    "changelog_uri" => "https://github.com/chef/chef/blob/main/CHANGELOG.md",
+    "documentation_uri" => "https://github.com/chef/chef/tree/main/chef-powershell/README.md",
+    "homepage_uri" => "https://github.com/chef/chef/tree/main/chef-powershell",
+    "source_code_uri" => "https://github.com/chef/chef/tree/main/chef-powershell",
+  }
+
+  spec.require_paths = %w{lib bin}
+
+  #
+  # NOTE: DO NOT ADD RUNTIME DEPS TO OTHER CHEF ECOSYSTEM GEMS
+  # (e.g. chef, ohai, mixlib-anything, ffi-yajl, and IN PARTICULAR NOT chef-config)
+  #
+  # This is so that this set of common code can be reused in any other library without
+  # creating circular dependencies.  If you find yourself wanting to do that you probably
+  # have a helper that should go into the library you want to declare a dependency on,
+  # or you need to create another gem that is not this one.  You may also want to rub some
+  # dependency injection on your API to invert things so that you don't have to take
+  # a dependency on the thing you need (i.e. allow injecting a hash-like thing instead of taking
+  # a dep on mixlib-config and then require the consumer to wire up chef-config to your
+  # API).  Same for mixlib-log and Chef::Log in general.
+  #
+  # ABSOLUTELY NO EXCEPTIONS
+  #
+  spec.bindir        = "bin"
+  spec.executables   = []
+  spec.files = %w{Rakefile LICENSE} + Dir.glob("*.gemspec") +
+    Dir.glob("{lib,spec,bin}/**/*", File::FNM_DOTMATCH).reject { |f| File.directory?(f) }
+end

data/lib/chef-powershell/exceptions.rb

@@ -0,0 +1,27 @@
+#
+# Author:: John McCrae (<john.mccrae@progress.com>)
+# Copyright:: Copyright (c) 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.
+
+class Chef_PowerShell
+  class PowerShellExceptions
+    class PowerShellCommandFailed < RuntimeError; end
+
+    class JSON
+      class EncodeError < RuntimeError; end
+      class ParseError < RuntimeError; end
+    end
+  end
+end

data/lib/chef-powershell/json_compat.rb

@@ -0,0 +1,63 @@
+#
+# Author:: Tim Hinderliter (<tim@chef.io>)
+# Copyright:: Copyright (c) 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.
+
+# Wrapper class for interacting with JSON.
+
+autoload :FFI_Yajl, "ffi_yajl"
+require_relative "exceptions"
+# We're requiring this to prevent breaking consumers using Hash.to_json
+require "json" unless defined?(JSON)
+
+class Chef
+  class JSONCompat
+
+    class << self
+
+      def parse(source, opts = {})
+        FFI_Yajl::Parser.parse(source, opts)
+      rescue FFI_Yajl::ParseError => e
+        raise Chef::PowerShellExceptions::JSON::ParseError, e.message
+      end
+
+      def from_json(source, opts = {})
+        obj = parse(source, opts)
+
+        # JSON gem requires top level object to be a Hash or Array (otherwise
+        # you get the "must contain two octets" error). Yajl doesn't impose the
+        # same limitation. For compatibility, we re-impose this condition.
+        unless obj.is_a?(Hash) || obj.is_a?(Array)
+          raise Chef::PowerShellExceptions::JSON::ParseError, "Top level JSON object must be a Hash or Array. (actual: #{obj.class})"
+        end
+
+        obj
+      end
+
+      def to_json(obj, opts = nil)
+        FFI_Yajl::Encoder.encode(obj, opts)
+      rescue FFI_Yajl::EncodeError => e
+        raise Chef::PowerShellExceptions::JSON::EncodeError, e.message
+      end
+
+      def to_json_pretty(obj, opts = nil)
+        options_map = { pretty: true }
+        options_map[:indent] = opts[:indent] if opts.respond_to?(:key?) && opts.key?(:indent)
+        to_json(obj, options_map).chomp
+      end
+
+    end
+  end
+end

data/lib/chef-powershell/powershell.rb

@@ -0,0 +1,86 @@
+#
+# Author:: Stuart Preston (<stuart@chef.io>)
+# Copyright:: Copyright (c) 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.
+
+require "ffi" unless defined?(FFI)
+require_relative "json_compat"
+require_relative "exceptions"
+require_relative "unicode"
+require "chef-powershell"
+
+class Chef_PowerShell
+  class PowerShell
+    extend FFI::Library
+
+    attr_reader :result
+    attr_reader :errors
+    attr_reader :verbose
+
+    # Run a command under PowerShell via FFI
+    # This implementation requires the managed dll and native wrapper to be in the library search
+    # path on Windows (i.e. c:\windows\system32 or in the same location as ruby.exe).
+    #
+    # Requires: .NET Framework 4.0 or higher on the target machine.
+    #
+    # @param script [String] script to run
+    # @return [Object] output
+    def initialize(script)
+      # This Powershell DLL source lives here: https://github.com/chef/chef-powershell-shim
+      # Every merge into that repo triggers a Habitat build and promotion. Running
+      # the rake :update_chef_exec_dll task in this (chef/chef) repo will pull down
+      # the built packages and copy the binaries to chef-powershell/bin/ruby_bin_folder. Bundle install
+      # ensures that the correct architecture binaries are installed into the path.
+      powershell_dll = Gem.loaded_specs["chef-powershell"].full_gem_path + "/bin/ruby_bin_folder/#{ENV["PROCESSOR_ARCHITECTURE"]}/Chef.PowerShell.Wrapper.dll"
+      @dll ||= powershell_dll
+      exec(script)
+    end
+
+    #
+    # Was there an error running the command
+    #
+    # @return [Boolean]
+    #
+    def error?
+      return true if errors.count > 0
+
+      false
+    end
+
+    #
+    # @raise [Chef::ChefPowerShell::CommandFailed] raise if the command failed
+    #
+    def error!
+      raise Chef_PowerShell::PowerShellExceptions::PowerShellCommandFailed, "Unexpected exit in PowerShell command: #{@errors}" if error?
+    end
+
+    # protected
+    private
+
+    def self.attach(dll, script)
+      ffi_lib dll
+      attach_function :execute_powershell, :ExecuteScript, [:string], :pointer
+    end
+
+    def exec(script)
+      self.class.attach(@dll, script)
+      execution = execute_powershell(script).read_utf16string
+      hashed_outcome = Chef::JSONCompat.parse(execution)
+      @result = Chef::JSONCompat.parse(hashed_outcome["result"])
+      @errors = hashed_outcome["errors"]
+      @verbose = hashed_outcome["verbose"]
+    end
+  end
+end

data/lib/chef-powershell/powershell_exec.rb

@@ -0,0 +1,132 @@
+#
+# Author:: Stuart Preston (<stuart@chef.io>)
+# Copyright:: Copyright (c) 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.
+
+require_relative "./powershell"
+require_relative "./pwsh"
+
+# The powershell_exec mixin provides in-process access to the PowerShell engine.
+#
+# powershell_exec is initialized with a string that should be set to the script
+# to run and also takes an optional interpreter argument which must be either
+# :powershell (Windows PowerShell which is the default) or :pwsh (PowerShell
+# Core). It will return a Chef::PowerShell object that provides 5 methods:
+#
+# .result - returns a hash representing the results returned by executing the
+#           PowerShell script block
+# .verbose - this is an array of string containing any messages written to the
+#           PowerShell verbose stream during execution
+# .errors - this is an array of string containing any messages written to the
+#           PowerShell error stream during execution
+# .error? - returns true if there were error messages written to the PowerShell
+#           error stream during execution
+# .error! - raise Chef::PowerShell::CommandFailed if there was an error
+#
+# Some examples of usage:
+#
+# > powershell_exec("(Get-Item c:\\windows\\system32\\w32time.dll).VersionInfo"
+#   ).result["FileVersion"]
+#  => "10.0.14393.0 (rs1_release.160715-1616)"
+#
+# > powershell_exec("(get-process ruby).Mainmodule").result["FileName"]
+#  => C:\\opscode\\chef\\embedded\\bin\\ruby.exe"
+#
+# > powershell_exec("$a = $true; $a").result
+#  => true
+#
+# > powershell_exec("$PSVersionTable", :pwsh).result["PSEdition"]
+#  => "Core"
+#
+# > powershell_exec("not-found").errors
+#  => ["ObjectNotFound: (not-found:String) [], CommandNotFoundException: The
+#  term 'not-found' is not recognized as the name of a cmdlet, function, script
+#  file, or operable program. Check the spelling of the name, or if a path was
+#  included, verify that the path is correct and try again. (at <ScriptBlock>,
+#   <No file>: line 1)"]
+#
+# > powershell_exec("not-found").error?
+#  => true
+#
+# > powershell_exec("get-item c:\\notfound -erroraction stop")
+# WIN32OLERuntimeError: (in OLE method `ExecuteScript': )
+#     OLE error code:80131501 in System.Management.Automation
+#       The running command stopped because the preference variable
+#       "ErrorActionPreference" or common parameter is set to Stop: Cannot find
+#       path 'C:\notfound' because it does not exist.
+#
+# *Why use this and not powershell_out?* Startup time to invoke the PowerShell
+# engine is much faster (over 7X faster in tests) than writing the PowerShell
+# to disk, shelling out to powershell.exe and retrieving the .stdout or .stderr
+# methods afterwards.  Additionally we are able to have a higher fidelity
+# conversation with PowerShell because we are now working with the objects that
+# are returned by the script, rather than having to parse the stdout of
+# powershell.exe to get a result.
+#
+# *How does this work?*  In .NET terms, when you run a PowerShell script block
+# through the engine, behind the scenes you get a Collection<PSObject> returned
+# and simply we are serializing this, adding any errors that were generated to
+# a custom JSON string transferred in memory to Ruby.  The easiest way to
+# develop for this approach is to imagine that the last thing that happens in
+# your PowerShell script block is "ConvertTo-Json".  That's exactly what we are
+# doing here behind the scenes.
+#
+# There are a handful of current limitations with this approach:
+# - Windows UAC elevation is controlled by the token assigned to the account
+#   that Ruby.exe is running under.
+# - Terminating errors will result in a WIN32OLERuntimeError and typically are
+#   handled as an exception.
+# - There are no return/error codes, as we are not shelling out to
+#   powershell.exe but calling a method inline, no errors codes are returned.
+# - There is no settable timeout on powershell_exec method execution.
+# - It is not possible to impersonate another user running powershell, the
+#   credentials of the user running Chef Client are used.
+#
+
+class Chef_PowerShell
+  module ChefPowerShell
+    module PowershellExec
+      # The Chef.PowerShell.Wrapper.dll file looks in the same folder as ruby.exe OR in the folder specified by the environment variable CHEF_POWERSHELL_BIN for other chef powershell dll's
+      # We don't want to move files around so we're setting the variable here to keep everything tidy.
+      file_path = Gem.loaded_specs["chef-powershell"].full_gem_path + "/bin/ruby_bin_folder/#{ENV["PROCESSOR_ARCHITECTURE"]}/"
+      ENV["CHEF_POWERSHELL_BIN"] = file_path
+      # Run a command under PowerShell via a managed (.NET) API.
+      #
+      # Requires: .NET Framework 4.0 or higher on the target machine.
+      #
+      # @param script [String] script to run
+      # @param interpreter [Symbol] the interpreter type, `:powershell` or `:pwsh`
+      # @return [Chef::PowerShell] output
+      def powershell_exec(script, interpreter = :powershell)
+        case interpreter
+        when :powershell
+          Chef_PowerShell::PowerShell.new(script)
+        when :pwsh
+          Chef_PowerShell::Pwsh.new(script)
+        else
+          raise ArgumentError, "Expected interpreter of :powershell or :pwsh"
+        end
+      end
+
+      # The same as the #powershell_exec method except this will raise
+      # Chef::PowerShell::CommandFailed if the command fails
+      def powershell_exec!(script, interpreter = :powershell)
+        cmd = powershell_exec(script, interpreter)
+        cmd.error!
+        cmd
+      end
+    end
+  end
+end

data/lib/chef-powershell/pwsh.rb

@@ -0,0 +1,70 @@
+#
+# Author:: Matt Wrock (<mwrock@chef.io>)
+# Copyright:: Copyright (c) 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.
+
+class Chef_PowerShell
+  class Pwsh < Chef_PowerShell::PowerShell
+    # Run a command under pwsh (powershell core) via FFI
+    # This implementation requires the managed dll, native wrapper and a
+    # published, self contained dotnet core directory tree to exist in the
+    # bindir directory.
+    #
+    # @param script [String] script to run
+    # @return [Object] output
+    def initialize(script)
+      @dll = Pwsh.dll
+      super
+    end
+
+    protected
+
+    def exec(script)
+      # Note that we need to override the location of the shared dotnet core library
+      # location. With most .net core applications, you can simply publish them as a
+      # "self-contained" application allowing consumers of the application to run them
+      # and use its own stand alone version of the .net core runtime. However because
+      # this is simply a dll and not an exe, it will look for the runtime in the shared
+      # .net core installation folder. By setting DOTNET_MULTILEVEL_LOOKUP to 0 we can
+      # override that folder's location with DOTNET_ROOT. To avoid the possibility of
+      # interfering with other .net core processes that might rely on the common shared
+      # location, we revert these variables after the script completes.
+      original_dml = ENV["DOTNET_MULTILEVEL_LOOKUP"]
+      original_dotnet_root = ENV["DOTNET_ROOT"]
+      original_dotnet_root_x86 = ENV["DOTNET_ROOT(x86)"]
+
+      ENV["DOTNET_MULTILEVEL_LOOKUP"] = "0"
+      ENV["DOTNET_ROOT"] = RbConfig::CONFIG["bindir"]
+      ENV["DOTNET_ROOT(x86)"] = RbConfig::CONFIG["bindir"]
+
+      super
+    ensure
+      ENV["DOTNET_MULTILEVEL_LOOKUP"] = original_dml
+      ENV["DOTNET_ROOT"] = original_dotnet_root
+      ENV["DOTNET_ROOT(x86)"] = original_dotnet_root_x86
+    end
+
+    def self.dll
+      # This Powershell DLL source lives here: https://github.com/chef/chef-powershell-shim
+      # Every merge into that repo triggers a Habitat build and promotion. Running
+      # the rake :update_chef_exec_dll task in this (chef/chef) repo will pull down
+      # the built packages and copy the binaries to distro/ruby_bin_folder. Bundle install
+      # ensures that the correct architecture binaries are installed into the path.
+      # Also note that the version of pwsh is determined by which assemblies the dll was
+      # built with. To update powershell, those dependencies must be bumped.
+      @dll ||= Dir.glob("#{RbConfig::CONFIG["bindir"]}/**/Chef.PowerShell.Wrapper.Core.dll").last
+    end
+  end
+end

data/lib/chef-powershell/unicode.rb

@@ -0,0 +1,56 @@
+#
+# Author:: John Keiser (<jkeiser@chef.io>)
+# Author:: Seth Chisamore (<schisamo@chef.io>)
+# Copyright:: Copyright (c) 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.
+#
+
+require_relative "wide_string"
+
+module FFI
+  class Pointer
+    include Chef::Mixin::WideString
+
+    def read_wstring(num_wchars = nil)
+      if num_wchars.nil?
+        # Find the length of the string
+        length = 0
+        last_char = nil
+        while last_char != "\000\000"
+          length += 1
+          last_char = get_bytes(0, length * 2)[-2..]
+        end
+
+        num_wchars = length
+      end
+
+      wide_to_utf8(get_bytes(0, num_wchars * 2))
+    end
+
+    def read_utf16string
+      offset = 0
+      offset += 2 while get_bytes(offset, 2) != "\x00\x00"
+      get_bytes(0, offset).force_encoding("utf-16le").encode("utf-8")
+    end
+  end
+end
+
+class String
+  include Chef::Mixin::WideString
+
+  def to_wstring
+    utf8_to_wide(self)
+  end
+end