ronin-exploits

CI Code Climate

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:

$ 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:

$ 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-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 "[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:

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

Requirements

Install

$ gem install ronin-exploits

Development

  1. Fork It!
  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/.