afl 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f00f7dee91372b0f75e94feb6f5b975cec6fe451d368eb8b5541026e2fc10f0c
+  data.tar.gz: 9a061469bb4a76d80c978f11bb9199256c62ac84cc9dc783cac08636c8a18c30
+SHA512:
+  metadata.gz: 88ce3e69b1f776b4c5e5057522ff1d8d49f570ca29021d46c709149e367fb0a433ee5ac4f2dfe36a0ab8f012f56c330e9a05649d6f8f6147b6a65ce824154eb9
+  data.tar.gz: 22e2509c7800ce93037348bf65dc97e6c270eab32abd39b9a57aa1fed289cd1e2bc647cf3dae3e80dfe9a12accffdf0c6cf12389e11ce88874e86a84a5001086

data/.gitignore

@@ -0,0 +1,12 @@
+benchmarks/minimal/output/*
+
+example/work/output/*
+
+lib/afl/afl.bundle
+lib/afl/afl.o
+lib/afl/Makefile
+
+test/output/*
+test/input/*
+
+*.gem

data/LICENSE

@@ -0,0 +1,44 @@
+afl-ruby is licensed under the MIT license:
+
+Copyright (c) 2018- Stripe, Inc. (https://stripe.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+afl-ruby contains code directly dirived and based upon code from afl-python,
+also released under the MIT license:
+
+Copyright © 2013-2017 Jakub Wilk <jwilk@jwilk.net>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/Makefile

@@ -0,0 +1,21 @@
+VERSION=0.0.0
+
+# Debug pretty printer
+print-%: ; @echo $*=$($*)
+
+default: build uninstall install
+
+build:
+	gem build afl.gemspec
+
+uninstall:
+	gem uninstall --ignore-dependencies afl
+
+install:
+	gem install --verbose afl-${VERSION}.gem
+
+test: default
+	ruby harness.rb
+
+.PHONY: build install uninstall default test
+.DEFAULT: default

data/README.md

@@ -0,0 +1,108 @@
+# afl-ruby
+
+AFL for Ruby! You can learn more about AFL itself [here](http://lcamtuf.coredump.cx/afl/).
+
+## Getting Started
+
+### 0. Clone the repo
+
+`afl-ruby` is not yet available on Rubygems, so for now you'll have to clone and build it yourself.
+
+    git clone git@github.com:richo/afl-ruby.git
+
+### 1. Build the extension
+
+You will need to manually build the native extension to the Ruby interpreter in order to allow AFL to instrument your Ruby code. To do this:
+
+    cd lib/afl
+    ruby ../../ext/afl/extconf.rb
+    make
+
+### 2. Instrument your code
+
+To instrument your code for AFL, call `AFL.init` when you're ready to initialize the AFL forkserver,
+then wrap the block of code that you want to fuzz in `AFL.with_exceptions_as_crashes { ... }`. For
+example:
+
+```ruby
+def byte
+  $stdin.read(1)
+end
+
+def c
+  r if byte == 'r'
+end
+
+def r
+  s if byte == 's'
+end
+
+def s
+  h if byte == 'h'
+end
+
+def h
+  raise "Crashed"
+end
+
+require 'afl'
+
+unless ENV['NO_AFL']
+  AFL.init
+end
+
+AFL.with_exceptions_as_crashes do
+  c if byte == 'c'
+  exit!(0)
+end
+```
+
+### 3. Patch AFL
+
+AFL checks if you're an instrumented binary by seeing if you have the AFL environment variable anywhere in your binary. We're using a bog stock ruby interpreter, so we can't do that. Apply `afl-fuzz.c.patch` before building AFL to remove this check. Assuming you have cloned `afl` and `afl-ruby` in the same directory (i.e. in `~/MYCODE/afl` and `~/MYCODE/afl-ruby`) you can do this by:
+
+    cd ../afl
+    git checkout -b apply-ruby-patch
+    git apply ../afl-fuzz.c.patch
+    git add .
+    git commit -m "Apply Ruby patch"
+    make install
+    # Check that this did indeed update your AFL
+    ls -la $(which afl-fuzz)
+
+### 4. Run the example
+
+You should then be able to run the sample harness in the `example/` directory:
+
+    /path/to/afl/afl-fuzz -i example/work/input -o example/work/output -- /usr/bin/ruby example/harness.rb
+
+It should only take a few seconds to find a crash. Once a crash is found it should be written to `example/work/output/crashes/` for you to inspect.
+
+### Troubleshooting
+
+If AFL complains that `Program '/usr/bin/ruby' is not a 64-bit Mach-O binary` then this may be because your system Ruby has the old Mach-O magic header bytes, which AFL does not accept. You should try running `afl-fuzz` using a different Ruby interpreter. For example, you can use an rbenv Ruby like so:
+
+    # Find out which versions rbenv has available
+    ls ~/.rbenv/versions
+    # Pick an available version, then run something like this:
+    /path/to/afl/afl-fuzz -i work/input -o work/output -- ~/.rbenv/versions/2.4.1/bin/ruby harness.rb
+
+# Developing
+
+## Extensions
+
+Be sure to build the C extension (see "Build the extension" above).
+
+## Tests
+
+To run the basic test suite, simply run:
+
+    rake test
+
+Make sure you have built the extension and patched AFL first, as above.
+
+# Credits
+
+Substantial portions of afl-ruby are either inspired by, or transposed directly from afl-python by Jakub Wilk <jwilk@jwilk.net> licensed under MIT.
+
+[Stripe](https://stripe.com) allowed both myself and [rob](https://github.com/robert) to spend substantial amounts of company time developing afl-ruby.

data/Rakefile

@@ -0,0 +1,4 @@
+task :default => :test
+task :test do
+  Dir.glob('./test/*_test.rb').each { |file| require file}
+end

data/afl-fuzz.c.patch

@@ -0,0 +1,11 @@
+--- afl-fuzz.c.orig	2018-02-16 16:38:20.388534866 +0000
++++ afl-fuzz.c	2018-02-16 16:38:30.464519660 +0000
+@@ -6917,7 +6917,7 @@
+          "    For that, you can use the -n option - but expect much worse results.)\n",
+          doc_path);
+ 
+-    FATAL("No instrumentation detected");
++    // FATAL("No instrumentation detected");
+ 
+   }
+ 

data/afl.gemspec

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.push lib unless $LOAD_PATH.include? lib
+require 'afl/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'afl'
+  s.version     = AFL::VERSION
+  s.authors     = ['Richo Healey']
+  s.email       = ['richo@psych0tik.net']
+  s.homepage    = 'http://github.com/richo/afl-ruby'
+  s.summary     = 'AFL support for ruby'
+  s.description = 'American Fuzzy Lop (AFL) support for ruby'
+  s.license     = 'MIT'
+
+  s.files         = `git ls-files -z`.split("\0")
+  s.test_files    = Dir['test/**/*']
+  s.extensions    = %w[ext/afl_ext/extconf.rb]
+  s.require_paths = ['lib']
+end

