Class: Ronin::Payloads::Payload

Inherits:
Object
  • Object
show all
Includes:
Behaviors::Buildable, Behaviors::Deployable, Behaviors::Testable, Model::TargetsArch, Model::TargetsOS, HasPayload, Ronin::PostExploitation::Mixin, Script
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.

Metadata

A Payload is described via metadata, which is cached into the Ronin Database. The cacheable metadata must be defined within a cache block, so that the metadata is set only before the payload is cached:

cache do
  self.name = 'BindShell payload'
  self.version = '0.1'
  self.description = %{
    An assembly Bind Shell payload, which binds a shell to a
    given port.
  }

  # ...
end

License

A Payload may associate with a specific software license using the licensed_under method:

cache do
  # ...

  licensed_under :cc_sa_by
end

Authors

A Payload may have one or more authors which contributed to the payload, using the author method:

cache do
  # ...

  author name: 'evoltech', organization: 'HackBloc'
  author name: 'postmodern', organization: 'SophSec'
end

Targeting

A Payload may target a specific Architecture or Operating System. Targetting information can be set using the arch and os! methods.

cache do
  # ...

  arch! :i686
  os! name: 'Linux'
end

Methods

The functionality of a Payload is defined by three main methods:

  • build - Handles building the payload.
  • test - Optional method which handles testing a built payload.
  • deploy - Handles deploying a built and verified payload against a host.
  • evacuate - Handles cleaning up after a deployed payload.

The build, test, deploy, evacuate methods can be invoked individually using the build!, test!, deploy!, evacuate! methods, respectively.

Exploit/Payload Coupling

When an exploit is coupled with a Payload, the #exploit method will contain the coupled exploit. When the payload is built along with the exploit, it will receive the same options given to the exploit.

Payload Chaining

All Payload classes include the HasPayload module, which allows another payload to be chained together with a Payload.

To chain a cached payload, from the Ronin Database, simply use the use_payload! method:

payload.use_payload!(:name.like '%Bind Shell%')

In order to chain a payload, loaded directly from a file, call the use_payload_from! method:

payload.use_payload_from!('path/to/my_payload.rb')

Direct Known Subclasses

BinaryPayload, BindShell, RPC, Web

Instance Attribute Summary collapse

Attributes included from HasPayload

#payload

Instance Method Summary collapse

Methods included from Ronin::PostExploitation::Mixin

#fs, #post_exploitation, #process, #resources, #shell

Methods included from HasPayload

#default_payload, #method_missing, #payload_class, #respond_to?, #use_payload!, #use_payload_from!

Methods included from Model::TargetsOS

included

Methods included from Model::TargetsArch

included

Constructor Details

#initialize(attributes = {}) ⇒ Payload

Creates a new Payload object.


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

def initialize(attributes={})
  super(attributes)

  @helpers = Set[]
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Ronin::Payloads::HasPayload

Instance Attribute Details

#exploitObject

The exploit to deploy with


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

def exploit
  @exploit
end

#helpersObject (readonly)

The helpers used by the payload


153
154
155
# File 'lib/ronin/payloads/payload.rb', line 153

def helpers
  @helpers
end

#raw_payloadObject

The raw payload


159
160
161
# File 'lib/ronin/payloads/payload.rb', line 159

def raw_payload
  @raw_payload
end

Instance Method Details

#build!(options = {}) {|payload| ... } ⇒ Object

Note:

Sets the @raw_payload instance variable to an empty String, before building the payload.

Builds the payload.

Yields:

  • (payload)

    If a block is given, it will be yielded the result of the

Yield Parameters:

  • payload (Payload)

    The built payload.


190
191
192
193
194
195
196
197
198
# File 'lib/ronin/payloads/payload.rb', line 190

def build!(options={},&block)
  @raw_payload = ''

  if @payload.respond_to?(:build!)
    @payload.build!(options)
  end

  super(options,&block)
end

#helper(name) ⇒ Boolean (protected)

Loads a helper module from ronin/payloads/helpers and extends the payload with it.

Examples:

helper :shell

Raises:

  • (UnknownHelper)

    No valid helper module could be found or loaded with the similar name.


221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
# File 'lib/ronin/payloads/payload.rb', line 221

def helper(name)
  name = name.to_sym

  return false if @helpers.include?(name)

  unless (helper_module = Helpers.require_const(name))
    raise(UnknownHelper,"unknown helper #{name}",caller)
  end

  unless helper_module.kind_of?(Module)
    raise(UnknownHelper,"unknown helper #{name}",caller)
  end

  @helpers << name
  extend helper_module
  return true
end