= Ronin Exploits

* http://ronin.rubyforge.org/exploits/
* http://github.com/postmodern/ronin-exploits
* irc.freenode.net ##ronin
* Postmodern (postmodern.mod3 at gmail.com)

== DESCRIPTION:

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

Ronin is a Ruby platform designed for information security and data
exploration tasks. Ronin allows for the rapid development and distribution
of code over many of the common Source-Code-Management (SCM) systems.

=== Free

All source code within Ronin is licensed under the GPL-2, therefore no user
will ever have to pay for Ronin or updates to Ronin. Not only is the
source code free, the Ronin project will not sell enterprise grade security
snake-oil solutions, give private training classes or later turn Ronin into
commercial software.

=== Modular

Ronin was not designed as one monolithic framework but instead as a
collection of libraries which can be individually installed. This allows
users to pick and choose what functionality they want in Ronin.

=== Decentralized

Ronin does not have a central repository of exploits and payloads which
all developers contribute to. Instead Ronin has Overlays, repositories of
code that can be hosted on any CVS/SVN/Git/Rsync server. Users can then use
Ronin to quickly install or update Overlays. This allows developers and
users to form their own communities, independent of the main developers
of Ronin.

== 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:
  * Wether they are local or remote.
  * Protocol they use.
  * Contributing authors.
  * Disclosure status.
  * Level of weaponization.
  * Behaviors the vulnerability allows.
  * Architectures they target.
  * OSes they target.
  * Products they target.
  * Helpers they use.

== REQUIREMENTS:

* {ronin}[http://ronin.rubyforge.org/] >= 0.2.3

== INSTALL:

  $ sudo gem install ronin-exploits

== 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 call(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')

        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

== 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