data/benchmarks/minimal/harness.rb

@@ -0,0 +1,26 @@
+require 'socket'
+require_relative '../../lib/afl'
+
+# This is a completely trivial harness that allows us to measure just the
+# cost of the AFL machinery. The harness does nothing apart from send a
+# message that it has completed an iteration to the Benchmarker via a
+# UNIX socket.
+
+MAX_ATTEMPTS = 10
+attempts = 0
+begin
+  socket = UNIXSocket.open('/tmp/sock')
+rescue Errno::ENOENT
+  attempts += 1
+  if attempts >= MAX_ATTEMPTS
+    sleep(1)
+    retry
+  end
+  raise
+end
+
+AFL.init
+AFL.with_exceptions_as_crashes do
+  socket.send('1', 0)
+end
+exit(0)

data/benchmarks/minimal/input/1

@@ -0,0 +1 @@
+TEST

data/benchmarks/minimal/raw_harness.rb

@@ -0,0 +1,6 @@
+require 'socket'
+require_relative '../../lib/afl'
+
+AFL.init
+AFL.with_exceptions_as_crashes {}
+exit(0)

data/benchmarks/minimal/raw_run

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+export AFL_I_DONT_CARE_ABOUT_MISSING_CRASHES=1
+
+afl-fuzz -i ./benchmarks/minimal/input -o ./benchmarks/minimal/output \
+  -- ~/.rbenv/versions/2.4.1/bin/ruby \
+  ./benchmarks/minimal/raw_harness.rb

