From 88fe619c489197da4bcf4b65cb55e44f6be82571 Mon Sep 17 00:00:00 2001 From: Meatballs Date: Wed, 23 Apr 2014 00:15:12 +0100 Subject: [PATCH] Yarddoc exploit::powershell --- lib/msf/core/exploit/powershell.rb | 89 ++++++++++++++++++++++++++++-- 1 file changed, 83 insertions(+), 6 deletions(-) diff --git a/lib/msf/core/exploit/powershell.rb b/lib/msf/core/exploit/powershell.rb index 23a6813407..1df7a59817 100644 --- a/lib/msf/core/exploit/powershell.rb +++ b/lib/msf/core/exploit/powershell.rb @@ -6,7 +6,6 @@ module Exploit::Powershell PowershellScript = Rex::Exploitation::Powershell::Script - def initialize(info = {}) super register_advanced_options( @@ -29,6 +28,9 @@ module Exploit::Powershell # # Reads script into a PowershellScript # + # @param script_path [String] Path to the Script File + # + # @return [PowershellScript] PowerShellScript object def read_script(script_path) return PowershellScript.new(script_path) end @@ -38,6 +40,10 @@ module Exploit::Powershell # If script is a path to a file then read the file # otherwise treat it as the contents of a file # + # @param script [String] Script file or path to script + # @param subs [Array] Substitutions to insert + # + # @return [String] Modified script file def make_subs(script, subs) if ::File.file?(script) script = ::File.read(script) @@ -53,6 +59,9 @@ module Exploit::Powershell # # Return an array of substitutions for use in make_subs # + # @param subs [String] A ; seperated list of substitutions + # + # @return [Array] An array of substitutions def process_subs(subs) return [] if subs.nil? or subs.empty? new_subs = [] @@ -67,6 +76,10 @@ module Exploit::Powershell # Return an encoded powershell script # Will invoke PSH modifiers as enabled # + # @param script_in [String] Script contents + # @param eof [String] Marker to indicate the end of file appended to script + # + # @return [String] Encoded script def encode_script(script_in, eof = nil) # Build script object psh = PowershellScript.new(script_in) @@ -83,6 +96,10 @@ module Exploit::Powershell # Return a gzip compressed powershell script # Will invoke PSH modifiers as enabled # + # @param script_in [String] Script contents + # @param eof [String] Marker to indicate the end of file appended to script + # + # @return [String] Compressed script with decompression stub def compress_script(script_in, eof = nil) # Build script object psh = PowershellScript.new(script_in) @@ -96,8 +113,15 @@ module Exploit::Powershell end # - # Generate a powershell command line + # Generate a powershell command line, options are passed on to + # generate_psh_args # + # @param opts [Hash] The options to generate the command line + # @option opts [String] :path Path to the powershell binary + # @option opts [Boolean] :no_full_stop Whether powershell binary + # should include .exe + # + # @return [String] Powershell command line with arguments def generate_psh_command_line(opts) if opts[:path] and (opts[:path][-1,1] != "\\") opts[:path] << "\\" @@ -119,6 +143,32 @@ module Exploit::Powershell # The format will be have no space at the start and have a space # afterwards e.g. "-Arg1 x -Arg -Arg x " # + # @param opts [Hash] The options to generate the command line + # @option opts [Boolean] :shorten Whether to shorten the powershell + # arguments (v2.0 or greater) + # @option opts [String] :encodedcommand Powershell script as an + # encoded command (-EncodedCommand) + # @option opts [String] :executionpolicy The execution policy + # (-ExecutionPolicy) + # @option opts [String] :inputformat The input format (-InputFormat) + # @option opts [String] :file The path to a powershell file (-File) + # @option opts [Boolean] :noexit Whether to exit powershell after + # execution (-NoExit) + # @option opts [Boolean] :nologo Whether to display the logo (-NoLogo) + # @option opts [Boolean] :noninteractive Whether to load a non + # interactive powershell (-NonInteractive) + # @option opts [Boolean] :mta Whether to run as Multi-Threaded + # Apartment (-Mta) + # @option opts [String] :outputformat The output format + # (-OutputFormat) + # @option opts [Boolean] :sta Whether to run as Single-Threaded + # Apartment (-Sta) + # @option opts [Boolean] :noprofile Whether to use the current users + # powershell profile (-NoProfile) + # @option opts [String] :windowstyle The window style to use + # (-WindowStyle) + # + # @return [String] Powershell command arguments def generate_psh_args(opts) return "" unless opts @@ -189,10 +239,15 @@ module Exploit::Powershell end # - # Runs powershell in hidden window raising interactive proc msg - # Detect the architecture + # Wraps the powershell code to launch a hidden window and + # detect the execution environment and spawn the appropriate + # powershell executable for the payload architecture. # - + # @param ps_code [String] Powershell code + # @param payload_arch [String] The payload architecture 'x86'/'x86_64' + # @param encoded [Boolean] Indicates whether ps_code is encoded or not + # + # @return [String] Wrapped powershell code def run_hidden_psh(ps_code, payload_arch, encoded) arg_opts = { :noprofile => true, @@ -233,8 +288,30 @@ EOS end # - # Creates cmd script to execute psh payload + # Creates a powershell command line string which will execute the + # payload in a hidden window in the appropriate execution environment + # for the payload architecture. Opts are passed through to + # run_hidden_psh, generate_psh_command_line and generate_psh_args # + # @param pay [String] The payload shellcode + # @param payload_arch [String] The payload architecture 'x86'/'x86_64' + # @param opts [Hash] The options to generate the command + # @option opts [Boolean] :persist Loop the payload to cause + # re-execution if the shellcode finishes + # @option opts [Integer] :prepend_sleep Sleep for the specified time + # before executing the payload + # @option opts [String] :method The powershell injection technique to + # use: 'net'/'reflection'/'old' + # @option opts [Boolean] :encode_inner_payload Encodes the powershell + # script within the hidden/architecture detection wrapper + # @option opts [Boolean] :encode_final_payload Encodes the final + # powershell script + # @option opts [Boolean] :remove_comspec Removes the %COMSPEC% + # environment variable at the start of the command line + # @option opts [Boolean] :use_single_quotes Wraps the -Command + # argument in single quotes unless :encode_final_payload + # + # @return [String] Powershell command line with payload def cmd_psh_payload(pay, payload_arch, opts={}) opts[:persist] ||= datastore['Powershell::persist'] opts[:prepend_sleep] ||= datastore['Powershell::prepend_sleep']