ronin-fuzzer 0.1.0.beta1

data/lib/ronin/fuzzing.rb

@@ -0,0 +1,365 @@
+#
+# ronin-fuzzer - A Ruby library for generating, mutating, and fuzzing data.
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# This file is part of ronin-fuzzer.
+#
+# ronin-fuzzer 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-fuzzer 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-fuzzer.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/fuzzing/fuzzer'
+require 'ronin/fuzzing/mutator'
+require 'ronin/fuzzing/repeater'
+require 'ronin/fuzzing/core_ext'
+
+require 'set'
+
+module Ronin
+  #
+  # Contains class-methods which generate malicious data for fuzzing.
+  #
+  # @see Fuzzing.[]
+  #
+  module Fuzzing
+    # Short String lengths
+    SHORT_LENGTHS = Set[1, 100, 500, 1_000, 10_000]
+
+    # Long String lengths
+    LONG_LENGTHS = Set[
+      128, 255, 256, 257, 511, 512, 513, 1023, 1024, 2048, 2049, 4095,
+      4096, 4097, 5_000, 10_000, 20_000, 32762, 32763, 32764, 32765, 32766,
+      32767, 32768, 32769,
+      0xffff-2, 0xffff-1, 0xffff, 0xffff+1, 0xffff+2,
+      99_999, 100_000, 500_000, 1_000_000
+    ]
+
+    # Null bytes in various encodings
+    NULL_BYTES = ['%00', '%u0000', "\x00"]
+
+    # Newline characters
+    NEW_LINES = ["\n", "\r", "\n\r"]
+
+    # Format String flags
+    FORMAT_STRINGS = ['%p', '%s', '%n']
+
+    #
+    # Returns a fuzzer method.
+    #
+    # @param [Symbol] name
+    #   The name of the fuzzer to return.
+    #
+    # @return [Enumerator]
+    #   An Enumerator for the fuzzer method.
+    #
+    # @raise [NoMethodError]
+    #   The fuzzing method could not be found.
+    #
+    # @api semipublic
+    #
+    def self.[](name)
+      if (!respond_to?(name) || Module.respond_to?(name))
+        raise(NoMethodError,"no such fuzzing method: #{name}")
+      end
+
+      return enum_for(name)
+    end
+
+    module_function
+
+    #
+    # Various bad-strings.
+    #
+    # @yield [string]
+    #   The given block will be passed each bad-string.
+    #
+    # @yieldparam [String] string
+    #   A bad-string containing known control characters, deliminators
+    #   or null-bytes (see {NULL_BYTES}), of varying length
+    #   (see {SHORT_LENGTHS} and {LONG_LENGTHS}).
+    #
+    def bad_strings(&block)
+      yield ''
+
+      chars = [
+        'A', 'a', '1', '<', '>', '"', "'", '/', "\\", '?', '=', 'a=', '&',
+        '.', ',', '(', ')', ']', '[', '%', '*', '-', '+', '{', '}',
+        "\x14", "\xfe", "\xff"
+      ]
+      
+      chars.each do |c|
+        LONG_LENGTHS.each { |length| yield c * length }
+      end
+
+      yield '!@#$%%^#$%#$@#$%$$@#$%^^**(()'
+      yield '%01%02%03%04%0a%0d%0aADSF'
+      yield '%01%02%03@%04%0a%0d%0aADSF'
+
+      NULL_BYTES.each do |c|
+        SHORT_LENGTHS.each { |length| yield c * length }
+      end
+
+      yield "%\xfe\xf0%\x00\xff"
+      yield "%\xfe\xf0%\x00\xff" * 20
+
+      SHORT_LENGTHS.each do |length|
+        yield "\xde\xad\xbe\xef" * length
+      end
+
+      yield "\n\r" * 100
+      yield "<>"   * 500
+    end
+
+    #
+    # Various format-strings.
+    #
+    # @yield [fmt_string]
+    #   The given block will be passed each format-string.
+    #
+    # @yieldparam [String] fmt_string
+    #   A format-string containing format operators (see {FORMAT_STRINGS}).
+    #
+    def format_strings(&block)
+      FORMAT_STRINGS.each do |fmt|
+        yield fmt
+        yield fmt * 100
+        yield fmt * 500
+        yield "\"#{fmt}\"" * 500
+      end
+    end
+
+    #
+    # Various bad paths and directory traversals.
+    #
+    # @yield [path]
+    #   The given block will be passed each path.
+    #
+    # @yieldparam [String] path
+    #   A known bad path.
+    #
+    def bad_paths(&block)
+      padding = 'A' * 5_000
+
+      yield "/.:/#{padding}\x00\x00"
+      yield "/.../#{padding}\x00\x00"
+
+      yield "\\\\*"
+      yield "\\\\?\\"
+
+      yield "/\\" * 5_000
+      yield '/.'  * 5_000
+
+      NULL_BYTES.each do |c|
+        if c.start_with?('%')
+          yield "#{c}/"
+          yield "/#{c}"
+          yield "/#{c}/"
+        end
+      end
+    end
+
+    #
+    # The range of bit-fields.
+    #
+    # @yield [bitfield]
+    #   The given block will be passed each bit-field.
+    #
+    # @yieldparam [String] bitfield
+    #   A bit-field (8bit - 64bit).
+    #
+    def bit_fields(&block)
+      ("\x00".."\xff").each do |c|
+        yield c
+        yield c << c # x2
+        yield c << c # x4
+        yield c << c # x8
+      end
+    end
+
+    #
+    # The range of signed bit-fields.
+    #
+    # @yield [bitfield]
+    #   The given block will be passed each bit-field.
+    #
+    # @yieldparam [String] bitfield
+    #   A signed bit-field (8bit - 64bit).
+    #
+    def signed_bit_fields(&block)
+      ("\x80".."\xff").each do |c|
+        yield c
+        yield c << c # x2
+        yield c << c # x4
+        yield c << c # x8
+      end
+    end
+
+    #
+    # The range of unsigned 8bit integers.
+    #
+    # @yield [int]
+    #   The given block will be passed each integer.
+    #
+    # @yieldparam [String] int
+    #   A unsigned 8bit integer.
+    #
+    def uint8(&block)
+      ("\x00".."\xff").each(&block)
+    end
+
+    #
+    # The range of unsigned 16bit integers.
+    #
+    # @yield [int]
+    #   The given block will be passed each integer.
+    #
+    # @yieldparam [String] int
+    #   A unsigned 16bit integer.
+    #
+    def uint16
+      uint8 { |c| yield c * 2 }
+    end
+
+    #
+    # The range of unsigned 32bit integers.
+    #
+    # @yield [int]
+    #   The given block will be passed each integer.
+    #
+    # @yieldparam [String] int
+    #   A unsigned 32bit integer.
+    #
+    def uint32
+      uint8 { |c| yield c * 4 }
+    end
+
+    #
+    # The range of unsigned 64bit integers.
+    #
+    # @yield [int]
+    #   The given block will be passed each integer.
+    #
+    # @yieldparam [String] int
+    #   A unsigned 64bit integer.
+    #
+    def uint64
+      uint8 { |c| yield c * 8 }
+    end
+
+    #
+    # The range of signed 8bit integers.
+    #
+    # @yield [int]
+    #   The given block will be passed each integer.
+    #
+    # @yieldparam [String] int
+    #   A signed 8bit integer.
+    #
+    def int8(&block)
+      ("\x00".."\x70").each(&block)
+    end
+
+    #
+    # The range of signed 16bit integers.
+    #
+    # @yield [int]
+    #   The given block will be passed each integer.
+    #
+    # @yieldparam [String] int
+    #   A signed 16bit integer.
+    #
+    def int16
+      int8 { |c| yield c * 2 }
+    end
+
+    #
+    # The range of signed 32bit integers.
+    #
+    # @yield [int]
+    #   The given block will be passed each integer.
+    #
+    # @yieldparam [String] int
+    #   A signed 32bit integer.
+    #
+    def int32
+      int8 { |c| yield c * 4 }
+    end
+
+    #
+    # The range of signed 64bit integers.
+    #
+    # @yield [int]
+    #   The given block will be passed each integer.
+    #
+    # @yieldparam [String] int
+    #   A signed 64bit integer.
+    #
+    def int64
+      int8 { |c| yield c * 8 }
+    end
+
+    #
+    # The range of negative-signed 8bit integers.
+    #
+    # @yield [int]
+    #   The given block will be passed each integer.
+    #
+    # @yieldparam [String] int
+    #   A negative-signed 8bit integer.
+    #
+    def sint8(&block)
+      ("\x80".."\xff").each(&block)
+    end
+
+    #
+    # The range of negative-signed 16bit integers.
+    #
+    # @yield [int]
+    #   The given block will be passed each integer.
+    #
+    # @yieldparam [String] int
+    #   A negative-signed 16bit integer.
+    #
+    def sint16
+      sint8 { |c| yield c * 2 }
+    end
+
+    #
+    # The range of negative-signed 32bit integers.
+    #
+    # @yield [int]
+    #   The given block will be passed each integer.
+    #
+    # @yieldparam [String] int
+    #   A negative-signed 32bit integer.
+    #
+    def sint32
+      sint8 { |c| yield c * 4 }
+    end
+
+    #
+    # The range of negative-signed 64bit integers.
+    #
+    # @yield [int]
+    #   The given block will be passed each integer.
+    #
+    # @yieldparam [String] int
+    #   A negative-signed 64bit integer.
+    #
+    def sint64
+      sint8 { |c| yield c * 8 }
+    end
+
+  end
+end