data/benchmarks/minimal/run.rb

@@ -0,0 +1,67 @@
+require 'socket'
+require 'fileutils'
+require_relative '../../lib/afl'
+
+# Usage:
+#
+#   ruby ./benchmarks/minimal/run.rb
+
+puts("Running benchmark...")
+
+ENV['AFL_I_DONT_CARE_ABOUT_MISSING_CRASHES'] = '1'
+
+input_dir = File.expand_path('input', File.dirname(__FILE__))
+output_dir = File.expand_path('output', File.dirname(__FILE__))
+target_path = File.expand_path('harness.rb', File.dirname(__FILE__))
+
+cmdline_args = [
+  'afl-fuzz',
+  '-i',
+  input_dir,
+  '-o',
+  output_dir,
+  '--',
+  'ruby',
+  target_path,
+]
+
+SOCKET_PATH = '/tmp/sock'
+
+if File.exist?(SOCKET_PATH)
+  FileUtils.rm(SOCKET_PATH)
+end
+
+afl_io = IO.popen(cmdline_args)
+server = UNIXServer.open(SOCKET_PATH)
+accepted_socket = server.accept
+
+puts("Socket connection accepted")
+
+begin
+  start_time = Time.now
+  last_checkpoint_time = start_time
+  timeout_s = 200
+  poll_s = 0.5
+  total_iterations = 0
+
+  while Time.now <= start_time + timeout_s do
+    break if afl_io.closed?
+    d = accepted_socket.recv(10000)
+
+    new_iterations = d.length
+    last_checkpoint_time_delta = Time.now - last_checkpoint_time
+    last_checkpoint_time = Time.now
+    current_iterations_per_s = new_iterations.to_f / last_checkpoint_time_delta
+
+    total_iterations += new_iterations
+    total_elapsed_time = Time.now - start_time
+    overall_iterations_per_s = total_iterations.to_f / total_elapsed_time
+
+    puts("ITERATIONS: #{total_iterations}\t ELAPSED TIME: #{total_elapsed_time}\t CURRENT ITERATIONS / S: #{current_iterations_per_s}\t TOTAL ITERATIONS / S: #{overall_iterations_per_s}")
+    sleep(poll_s)
+  end
+  end_time = Time.now
+ensure
+  Process.kill('TERM', afl_io.pid)
+end
+puts("Benchmark completed")

data/example/harness.rb

@@ -0,0 +1,33 @@
+$: << "../lib"
+def byte
+  $stdin.read(1)
+end
+
+def c
+  r if byte == 'r'
+end
+
+def r
+  s if byte == 's'
+end
+
+def s
+  h if byte == 'h'
+end
+
+def h
+  raise "Crashed"
+end
+
+require 'afl'
+
+AFL.with_logging_to_file('/tmp/afl-debug-test-harness') do
+  unless ENV['NO_AFL']
+    AFL.init
+  end
+
+  AFL.with_exceptions_as_crashes do
+    c if byte == 'c'
+    exit!(0)
+  end
+end

data/example/work/input/1

@@ -0,0 +1 @@
+BUTTS

data/ext/afl_ext/afl_ext.c

