= Ronin Exploits

* http://ronin.rubyforge.org/exploits/
* http://github.com/postmodern/ronin-exploits
* http://github.com/postmodern/ronin-exploits/issues
* http://groups.google.com/group/ronin-ruby
* irc.freenode.net #ronin

== DESCRIPTION:

Ronin Exploits is a Ruby library for Ronin that provides exploitation and
payload crafting functionality.

Ronin is a Ruby platform for exploit development and security research.
Ronin allows for the rapid development and distribution of code, exploits
or payloads over many common Source-Code-Management (SCM) systems.

=== Ruby

Ronin's Ruby environment allows security researchers to leverage Ruby with
ease. The Ruby environment contains a multitude of convenience methods
for working with data in Ruby, a Ruby Object Database, a customized Ruby
Console and an extendable command-line interface.

=== Extend

Ronin's more specialized features are provided by additional Ronin
libraries, which users can choose to install. These libraries can allow
one to write and run Exploits and Payloads, scan for PHP vulnerabilities,
perform Google Dorks  or run 3rd party scanners.

=== Publish

Ronin allows users to publish and share code, exploits, payloads or other
data via Overlays. Overlays are directories of code and data that can be
hosted on any SVN, Hg, Git or Rsync server. Ronin makes it easy to create,
install or update Overlays.

== FEATURES:

* Ability to define Payloads based on:
  * Contributing authors.
  * Behaviors they control.
  * Helpers they use.
* Ability to define Payload Encoders:
  * Architectures they target.
  * OSes they target.
* Ability to define Exploits based on:
  * Whether they are local or remote.
  * Protocol they use.
  * Contributing authors.
  * Behaviors they control.
  * Disclosure status.
  * Level of weaponization.
  * Architectures they target.
  * OSes they target.
  * Products they target.
  * Helpers they use.
* Provides a simple three phase process of building, verifying and
  deploying Exploits and Payloads.
* Allows adding arbitrary target data to the targets of Exploits.
* Allows combining Payloads with Exploits.
* Allows using a raw-payload with an Exploit.
* Allows the addition of multiple Payload Encoders to an Exploit.
* Allows chaining multiple Payloads together.
* Provides a multitude of exploit and payload generators which can create
  customized skeleton Ruby Exploits and Payloads.

== SYNOPSIS:

* Generate a skeleton exploit, with some custom information:

    $ ronin-gen exploit exploit.rb --name Example \
                                   --controls command_exec \
           --status proven \
           --authors Postmodern \
           --description "This is an example."

  * To generate other types of exploits, you can specify +local_exploit+,
    +remote_exploit+, +remote_tcp_exploit+, +remote_udp_exploit+,
    +ftp_exploit+, +http_exploit+ or +web_exploit+, instead of simply
    +exploit+.

* Generate a skeleton payload, with some custom information:

    $ ronin-gen payload payload.rb --name Example \
                                   --controls file_read file_write \
           --authors Postmodern \
           --description "This is an example."

  * To generate other types of payloads, you can specify +binary_payload+,
    +shellcode+ or +nops+, instead of simply +payload+.

* List available payloads:

    $ ronin-payloads

* Print information about a payload:

    $ ronin-payloads -n NAME -v

* Build and output a payload:

    $ ronin-payload NAME

* Build and output a raw unescaped payload:

    $ ronin-payload NAME --raw

* Load a payload from a file, then build and output it:

    $ ronin-payload -f FILE

* List available exploits:

    $ ronin-exploits

* Print information about an exploit:

    $ ronin-exploits -n NAME -v

* Build and deploy an exploit:

    $ ronin-exploit -n NAME --host example.com --port 9999

* Load an exploit from a file, then build and deploy it:

    $ ronin-exploit -f FILE --host example.com --port 9999

* Build and deploy an exploit, with a payload:

    $ ronin-exploit -n NAME --host example.com --port 9999 -P PAYLOAD_NAME

* Build and deploy an exploit, with a raw payload:

    $ ronin-exploit -n NAME --host example.com --port 9999 \
                    --raw-payload \
        `echo -en "\x66\x31\xc0\xfe\xc0\xb3\xff\xcd\x80"`

== EXAMPLES:

* Define a shellcode payload:

    ronin_shellcode do
      #
      # Cacheable data.
      #
      cache do
        self.name = 'test'
        self.version = '0.5'
        self.description = %{This is an example shellcode payload.}

        author(:name => 'Postmodern', :organization => 'SophSec')

        self.arch :i686
        self.os :name => 'Linux'
      end

      #
      # Configurable parameters.
      #
      parameter :exit_status,
                :default => 0,
                :description => 'Exit status of shellcode'

      #
      # Builds the assembly payload, which will call the SYS_EXIT
      # syscall with the exit_status of the shellcode.
      #
      def build
        @payload = "\x66\x31\xc0\xfe\xc0"

        unless @exit_status == 0
          @payload << "\xb3#{@exit_status.chr}"
        else
          @payload << "\x66\x31\xdb"
        end

        @payload << "\xcd\x80"
        return @payload
      end
    end

* Define a payload encoder:

    ronin_payload_encoder do
      #
      # Cacheable data.
      #
      cache do
        self.name = 'base64_encode'
        self.description = %{Example base64 payload encoder}

        self.arch :i686
        self.os :name => 'Linux'
      end

      #
      # Base64 encodes the specified _data_.
      #
      def encode(data)
        return data.to_s.base64_encode
      end
    end

* Define a remote TCP exploit:

    ronin_remote_tcp_exploit do
      helper :buffer_overflow

      #
      # Cacheable data.
      #
      cache do
        self.name = 'test'
        self.description = %{This is an example exploit.}

        self.status = :potential
        self.disclosure = [:in_wild, :public]

        author(:name => 'Postmodern', :organization => 'SophSec')

        controlling :code_exec

        targeting do |target|
          target.arch :i686
          target.os :name => 'Linux'
          target.product :name => 'ExampleWare', :version => '2.4.7b'
        end
      end

      #
      # Builds the exploit.
      #
      def build
        @buffer = "USER #{build_buffer}\n"
      end

      #
      # Deploys the built exploit.
      #
      def deploy
        tcp_send @buffer
      end
    end

== REQUIREMENTS:

* {ronin}[http://ronin.rubyforge.org/] >= 0.3.0
* {ronin-gen}[http://ronin.rubyforge.org/gen/] >= 0.2.0

== INSTALL:

  $ sudo gem install ronin-exploits

== LICENSE:

Ronin Exploits - A Ruby library for Ronin that provides exploitation and
payload crafting functionality.

Copyright (c) 2007-2009 Hal Brodigan (postmodern.mod3 at gmail.com)

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA