winrm-elevated 0.4.0 → 1.0.0

data/README.md

@@ -1,82 +1,86 @@
-# Runs PowerShell commands as elevated over Windows Remote Management (WinRM) via a scheduled task
-[![Gem Version](https://badge.fury.io/rb/winrm-elevated.svg)](http://badge.fury.io/rb/winrm-elevated)
-
-This gem allows you to break out of the magical WinRM constraints thus allowing to reach out to network shares and even install Windows updates, .NET, SQL Server etc.
-
-## Running commands elevated
-```ruby
-require 'winrm'
-require 'winrm-elevated'
-
-service = WinRM::WinRMWebService.new(...
-service.create_executor do |executor|
-  elevated_runner = WinRM::Elevated::Runner.new(executor)
-  result = elevated_runner.powershell_elevated('dir', 'Administrator', 'password')
-  puts "Std out: #{result.output}"
-end
-```
-
-### Impersonating a service account
-By passing a `nil` password, winrm-elevated will assume that the command should run as a service account:
-```ruby
-require 'winrm'
-require 'winrm-elevated'
-
-service = WinRM::WinRMWebService.new(...
-service.create_executor do |executor|
-  elevated_runner = WinRM::Elevated::Runner.new(service)
-  result = elevated_runner.powershell_elevated('dir', 'System', nil)
-  puts "Std out: #{result.output}"
-end
-```
-
-## How does it work?
-
-The gem works by creating a new logon session local to the Windows box by using a scheduled task. After this point WinRM is just used to read output from the scheduled task via a log file.
-
-1. The command you'd like to run outside the WinRM context is encoded and placed inside the PowerShell script elevated_shell.ps1.
-2. The script is uploaded to the machine over WinRM.
-3. The script is executed over WinRM and the script does the following:
-  1. Scheduled task is created which will execute your command and redirect stdout and stderr to a location known by elevated_shell.ps1.
-  2. The scheduled task is executed.
-  3. elevated_shell.ps1 polls the stdout and stderr log files and writes them back to WinRM. The script continues in this loop until the scheduled task is complete.
-
-## Troubleshooting
-
-If you're having trouble, first of all its most likely a network or WinRM configuration
-issue. Take a look at the [WinRM gem troubleshooting](https://github.com/WinRb/WinRM#troubleshooting)
-first.
-
-## Contributing
-
-1. Fork it.
-2. Create a branch (git checkout -b my_feature_branch)
-3. Run the unit and integration tests (bundle exec rake integration)
-4. Commit your changes (git commit -am "Added a sweet feature")
-5. Push to the branch (git push origin my_feature_branch)
-6. Create a pull requst from your branch into master (Please be sure to provide enough detail for us to cipher what this change is doing)
-
-### Running the tests
-
-We use Bundler to manage dependencies during development.
-
-```
-$ bundle install
-```
-
-Once you have the dependencies, you can run the unit tests with `rake`:
-
-```
-$ bundle exec rake spec
-```
-
-To run the integration tests you will need a Windows box with the WinRM service properly configured. Its easiest to use the Vagrant Windows box in the Vagrantilfe of this repo.
-
-1. Create a Windows VM with WinRM configured (see above).
-2. Copy the config-example.yml to config.yml - edit this file with your WinRM connection details.
-3. Run `bundle exec rake integration`
-
-## WinRM-elevated Authors
-* Shawn Neal (https://github.com/sneal)
-
-[Contributors](https://github.com/WinRb/winrm-elevated/graphs/contributors)
+# Runs PowerShell commands as elevated over Windows Remote Management (WinRM) via a scheduled task
+[![Gem Version](https://badge.fury.io/rb/winrm-elevated.svg)](http://badge.fury.io/rb/winrm-elevated)
+
+This gem allows you to break out of the magical WinRM constraints thus allowing to reach out to network shares and even install Windows updates, .NET, SQL Server etc.
+
+## Running commands elevated
+```ruby
+require 'winrm'
+require 'winrm-elevated'
+
+conn = WinRM::Connection.new(...
+conn.shell(:elevated) do |shell|
+  shell.run('$PSVersionTable') do |stdout, stderr|
+    STDOUT.print stdout
+    STDERR.print stderr
+  end
+end
+```
+
+### Impersonating a service account
+By passing a `nil` password, winrm-elevated will assume that the command should run as a service account:
+```ruby
+require 'winrm'
+require 'winrm-elevated'
+
+conn = WinRM::Connection.new(...
+conn.shell(:elevated) do |shell|
+  shell.username = 'System'
+  shell.password = nil
+  shell.run('$PSVersionTable') do |stdout, stderr|
+    STDOUT.print stdout
+    STDERR.print stderr
+  end
+end
+```
+
+## How does it work?
+
+The gem works by creating a new logon session local to the Windows box by using a scheduled task. After this point WinRM is just used to read output from the scheduled task via a log file.
+
+1. The command you'd like to run outside the WinRM context is saved to a temporary file.
+2. This file is uploaded to the machine over WinRM.
+3. A script is executed over WinRM and does the following:
+  1. Scheduled task is created which will execute your command and redirect stdout and stderr to a location known by elevated_shell.ps1.
+  2. The scheduled task is executed.
+  3. elevated_shell.ps1 polls the stdout and stderr log files and writes them back to WinRM. The script continues in this loop until the scheduled task is complete.
+
+## Troubleshooting
+
+If you're having trouble, first of all its most likely a network or WinRM configuration
+issue. Take a look at the [WinRM gem troubleshooting](https://github.com/WinRb/WinRM#troubleshooting)
+first.
+
+## Contributing
+
+1. Fork it.
+2. Create a branch (git checkout -b my_feature_branch)
+3. Run the unit and integration tests (bundle exec rake integration)
+4. Commit your changes (git commit -am "Added a sweet feature")
+5. Push to the branch (git push origin my_feature_branch)
+6. Create a pull requst from your branch into master (Please be sure to provide enough detail for us to cipher what this change is doing)
+
+### Running the tests
+
+We use Bundler to manage dependencies during development.
+
+```
+$ bundle install
+```
+
+Once you have the dependencies, you can run the unit tests with `rake`:
+
+```
+$ bundle exec rake spec
+```
+
+To run the integration tests you will need a Windows box with the WinRM service properly configured. Its easiest to use the Vagrant Windows box in the Vagrantilfe of this repo.
+
+1. Create a Windows VM with WinRM configured (see above).
+2. Copy the config-example.yml to config.yml - edit this file with your WinRM connection details.
+3. Run `bundle exec rake integration`
+
+## WinRM-elevated Authors
+* Shawn Neal (https://github.com/sneal)
+
+[Contributors](https://github.com/WinRb/winrm-elevated/graphs/contributors)

data/Rakefile

@@ -1,28 +1,28 @@
-# encoding: UTF-8
-require 'rubygems'
-require 'bundler/setup'
-require 'rspec/core/rake_task'
-require 'rubocop/rake_task'
-require 'bundler/gem_tasks'
-
-# Change to the directory of this file.
-Dir.chdir(File.expand_path('../', __FILE__))
-
-RSpec::Core::RakeTask.new(:spec) do |task|
-  task.pattern = 'spec/*_spec.rb'
-  task.rspec_opts = ['--color', '-f documentation']
-  task.rspec_opts << '-tunit'
-end
-
-# Run the integration test suite
-RSpec::Core::RakeTask.new(:integration) do |task|
-  task.pattern = 'spec/*_spec.rb'
-  task.rspec_opts = ['--color', '-f documentation']
-  task.rspec_opts << '-tintegration'
-end
-
-RuboCop::RakeTask.new
-
-task default: [:spec, :rubocop]
-
-task all: [:default, :integration]
+# encoding: UTF-8
+require 'rubygems'
+require 'bundler/setup'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+require 'bundler/gem_tasks'
+
+# Change to the directory of this file.
+Dir.chdir(File.expand_path('../', __FILE__))
+
+RSpec::Core::RakeTask.new(:spec) do |task|
+  task.pattern = 'spec/*_spec.rb'
+  task.rspec_opts = ['--color', '-f documentation']
+  task.rspec_opts << '-tunit'
+end
+
+# Run the integration test suite
+RSpec::Core::RakeTask.new(:integration) do |task|
+  task.pattern = 'spec/*_spec.rb'
+  task.rspec_opts = ['--color', '-f documentation']
+  task.rspec_opts << '-tintegration'
+end
+
+RuboCop::RakeTask.new
+
+task default: [:spec, :rubocop]
+
+task all: [:default, :integration]

data/VERSION

@@ -1 +1 @@
-0.4.0
+1.0.0

data/appveyor.yml

@@ -1,39 +1,39 @@
-version: "master-{build}"
-
-os: Windows Server 2012 R2
-platform:
-  - x64
-
-environment:
-  winrm_user: test_user
-  winrm_pass: Pass@word1
-
-  matrix:
-    - ruby_version: "21"
-      winrm_endpoint: http://localhost:5985/wsman
-
-clone_folder: c:\projects\winrm-elevated
-clone_depth: 1
-branches:
-  only:
-    - master
-
-install:
-  - ps: net user /add $env:winrm_user $env:winrm_pass
-  - ps: net localgroup administrators $env:winrm_user /add
-  - ps: winrm set winrm/config/client/auth '@{Basic="true"}'
-  - ps: winrm set winrm/config/service/auth '@{Basic="true"}'
-  - ps: winrm set winrm/config/service '@{AllowUnencrypted="true"}'
-  - ps: $env:PATH="C:\Ruby$env:ruby_version\bin;$env:PATH"
-  - ps: Write-Host $env:PATH
-  - ps: ruby --version
-  - ps: gem --version
-  - ps: gem install bundler --quiet --no-ri --no-rdoc
-  - ps: bundler --version
-
-build_script:
-  - bundle install || bundle install || bundle install
-
-test_script:
-  - SET SPEC_OPTS=--format progress
-  - bundle exec rake integration
+version: "master-{build}"
+
+os: Windows Server 2012 R2
+platform:
+  - x64
+
+environment:
+  winrm_user: test_user
+  winrm_password: Pass@word1
+
+  matrix:
+    - ruby_version: "21"
+      winrm_endpoint: http://localhost:5985/wsman
+
+clone_folder: c:\projects\winrm-elevated
+clone_depth: 1
+branches:
+  only:
+    - master
+
+install:
+  - ps: net user /add $env:winrm_user $env:winrm_password
+  - ps: net localgroup administrators $env:winrm_user /add
+  - ps: winrm set winrm/config/client/auth '@{Basic="true"}'
+  - ps: winrm set winrm/config/service/auth '@{Basic="true"}'
+  - ps: winrm set winrm/config/service '@{AllowUnencrypted="true"}'
+  - ps: $env:PATH="C:\Ruby$env:ruby_version\bin;$env:PATH"
+  - ps: Write-Host $env:PATH
+  - ps: ruby --version
+  - ps: gem --version
+  - ps: gem install bundler --quiet --no-ri --no-rdoc
+  - ps: bundler --version
+
+build_script:
+  - bundle install || bundle install || bundle install
+
+test_script:
+  - SET SPEC_OPTS=--format progress
+  - bundle exec rake integration

data/changelog.md

@@ -1,18 +1,18 @@
-# WinRM-Elevated Gem Changelog
-
-# 0.4.0
-- Initialize `Elevated::Runner` with a `CommandExecutor` instead of a `WinrmService` client
-- Run commands from newer winrm executor
-- Use latest winrm-fs 0.4.2
-- Allow task to run as a service account
-- Provide an artificially long timeout to the task to keep the task from dying after 60 seconds
-
-# 0.3.0
-- [Name Powershell Script and Log Files Uniquely](https://github.com/WinRb/winrm-elevated/pull/6)
-
-# 0.2.0
-- [Only upload the elevated runner script once per winrm session](https://github.com/WinRb/winrm-elevated/pull/3)
-- Bump WinRM (1.5) and WinRM-fs (0.3.0) gem constraints
-
-# 0.1.0
-- Initial Release
+# WinRM-Elevated Gem Changelog
+
+# 0.4.0
+- Initialize `Elevated::Runner` with a `CommandExecutor` instead of a `WinrmService` client
+- Run commands from newer winrm executor
+- Use latest winrm-fs 0.4.2
+- Allow task to run as a service account
+- Provide an artificially long timeout to the task to keep the task from dying after 60 seconds
+
+# 0.3.0
+- [Name Powershell Script and Log Files Uniquely](https://github.com/WinRb/winrm-elevated/pull/6)
+
+# 0.2.0
+- [Only upload the elevated runner script once per winrm session](https://github.com/WinRb/winrm-elevated/pull/3)
+- Bump WinRM (1.5) and WinRM-fs (0.3.0) gem constraints
+
+# 0.1.0
+- Initial Release

data/lib/winrm/shells/elevated.rb

@@ -0,0 +1,99 @@
+# encoding: UTF-8
+#
+# Copyright 2015 Shawn Neal <sneal@sneal.net>
+#
+# 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 'erubis'
+require 'winrm'
+require 'winrm-fs'
+require 'securerandom'
+
+module WinRM
+  module Shells
+    # Runs PowerShell commands elevated via a scheduled task
+    class Elevated
+      # Create a new elevated shell
+      # @param connection_opts [ConnectionOpts] The WinRM connection options
+      # @param transport [HttpTransport] The WinRM SOAP transport
+      # @param logger [Logger] The logger to log diagnostic messages to
+      def initialize(connection_opts, transport, logger)
+        @logger = logger
+        @username = connection_opts[:user]
+        @password = connection_opts[:password]
+        @shell = Powershell.new(connection_opts, transport, logger)
+        @winrm_file_transporter = WinRM::FS::Core::FileTransporter.new(@shell)
+      end
+
+      # @return [String] The admin user name to execute the scheduled task as
+      attr_accessor :username
+
+      # @return [String] The admin user password
+      attr_accessor :password
+
+      # Run a command or PowerShell script elevated without any of the
+      # restrictions that WinRM puts in place.
+      #
+      # @param [String] The command or PS script to wrap in a scheduled task
+      #
+      # @return [WinRM::Output] :stdout and :stderr
+      def run(command, &block)
+        # if an IO object is passed read it, otherwise assume the contents of the file were passed
+        script_text = command.respond_to?(:read) ? command.read : command
+
+        script_path = upload_elevated_shell_script(script_text)
+        wrapped_script = wrap_in_scheduled_task(script_path, username, password)
+        @shell.run(wrapped_script, &block)
+      end
+
+      # Closes the shell if one is open
+      def close
+        @shell.close
+      end
+
+      private
+
+      def upload_elevated_shell_script(script_text)
+        elevated_shell_path = 'c:/windows/temp/winrm-elevated-shell-' + SecureRandom.uuid + '.ps1'
+        with_temp_file(script_text) do |temp_file|
+          @winrm_file_transporter.upload(temp_file, elevated_shell_path)
+        end
+        elevated_shell_path
+      end
+
+      def with_temp_file(script_text)
+        file = Tempfile.new(['winrm-elevated-shell', 'ps1'])
+        file.write(script_text)
+        file.write("\r\n$Host.SetShouldExit($LASTEXITCODE)")
+        file.fsync
+        file.close
+        yield file.path
+      ensure
+        file.close
+        file.unlink
+      end
+
+      def elevated_shell_script_content
+        IO.read(File.expand_path('../../../winrm-elevated/scripts/elevated_shell.ps1', __FILE__))
+      end
+
+      def wrap_in_scheduled_task(script_path, username, password)
+        Erubis::Eruby.new(elevated_shell_script_content).result(
+          username: username,
+          password: password,
+          script_path: script_path
+        )
+      end
+    end
+  end
+end