@@ -0,0 +1,213 @@
+#include <sys/shm.h>
+#include <fcntl.h>
+
+#include <ruby.h>
+#include <ruby/st.h>
+#include <errno.h>
+#include <signal.h>
+#include <stdio.h>
+#include <unistd.h>
+
+// These need to be in sync with afl-fuzz
+static const char* SHM_ENV_VAR = "__AFL_SHM_ID";
+static const int FORKSRV_FD = 198;
+#define MAP_SIZE_POW2 16
+static const int MAP_SIZE = 1 << MAP_SIZE_POW2;
+static unsigned char *afl_area = NULL;
+
+static VALUE AFL = Qnil;
+static VALUE init_done = Qfalse;
+
+#ifdef AFL_RUBY_EXT_DEBUG_LOG
+static FILE *aflogf = NULL;
+
+static void aflogf_init(void) {
+    int fd = open("/tmp/aflog",
+            O_WRONLY | O_CREAT | O_TRUNC,
+            S_IRUSR | S_IWUSR);
+    if (fd < 0) {
+        fprintf(stderr, "unable to open() /tmp/aflog\n");
+        _exit(1);
+    }
+
+    aflogf = fdopen(fd, "w");
+    if (!aflogf) {
+        fprintf(stderr, "unable to fdopen() /tmp/aflog\n");
+        _exit(1);
+    }
+}
+
+static void aflog_printf(const char *fmt, ...) {
+    va_list ap;
+
+    if (!aflogf) aflogf_init();
+
+    va_start(ap, fmt);
+    vfprintf(aflogf, fmt, ap);
+    va_end(ap);
+
+    // quiesce aflogf's writer buffer to disk immediately
+    fflush(aflogf);
+}
+
+#define LOG aflog_printf
+#else
+#define LOG(...)
+#endif
+
+/**
+ * Returns the location in the AFL shared memory to write the
+ * given Ruby trace data to.
+ *
+ * Borrowed from afl-python for consistency, then refactored
+ * https://github.com/jwilk/python-afl/blob/8df6bfefac5de78761254bf5d7724e0a52d254f5/afl.pyx#L74-L87
+ */
+#define LHASH_INIT       0x811C9DC5
+#define LHASH_MAGIC_MULT 0x01000193
+#define LHASH_NEXT(x)    h = ((h ^ (unsigned char)(x)) * LHASH_MAGIC_MULT)
+
+static inline unsigned int lhash(const char *key, size_t offset) {
+    const char *const last = &key[strlen(key) - 1];
+    uint32_t h = LHASH_INIT;
+    while (key <= last)               LHASH_NEXT(*key++);
+    for (; offset != 0; offset >>= 8) LHASH_NEXT(offset);
+    return h;
+}
+
+/**
+ * Write Ruby trace data to AFL's shared memory.
+ *
+ * TODO: link to the AFL code that this is mimicking.
+ */
+static VALUE afl_trace(VALUE _self, VALUE file_name, VALUE line_no) {
+    static int prev_location;
+    int offset;
+    VALUE exc = rb_const_get(AFL, rb_intern("RuntimeError"));
+
+    if (init_done == Qfalse) {
+        rb_raise(exc, "AFL not initialized, call ::AFL.init first!");
+    }
+
+    char* fname = StringValueCStr(file_name);
+    size_t lno = FIX2INT(line_no);
+    unsigned int location = lhash(fname, lno) % MAP_SIZE;
+    LOG("[+] %s:%zu\n", fname, lno);
+
+    offset = location ^ prev_location;
+    prev_location = location / 2;
+    LOG("[!] offset 0x%x\n", offset);
+    afl_area[offset] += 1;
+
+    LOG("[-] done with trace");
+    return Qtrue;
+}
+
+/**
+ * Initialize the AFL forksrv by testing that we can write to it.
+ */
+static VALUE afl__init_forkserver(void) {
+    LOG("Testing writing to forksrv fd=%d\n", FORKSRV_FD);
+
+    int ret = write(FORKSRV_FD + 1, "\0\0\0\0", 4);
+    if (ret != 4) {
+        VALUE exc = rb_const_get(AFL, rb_intern("RuntimeError"));
+        rb_raise(exc, "Couldn't write to forksrv");
+    }
+
+    LOG("Successfully wrote out nulls to forksrv ret=%d\n", ret);
+    return Qnil;
+}
+
+static VALUE afl__forkserver_read(VALUE _self) {
+    unsigned int value;
+    int ret = read(FORKSRV_FD, &value, 4);
+    LOG("Read from forksrv value=%d ret=%d", value, ret);
+    if (ret != 4) {
+        LOG("Couldn't read from forksrv errno=%d", errno);
+        VALUE exc = rb_const_get(AFL, rb_intern("RuntimeError"));
+        rb_raise(exc, "Couldn't read from forksrv");
+    }
+    return INT2FIX(value);
+}
+
+/**
+ * Write a value (generally a child_pid) to the AFL forkserver.
+ */
+static VALUE afl__forkserver_write(VALUE _self, VALUE v) {
+    unsigned int value = FIX2INT(v);
+
+    int ret = write(FORKSRV_FD + 1, &value, 4);
+    LOG("Wrote to forksrv_sock value=%d ret=%d\n", value, ret);
+    if (ret != 4) {
+        VALUE exc = rb_const_get(AFL, rb_intern("RuntimeError"));
+        rb_raise(exc, "Couldn't write to forksrv");
+    }
+    return INT2FIX(ret);
+}
+
+/**
+ *  Initialize AFL's shared memory segment.
+ */
+static VALUE afl__init_shm(void) {
+    LOG("Initializing SHM\n");
+    VALUE exc = rb_const_get(AFL, rb_intern("RuntimeError"));
+
+    if (init_done == Qtrue) {
+        rb_raise(exc, "AFL already initialized");
+    }
+
+    const char * afl_shm_id_str = getenv(SHM_ENV_VAR);
+    if (afl_shm_id_str == NULL) {
+        rb_raise(
+            exc,
+            "No AFL SHM segment specified. AFL's SHM env var is not set."
+            "Are we actually running inside AFL?");
+    }
+
+    const int afl_shm_id = atoi(afl_shm_id_str);
+    afl_area = shmat(afl_shm_id, NULL, 0);
+    if (afl_area == (void*) -1) {
+        rb_raise(exc, "Couldn't map shm segment");
+    }
+    LOG("afl_area at 0x%zx\n", afl_area);
+
+    init_done = Qtrue;
+
+    LOG("Done initializing SHM\n");
+    return Qtrue;
+}
+
+/**
+ * Close the AFL forksrv file descriptors.
+ */
+static VALUE afl__close_forksrv_fds(VALUE _self) {
+    close(FORKSRV_FD);
+    close(FORKSRV_FD + 1);
+    return Qnil;
+}
+
+static VALUE afl_bail_bang(VALUE _self) {
+    LOG("bailing\n");
+#ifdef AFL_RUBY_EXT_DEBUG_LOG
+    if (aflogf) {
+        fclose(aflogf);
+        aflogf = NULL;
+    }
+#endif
+    _exit(0);
+}
+
+void Init_afl_ext(void) {
+    AFL = rb_const_get(rb_cObject, rb_intern("AFL"));
+    LOG("...\n");
+
+    rb_define_module_function(AFL, "trace", afl_trace, 2);
+    rb_define_module_function(AFL, "_init_shm", afl__init_shm, 0);
+    rb_define_module_function(AFL, "_init_forkserver", afl__init_forkserver, 0);
+    rb_define_module_function(AFL, "_close_forksrv_fds", afl__close_forksrv_fds, 0);
+    rb_define_module_function(AFL, "_forkserver_read", afl__forkserver_read, 0);
+    rb_define_module_function(AFL, "_forkserver_write", afl__forkserver_write, 1);
+    rb_define_module_function(AFL, "bail!", afl_bail_bang, 0);
+    VALUE vFORKSRV_FD = INT2FIX(FORKSRV_FD);
+    rb_define_const(AFL, "FORKSRV_FD", vFORKSRV_FD);
+}

