ronin-exploits 1.0.0.beta2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b7d601e1580ea5719c365a686d579659df4deb60d77eff285d74ac1280d93b3
-  data.tar.gz: 87e9cef6168d40862c0442aabdaaa69d51563cbae6ff93abb8a3c4c0ef0b6704
+  metadata.gz: f4fb437a6634a2eef3dae27f5d940718e94d1e5d7839113e9b02d849daeb2f81
+  data.tar.gz: 661bbae01973ba0ec2e367abef7fd137534dff1597b8486dde94e64afcc6e780
 SHA512:
-  metadata.gz: 37e77fed488fdcfed0357d792738b3bb231cbeae749631291aa12544a8b225ca14fe548cf70985ae88d9946f5e1f8ead8c1d0078d486fa4d0ed837b33fca9aa6
-  data.tar.gz: e032ca57e0b63ca63b93e79d6479c631a8939eaa5406d4d4d68bafebfd5b16ffdfc5e6f58f245440036ec0f2869937709c84cf915ce78e10efc4fb03c0bcc303
+  metadata.gz: 9c40d3ba6b13842ddb66b762cac6aaa26a22f3feb03a8f68abf1fdc7d90696fb4cc03da0fd4472ea77af9e861eb92cf4a7165a5fc023b4ecb4e59f0ef13fa234
+  data.tar.gz: 8b81f266e3b256f028a01b1d10a85d0d1d09cfbcdfecab07e5bf25ebae0f96adee5b7881515eb4cfaccae5ae0e4807377315f50db9213ab5268b179db3e87640

data/.github/workflows/ruby.yml

@@ -21,6 +21,7 @@ jobs:
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
       - name: Install libsqlite3
         run: |
           sudo apt update -y && \

data/README.md

@@ -2,6 +2,7 @@
 
 [![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)
@@ -17,27 +18,30 @@ 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 and API for writing exploits in as few lines as
-  possible.
-* Supports defining exploits as plain old Ruby classes.
+* 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
-  * 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)
+  * [Stack Overflows][docs-stack-overflow]
+  * [SEH Overflows][docs-seh-overflow]
+  * [Heap Overflows][docs-heap-overflow]
+  * [Use After Free (UAF)][docs-use-after-free]
+  * [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
@@ -46,6 +50,18 @@ research and development.
 * 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-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.

data/gemspec.yml

@@ -1,11 +1,13 @@
 name: ronin-exploits
 summary: A Ruby micro-framework for writing and running exploits and payloads.
-description:
+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-reps.
 
+  It's like a simpler version of Metasploit.
+
 license: LGPL-3.0
 authors: Postmodern
 email: postmodern.mod3@gmail.com
@@ -32,13 +34,13 @@ generated_files:
 dependencies:
   uri-query_params: ~> 0.6
   # Ronin dependencies:
-  ronin-support: ~> 1.0.0.beta1
-  ronin-code-sql: ~> 2.0.0.beta1
-  ronin-payloads: ~> 0.1.0.beta1
-  ronin-vulns: ~> 0.1.0.beta1
-  ronin-post_ex: ~> 0.1.0.beta1
-  ronin-core: ~> 0.1.0.beta1
-  ronin-repos: ~> 0.1.0.beta1
+  ronin-support: ~> 1.0
+  ronin-code-sql: ~> 2.0
+  ronin-payloads: ~> 0.1
+  ronin-vulns: ~> 0.1
+  ronin-post_ex: ~> 0.1
+  ronin-core: ~> 0.1
+  ronin-repos: ~> 0.1
 
 development_dependencies:
   bundler: ~> 2.0

data/lib/ronin/exploits/cli/commands/new.rb

@@ -252,7 +252,7 @@ module Ronin
           man_page 'ronin-exploits-new.1'
 
           #
-          # Initialies the `ronin-exploits new` command.
+          # Initializes the `ronin-exploits new` command.
           #
           # @param [Hash{Symbol => Object}] kwargs
           #   Additional keyword arguments.

data/lib/ronin/exploits/cli/commands/run.rb

@@ -118,7 +118,11 @@ module Ronin
                                    type: /\A[^=\s]+=.+\z/,
                                    usage: 'NAME=VALUE'
                                  },
