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.
Copyright (c) 2007-2024 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/.