data/ext/afl_ext/extconf.rb

@@ -0,0 +1,8 @@
+require 'mkmf'
+
+if enable_config('debug')
+  debug = '-DAFL_RUBY_EXT_DEBUG_LOG'
+  $defs.push(debug) unless $defs.include? debug
+end
+
+create_makefile('afl_ext')

data/lib/afl.rb

@@ -0,0 +1,134 @@
+class AFL
+
+  class RuntimeError < StandardError; end
+
+  DEFAULT_DEBUG_LOG_FILE = '/tmp/afl-debug-output'
+
+  # Initialize AFL. When using the forksrv, try to call
+  # this as late as possible, after you have done all your
+  # expensive, generic setup that will not change between
+  # test-cases. Your test-cases will start their runs at
+  # the point where you call `AFL.init`.
+  def self.init
+    self._init_shm
+
+    # Use Ruby's TracePoint to report the Ruby traces that
+    # have been executed to AFL.
+    @trace = TracePoint.new(:call, :c_call) do |tp|
+      AFL.trace(tp.path, tp.lineno)
+    end
+
+    unless ENV['AFL_NO_FORKSRV']
+      self._init_forkserver
+      self.spawn_child
+      self._close_forksrv_fds
+    end
+
+    @trace.enable
+  end
+
+  # Turn off reporting of trace information to AFL.
+  def self.deinit
+    @trace.disable
+  end
+
+  # Turn exceptions raised within the block into crashes
+  # that can be recorded by AFL.
+  def self.with_exceptions_as_crashes
+    begin
+      yield
+    rescue Exception
+      self.crash!
+    end
+  end
+
+  # AFL does not print the output of the inferior to the
+  # terminal. This can make it difficult to debug errors.
+  # This method logs the output to tmpfiles for you to
+  # inspect. It should only be used for debugging.
+  #
+  # Note that this method truncates the log file at the
+  # beginning of each call to it in order to conserve
+  # disk space. A good workflow is therefore to keep:
+  #
+  #   tail -f /tmp/afl-debug-output
+  #
+  # running in one window whilst running your debug 
+  # script in another.
+  #
+  # Example usage:
+  #
+  #   AFL.with_logging_to_file do
+  #     run_your_program
+  #   end
+  def self.with_logging_to_file(path=DEFAULT_DEBUG_LOG_FILE)
+    initial_stdout, initial_stderr = $stdout, $stderr
+    fh = File.open(path, 'w')
+    $stdout.reopen(fh)
+    $stderr.reopen(fh)
+
+    yield
+  ensure
+    fh.flush
+    fh.close
+    $stdout.reopen(initial_stdout)
+    $stderr.reopen(initial_stderr)
+  end
+
+  # Manually log a debug message to a tmpfile.
+  def self.log(msg)
+    fh = File.open('/tmp/aflog-rubby', 'w')
+    fh.write(msg)
+    fh.write("\n")
+    fh.flush
+    fh.close
+  end
+
+  def self.crash!
+    Process.kill("USR1", $$)
+  end
+
+  # #spawn_child is a Ruby wrapper around AFL's forksrv.
+  #
+  # When we want to run a new test-case, #spawn_child forks off a new
+  # thread. This thread returns to the main program, where it runs the
+  # test-case and then exits.
+  # 
+  # Meanwhile, the forksrv thread has been waiting for its child to exit.
+  # Once this happens, it waits for another test-case to be ready, when
+  # it forks off another new thread and the cycle continues.
+  #
+  # This is very useful because it allows us to strategically choose our
+  # fork point in order to "cache" expensive setup of our inferior.
+  # Forking as late as possible means that our test-cases take less time.
+  def self.spawn_child
+    loop do
+      # Read and discard the previous test's status.  We don't care about the
+      # value, but if we don't read it, the fork server eventually blocks, and
+      # then we block on the call to _forkserver_write below
+      self._forkserver_read
+
+      # Fork a child process
+      child_pid = fork
+
+      # If we are the child thread, return back to the main program
+      # and actually run a testcase.
+      #
+      # If we are the parent, we are the forkserver and we should
+      # continue in this loop so we can fork another child once this
+      # one has returned.
+      return if child_pid.nil?
+
+      # Write child's thread's pid to AFL's fork server
+      self._forkserver_write(child_pid)
+      # Wait for the child to return
+      _pid, status = Process.waitpid2(child_pid)
+
+      # Report the child's exit status to the AFL forkserver
+      report_status = status.termsig || status.exitstatus
+      self._forkserver_write(report_status)
+    end
+  end
+end
+
+require 'afl_ext'