-                                 desc: 'Sets a param on the payload'
+                                 desc: 'Sets a param on the payload' do |param|
+                                   name, value = param.split('=',2)
+
+                                   @payload_params[name.to_sym] = value
+                                 end
 
           # Encoder options
           option :encoder_file, value: {
@@ -228,6 +232,7 @@ module Ronin
 
             @load_encoders  = []
             @encoder_params = Hash.new { |hash,key| hash[key] = {} }
+            @payload_params = {}
             @target_kwargs  = {}
           end
 
@@ -244,6 +249,7 @@ module Ronin
             load_payload
             initialize_encoders
             initialize_payload
+            validate_payload
             initialize_exploit
             validate_exploit
             run_exploit
@@ -257,6 +263,10 @@ module Ronin
             perform_cleanup
           end
 
+          #
+          # Loads the payload encoder classes specified by `--encoder` or
+          # `--encoder-file`.
+          #
           def load_encoders
             @encoder_classes = @load_encoders.map do |(type,value)|
               case type
@@ -266,12 +276,20 @@ module Ronin
             end
           end
 
+          #
+          # Initializes the payload encoders specified by `--encoder` or
+          # `--encoder-file`.
+          #
           def initialize_encoders
             @encoders = @encoder_classes.map do |encoder_class|
               encoder_class.new(params: @encoder_params[encoder_class.id])
             end
           end
 
+          #
+          # Loads the payload class specified by `--payload` or
+          # `--payload-file`.
+          #
           def load_payload
             @payload_class = if options[:payload]
                                super(options[:payload])
@@ -280,6 +298,10 @@ module Ronin
                              end
           end
 
+          #
+          # Initializes the payload specified by `--payload`, `--payload-file`,
+          # `--read-payload`, or `--payload-string`.
+          #
           def initialize_payload
             @payload = if @payload_class
                          super(@payload_class, params:   @payload_params,
@@ -291,6 +313,16 @@ module Ronin
                        end
           end
 
+          #
+          # Validates the payload.
+          #
+          def validate_payload
+            super(@payload)
+          end
+
+          #
+          # Initializes the exploit.
+          #
           def initialize_exploit
             kwargs = {params: @params}
 
@@ -309,13 +341,16 @@ module Ronin
             super(**kwargs)
           end
 
+          #
+          # Runs the exploit.
+          #
           def run_exploit
             log_info "Running exploit #{@exploit.class_id} ..."
 
             begin
               @exploit.exploit(dry_run: options[:dry_run])
             rescue ExploitError => error
-              print_error("failed to run exploit #{@exploit.class_id}: #{error.message}")
+              print_error "failed to run exploit #{@exploit.class_id}: #{error.message}"
               exit(1)
             rescue => error
               print_exception(error)
@@ -324,6 +359,9 @@ module Ronin
             end
           end
 
+          #
+          # Starts an interactive ruby shell within the exploit object.
+          #
           def start_shell
             log_info "Exploit #{@exploit.class_id} launched!"
             log_info "Starting interactive Ruby shell ..."
@@ -331,12 +369,15 @@ module Ronin
             RubyShell.start(name: @exploit_class.name, context: @exploit)
           end
 
+          #
+          # Performs the post-exploitation stage.
+          #
           def post_exploitation
             if @exploit_class.include?(Mixins::HasPayload) &&
                @exploit.payload.kind_of?(Ronin::Payloads::Payload) &&
-               @exploit.payload.kind_of?(Ronin::Payloads::Mixins::PostExt)
+               @exploit.payload.kind_of?(Ronin::Payloads::Mixins::PostEx)
               unless @exploit.payload.session
-                print_error("payload (#{@exploit.payload.class_id}) did not create a post-exploitation session")
+                print_error "payload (#{@exploit.payload.class_id}) did not create a post-exploitation session"
 
                 perform_cleanup
                 eixt(1)
@@ -349,6 +390,9 @@ module Ronin
             end
           end
 
+          #
+          # Prints any loot collected by the exploit.
+          #
           def print_loot
             unless @exploit.loot.empty?
               log_info "Exploit found the following loot:"
@@ -372,15 +416,21 @@ module Ronin
             end
           end
 
+          #
+          # Saves the collected loot to the `--save-loot` directory.
+          #
           def save_loot
             @exploit.loot.save(options.fetch(:save_loot))
           end
 
+          #
+          # Performs the cleanup stage of the exploit.
+          #
           def perform_cleanup
             begin
               @exploit.perform_cleanup
             rescue ExploitError => error
-              print_error("failed to cleanup exploit #{@exploit.class_id}: #{error.message}")
+              print_error "failed to cleanup exploit #{@exploit.class_id}: #{error.message}"
               exit(1)
             rescue => error
               print_exception(error)

data/lib/ronin/exploits/exploit.rb

@@ -52,7 +52,7 @@ module Ronin
     # The {Exploit} class defines six key parts:
     #
     # 1. Metadata - defines information about the exploit.
-    # 2. Params - user configurable parameters.
+    # 2. [Params] - user configurable parameters.
     # 3. {Exploit#test test} - optional method that tests whether the target is
     #    vulnerable or not.
     # 4. {Exploit#build build} - method which builds the exploit.
@@ -60,6 +60,8 @@ module Ronin
     # 6. {Exploit#cleanup cleanup} - optional Method which performs additional
     #    cleanup steps.
     #
+    # [Params]: https://ronin-rb.dev/docs/ronin-core/Ronin/Core/Params/Mixin.html
+    #
     # ## Example
     # 
     #     require 'ronin/exploits/exploit'
@@ -136,7 +138,7 @@ module Ronin
     #
     # ### description
     #
-    # Defines a longer multi-paragraph escription of the exploit.
+    # Defines a longer multi-paragraph description of the exploit.
     #
     #     description <<~EOS
     #       This is my first exploit.
@@ -313,7 +315,7 @@ module Ronin
       end
 
       #
-      # Determines whether the exploit has been publically released yet.
+      # Determines whether the exploit has been publicly released yet.
       #
       # @return [Boolean]
       #
@@ -526,7 +528,7 @@ module Ronin
       end
 
       #
-      # Builds the exploit and then launchs the exploit.
+      # Builds the exploit and then launches the exploit.
       #
       # @param [Boolean] dry_run
       #   If `true` performs a dry-run by only calling {#build} and **not**
@@ -633,7 +635,7 @@ module Ronin
       end
 
       #
-      # Place holder method for testing whether the targeet is vulnerable.
+      # Place holder method for testing whether the target is vulnerable.
       #
       # @return [Test::Vulnerable, Test::NotVulnerable, Test::Unknown]
       #

data/lib/ronin/exploits/lfi.rb

@@ -73,7 +73,7 @@ module Ronin
       # Gets or sets the directory traversal depth for the LFI vulnerability.
       #
       # @param [Integer, nil] new_depth
-      #   The optional new directory trasversal depth to set.
+      #   The optional new directory traversal depth to set.
       #
       # @return [Integer]
       #   The LFI vulnerability's directory traverse depth.

data/lib/ronin/exploits/metadata/arch.rb

@@ -40,7 +40,7 @@ module Ronin
 
         module ClassMethods
           #
-          # Gets or sets the exploits's targetted architecture.
+          # Gets or sets the exploit's targeted architecture.
           #
           # @param [:x86, :x86_64, :ia64, :amd64, :ppc, :ppc64, :mips, :mips_le, :mips_be, :mips64, :mips64_le, :mips64_be, :arm, :arm_le, :arm_be, :arm64, :arm64_le, :arm64_be, nil] new_arch
           #   The optional new architecture to set.

data/lib/ronin/exploits/metadata/default_filename.rb

@@ -40,7 +40,7 @@ module Ronin
 
         module ClassMethods
           #
-          # Gets or sets the exploits's default filename.
+          # Gets or sets the exploit's default filename.
           #
           # @param [Integer, nil] new_default_filename
           #   The optional new default filename to set.

data/lib/ronin/exploits/metadata/default_port.rb

@@ -40,7 +40,7 @@ module Ronin
 
         module ClassMethods
           #
-          # Gets or sets the exploits's default port.
+          # Gets or sets the exploit's default port.
           #
           # @param [Integer, nil] new_default_port
           #   The optional new default port number to set.

data/lib/ronin/exploits/mixins/file_builder.rb

@@ -24,8 +24,8 @@ module Ronin
   module Exploits
     module Mixins
       #
-      # Adds methods for building exploit files. Also adds a `filenam`
-      # param and a
+      # Adds methods for building exploit files. Also adds a `filename` param
+      # and a
       # {Metadata::DefaultFilename::ClassMethods#default_filename default_filename}
       # class method.
       #

data/lib/ronin/exploits/mixins/nops.rb

@@ -81,7 +81,7 @@ module Ronin
         end
 
         #
-        # An individual NOP instructure for the target architecture of the
+        # An individual NOP instruction for the target architecture of the
         # exploit.
         #
         # @return [String]

data/lib/ronin/exploits/params/base_url.rb

@@ -64,7 +64,7 @@ module Ronin
         end
 
         #
-        # Expands the URL or path into a fully qualitifed URL.
+        # Expands the URL or path into a fully qualified URL.
         #
         # @param [String] path
         #   The URL or path to expand.

data/lib/ronin/exploits/version.rb

@@ -21,6 +21,6 @@
 module Ronin
   module Exploits
     # ronin-exploits version
-    VERSION = '1.0.0.beta2'
+    VERSION = '1.0.0'
   end
 end

data/ronin-exploits.gemspec

@@ -27,6 +27,8 @@ Gem::Specification.new do |gem|
   gem.files  = `git ls-files`.split($/)
   gem.files  = glob[gemspec['files']] if gemspec['files']
   gem.files += Array(gemspec['generated_files'])
+  # exclude test files from the packages gem
+  gem.files -= glob[gemspec['test_files'] || 'spec/{**/}*']
 
   gem.executables = gemspec.fetch('executables') do
     glob['bin/*'].map { |path| File.basename(path) }
@@ -34,7 +36,6 @@ Gem::Specification.new do |gem|
   gem.default_executable = gem.executables.first if Gem::VERSION < '1.7.'
 
   gem.extensions       = glob[gemspec['extensions'] || 'ext/**/extconf.rb']
-  gem.test_files       = glob[gemspec['test_files'] || 'spec/{**/}*_spec.rb']
   gem.extra_rdoc_files = glob[gemspec['extra_doc_files'] || '*.{txt,md}']
 
   gem.require_paths = Array(gemspec.fetch('require_paths') {