# ronin-exploits

[![CI](https://github.com/ronin-rb/ronin-exploits/actions/workflows/ruby.yml/badge.svg)](https://github.com/ronin-rb/ronin-exploits/actions/workflows/ruby.yml)
[![Code Climate](https://codeclimate.com/github/ronin-rb/ronin-exploits.svg)](https://codeclimate.com/github/ronin-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) |
  [Twitter](https://twitter.com/ronin_rb) |
  [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].

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:
  * Stack Overflows
  * SEH Overflows
  * Heap Overflows
  * Use After Free (UAF)
  * Open Redirect
  * Local File Inclusions (LFI)
  * Remote File Inclusions (RFI)
  * SQL injections (SQLi)
  * Cross-Site Scripting (XSS)
  * Server-Side Template Injection (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).

## 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-exploits
$ cd my-exploits/
$ 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
```

## 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-2022 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