ronin-exploits 0.3.0 → 1.0.0.beta1

data/{History.txt → ChangeLog.md}

@@ -1,4 +1,104 @@
-=== 0.3.0 / 2009-09-24
+### 1.0.0 / 2023-XX-XX
+
+* Upgraded to the LGPL-3 license.
+* Require `ruby` >= 3.0.0.
+* Added [ronin-support] ~> 1.0 as a dependency.
+* Added [ronin-post_ex] ~> 0.1 as a dependency.
+* Added [ronin-payloads] ~> 0.1 as a dependency.
+* Added [ronin-vulns] ~> 0.1 as a dependency.
+* Added [ronin-core] ~> 0.1 as a dependency.
+* Added [ronin-repos] ~> 0.1 as a dependency.
+* Added {Ronin::Exploits::Advisory}.
+* Added {Ronin::Exploits::Loot}.
+* Added {Ronin::Exploits::Loot::File}.
+* Added {Ronin::Exploits::TestResult}.
+* Added {Ronin::Exploits::Exploit.exploit}.
+* Added {Ronin::Exploits::Exploit#perform_test}.
+* Added {Ronin::Exploits::Exploit#perform_build}.
+* Added {Ronin::Exploits::Exploit#perform_launch}.
+* Added {Ronin::Exploits::Exploit#perform_cleanup}.
+* Added {Ronin::Exploits::Exploit#exploit}.
+* Added {Ronin::Exploits::Exploit#validate}.
+* Added {Ronin::Exploits::Exploit#Vulnerable}.
+* Added {Ronin::Exploits::Exploit#NotVulnerable}.
+* Added {Ronin::Exploits::Exploit#Unknown}.
+* Added {Ronin::Exploits::Exploit#test}.
+* Added {Ronin::Exploits::Exploit#build}.
+* Added {Ronin::Exploits::Exploit#launch}.
+* Added {Ronin::Exploits::Exploit#cleanup}.
+* Added {Ronin::Exploits::MemoryCorruption}.
+* Added {Ronin::Exploits::StackOverflow}.
+* Added {Ronin::Exploits::SEHOverflow}.
+* Added {Ronin::Exploits::HeapOverflow}.
+* Added {Ronin::Exploits::UseAfterFree}.
+* Added {Ronin::Exploits::WebVuln}.
+* Added {Ronin::Exploits::OpenRedirect}.
+* Added {Ronin::Exploits::LFI}.
+* Added {Ronin::Exploits::RFI}.
+* Added {Ronin::Exploits::SQLI}.
+* Added {Ronin::Exploits::SSTI}.
+* Added {Ronin::Exploits::XSS}.
+* Added {Ronin::Exploits::ClientSideWebVuln}.
+* Added {Ronin::Exploits::Mixins::Binary}.
+* Added {Ronin::Exploits::Mixins::FileBuilder}.
+* Added {Ronin::Exploits::Mixins::FormatString}.
+* Added {Ronin::Exploits::Mixins::HasTargets}.
+* Added {Ronin::Exploits::Mixins::HasTargets}.
+* Added {Ronin::Exploits::Mixins::HasPayload}.
+* Added {Ronin::Exploits::Mixins::HTTP}.
+* Added {Ronin::Exploits::Mixins::Loot}.
+* Added {Ronin::Exploits::Mixins::NOPS}.
+* Added {Ronin::Exploits::Mixins::RemoteTCP}.
+* Added {Ronin::Exploits::Mixins::RemoteUDP}.
+* Added {Ronin::Exploits::Mixins::SEH}.
+* Added {Ronin::Exploits::Mixins::StackOverflow}.
+* Added {Ronin::Exploits::Mixins::Text}.
+* Added {Ronin::Exploits::Params::BaseURL}.
+* Added {Ronin::Exploits::Params::BindHost}.
+* Added {Ronin::Exploits::Params::BindPort}.
+* Added {Ronin::Exploits::Params::Filename}.
+* Added {Ronin::Exploits::Params::Host}.
+* Added {Ronin::Exploits::Params::Port}.
+* Renamed `ronin/exploits/helpers` to `ronin/exploits/mixins`.
+* Extracted `Ronin::Payloads` into [ronin-payloads].
+* Extracted agent payloads into separate `ronin-agent-` repos.
+  * [ronin-agent-php](https://github.com/ronin-rb/ronin-agent-php#readme)
+  * [ronin-agent-ruby](https://github.com/ronin-rb/ronin-agent-ruby#readme)
+  * [ronin-agent-nodejs](https://github.com/ronin-rb/ronin-agent-nodejs#readme)
+* Refactored the `ronin-exploit` command into the `ronin-exploits run` command.
+* Refactored {Ronin::Exploits::Exploit} as a Plain Old Ruby Class that defines
+  method data, params, and the `build`, `launch`, and `cleanup` methods.
+* Refactored `Ronin::UI` into {Ronin::Exploits::CLI}.
+* Removed the `open_namespace` dependency.
+* Removed the `data_paths` dependency.
+* Removed the `ronin-gen` dependency.
+* Removed the `ronin` dependency; `ronin` now requires `ronin-exploits` and all
+  other `ronin-` gems.
+* Removed `Ronin::Exploits::Controls`.
+* Removed `Ronin::Exploits::Generators` in favor of the `ronin-exploits new`
+  command.
+* Removed `Ronin::Exploits::UnknownHelper`.
+* Removed `Ronin::Exploits::Helpers::Padding` in favor of calling `String#pad`.
+* Removed `Ronin::Exploits::Exploit#helpers` in favor of `included_modules`.
+* Removed `Ronin::Exploits::Exploit#helper` in favor of including
+  {Ronin::Exploits::Mixins} modules.
+* Removed `Ronin::Exploits::Local`.
+* Removed `Ronin::Exploits::Remote`.
+* Removed `Ronin::Exploits::RemoteTCP` in favor of including
+  {Ronin::Exploits::Mixins::RemoteTCP}.
+* Removed `Ronin::Exploits::RemoteUDP` in favor of including
+  {Ronin::Exploits::Mixins::RemoteUDP}.
+* Removed `Ronin::Exploits::HTTP` in favor of including
+  {Ronin::Exploits::Mixins::HTTP}.
+* Removed `Ronin::Exploits::FTP`.
+* Removed all database models and code in favor of Plain Old Ruby Classes.
+
+### 0.3.1 / 2009-10-01
+
+* Removed duplicate `default_port` properties from Ronin::Exploits::FTP
+  and Ronin::Exploits::HTTP, which were causing dm-core 0.10.1 to crash.
+
+### 0.3.0 / 2009-09-24
 
 * Require ronin >= 0.3.0.
 * Require ronin-gen >= 0.2.0.
@@ -84,7 +184,7 @@
 * Removed Ronin::Payloads::Payload#payload to raw_payload.
 * Removed Ronin::Payloads::Payload#call.
 * Moved to YARD based documentation.
-* Updated the project summary and 3-point description for Ronin Exploits.
+* Updated the project summary and 3-point description for ronin-exploits.
 * Ronin::Model::TargetsArch now auto-defines a relationship with Arch.
 * Ronin::Model::TargetsOS now auto-defines a relationship with OS.
 * Ronin::Model::TargetsProduct now auto-defines a relationship with Product.
@@ -120,7 +220,7 @@
 * Made Ronin::Payloads::Payload#to_s more robust.
 * Safely load payload helpers using the new require_within method.
 
-=== 0.2.1 / 2009-07-02
+### 0.2.1 / 2009-07-02
 
 * Use Hoe >= 2.0.0.
 * Require ronin >= 0.2.4.
@@ -147,7 +247,7 @@
 * Allow Payload#controlling to accept multiple behaviors.
 * Added more specs.
 
-=== 0.2.0 / 2009-04-11
+### 0.2.0 / 2009-04-11
 
 * Added Ronin::TargetedArch.
 * Added Ronin::TargetedOS.
@@ -172,12 +272,12 @@
   * Removed the Ronin::Exploits::Requirement.
   * Rewrote Ronin::Exploits::Exploit:
     * Use the new Ronin::Cacheable module.
-    * Added a status property, which may be either <tt>:potential</tt>,
-      <tt>:proven</tt>, <tt>:weaponized</tt>, but will default to
-      <tt>:potential</tt>.
+    * Added a status property, which may be either `:potential`,
+      `:proven`, `:weaponized`, but will default to
+      `:potential`.
     * Added a disclosure property, which can be a combination of
-      <tt>:private</tt>, <tt>:in_wild</tt>, <tt>:vendor_aware</tt>
-      or <tt>:public</tt>.
+      `:private`, `:in_wild`, `:vendor_aware`
+      or `:public`.
     * Added Exploit#helper, which will extend the Exploit object with the
       Helper module with the similar name.
     * Added the Exploit#build!, Exploit#verify!, Exploit#deploy!
@@ -225,18 +325,18 @@
     * Removed encoders from the Payload class.
 * Added specs.
 
-=== 0.1.1 / 2009-01-22
+### 0.1.1 / 2009-01-22
 
-* Removed old references to the <tt>ronin/vulnerability</tt> directory.
+* Removed old references to the `ronin/vulnerability` directory.
 * Removed old references to the Ronin::Vulnerability namespace.
-* Removed past usage of the <tt>:value</tt> option with parameters.
-  * Parametes now uses the <tt>:default</tt> option, for specifying the
+* Removed past usage of the `:value` option with parameters.
+  * Parametes now uses the `:default` option, for specifying the
     default value of parameters.
 * Added the missing Ronin::Exploits::PayloadSize exception.
 * Reduce usage of first_or_create.
 * Updated target methods.
 
-=== 0.1.0 / 2008-01-08
+### 0.1.0 / 2008-01-08
 
 * Initial release.
   * Supports many basic exploit types:
@@ -254,3 +354,11 @@
     with Exploits and Payloads.
   * Provides a semi-intelligent XOR translator (Ronin::Translators::XOR).
 
+[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

data/Gemfile

@@ -0,0 +1,50 @@
+source 'https://rubygems.org'
+
+gemspec
+
+platforms :jruby do
+  gem 'jruby-openssl',	'~> 0.7'
+end
+
+# gem 'fake_io', '~> 0.1', github: 'postmodern/fake_io.rb',
+#                          branch: 'main'
+
+# gem 'command_kit', '~> 0.4', github: 'postmodern/command_kit.rb',
+#                              branch: 'main'
+
+# Ronin dependencies
+# gem 'ronin-support',  '~> 1.0', github: "ronin-rb/ronin-support",
+#                                 branch: 'main'
+# gem 'ronin-payloads', '~> 0.1', github: "ronin-rb/ronin-payloads",
+#                                 branch: 'main'
+# gem 'ronin-vulns',    '~> 0.1', github: "ronin-rb/ronin-vulns",
+#                                 branch: 'main'
+# gem 'ronin-post_ex',  '~> 0.1', github: "ronin-rb/ronin-post_ex",
+#                                 branch: 'main'
+# gem 'ronin-core',     '~> 0.1', github: "ronin-rb/ronin-core",
+#                                 branch: 'main'
+# gem 'ronin-repos',    '~> 0.1', github: "ronin-rb/ronin-repos",
+#                                 branch: 'main'
+# gem 'ronin-code-asm', '~> 1.0', github: "ronin-rb/ronin-code-asm",
+#                                 branch: 'main'
+# gem 'ronin-code-sql', '~> 2.0', github: "ronin-rb/ronin-code-sql",
+#                                 branch: 'main'
+
+group :development do
+  gem 'rake'
+
+  gem 'rubygems-tasks',  '~> 0.1'
+  gem 'rspec',           '~> 3.0'
+  gem 'simplecov',       '~> 0.20'
+
+  gem 'kramdown',	       '~> 2.0'
+  gem 'kramdown-man',    '~> 0.1'
+
+  gem 'redcarpet',       platform: :mri
+  gem 'yard',            '~> 0.9'
+  gem 'yard-spellcheck', require: false
+
+  gem 'dead_end',        require: false
+  gem 'sord',            require: false, platform: :mri
+  gem 'stackprof',       require: false, platform: :mri
+end

data/README.md

@@ -0,0 +1,454 @@
+# 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