ronin-exploits

Description

ronin-exploits is a Ruby micro-framework for writing and running exploits. ronin-exploits allows one to write exploits as plain old Ruby classes. ronin-exploits can be distributed as Ruby files or as git repositories that can be installed using ronin-repos.

tl;dr It's like a simpler and more modular version of Metasploit.

ronin-exploits is part of the ronin-rb project, a Ruby toolkit for security research and development.

Features

Provides a succinct syntax and API for writing exploits in as few lines as possible.
Supports defining exploits as plain old Ruby classes.
Supports loading exploits from Ruby files or from installed 3rd-party git repositories.
Provides base classes and mixin modules for a variety of exploit types:
Uses the ronin-payloads library for exploit payloads.
Uses the ronin-post_ex library for post-exploitation.
Provides a simple CLI for listing, displaying, running, and generating new exploits.
Has 9%% test coverage.
Has 86% documentation coverage.
Small memory footprint (~47Kb).

Anti-Features

No magic: exploits are defined as classes in files.
No global state that could cause memory leaks.
Not a big bulky framework, just a library.
Not a central repository. Additional Ronin exploits can be hosted in other git repositories. This prevents censorship of exploit research.
Does not contain any pre-written exploits. This prevents ronin-exploits from being taken down or censored.

Synopsis

Usage: ronin-exploits [options] [COMMAND [ARGS...]]

Options:
    -h, --help                       Print help information

Arguments:
    [COMMAND]                        The command name to run
    [ARGS ...]                       Additional arguments for the command

Commands:
    completion
    help
    irb
    list, ls
    new
    run
    show, info

Generate a new exploit file:

$ ronin-exploits new example_exploit.rb --type stack-overflow \
    --arch x86 --os linux --software ExampleWare --software-version 1.2.3 \
    --author Postmodern --author-email "postmodern.mod3@gmail.com" \
    --summary "Example exploit" --description "This is an example."

Install a 3rd-party repository of exploits:

$ ronin-repos install https://github.com/user/exploits.git

List available exploits:

$ ronin-exploits list

Print information about an exploit:

$ ronin-exploits show NAME

Print information about an exploit from a file:

$ ronin-exploits show -f path/to/exploit.rb

Run an exploit:

$ ronin-exploits run my_exploit --param host=example.com --param port=9999

Load an exploit from a specific file, then run it:

$ ronin-exploits run -f path/to/my_exploit.rb --param host=example.com --param port=9999

Run an exploit with a raw payload:

$ ronin-exploits run my_exploit --param host=example.com --param port=9999 \
    --payload-string $'\x66\x31\xc0\xfe\xc0\xb3\xff\xcd\x80'

Read a raw payload from a file:

$ ronin-exploits run my_exploit --param host=example.com --param port=9999 \
    --read-payload shellcode.bin

Generate a ronin repository of your own exploits (and/or payloads):

$ ronin-repos new my-repo
$ cd my-repo/
$ mkdir exploits
$ ronin-exploits new exploits/my_exploit.rb --type stack-overflow \
    --arch x86 --os linux --software ExampleWare --software-version 1.2.3 \
    --author You --author-email "you@example.com" \
    --summary "My exploit" --description "This is my example."
$ vim exploits/my_exploit.rb
$ git add exploits/my_exploit.rb
$ git commit
$ git push

Examples

Define a basic remote TCP exploit:

require 'ronin/exploits/exploit'
require 'ronin/exploits/mixins/remote_tcp'

module Ronin
  module Exploits
    class MyExploit < Exploit

      include Mixins::RemoteTCP

      register 'my_exploit'

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

      author '...'
      author '...', email: '...', twitter: '...'

      disclosure_date 'YYY-MM-DD'
      release_date 'YYYY-MM-DD'

      advisory 'CVE-YYYY-NNNN'
      advisory 'GHSA-XXXXXX'
      software 'TestHTTP'
      software_versions '1.0.0'..'1.5.4'

      param :cmd, desc: 'The command to run'

      def test
        # ...
      end

      def build
        # ...
      end

      def launch
        # ...
      end

      def cleanup
        # ...
      end

    end
  end
end

Define a Stack Overflow exploit:

require 'ronin/exploits/stack_overflow'
require 'ronin/exploits/mixins/remote_tcp'

