googleprojectzero/Jackalope: Coverage-Guided Fuzzing for Black-Box Binaries

Why Jackalope targets black-box fuzzing

Jackalope addresses a specific gap in coverage-guided fuzzing: testing binaries when source code is unavailable. The README says many coverage-guided fuzzers expect source code, while comparatively few target black-box binaries, particularly on Windows and macOS. Jackalope is therefore aimed at engineers who have a compiled executable, a target interface that accepts generated samples, and a need to explore crashes or previously unseen coverage.

The project is also relevant when the target's input format makes generic fuzzing ineffective. Its stated design goals include custom mutators, custom sample delivery mechanisms and custom instrumentation. That places the project closer to a fuzzing framework than a single fixed command-line product. The C++ repository contains separate source files for instrumentation, mutation, delivery, coverage tracking, minimization and server-client operation, which reflects those extension points in the repository layout.

Jackalope does not hide the limitation of its default mutation engine. According to the README, it ships with generic mutators for binary formats and a grammar-based mutation engine, but it does not currently include advanced mutation strategies. A project that needs a domain-aware parser, format-aware transformations or a mature strategy library may have to implement or integrate those pieces separately.

TinyInst instrumentation and execution flow

By default, Jackalope uses TinyInst for binary instrumentation. The repository includes `tinyinstinstrumentation.h` and `tinyinstinstrumentation.cpp`, alongside the general `instrumentation.h` and `instrumentation.cpp` interfaces. This separation indicates that instrumentation is a replaceable component rather than a fixed behavior. The README also states that Jackalope can use Sanitizer Coverage on Linux when source code for the target is available, but that mode is documented separately in `README_sancov.md`.

The normal command shape is `./fuzzer <fuzzer arguments> <instrumentation and other components arguments> -- <target command line>`. During a fuzzing run, the fuzzer loads an input sample, mutates it, delivers it to the target, observes the result and uses coverage information to decide whether the result should enter the corpus. The repository includes `rangetracker.cpp` and `rangetracker.h` for tracking ranges, while `runresult.h` represents the result of a target run. The README documents retries for crashes and new coverage, including `-crash_retry` and `-coverage_retry`, and says unreliable crashes and coverage can be marked flaky.

Sample minimization is enabled by default through `-minimize_samples`. Coverage reproduction can restart the target by default through `-clean_target_on_coverage`. These defaults improve corpus quality, but they also add target executions around interesting findings. For a slow target, the README specifically suggests considering a lower `-iterations_per_round` value.

File, shared-memory and distributed operation

Jackalope supports two sample delivery mechanisms. With `-delivery file`, each sample is written as a file and the target command receives a path in place of `@@`. This is useful for targets that already accept a file path. The optional `-file_extension` argument appends a filename extension, which matters when the target selects behavior based on the input file's suffix.

With `-delivery shmem`, Jackalope creates shared memory and replaces `@@` with the shared-memory name. The target is responsible for opening that shared memory and extracting the sample, so this mode requires cooperation from the target's input path. On Android, the README gives a specific condition for this mode: the VM must support shared memory through `/dev/shm`, and the build uses `-DANDROID_TARGET=VM`.

Jackalope can run multiple fuzzing threads on one machine with `-nthreads`. It also has a server mode. One process can run with `-start_server`, while worker processes specify the server with `-server`. The server collects and distributes samples, crashes and coverage across workers. This architecture makes it possible to separate fuzzing capacity across machines, but it does not remove the need for compatible target commands, synchronized state and reliable server connectivity. The README documents restoration for both the fuzzer and server processes through `-restore` or `-resume`.

Building Jackalope across supported platforms

The README lists Python 3 as a prerequisite, then requires a platform build environment, CMake, Visual Studio command prompt configuration on Windows, or Xcode configuration on macOS. The documented build sequence is:

cd Jackalope
git clone --recurse-submodules [email protected]:googleprojectzero/TinyInst.git
mkdir build
cd build
cmake <generator arguments> ..
cmake --build . --config Release

