Class: Msf::EncodedPayload

Inherits:
Object
  • Object
show all
Includes:
Framework::Offspring
Defined in:
lib/msf/core/encoded_payload.rb

Overview

This class wrappers an encoded payload buffer and the means used to create one.

Instance Attribute Summary collapse

Attributes included from Framework::Offspring

#framework

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(framework, pinst, reqs) ⇒ EncodedPayload

Creates an instance of an EncodedPayload.


33
34
35
36
37
 
# File 'lib/msf/core/encoded_payload.rb', line 33

def initialize(framework, pinst, reqs)
  self.framework = framework
  self.pinst     = pinst
  self.reqs      = reqs
end

Instance Attribute Details

#encoded ⇒ Object

The encoded version of the raw payload plus the NOP sled if one was generated.


415
416
417
 
# File 'lib/msf/core/encoded_payload.rb', line 415

def encoded
  @encoded
end

#encoder ⇒ Object

The encoder that was used


427
428
429
 
# File 'lib/msf/core/encoded_payload.rb', line 427

def encoder
  @encoder
end

#iterations ⇒ Object

The number of encoding iterations used


435
436
437
 
# File 'lib/msf/core/encoded_payload.rb', line 435

def iterations
  @iterations
end

#nop ⇒ Object

The NOP generator that was used


431
432
433
 
# File 'lib/msf/core/encoded_payload.rb', line 431

def nop
  @nop
end

#nop_sled ⇒ Object

The NOP sled itself


423
424
425
 
# File 'lib/msf/core/encoded_payload.rb', line 423

def nop_sled
  @nop_sled
end

#nop_sled_size ⇒ Object

The size of the NOP sled


419
420
421
 
# File 'lib/msf/core/encoded_payload.rb', line 419

def nop_sled_size
  @nop_sled_size
end

#raw ⇒ Object

The raw version of the payload


410
411
412
 
# File 'lib/msf/core/encoded_payload.rb', line 410

def raw
  @raw
end

Class Method Details

.create(pinst, reqs = {}) ⇒ Object

This method creates an encoded payload instance and returns it to the caller.


21
22
23
24
25
26
27
28
 
# File 'lib/msf/core/encoded_payload.rb', line 21

def self.create(pinst, reqs = {})
  # Create the encoded payload instance
  p = EncodedPayload.new(pinst.framework, pinst, reqs)

  p.generate(reqs['Raw'])

  return p
end

Instance Method Details

#encode ⇒ Object

Scans for a compatible encoder using ranked precedence and populates the encoded attribute.


106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
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
205
206
207
208
209
210
211
212
213
214
215
216
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
 
# File 'lib/msf/core/encoded_payload.rb', line 106

