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

“sage: 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: help irb list, ls new run show, info

“

Generate a new exploit file:

“ell $ 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:

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

“

List available exploits:

“ell $ ronin-exploits list

“

Print information about an exploit:

“ell $ ronin-exploits show NAME

“

Print information about an exploit from a file:

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

“

Run an exploit:

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

“

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

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

“

Run an exploit with a raw payload:

“ell $ 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:

“ell $ 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):

“ell $ 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:

“by 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:

“by 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:

“by 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 an Open Redirect exploit:

“by 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:

“by 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:

“by 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:

“by 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:

“by 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:

“by 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.1
ronin-repos ~> 0.1
ronin-payloads ~> 0.1
ronin-vulns ~> 0.1
ronin-post_ex ~> 0.1

Install

“ell $ gem install ronin-exploits

“

Development

Fork It!
Clone It!
cd ronin-exploits
bundle install
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/.