How googleprojectzero/jackalope works
Main Components
• Fuzzer Process (client)
– Core class: Fuzzer (manages corpus, coverage, scheduling)
– Threads: multiple fuzzing threads (-nthreads)
– Subcomponents (via factory/strategy pattern):
• Mutator Engine
• SampleDelivery (file or shared-memory)
• Instrumentation (TinyInst or sancov)
• PRNG (Mersenne Twister)
• RangeTracker (optional for read‐range tracking)
• Target Binary
– Receives sample via file or shared memory
– Runs under instrumentation/debugger
• Server Process (optional)
– Central coordinator for multi-machine fuzzing
– Collects “new coverage” samples and crashes from clients
– Distributes corpus updates back to clients
• Client Module
– Networking layer to talk to Server (over TCP/IPC)
– Used when “-server” or “-start_server” flags set
Relationships & Data Flows
a. Startup
– Fuzzer reads input directory (“-in”) → initializes corpus
– Optionally spawn Server (-start_server)
– Clients connect to Server (-server <address>)
b. Fuzz Loop (per thread)
1. Fuzzer pops a Sample from corpus queue
2. MutatorEngine.Mutate(Sample) → mutated Sample
3. SampleDelivery.Deliver(mutated Sample) → writes file or shmem
4. Instrumentation.Run(target, arguments) → executes target, gathers coverage data
5. Fuzzer analyzes coverage:
• If new coverage → enqueue Sample, notify Server via Client
• If crash → record crash, resend to Server for triage
6. AdjustSamplePriority(sample) → reinsert or discard
c. Server–Client
– Clients send “new sample + coverage metadata”
– Server merges into global corpus, broadcasts to other clients
– Server maintains persistent storage of best corpus
Architectural Patterns
• Plugin / Strategy Pattern: factories in Fuzzer for Mutator, Instrumentation, SampleDelivery, PRNG
• Multi-threading & concurrency: Fuzzer schedules jobs to worker threads; uses mutex, thread, shm helpers
• Client–Server / distributed fuzzer pattern
• Extension points: subclassing Fuzzer enables custom behavior
– Fuzzer (fuzzer.cpp/h)
– Mutator (mutator.cpp/h + mutators/grammar/)
– Instrumentation (instrumentation.cpp/h, sancov*, tinyinstinstrumentation.cpp/h)
– SampleDelivery (sampledelivery.cpp/h, shm.cpp/h)
– PRNG (prng.cpp/h, third_party/Mersenne/)
– Server (server.cpp/h)
– Client (client.cpp/h)
– RangeTracker (rangetracker.cpp/h)
– Minimizer (minimizer.cpp/h)
– Directory (directory.cpp/h)
– Mutex, Thread wrappers (mutex.cpp/h, thread.cpp/h)