def encode
  # If the exploit has bad characters, we need to run the list of encoders
  # in ranked precedence and try to encode without them.
  if reqs['BadChars'] or reqs['Encoder'] or reqs['ForceEncode']
    encoders = pinst.compatible_encoders

    # Fix encoding issue
    if reqs['Encoder']
      reqs['Encoder'] = reqs['Encoder'].encode(framework.encoders.keys[0].encoding)
    end
    # If the caller had a preferred encoder, use this encoder only
    if ((reqs['Encoder']) and (preferred = framework.encoders[reqs['Encoder']]))
      encoders = [ [reqs['Encoder'], preferred] ]
    elsif (reqs['Encoder'])
      wlog("#{pinst.refname}: Failed to find preferred encoder #{reqs['Encoder']}")
      raise NoEncodersSucceededError, "Failed to find preferred encoder #{reqs['Encoder']}"
    end

    encoders.each { |encname, encmod|
      self.encoder = encmod.new
      self.encoded = nil

      # If the encoding is requested by an exploit check compatibility
      # options first of all. For the 'generic/none' encoder compatibility
      # options don't apply.
      if (reqs['Exploit'] &&
          !reqs['Exploit'].compatible?(self.encoder) &&
          encname !~ /generic\/none/)
        wlog("#{pinst.refname}: Encoder #{encoder.refname} doesn't match the exploit Compat options",
          'core', LEV_1)
        next
      end

      # If there is an encoder type restriction, check to see if this
      # encoder matches with what we're searching for.
      if ((reqs['EncoderType']) and
          (self.encoder.encoder_type.split(/\s+/).include?(reqs['EncoderType']) == false))
        wlog("#{pinst.refname}: Encoder #{encoder.refname} is not a compatible encoder type: #{reqs['EncoderType']} != #{self.encoder.encoder_type}",
          'core', LEV_1)
        next
      end

      # If the exploit did not explicitly request a kind of encoder and
      # the current encoder has a manual ranking, then it should not be
      # considered as a valid encoder.  A manual ranking tells the
      # framework that an encoder must be explicitly defined as the
      # encoder of choice for an exploit.
      if ((reqs['EncoderType'].nil?) and
          (reqs['Encoder'].nil?) and
          (self.encoder.rank == ManualRanking))
        wlog("#{pinst.refname}: Encoder #{encoder.refname} is manual ranked and was not defined as a preferred encoder.",
          'core', LEV_1)
        next
      end

      # Import the datastore from payload (and likely exploit by proxy)
      self.encoder.share_datastore(pinst.datastore)

      # If we have any encoder options, import them into the datastore
      # of the encoder.
      if (reqs['EncoderOptions'])
        self.encoder.datastore.import_options_from_hash(reqs['EncoderOptions'])
      end

      # Validate the encoder to make sure it's properly initialized.
      begin
        self.encoder.validate
      rescue ::Exception
        wlog("#{pinst.refname}: Failed to validate encoder #{encoder.refname}: #{$!}",
          'core', LEV_1)
        next
      end

      eout = self.raw.dup

      next_encoder = false

      # Try encoding with the current encoder
      #
      # NOTE: Using more than one iteration may cause successive iterations to switch
      # to using a different encoder.
      #
      1.upto(self.iterations) do |iter|
        err_start = "#{pinst.refname}: iteration #{iter}"

        begin
          eout = self.encoder.encode(eout, reqs['BadChars'], nil, pinst.platform)
        rescue EncodingError
          wlog("#{err_start}: Encoder #{encoder.refname} failed: #{$!}", 'core', LEV_1)
          dlog("#{err_start}: Call stack\n#{[email protected].join("\n")}", 'core', LEV_3)
          next_encoder = true
          break

        rescue ::Exception
          elog("#{err_start}: Broken encoder #{encoder.refname}: #{$!}", 'core', LEV_0)
          dlog("#{err_start}: Call stack\n#{[email protected].join("\n")}", 'core', LEV_1)
          next_encoder = true
          break
        end

        # Get the minimum number of nops to use
        min = (reqs['MinNops'] || 0).to_i
        min = 0 if reqs['DisableNops']

        # Check to see if we have enough room for the minimum requirements
        if ((reqs['Space']) and (reqs['Space'] < eout.length + min))
          wlog("#{err_start}: Encoded payload version is too large (#{eout.length} bytes) with encoder #{encoder.refname}",
            'core', LEV_1)
          next_encoder = true
          break
        end

        ilog("#{err_start}: Successfully encoded with encoder #{encoder.refname} (size is #{eout.length})",
          'core', LEV_0)
      end

      next if next_encoder

      self.encoded = eout
      break
    }

    # If the encoded payload is nil, raise an exception saying that we
    # suck at life.
    if (self.encoded == nil)
      self.encoder = nil

      raise NoEncodersSucceededError,
        "#{pinst.refname}: All encoders failed to encode.",
        caller
    end

  # If there are no bad characters, then the raw is the same as the
  # encoded
  else
    self.encoded = raw
  end

  # Prefix the prepend encoder value
  self.encoded = (reqs['PrependEncoder'] || '') + self.encoded
  self.encoded << (reqs['AppendEncoder'] || '')
