// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! A fuzzing loop of our own, beside Zig's. //! //! `zig build fuzz --fuzz` is Zig's fuzzer, with coverage feedback, and is //! the one to leave running. This is the one CI runs: it stops after a fixed //! number of inputs, and what it has instead of coverage feedback is a corpus //! of inputs that reach interesting states -- the seeds in `tests/fuzz.zig`, //! and anything found since -- and mutation of those. That is enough: the state a decoder //! holds is a byte or two, so an input that reaches a bad state is short and //! near an input that already reaches a good one. //! //! ``` //! zig build fuzz-run # until interrupted //! zig build fuzz-run -- --iterations=100000 # a fixed number //! zig build fuzz-run -- --target=split # one property //! ``` //! //! The input format is `std.testing.Smith`'s, and getting it wrong is silent: //! a slice whose length does not fit is read as the empty slice, and a value //! outside the range asked for becomes the lowest value in that range. A //! generator writing random bytes therefore reports millions of iterations //! having tested the empty string against the first encoding in the list. //! `Target.questions` and `Target.capacity` are what this needs to avoid //! that. const std = @import("std"); const fuzz_targets = @import("fuzz_targets"); const Allocator = std.mem.Allocator; /// How many inputs are kept per target. The corpus is a ring: a new input /// that did something is written over the oldest one. const corpus_capacity = 256; pub fn main(init: std.process.Init) !void { const gpa = init.gpa; var iterations: ?usize = null; var only: ?[]const u8 = null; var seed: u64 = 0; var args = init.minimal.args.iterate(); _ = args.next(); while (args.next()) |arg| { if (std.mem.startsWith(u8, arg, "--iterations=")) { iterations = try std.fmt.parseInt(usize, arg["--iterations=".len..], 10); } else if (std.mem.startsWith(u8, arg, "--target=")) { only = arg["--target=".len..]; } else if (std.mem.startsWith(u8, arg, "--seed=")) { seed = try std.fmt.parseInt(u64, arg["--seed=".len..], 10); } else { std.debug.print("usage: fuzz [--iterations=N] [--target=NAME] [--seed=N]\n", .{}); std.process.exit(1); } } // The clock, because Zig has no ambient random source and an `Io` is // passed in rather than reached for. Any two runs a nanosecond apart get // different corpora, which is all a seed has to do. if (seed == 0) { const nanoseconds = std.Io.Timestamp.now(init.io, .real).nanoseconds; seed = @truncate(@as(u96, @bitCast(nanoseconds))); } var prng: std.Random.DefaultPrng = .init(seed); const random = prng.random(); var buffer: [4096]u8 = undefined; var stderr = std.Io.File.stderr().writer(init.io, &buffer); const w = &stderr.interface; try w.print("seed {d}\n", .{seed}); try w.flush(); for (fuzz_targets.targets) |target| { if (only) |name| if (!std.mem.eql(u8, name, target.name)) continue; try run(gpa, random, target, iterations, w); } } fn run( gpa: Allocator, random: std.Random, target: fuzz_targets.Target, iterations: ?usize, w: *std.Io.Writer, ) !void { var corpus: std.ArrayList([]u8) = .empty; defer { for (corpus.items) |item| gpa.free(item); corpus.deinit(gpa); } var next: usize = 0; var done: usize = 0; while (iterations == null or done < iterations.?) : (done += 1) { const input = if (corpus.items.len > 0 and random.boolean()) try mutate(gpa, random, target, corpus.items[random.uintLessThan(usize, corpus.items.len)]) else try generate(gpa, random, target); defer gpa.free(input); // A leak in a target is a finding as much as a crash is, so each // input gets an allocator of its own that is checked afterwards. var debug_allocator: std.heap.DebugAllocator(.{}) = .init; fuzz_targets.backing = debug_allocator.allocator(); var smith: std.testing.Smith = .{ .in = input }; const result = target.run(&smith); const leaked = debug_allocator.deinit() == .leak; if (result) |_| {} else |err| { try w.print("{s}: {t}\n input: {x}\n", .{ target.name, err, input }); try w.flush(); std.process.exit(1); } if (leaked) { try w.print("{s}: leaked\n input: {x}\n", .{ target.name, input }); try w.flush(); std.process.exit(1); } // Everything that ran goes in the corpus, because without coverage // there is nothing better to select on than recency and variety. if (corpus.items.len < corpus_capacity) { try corpus.append(gpa, try gpa.dupe(u8, input)); } else { gpa.free(corpus.items[next]); corpus.items[next] = try gpa.dupe(u8, input); next = (next + 1) % corpus.items.len; } if (done % 100_000 == 0 and done != 0) { try w.print("{s}: {d}\n", .{ target.name, done }); try w.flush(); } } try w.print("{s}: {d} inputs, no findings\n", .{ target.name, done }); try w.flush(); } /// A fresh input in the layout the target reads: `questions` little-endian /// `u64`s, then a little-endian `u32` length and that many bytes. fn generate( gpa: Allocator, random: std.Random, target: fuzz_targets.Target, ) ![]u8 { const len = random.uintAtMost(u32, @intCast(target.capacity)); const buf = try gpa.alloc(u8, target.questions * 8 + 4 + len); for (0..target.questions) |i| { // Within a u32, because that is what the targets ask for: a wider // value would be silently replaced by the bottom of the range. std.mem.writeInt(u64, buf[i * 8 ..][0..8], random.int(u32), .little); } std.mem.writeInt(u32, buf[target.questions * 8 ..][0..4], len, .little); const bytes = buf[target.questions * 8 + 4 ..]; random.bytes(bytes); // Half the inputs are pushed towards the bytes that mean something: // lead bytes, escapes, and ASCII. Uniform random bytes reach a // multi-byte sequence often enough, but reach a *valid* one, or an // escape sequence, almost never. if (random.boolean()) { const interesting = [_]u8{ 0x00, 0x0a, 0x1b, 0x24, 0x28, 0x40, 0x41, 0x42, 0x49, 0x4a, 0x5c, 0x7e, 0x7f, 0x80, 0x81, 0x8e, 0x8f, 0x9f, 0xa1, 0xc1, 0xd8, 0xdc, 0xe0, 0xfc, 0xfe, 0xff, }; for (bytes) |*byte| { if (random.boolean()) byte.* = interesting[random.uintLessThan(usize, interesting.len)]; } } return buf; } /// A copy of a corpus entry with something changed. The questions and the /// length are left alone by most mutations, because rewriting them at random /// mostly produces an input that tests nothing. fn mutate( gpa: Allocator, random: std.Random, target: fuzz_targets.Target, parent: []const u8, ) ![]u8 { const buf = try gpa.dupe(u8, parent); const header = target.questions * 8 + 4; if (buf.len <= header) return buf; const bytes = buf[header..]; switch (random.uintLessThan(u8, 4)) { // Flip a bit. 0 => { const i = random.uintLessThan(usize, bytes.len); bytes[i] ^= @as(u8, 1) << random.int(u3); }, // Replace a byte. 1 => bytes[random.uintLessThan(usize, bytes.len)] = random.int(u8), // Swap two bytes, which moves a lead byte next to a different // trailing one. 2 => { const i = random.uintLessThan(usize, bytes.len); const j = random.uintLessThan(usize, bytes.len); std.mem.swap(u8, &bytes[i], &bytes[j]); }, // Ask a different question: a different encoding, or a different // seam. else => if (target.questions > 0) { const i = random.uintLessThan(usize, target.questions); std.mem.writeInt(u64, buf[i * 8 ..][0..8], random.int(u32), .little); }, } return buf; }