Class: Ronin::Payloads::Payload

Inherits:
Object
  • Object
show all
Includes:
Core::Metadata::Authors, Core::Metadata::Description, Core::Metadata::ID, Core::Metadata::References, Core::Metadata::Summary, Core::Params::Mixin, Support::CLI::Printing
Defined in:
lib/ronin/payloads/payload.rb

Overview

The Payload class allows for describing payloads, which are delivered via exploits, purely in Ruby. Payloads contain metadata about the payload and methods which define the functionality of the payload. Payloads may also be coupled with exploits, or chained together with other payloads.

Payload API Methods

  • initialize - Initializes a new instance of the payload.
  • build - contains the logic to build the payload. The built payload must be stored in the @payload instance variable.
  • prelaunch - contains additional logic that runs before the payload has been launched by the exploit.
  • postlaunch - contains additional logic that runs after the payload has been launched by the exploit.
  • cleanup - contains additional logic to cleanup or shutdown the payload.

Example

module Ronin
  module Payloads
    class MyPayload < Payload

      register 'my_payload'

      summary 'My first payload'
      description <<~EOS
        This is my first payload.
        Bla bla bla bla.
      EOS

      author 'John Smith'
      author 'John Smith', email: '...', twitter: '...'

      param :foo, desc: 'Simple param'
      param :bar, Integer, desc: 'A param iwth a typo'

      def build
        @payload = "..."
      end

      def prelaunch
        # ...
      end

      def postlaunch
        # ...
      end

      def cleanup
        # ...
      end

    end
  end
end

Instance Attribute Summary collapse

String Methods collapse

Payload API Methods collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(encoders: nil, **kwargs) ⇒ Payload

Initializes the payload.

Parameters:

  • encoders (Array<Encoders::Encoder>, nil) (defaults to: nil) —

    The optional list of payload encoders to use.

Raises:



179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/ronin/payloads/payload.rb', line 179

def initialize(encoders: nil, **kwargs)
  super(**kwargs)

  @encoders = Encoders::Pipeline.new

  if encoders
    encoders.each do |encoder|
      unless encoder.kind_of?(self.class.encoder_class)
        raise(IncompatibleEncoder,"encoder for payload #{self.class} was not of type #{self.class.encoder_class}: #{encoder.inspect}")
      end

      @encoders << encoder
    end
  end
end

Instance Attribute Details

#encoders ⇒ Encoders::Pipeline (readonly)

The payload's encoder pipeline.

Returns:



167
168
169
 
# File 'lib/ronin/payloads/payload.rb', line 167

def encoders
  @encoders
end

#payload ⇒ Object (readonly)

The built payload



162
163
164
 
# File 'lib/ronin/payloads/payload.rb', line 162

def payload
  @payload
end

Class Method Details

.encoder_class(new_encoder_class = nil) ⇒ Class<Encoders::Encoder>

Gets or sets the payload encoder base class that is compatible with the payload.

Parameters:

  • new_encoder_class (Class<Encoders::Encoder>, nil) (defaults to: nil) —

    The optional new payload encoder base class to set.

Returns:

  • (Class<Encoders::Encoder>) —

    The exploit's compatible payload encoder base class.



135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/ronin/payloads/payload.rb', line 135

def self.encoder_class(new_encoder_class=nil)
  if new_encoder_class
    @encoder_class = new_encoder_class
  else
    @encoder_class ||= if superclass < ClassMethods
                         superclass.encoder_class
                       else
                         Encoders::Encoder
                       end
  end
end

.payload_type ⇒ Symbol

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Note:

This is used internally to map an payload class to a printable type.

Returns the type or kind of payload.

Returns:

  • (Symbol) 


157
158
159
 
# File 'lib/ronin/payloads/payload.rb', line 157

def self.payload_type
  :payload
end

.register(payload_id) ⇒ Object

Note:

The given id must match the file name.

Registers the payload with Ronin::Payloads.

Examples:

register 'shellcode/x86_64/linux/binsh'

Parameters:

  • payload_id (String) —

    The payload's ID.



120
121
122
123
 
# File 'lib/ronin/payloads/payload.rb', line 120

def self.register(payload_id)
  id(payload_id)
  Payloads.register(payload_id,self)
end

Instance Method Details

#build ⇒ Object

This method is abstract.

Builds the payload.



399
400
 
# File 'lib/ronin/payloads/payload.rb', line 399

def build
end

#built? ⇒ Boolean

Determines whether the payload was built.

Returns:

  • (Boolean) 


217
218
219
 
# File 'lib/ronin/payloads/payload.rb', line 217

