Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ronin-rb/ronin-exploits

A Ruby micro-framework for writing and running exploits
https://github.com/ronin-rb/ronin-exploits

ctf-tools exploit exploit-development exploitation-framework hacking-tools hacktoberfest infosec ruby security security-tools

Last synced: 2 months ago
JSON representation

A Ruby micro-framework for writing and running exploits

Awesome Lists containing this project

README 

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

[![Gem Version](https://badge.fury.io/rb/ronin-exploits.svg)](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]

  * [Command Injection][docs-command-injection]

  * [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-command-injection]: https://ronin-rb.dev/docs/ronin-exploits/Ronin/Exploits/CommandInjection.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:

    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.



[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.2

* [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. `./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-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 .



[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#readm