Yarddoc exploit::powershell

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']