def built?
  !(@payload.nil? || @payload.empty?)
end

#built_payload ⇒ String

Note:

This method will lazy-build the payload if unbuilt.

The built payload String.

Returns:

  • (String) —

    The built payload String.



246
247
248
249
250
 
# File 'lib/ronin/payloads/payload.rb', line 246

def built_payload
  perform_build unless built?

  return @payload
end

#bytesize ⇒ Integer Also known as: size

The size of the payload in bytes.

Returns:

  • (Integer) 


360
361
362
 
# File 'lib/ronin/payloads/payload.rb', line 360

def bytesize
  encoded_payload.bytesize
end

#cleanup ⇒ Object

This method is abstract.

Placeholder method to clean up the payload.



425
426
 
# File 'lib/ronin/payloads/payload.rb', line 425

def cleanup
end

#encode_payload ⇒ String

Note:

This method will return a new, potentially different, String each time.

Encodes the built payload.

Returns:

  • (String) —

    The encoded payload String.



273
274
275
 
# File 'lib/ronin/payloads/payload.rb', line 273

def encode_payload
  @encoders.encode(built_payload)
end

#encoded_payload ⇒ String

Note:

This method will lazy build then lazy encode the payload and save the result.

The encoded payload.

Returns:

  • (String) —

    The encoded payload String.

See Also:



289
290
291
 
# File 'lib/ronin/payloads/payload.rb', line 289

def encoded_payload
  @encoded_payload ||= encode_payload
end

#length ⇒ Integer

The number of characters in the payload.

Returns:

  • (Integer) 


351
352
353
 
# File 'lib/ronin/payloads/payload.rb', line 351

def length
  encoded_payload.length
end

#perform_build ⇒ Object

Builds the payload.

See Also:



228
229
230
231
232
233
234
235
236
 
# File 'lib/ronin/payloads/payload.rb', line 228

def perform_build
  @payload = nil

  build

  unless built?
    raise(PayloadNotBuilt,"the payload was not built for some reason: #{inspect}")
  end
end

#perform_cleanup ⇒ Object

Performs the cleanup step.

See Also:



337
338
339
340
 
# File 'lib/ronin/payloads/payload.rb', line 337

def perform_cleanup
  cleanup
  @payload = nil
end

#perform_postlaunch ⇒ Object

Performs the post-launch step.

See Also:



326
327
328
 
# File 'lib/ronin/payloads/payload.rb', line 326

def perform_postlaunch
  postlaunch
end

#perform_prelaunch ⇒ Object

Performs the prelaunch step.

See Also:



315
316
317
 
# File 'lib/ronin/payloads/payload.rb', line 315

def perform_prelaunch
  prelaunch
end

#perform_validate ⇒ Object

Validates that the payload is ready to be built.

Raises:

  • (Ronin::Core::Params::RequiredParam) —

    One of the required params was not set.

  • (ValidationError) —

    Another payload validation error occurred.



206
207
208
209
210
 
# File 'lib/ronin/payloads/payload.rb', line 206

def perform_validate
  validate_params
  @encoders.validate
  validate
end

#postlaunch ⇒ Object

This method is abstract.

Placeholder method that runs after the payload is launched by the exploit.



417
418
 
# File 'lib/ronin/payloads/payload.rb', line 417

def postlaunch
end

#prelaunch ⇒ Object

This method is abstract.

Placeholder method that runs before the payload is launched by the exploit.



408
409
 
# File 'lib/ronin/payloads/payload.rb', line 408

def prelaunch
end

#rebuild_payload ⇒ String

Forcibly rebuilds the payload.

Returns:

  • (String) —

    The re-built payload String.



258
259
260
261
 
# File 'lib/ronin/payloads/payload.rb', line 258

def rebuild_payload
  @payload = nil
  perform_build
end

#reencode_payload ⇒ String

Note:

This will re-encode the built payload and update #encoded_payload.

Forcibly re-encodes the payload.

Returns:

  • (String) —

    The re-encoded payload String.

See Also:



304
305
306
 
# File 'lib/ronin/payloads/payload.rb', line 304

def reencode_payload
  @encoded_payload = encode_payload
end

#to_s ⇒ String Also known as: to_str

Converts the payload into a String.

Returns:

  • (String) —

    The built and encoded payload.

See Also:



374
375
376
 
# File 'lib/ronin/payloads/payload.rb', line 374

def to_s
  encoded_payload
end

#validate ⇒ Object

This method is abstract.

Place holder method for additional validation logic.



391
392
 
# File 'lib/ronin/payloads/payload.rb', line 391

def validate
end