The HTTPS form of the TinyInst clone is also documented:

cd Jackalope
git clone --recurse-submodules https://github.com/googleprojectzero/TinyInst.git

Generator arguments depend on the host. The README gives `-G Xcode` for macOS, `-G "Visual Studio 16 2019" -A x64` for a 64-bit Windows build with Visual Studio 2019, and no generator arguments for Linux. Android cross-compilation requires additional CMake arguments described in TinyInst's Android build instructions. The macOS arm64e case also has separate instructions in TinyInst.

After a successful Release build, the `fuzzer` executable is the entry point. The README does not document package-manager installation, a binary download or a release artifact. It therefore treats source compilation as the installation path. No GitHub releases are listed, so the build process and repository dependencies are more concrete adoption requirements than versioned binaries would be.

A first file-based fuzzing run

The README documents the executable form as `./fuzzer <fuzzer arguments> <instrumentation and other components arguments> -- <target command line>`. This is a usage template rather than a complete runnable command, because the target command and component arguments depend on the binary under test.

The README defines `-in` as the input directory, `-out` as the output directory and `-t` as the sample timeout in milliseconds. It also documents `-delivery file`, where each sample is output as a file and `@@` in the target arguments is replaced with a path to that file. The reader should see samples written to the output directory while the target consumes each generated file.

If the target expects a particular extension, the README documents `-file_extension` for adding it to filenames. For local parallelism, `-nthreads` controls the number of fuzzer threads, with a documented default of 1. For distributed operation, one instance can use `-start_server`, while fuzzers on worker machines use `-server`; the server collects and distributes samples, crashes and coverage.

For a slow target, the README says to consider decreasing `-iterations_per_round`, whose documented default is 1000. Restoration is available through `-restore` or `-resume` for both fuzzer and server processes. The output directory is where Jackalope writes its results, but the README does not define a complete directory layout or a stable schema for every output file. Engineers adopting Jackalope should inspect that layout in their own build rather than assume a particular automation contract.

Customization, limitations and maintenance cost

Jackalope's most distinctive feature is the ability to replace default behavior when a target does not fit generic fuzzing. It ships with binary instrumentation through TinyInst, generic mutators for binary formats, a grammar-based mutation engine, and sample delivery through files or shared memory. The README says the project can also run in parallel on one machine or across multiple machines through a server and workers.

The same flexibility is a limitation for buyers seeking a ready-made fuzzer. The repository includes mutator and instrumentation interfaces, but the README does not document an advanced built-in mutation strategy. Teams working on a format that requires specialized transformations may need to write custom code. Shared-memory delivery has another explicit boundary: the target must open the shared memory and extract the sample itself. A binary that only accepts ordinary file paths will not automatically support that mode.

The repository is not archived, and its last push was on 2026-08-25. The repository has no GitHub releases, so there is no documented release cadence or packaged upgrade path in the README. An upgrade therefore appears tied to repository changes and rebuilding from source, including the TinyInst submodule. That can create maintenance cost for teams that need reproducible binaries across Windows, macOS, Linux or Android.

The project is licensed under Apache License 2.0. The README includes the Apache License 2.0 notice and points to the license text. Teams should account for the license text, notices and their own distribution requirements when embedding or redistributing builds. This review does not provide legal advice.

Editorial conclusion

Engineers fuzzing proprietary or otherwise black-box binaries should adopt Jackalope when they need a customizable, parallel harness and can invest in target-specific mutators. Projects that need advanced mutation strategies out of the box, or that cannot build its C++ and TinyInst dependencies, should verify those limits before adoption. The first checks are target compatibility with TinyInst or Sanitizer Coverage, the required build environment, and whether file delivery matches the target's input interface.

Frequently asked questions

Official sources

1. googleprojectzero/Jackalope on GitHub
2. Issues
3. License: Apache-2.0
4. README