end

#encoded_exe(opts = {}) ⇒ Object

Convert the payload to an executable appropriate for its arch and platform.

opts are passed directly to Msf::Util::EXE.to_executable

see Msf::Exploit::EXE


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
 
# File 'lib/msf/core/encoded_payload.rb', line 338

def encoded_exe(opts={})
  # Ensure arch and platform are in the format that to_executable expects
  if opts[:arch] and not opts[:arch].kind_of? Array
    opts[:arch] = [ opts[:arch] ]
  end
  if (opts[:platform].kind_of? Msf::Module::PlatformList)
    opts[:platform] = opts[:platform].platforms
  end

  emod = pinst.assoc_exploit if pinst.respond_to? :assoc_exploit

  if emod
    if (emod.datastore["EXE::Custom"] and emod.respond_to? :get_custom_exe)
      return emod.get_custom_exe
    end
    # This is a little ghetto, grabbing datastore options from the
    # associated exploit, but it doesn't really make sense for the
    # payload to have exe options if the exploit doesn't need an exe.
    # Msf::Util::EXE chooses reasonable defaults if these aren't given,
    # so it's not that big of an issue.
    opts.merge!({
      :template_path => emod.datastore['EXE::Path'],
      :template => emod.datastore['EXE::Template'],
      :inject => emod.datastore['EXE::Inject'],
      :fallback => emod.datastore['EXE::FallBack'],
      :sub_method => emod.datastore['EXE::OldMethod']
    })
    # Prefer the target's platform/architecture information, but use
    # the exploit module's if no target specific information exists.
    opts[:platform] ||= emod.target_platform  if emod.respond_to? :target_platform
    opts[:platform] ||= emod.platform         if emod.respond_to? :platform
    opts[:arch] ||= emod.target_arch          if emod.respond_to? :target_arch
    opts[:arch] ||= emod.arch                 if emod.respond_to? :arch
  end
  # Lastly, try the payload's. This always happens if we don't have an
  # associated exploit module.
  opts[:platform] ||= pinst.platform if pinst.respond_to? :platform
  opts[:arch] ||= pinst.arch         if pinst.respond_to? :arch

  Msf::Util::EXE.to_executable(framework, opts[:arch], opts[:platform], encoded, opts)
end

#encoded_jar(opts = {}) ⇒ Object

Generate a jar file containing the encoded payload.

Uses the payload's generate_jar method if it is implemented (Java payloads should all have it). Otherwise, converts the payload to an executable and uses Msf::Util::EXE.to_jar to create a jar file that dumps the exe out to a random file name in the system's temporary directory and executes it.


389
390
391
392
393
394
395
 
# File 'lib/msf/core/encoded_payload.rb', line 389

def encoded_jar(opts={})
  return pinst.generate_jar(opts) if pinst.respond_to? :generate_jar

  opts[:spawn] ||= pinst.datastore["Spawn"]

  Msf::Util::EXE.to_jar(encoded_exe(opts), opts)
end

#encoded_war(opts = {}) ⇒ Object

Similar to encoded_jar but builds a web archive for use in servlet containers such as Tomcat.


401
402
403
404
405
 
# File 'lib/msf/core/encoded_payload.rb', line 401

def encoded_war(opts={})
  return pinst.generate_war(opts) if pinst.respond_to? :generate_war

  Msf::Util::EXE.to_jsp_war(encoded_exe(opts), opts)
end

#generate(raw = nil) ⇒ String

This method generates the full encoded payload and returns the encoded payload buffer.

Returns:

  • (String) —

    The encoded payload.


44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/msf/core/encoded_payload.rb', line 44