data/lib/afl/version.rb

@@ -0,0 +1,3 @@
+module AFL
+  VERSION = '0.0.3'
+end

data/test/afl_test.rb

@@ -0,0 +1,156 @@
+require ::File.expand_path('../../lib/afl', __FILE__)
+require 'minitest/autorun'
+
+def read_fuzzer_stats(path)
+  File.open(path) do |f|
+    f.readlines.map do |line|
+      els = line.split(/\s+/)
+      [els[0], els[2]]
+    end.to_h
+  end
+end
+
+describe AFL do
+  before do
+    @env = {
+      'AFL_I_DONT_CARE_ABOUT_MISSING_CRASHES' => '1',
+    }
+    @input_dir = File.expand_path('input', __dir__)
+    @output_dir = File.expand_path('output', __dir__)
+    @crash_dir = File.expand_path('crashes', @output_dir)
+    @queue_dir = File.expand_path('queue', @output_dir)
+
+    @target_path = File.expand_path('lib/crashing_test_harness.rb', __dir__)
+    @fuzzer_stats_path = File.expand_path('fuzzer_stats', @output_dir)
+
+    @all_dirs = [@input_dir, @output_dir, @crash_dir, @queue_dir]
+    @all_dirs.each do |d|
+      FileUtils.rm_rf(d, secure: true)
+    end
+
+    @all_dirs.each do |d|
+      unless Dir.exist?(d)
+        Dir.mkdir(d)
+      end
+    end
+
+    input_file = File.expand_path('test1.txt', @input_dir)
+    File.open(input_file, 'w+') do |f|
+      f.write('0')
+    end
+  end
+
+  after do
+    @all_dirs.each do |d|
+      FileUtils.rm_rf(d, secure: true)
+    end
+  end
+
+  describe 'fuzzing with AFL' do
+    it 'can find a very basic crash and explore multiple edges' do
+      cmdline_args = [
+        # Don't worry if we are forwarding crash notifications to an external
+        # crash reporting utility.
+        'afl-fuzz',
+        '-i',
+        @input_dir,
+        '-o',
+        @output_dir,
+        '--',
+        'ruby',
+        @target_path,
+      ]
+      afl_io = IO.popen(@env, cmdline_args)
+
+      begin
+        start_time = Time.now
+        timeout_s = 10
+        poll_s = 0.5
+
+        while Time.now <= start_time + timeout_s do
+          n_paths = Dir.glob(@queue_dir + '/id:*').length
+          have_paths = n_paths >= 2
+          have_crash = Dir.glob(@crash_dir + '/id:*').length >= 1
+
+          break if afl_io.closed?
+          break if have_crash && have_paths
+
+          sleep(poll_s)
+        end
+
+        assert(have_crash, 'Target program did not crash')
+        assert(have_paths, "Target program only produced #{n_paths} distinct paths")
+      ensure
+        Process.kill('TERM', afl_io.pid)
+      end
+    end
+
+    # In the past we had a bug where we didn't drain the forkserver's test output.
+    # This meant that we couldn't run more than 16,384 (2**14) execs before the
+    # fuzzer would hang and refuse to continue fuzzing. This test makes sure that
+    # doesn't happen again.
+    it 'can run more than 16,384 execs without hanging' do
+      cmdline_args = [
+        'afl-fuzz',
+        '-i',
+        @input_dir,
+        '-o',
+        @output_dir,
+        '--',
+        'ruby',
+        @target_path,
+      ]
+      afl_io = IO.popen(@env, cmdline_args)
+
+      # Spin until the first fuzzer_stats appear. At this point we know that the
+      # fuzzer has started fuzzing, and we can start the clock.
+      begin
+        read_fuzzer_stats(@fuzzer_stats_path)
+      rescue Errno::ENOENT
+        sleep(1)
+        retry
+      end
+
+      begin
+        fuzz_start_time = Time.now
+        timeout_s = 60 # Note that this test does usually take the full 60s to run
+        poll_s = 0.5
+        n_execs = 0
+        # The real target is 16_384 (2**14), but let's add a few more to make sure
+        target_n_execs = 17_000
+
+        while Time.now <= fuzz_start_time + timeout_s do
+          stats = read_fuzzer_stats(@fuzzer_stats_path)
+          n_execs = stats['execs_done'].to_i
+
+          break if afl_io.closed?
+          # The fuzzer_stats file doesn't get updated very frequently, so this
+          # condition is unlikely to ever be met. However, the fuzzer does write
+          # fuzzer_stats when it shuts down, so the SIGTERM that we send in the
+          # `ensure` block should make sure that we get the data we need.
+          break if n_execs >= target_n_execs
+
+          sleep(poll_s)
+        end
+      ensure
+        Process.kill('TERM', afl_io.pid)
+      end
+
+      # Make sure that afl gets a chance to write its final fuzzer_stats output
+      # after we SIGTERM it in the `ensure` block above.
+      results_read_start_time = Time.now
+      timeout_s = 10
+      poll_s = 0.5
+
+      while Time.now <= fuzz_start_time + timeout_s do
+        stats = read_fuzzer_stats(@fuzzer_stats_path)
+        n_execs = stats['execs_done'].to_i
+
+        break if n_execs >= target_n_execs
+        sleep(poll_s)
+      end
+
+      assert(n_execs >= target_n_execs, 'Target program did not complete as many execs as expected')
+    end
+  end
+end

