ronin-exploits

CI Code Climate Gem Version

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

Anti-Features

  • No magic: exploits are defined as classes in files.
  • No global state: exploits are fully isolated and can be ran directly.
  • Not a monolithic framework: just a library.
  • Batteries not included: ronin-exploits does not contain any builtin exploits. Instead, additional exploits are hosted and installed from other git repositories. This prevents ronin-exploits from being taken down or restricted.

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:

shell $ ronin-exploits new example_exploit.rb --type stack-overflow \ --arch x86 --os linux --software ExampleWare --software-version 1.2.3 \ --author Postmodern --author-email "[email protected]" \ --summary "Example exploit" --description "This is an example."

Install a 3rd-party repository of exploits:

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

List available exploits:

shell $ ronin-exploits list

Print information about an exploit:

shell $ ronin-exploits show NAME

Print information about an exploit from a file:

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

Run an exploit:

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

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

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

Run an exploit with a raw payload:

shell $ 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:

shell $ 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):

shell $ 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 "[email protected]" \ --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:

```ruby 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:

```ruby 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:

```ruby 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:

```ruby 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:

```ruby 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:

```ruby 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:

```ruby 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:

```ruby 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:

```ruby 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:

```ruby 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

Install

shell $ gem install ronin-exploits

Development

  1. Fork It!
  2. Clone It!
  3. cd ronin-exploits
  4. ./scripts/setup
  5. git checkout -b my_feature
  6. Code It!
  7. bundle exec rake spec
  8. 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.

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

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/.