def generate(raw = nil)
  self.raw           = raw
  self.encoded       = nil
  self.nop_sled_size = 0
  self.nop_sled      = nil
  self.encoder       = nil
  self.nop           = nil
  self.iterations    = reqs['Iterations'].to_i
  self.iterations    = 1 if self.iterations < 1

  # Increase thread priority as necessary.  This is done
  # to ensure that the encoding and sled generation get
  # enough time slices from the ruby thread scheduler.
  priority = Thread.current.priority

  if (priority == 0)
    Thread.current.priority = 1
  end

  begin
    # First, validate
    pinst.validate()

    # Generate the raw version of the payload first
    generate_raw() if self.raw.nil?

    # Encode the payload
    encode()

    # Build the NOP sled
    generate_sled()

    # Finally, set the complete payload definition
    self.encoded = (self.nop_sled || '') + self.encoded
  ensure
    # Restore the thread priority
    Thread.current.priority = priority
  end

  # Return the complete payload
  return encoded
end

#generate_raw ⇒ String

Generates the raw payload from the payload instance. This populates the #raw attribute.

Returns:

  • (String) —

    The raw, unencoded payload.


92
93
94
95
96
97
98
99
100
 
# File 'lib/msf/core/encoded_payload.rb', line 92

def generate_raw
  self.raw = (reqs['Prepend'] || '') + pinst.generate + (reqs['Append'] || '')

  # If an encapsulation routine was supplied, then we should call it so
  # that we can get the real raw payload.
  if reqs['EncapsulationRoutine']
    self.raw = reqs['EncapsulationRoutine'].call(reqs, raw)
  end
end

#generate_sled ⇒ Object

Construct a NOP sled if necessary


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
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
 
# File 'lib/msf/core/encoded_payload.rb', line 252

def generate_sled
  min   = reqs['MinNops'] || 0
  space = reqs['Space']

  self.nop_sled_size = min

  # Calculate the number of NOPs to pad out the buffer with based on the
  # requirements.  If there was a space requirement, check to see if
  # there's any room at all left for a sled.
  if ((space) and
     (space > encoded.length))
    self.nop_sled_size = reqs['Space'] - self.encoded.length
  end

  # If the maximum number of NOPs has been exceeded, wrap it back down.
  if ((reqs['MaxNops']) and
     (reqs['MaxNops'] < self.nop_sled_size))
    self.nop_sled_size = reqs['MaxNops']
  end

  # Check for the DisableNops setting
  self.nop_sled_size = 0 if reqs['DisableNops']

  # Now construct the actual sled
  if (self.nop_sled_size > 0)
    nops = pinst.compatible_nops

    # If the caller had a preferred nop, try to find it and prefix it
    if ((reqs['Nop']) and
        (preferred = framework.nops[reqs['Nop']]))
      nops.unshift([reqs['Nop'], preferred ])
    elsif (reqs['Nop'])
      wlog("#{pinst.refname}: Failed to find preferred nop #{reqs['Nop']}")
    end

    nops.each { |nopname, nopmod|
      # Create an instance of the nop module
      self.nop = nopmod.new

      # Propagate options from the payload and possibly exploit
      self.nop.share_datastore(pinst.datastore)

      # The list of save registers
      save_regs = (reqs['SaveRegisters'] || []) + (pinst.save_registers || [])

      if (save_regs.empty? == true)
        save_regs = nil
      end

      begin
        nop.copy_ui(pinst)

        self.nop_sled = nop.generate_sled(self.nop_sled_size,
          'BadChars'      => reqs['BadChars'],
          'SaveRegisters' => save_regs)
      rescue
        dlog("#{pinst.refname}: Nop generator #{nop.refname} failed to generate sled for payload: #{$!}",
          'core', LEV_1)

        self.nop = nil
      end

      break
    }

    if (self.nop_sled == nil)
      raise NoNopsSucceededError,
        "#{pinst.refname}: All NOP generators failed to construct sled for.",
        caller
    end
  else
    self.nop_sled = ''
  end

  return self.nop_sled
end