data/man/ronin-fuzzer-fuzz.1

@@ -0,0 +1,95 @@
+.\" Generated by kramdown-man 0.1.8
+.\" https://github.com/postmodern/kramdown-man#readme
+.TH ronin-fuzzer-fuzz 1 "2022-01-01" Ronin Fuzzer "User Manuals"
+.LP
+.SH SYNOPSIS
+.LP
+.HP
+\fBronin-fuzzer fuzz\fR \[lB]\fIoptions\fP\[rB] \[lB]\fITEMPLATE\fP\[rB]
+.LP
+.SH DESCRIPTION
+.LP
+.PP
+Fuzzes data read from a \fIFILE\fP or from \fBSTDIN\fR\. The fuzzed data can be written
+to output files, run in commands or sent to TCP\[sl]UDP services\.
+.LP
+.SH OPTIONS
+.LP
+.TP
+\fB-v\fR, \fB--[no-]verbose\fR
+Enable verbose output\.
+.LP
+.TP
+\fB-q\fR, \fB--[no-]quiet\fR
+Disable verbose output\.
+.LP
+.TP
+\fB--[no-]silent\fR
+Silence all output\.
+.LP
+.TP
+\fB-i\fR, \fB--input\fR \fIFILE\fP
+The input text FILE to parse\. Data will be read from \fBSTDIN\fR by default\.
+.LP
+.HP
+\fB-r\fR, \fB--rule\fR \[lB]\fIPATTERN\fP\[or]\fI\[sl]REGEXP\[sl]\fP\[or]STRING\[rB]:\[lB]\fIMETHOD\fP\[or]\fISTRING\fP\fI*N\fP\[lB]\-\fIM\fP\[rB]\[rB]
+The rule to apply to the \fIINPUT\fP\. Fuzzer rules consist of a pattern and 
+substitution\. Patterns may be one of the following:
+.LP
+.nf
+* A name of a Ronin Regular Expression (ex: \`unix\[ru]path\`)
+* A custom Regular Expression (ex: \`\[sl]\ed\[pl]\[sl]\`)
+* A plain String (ex: \`example\.com\`)\.
+
+  Substitutions may be one of the following:
+
+* A method from \`Ronin::Fuzzer\` (ex: \`bad\[ru]strings\`)
+* A *STRING*, repeated *N* or *M* times (ex: \`A*100\-200\`)\.
+.fi
+.LP
+.TP
+\fB-o\fR, \fB--output\fR \fIPATH\fP
+The output PATH to write the fuzzer to\.
+.LP
+.TP
+\fB-c\fR, \fB--command\fR \fICOMMAND\fP
+The command to run with the fuzzed data\. All ocurrences of \fB#string#\fR
+will be replaced with the fuzzed data, and ocurrences of \fB#path#\fR will
+be replaced with the path to the fuzzed data\.
+.LP
+.TP
+\fB-t\fR, \fB--tcp\fR \fIHOST\fP:\fIPORT\fP
+The TCP service to send the fuzzed data to\.
+.LP
+.TP
+\fB-u\fR, \fB--udp\fR \fIHOST\fP:\fIPORT\fP
+The UDP service to send the fuzzed data to\.
+.LP
+.TP
+\fB-p\fR, \fB--pause\fR \fISECONDS\fP
+Pause in between mutations\.
+.LP
+.SH EXAMPLES
+.LP
+.TP
+\fBronin-fuzzer fuzz -i http_request.txt -o bad.txt -r unix_path:bad_strings\fR
+Fuzzes a HTTP request, replacing every occurrence of a UNIX path, with
+strings from the \fBbad_strings\fR method\.
+.LP
+.SH LINKS
+.LP
+.PP
+Ronin Regular Expressions
+https:\[sl]\[sl]ronin\-rb\.dev\[sl]docs\[sl]ronin\-support\[sl]Regexp\.html
+.LP
+.TP
+\fBRonin::Fuzzer\fR
+https:\[sl]\[sl]ronin\-rb\.dev\[sl]docs\[sl]ronin\-fuzzer\[sl]Ronin\[sl]Fuzzer\.html
+.LP
+.SH AUTHOR
+.LP
+.PP
+Postmodern 
+.MT postmodern\.mod3\[at]gmail\.com
+.ME
+.LP

data/man/ronin-fuzzer-fuzz.1.md

@@ -0,0 +1,73 @@
+# ronin-fuzzer-fuzz 1 "2022-01-01" Ronin Fuzzer "User Manuals"
+
+## SYNOPSIS
+
+`ronin-fuzzer fuzz` [*options*] [*TEMPLATE*]
+
+## DESCRIPTION
+
+Fuzzes data read from a *FILE* or from `STDIN`. The fuzzed data can be written
+to output files, run in commands or sent to TCP/UDP services.
+
+## OPTIONS
+
+`-v`, `--[no-]verbose`
+	Enable verbose output.
+
+`-q`, `--[no-]quiet`
+	Disable verbose output.
+
+`--[no-]silent`
+	Silence all output.
+
+`-i`, `--input` *FILE*
+	The input text FILE to parse. Data will be read from `STDIN` by default.
+
+`-r`, `--rule` [*PATTERN*|*/REGEXP/*|STRING]:[*METHOD*|*STRING***N*[-*M*]]
+	The rule to apply to the *INPUT*. Fuzzer rules consist of a pattern and 
+	substitution. Patterns may be one of the following:
+
+	* A name of a Ronin Regular Expression (ex: `unix_path`)
+	* A custom Regular Expression (ex: `/\d+/`)
+	* A plain String (ex: `example.com`).
+
+	  Substitutions may be one of the following:
+
+	* A method from `Ronin::Fuzzer` (ex: `bad_strings`)
+	* A *STRING*, repeated *N* or *M* times (ex: `A*100-200`).
+
+`-o`, `--output` *PATH*
+	The output PATH to write the fuzzer to.
+
+`-c`, `--command` *COMMAND*
+	The command to run with the fuzzed data. All ocurrences of `#string#`
+	will be replaced with the fuzzed data, and ocurrences of `#path#` will
+	be replaced with the path to the fuzzed data.
+
+`-t`, `--tcp` *HOST*:*PORT*
+	The TCP service to send the fuzzed data to.
+
+`-u`, `--udp` *HOST*:*PORT*
+	The UDP service to send the fuzzed data to.
+
+`-p`, `--pause` *SECONDS*
+  Pause in between mutations.
+
+## EXAMPLES
+
+`ronin-fuzzer fuzz -i http_request.txt -o bad.txt -r unix_path:bad_strings`
+	Fuzzes a HTTP request, replacing every occurrence of a UNIX path, with
+	strings from the `bad_strings` method.
+
+## LINKS
+
+Ronin Regular Expressions
+	https://ronin-rb.dev/docs/ronin-support/Regexp.html
+
+`Ronin::Fuzzer`
+	https://ronin-rb.dev/docs/ronin-fuzzer/Ronin/Fuzzer.html
+
+## AUTHOR
+
+Postmodern <postmodern.mod3@gmail.com>
+

data/ronin-fuzzer.gemspec

@@ -0,0 +1,61 @@
+# encoding: utf-8
+
+require 'yaml'
+
+Gem::Specification.new do |gem|
+  gemspec = YAML.load_file('gemspec.yml')
+
+  gem.name    = gemspec.fetch('name')
+  gem.version = gemspec.fetch('version') do
+                  lib_dir = File.join(File.dirname(__FILE__),'lib')
+                  $LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
+
+                  require 'ronin/fuzzer/version'
+                  Ronin::Fuzzer::VERSION
+                end
+
+  gem.summary     = gemspec['summary']
+  gem.description = gemspec['description']
+  gem.licenses    = Array(gemspec['license'])
+  gem.authors     = Array(gemspec['authors'])
+  gem.email       = gemspec['email']
+  gem.homepage    = gemspec['homepage']
+  gem.metadata    = gemspec['metadata'] if gemspec['metadata']
+  
+  glob = lambda { |patterns| gem.files & Dir[*patterns] }
+
+  gem.files  = `git ls-files`.split($/)
+  gem.files  = glob[gemspec['files']] if gemspec['files']
+  gem.files += Array(gemspec['generated_files'])
+
+  gem.executables = gemspec.fetch('executables') do
+    glob['bin/*'].map { |path| File.basename(path) }
+  end
+
+  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') {
+    %w[ext lib].select { |dir| File.directory?(dir) }
+  })
+
+  gem.requirements              = gemspec['requirements']
+  gem.required_ruby_version     = gemspec['required_ruby_version']
+  gem.required_rubygems_version = gemspec['required_rubygems_version']
+  gem.post_install_message      = gemspec['post_install_message']
+
+  split = lambda { |string| string.split(/,\s*/) }
+
+  if gemspec['dependencies']
+    gemspec['dependencies'].each do |name,versions|
+      gem.add_dependency(name,split[versions])
+    end
+  end
+
+  if gemspec['development_dependencies']
+    gemspec['development_dependencies'].each do |name,versions|
+      gem.add_development_dependency(name,split[versions])
+    end
+  end
+end

