README.md
# ronin-exploits
[](https://github.com/ronin-rb/ronin-exploits/actions/workflows/ruby.yml)
[](https://codeclimate.com/github/ronin-rb/ronin-exploits)
[](https://badge.fury.io/rb/ronin-exploits)
* [Source](https://github.com/ronin-rb/ronin-exploits)
* [Issues](https://github.com/ronin-rb/ronin-exploits/issues)
* [Documentation](https://rubydoc.info/github/ronin-rb/ronin-exploits/frames)
* [Discord](https://discord.gg/6WAb3PsVX9) |
[Mastodon](https://infosec.exchange/@ronin_rb)
## 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](https://www.metasploit.com/).
ronin-exploits is part of the [ronin-rb] project, a [Ruby] toolkit for security
research and development.
## Features
* Provides a succinct [syntax](#examples) and [API][docs-exploit] for writing
exploits in as few lines as possible.
* Supports [defining exploits as plain old Ruby classes][docs-exploit].
* 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:
* [Stack Overflows][docs-stack-overflow]
* [SEH Overflows][docs-seh-overflow]
* [Heap Overflows][docs-heap-overflow]
* [Use After Free (UAF)][docs-use-after-free]
* [Open Redirect][docs-open-redirect]
* [Local File Inclusions (LFI)][docs-lfi]
* [Remote File Inclusions (RFI)][docs-rfi]
* [SQL injections (SQLi)][docs-sqli]
* [Cross-Site Scripting (XSS)][docs-xss]
* [Server-Side Template Injection (SSTI)][docs-ssti]
* 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).
[docs-exploit]: https://ronin-rb.dev/docs/ronin-exploits/Ronin/Exploits/Exploit.html
[docs-stack-overflow]: https://ronin-rb.dev/docs/ronin-exploits/Ronin/Exploits/StackOverflow.html
[docs-seh-overflow]: https://ronin-rb.dev/docs/ronin-exploits/Ronin/Exploits/SEHOverflow.html
[docs-heap-overflow]: https://ronin-rb.dev/docs/ronin-exploits/Ronin/Exploits/HeapOverflow.html
[docs-use-after-free]: https://ronin-rb.dev/docs/ronin-exploits/Ronin/Exploits/UseAfterFree.html
[docs-open-redirect]: https://ronin-rb.dev/docs/ronin-exploits/Ronin/Exploits/OpenRedirect.html
[docs-lfi]: https://ronin-rb.dev/docs/ronin-exploits/Ronin/Exploits/LFI.html
[docs-rfi]: https://ronin-rb.dev/docs/ronin-exploits/Ronin/Exploits/RFI.html
[docs-sqli]: https://ronin-rb.dev/docs/ronin-exploits/Ronin/Exploits/SQLI.html
[docs-xss]: https://ronin-rb.dev/docs/ronin-exploits/Ronin/Exploits/XSS.html
[docs-ssti]: https://ronin-rb.dev/docs/ronin-exploits/Ronin/Exploits/SSTI.html
## 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:
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 "postmodern.mod3@gmail.com" \
--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 "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:
```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 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.
[example-exploits]: https://github.com/ronin-rb/example-exploits
## 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
```shell
$ gem install ronin-exploits
```
## Development
1. [Fork It!](https://github.com/ronin-rb/ronin-exploits/fork)
2. Clone It!
3. `cd ronin-exploits`
4. `bundle install`
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-2023 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/>.
[Ruby]: https://www.ruby-lang.org
[ronin-rb]: https://ronin-rb.dev
[uri-query_params]: https://github.com/postmodern/uri-query_params#readme
[ronin-support]: https://github.com/ronin-rb/ronin-support#readme
[ronin-code-sql]: https://github.com/ronin-rb/ronin-code-sql#readme
[ronin-core]: https://github.com/ronin-rb/ronin-core#readme
[ronin-repos]: https://github.com/ronin-rb/ronin-repos#readme
[ronin-payloads]: https://github.com/ronin-rb/ronin-payloads#readme
[ronin-post_ex]: https://github.com/ronin-rb/ronin-post_ex#readme
[ronin-vulns]: https://github.com/ronin-rb/ronin-vulns#readme