data/test/lib/crashing_test_harness.rb

@@ -0,0 +1,23 @@
+$: << "../lib"
+require_relative('../../lib/afl')
+
+def function1
+  return 1
+end
+
+def function2
+  return 2
+end
+
+AFL.init
+AFL.with_exceptions_as_crashes do
+  input = $stdin.read(1)
+  if input == '7'
+    raise 'I hate the number 7'
+  elsif input.ord % 2 == 0
+    function1
+  else
+    function2
+  end
+  exit!(0)
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: afl
+version: !ruby/object:Gem::Version
+  version: 0.0.3
+platform: ruby
+authors:
+- Richo Healey
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-10-24 00:00:00.000000000 Z
+dependencies: []
+description: American Fuzzy Lop (AFL) support for ruby
+email:
+- richo@psych0tik.net
+executables: []
+extensions:
+- ext/afl_ext/extconf.rb
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- LICENSE
+- Makefile
+- README.md
+- Rakefile
+- afl-fuzz.c.patch
+- afl.gemspec
+- benchmarks/minimal/harness.rb
+- benchmarks/minimal/input/1
+- benchmarks/minimal/raw_harness.rb
+- benchmarks/minimal/raw_run
+- benchmarks/minimal/run.rb
+- example/harness.rb
+- example/work/input/1
+- ext/afl_ext/afl_ext.c
+- ext/afl_ext/extconf.rb
+- lib/afl.rb
+- lib/afl/.gitkeep
+- lib/afl/version.rb
+- test/afl_test.rb
+- test/lib/crashing_test_harness.rb
+homepage: http://github.com/richo/afl-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: AFL support for ruby
+test_files:
+- test/afl_test.rb
+- test/lib/crashing_test_harness.rb