data/spec/core_ext/string_spec.rb

@@ -0,0 +1,87 @@
+require 'spec_helper'
+require 'ronin/fuzzing/core_ext/string'
+
+describe String do
+  it "should provide String.generate" do
+    expect(described_class).to respond_to(:generate)
+  end
+
+  it "should provide String#repeating" do
+    expect(subject).to respond_to(:repeating)
+  end
+
+  it "should provide String#fuzz" do
+    expect(subject).to respond_to(:fuzz)
+  end
+
+  it "should provide String#mutate" do
+    expect(subject).to respond_to(:mutate)
+  end
+
+  describe "generate" do
+    subject { described_class }
+
+    it "should generate Strings from a template" do
+      strings = subject.generate([:numeric, 2]).to_a
+
+      expect(strings.grep(/^[0-9]{2}$/)).to eq(strings)
+    end
+  end
+
+  describe "#repeating" do
+    subject { 'A' }
+
+    context "when n is an Integer" do
+      let(:n) { 100 }
+
+      it "should multiply the String by n" do
+        expect(subject.repeating(n)).to eq(subject * n)
+      end
+    end
+
+    context "when n is Enumerable" do
+      let(:n) { [128, 512, 1024] }
+
+      it "should repeat the String by each length" do
+        strings = subject.repeating(n).to_a
+
+        expect(strings).to eq(n.map { |length| subject * length })
+      end
+    end
+  end
+
+  describe "#fuzz" do
+    subject { "foo bar" }
+
+    it "should apply each fuzzing rule individually" do
+      strings = subject.fuzz(/o/ => ['O', '0'], /a/ => ['A', '@']).to_a
+      
+      expect(strings).to match_array([
+        "fOo bar",
+        "f0o bar",
+        "foO bar",
+        "fo0 bar",
+        "foo bAr",
+        "foo b@r"
+      ])
+    end
+  end
+
+  describe "#mutate" do
+    subject { "foo bar" }
+
+    it "should apply every combination of mutation rules" do
+      strings = subject.mutate(/o/ => ['0'], /a/ => ['@']).to_a
+
+      expect(strings).to match_array([
+        "f0o bar",
+        "fo0 bar",
+        "f00 bar",
+        "foo b@r",
+        "f0o b@r",
+        "fo0 b@r",
+        "f00 b@r"
+      ])
+    end
+  end
+end