module Ronin
  module Exploits
    class MyExploit < StackOverflow

      register 'my_exploit'

      include Mixins::RemoteTCP

      def build
        ebp = 0x06eb9090
        eip = 0x1001ae86

        @buffer = buffer_overflow(length: 1024, nops: 16, payload: payload, bp: ebp, ip: eip)
      end

      def launch
        tcp_send "USER #{@buffer}"
      end

    end
  end
end

Define a SEH Overflow exploit:

require 'ronin/exploits/seh_overflow'
require 'ronin/exploits/mixins/remote_tcp'

module Ronin
  module Exploits
    class MyExploit < SEHOverflow

      register 'my_exploit'

      include Mixins::RemoteTCP

      def build
        nseh = 0x06eb9090 # short jump 6 bytes
        seh  = 0x1001ae86 # pop pop ret 1001AE86 SSLEAY32.DLL

        @buffer = seh_buffer_overflow(length: 1024, nops: 16, payload: payload, nseh: nseh, seh: seh)
      end

      def launch
        tcp_send "USER #{@buffer}"
      end

    end
  end
end

Define a Command Injection exploit:

require 'ronin/exploits/command_injection'
require 'ronin/exploits/mixins/http'

module Ronin
  module Exploits
    class MyExploit < CommandInjection

      register 'my_exploit'

      include Mixins::HTTP

      def launch
        http_post '/form.php', post_data: {var: "';#{payload}#"}
      end

    end
  end
end

Define an Open Redirect exploit:

require 'ronin/exploits/open_redirect'

module Ronin
  module Exploits
    class MyExploit < OpenRedirect

      register 'my_exploit'

      base_path '/path/to/page.php'
      query_param 'url'

    end
  end
end

Define a Local File Inclusion (LFI) exploit:

require 'ronin/exploits/lfi'

module Ronin
  module Exploits
    class MyExploit < LFI

      register 'my_exploit'

      base_path '/path/to/page.php'
      query_param 'template'
      depth 7

    end
  end
end

Define a Remote File Inclusion (RFI) exploit:

require 'ronin/exploits/rfi'

module Ronin
  module Exploits
    class MyExploit < RFI

      register 'my_exploit'

      base_path '/path/to/page.php'
      query_param 'template'

    end
  end
end

Define a SQL injection (SQLi) exploit:

require 'ronin/exploits/sqli'

module Ronin
  module Exploits
    class MyExploit < SQLI

      register 'my_exploit'

      base_path '/path/to/page.php'
      query_param 'id'
      escape_quote true

    end
  end
end

Define a Server-Side Template Injection (SSTI) exploit:

require 'ronin/exploits/ssti'

module Ronin
  module Exploits
    class MyExploit < SSTI

      register 'my_exploit'

      base_path '/path/to/page.php'
      query_param 'name'
      escape_expr ->(expr) { "${{#{expr}}}" }

    end
  end
end

Define a Cross-Site Scripting (XSS) exploit:

require 'ronin/exploits/xss'

module Ronin
  module Exploits
    class MyExploit < XSS

      register 'my_exploit'

      base_path '/path/to/page.php'
      query_param 'title'

    end
  end
end

For real-world example ronin exploits, see the example-exploits repository.

Requirements

Ruby >= 3.0.0
uri-query_params ~> 0.6
ronin-support ~> 1.0
ronin-code-sql ~> 2.0
ronin-core ~> 0.2
ronin-repos ~> 0.1
ronin-payloads ~> 0.1
ronin-vulns ~> 0.1
ronin-post_ex ~> 0.1

Install

$ gem install ronin-exploits

Development

Fork It!
Clone It!
cd ronin-exploits
./scripts/setup
git checkout -b my_feature
Code It!
bundle exec rake spec
git push origin my_feature

Disclaimer

ronin-exploits does not contain any exploits of it's own, but is a library for writing and running 3rd party exploits. Therefor, ronin-exploits must not and should not be considered to be malicious software (malware) or malicious in nature.

License

ronin-exploits - A Ruby library for ronin-rb that provides exploitation and payload crafting functionality.

ronin-exploits is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

ronin-exploits 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 Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with ronin-exploits. If not, see https://www.gnu.org/licenses/.

ronin-rb / ronin-exploits

readme