// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! Run the fuzz targets in `src/fuzz.zig` against input this makes up. //! //! Zig has a fuzzer of its own and those targets are written for it, so the //! obvious thing to run is `zig build test --fuzz`. With the devshell's patched //! Zig that now *compiles* — `flake.nix` says what the patch is — and then ends //! with //! //! ``` //! error: step 'run test': corrupted coverage file: pcs_len was zero //! ``` //! //! because nothing in 0.16.0 populates the table of program counters, however //! the modules are built. A fuzzer with no coverage is a random number //! generator, so this is one written down honestly: it makes an input, hands it //! to a target, and says so when one comes back with an error. What it has //! instead of coverage feedback is a corpus of real URIs, paths, LDAP URLs and //! stamps to mutate, and — unlike the other one — it says how many inputs it //! got through. //! //! ```console //! $ zig build fuzz-run # a minute of each //! $ zig build fuzz-run -- --seconds 300 --target click //! $ zig build fuzz-run -- --seed 12345 # exactly again //! $ zig build fuzz-run -- --input fuzz-findings/x.bin --target click //! ``` //! //! # What an input is //! //! Not a file: a `std.testing.Smith` reads it as a stream of answers, and the //! encoding is worth knowing before writing a generator for it. //! //! * `smith.slice(buf)` reads **four** bytes as a little-endian `u32` length, //! then that many bytes of content. A length larger than `buf.len` is not //! reduced into range — it yields an *empty* slice. So a string of random //! bytes gives almost every target nothing at all to parse, and a generator //! that does not write a plausible length is fuzzing nothing. The cap is //! `Target.content_max` for that reason. //! * `smith.value(T)` and `smith.index(n)` read **eight** bytes as a //! little-endian `u64` and, if the value is outside the range asked for, //! return that range's *minimum* rather than reducing it. Random bytes //! therefore make every `bool` false, every enum its first tag and every //! count its lowest — so the tail of an input here is a run of small numbers //! written on purpose, and the targets that ask only for numbers //! (`Target.slices == 0`) are given nothing else. //! //! `Target.slices` says how many length-prefixed chunks a target reads before //! that tail: two for `click` and `relativize`, which want a base *and* a //! reference, one for most, none for the three that build their input out of //! numbers. //! //! # Memory //! //! Unlike the other libraries with a loop like this, most of what is fuzzed //! here allocates, so the driver holds a `DebugAllocator` and asks it after //! every input whether anything was left behind. A leak is reported as a //! finding with the input that caused it, which is a property no fixed test can //! state: `Uri.parse` and everything built on it must free what they allocate //! on *every* path, including the ones an error takes. //! //! # The watchdog //! //! Nothing here should be able to loop — every parser walks a bounded input //! once — but "should" is what a fuzzer is for. A thread watches the clock, and //! an iteration that outlasts `--timeout` seconds is reported as a hang with //! the input that caused it. There is no way to unwind out of it, so that ends //! the run. const std = @import("std"); const targets = @import("fuzz_targets"); const Smith = std.testing.Smith; /// Milliseconds on a clock that only goes forwards while the machine is up. fn nowMs(io: std.Io) i64 { return @intCast(@divFloor(std.Io.Timestamp.now(io, .awake).nanoseconds, std.time.ns_per_ms)); } /// What the watchdog needs to see, written before each iteration begins. const Watch = struct { /// When the running iteration started, or zero between iterations. started_ms: std.atomic.Value(i64) = .init(0), /// The input it is running, which is what a hang has to report. input: []const u8 = &.{}, target: []const u8 = "", slices: u8 = 1, timeout_s: u32 = 10, dir: []const u8 = "", }; var watch: Watch = .{}; pub fn main(init: std.process.Init) !void { const io = init.io; // The targets' own allocator, checked for leaks after every input. It is // separate from the one this loop uses for its input buffer, so that a leak // it reports is the library's rather than ours. var debug: std.heap.DebugAllocator(.{}) = .init; defer _ = debug.deinit(); targets.backing = debug.allocator(); const gpa = init.gpa; var seconds: u32 = 60; var iterations: ?u64 = null; var seed: u64 = @bitCast(@as(i64, @truncate(std.Io.Timestamp.now(io, .real).nanoseconds))); var only: ?[]const u8 = null; var input_path: ?[]const u8 = null; var dir: []const u8 = "fuzz-findings"; var timeout_s: u32 = 10; var args: std.process.Args.Iterator = .init(init.minimal.args); _ = args.skip(); while (args.next()) |arg| { if (std.mem.eql(u8, arg, "--seconds")) { seconds = std.fmt.parseInt(u32, args.next() orelse "60", 10) catch 60; } else if (std.mem.eql(u8, arg, "--iterations")) { iterations = std.fmt.parseInt(u64, args.next() orelse "0", 10) catch null; } else if (std.mem.eql(u8, arg, "--seed")) { seed = std.fmt.parseInt(u64, args.next() orelse "0", 10) catch seed; } else if (std.mem.eql(u8, arg, "--target")) { only = args.next(); } else if (std.mem.eql(u8, arg, "--input")) { input_path = args.next(); } else if (std.mem.eql(u8, arg, "--findings")) { dir = args.next() orelse dir; } else if (std.mem.eql(u8, arg, "--timeout")) { timeout_s = std.fmt.parseInt(u32, args.next() orelse "10", 10) catch 10; } else { std.debug.print( \\usage: fuzz [--target NAME] [--seconds N | --iterations N] [--seed S] \\ [--timeout S] [--findings DIR] [--input FILE] \\ \\Targets: {s} \\ , .{targetNames()}); std.process.exit(2); } } watch.timeout_s = timeout_s; watch.dir = dir; const thread = try std.Thread.spawn(.{}, watchdog, .{io}); thread.detach(); // One input, from a file, and nothing else: this is how a finding is looked // at again after it has been fixed. if (input_path) |path| { const bytes = try std.Io.Dir.cwd().readFileAlloc(io, path, gpa, .limited(1 << 20)); defer gpa.free(bytes); const name = only orelse targets.all[0].name; const target = find(name) orelse { std.debug.print("no target called {s}; there are: {s}\n", .{ name, targetNames() }); std.process.exit(2); }; watch.input = bytes; watch.target = target.name; watch.slices = target.slices; watch.started_ms.store(nowMs(io), .release); target.run(bytes) catch |err| { std.debug.print("{s}: {t}\n", .{ target.name, err }); show(bytes, target.slices); std.process.exit(1); }; if (debug.detectLeaks() != 0) { std.debug.print("{s}: that input still leaks\n", .{target.name}); show(bytes, target.slices); std.process.exit(1); } std.debug.print("{s}: that input is fine now\n", .{target.name}); return; } var prng: std.Random.DefaultPrng = .init(seed); const random = prng.random(); var buffer: std.ArrayList(u8) = .empty; defer buffer.deinit(gpa); std.debug.print("seed {d}\n", .{seed}); var failures: usize = 0; for (targets.all) |target| { if (only) |name| if (!std.mem.eql(u8, name, target.name)) continue; var runs: u64 = 0; const deadline = nowMs(io) + @as(i64, seconds) * 1000; while (if (iterations) |n| runs < n else nowMs(io) < deadline) : (runs += 1) { try makeInput(gpa, &buffer, random, target); watch.input = buffer.items; watch.target = target.name; watch.slices = target.slices; watch.started_ms.store(nowMs(io), .release); const result = target.run(buffer.items); const leaks = debug.detectLeaks(); watch.started_ms.store(0, .release); if (result) |_| {} else |err| { failures += 1; std.debug.print("\n{s}: {t}\n", .{ target.name, err }); try report(io, dir, target.name, buffer.items, target.slices); // Keep going: one shape of failure is usually many inputs, and // stopping at the first says less than a handful does. if (failures >= 10) { std.debug.print("ten failures; stopping\n", .{}); std.process.exit(1); } } // A leak is the exception to that, and has to end the run: the // memory is still outstanding, so every later input would be // reported as leaking it too and the real culprit would be the one // line nobody reads. if (leaks != 0) { std.debug.print("\n{s}: leaked {d} allocations\n", .{ target.name, leaks }); try report(io, dir, target.name, buffer.items, target.slices); std.process.exit(1); } } std.debug.print("{s}: {d} runs\n", .{ target.name, runs }); } if (failures != 0) std.process.exit(1); } fn find(name: []const u8) ?targets.Target { for (targets.all) |t| if (std.mem.eql(u8, t.name, name)) return t; return null; } fn targetNames() []const u8 { comptime var names: []const u8 = ""; inline for (targets.all, 0..) |t, i| { names = names ++ (if (i == 0) "" else ", ") ++ t.name; } return names; } /// Make the next input: `target.slices` length-prefixed chunks and a tail of /// small numbers. /// /// The tail is not random bytes, and that is the whole of its point. A target /// that asks for a `bool` reads eight bytes and takes anything outside `{0, 1}` /// as `false`, so a random tail fuzzes one option set out of thirty-two; /// `normalize` has five booleans and `file-path` an enum, and neither would ever /// see anything but its default. Writing small little-endian numbers is what /// makes those questions have more than one answer. fn makeInput( gpa: std.mem.Allocator, out: *std.ArrayList(u8), random: std.Random, target: targets.Target, ) !void { out.clearRetainingCapacity(); var content: std.ArrayList(u8) = .empty; defer content.deinit(gpa); for (0..target.slices) |_| { content.clearRetainingCapacity(); if (target.corpus.len == 0 or random.uintLessThan(u8, 8) == 0) { // Sometimes nothing but noise, so that the shapes nobody thought of // are reachable at all. const len = random.uintLessThan(usize, target.content_max); try content.ensureUnusedCapacity(gpa, len); for (0..len) |_| content.appendAssumeCapacity(random.int(u8)); } else { const seed = target.corpus[random.uintLessThan(usize, target.corpus.len)]; try content.appendSlice(gpa, seed); const rounds = 1 + random.uintLessThan(usize, 8); for (0..rounds) |_| try mutate(gpa, &content, random); } if (content.items.len > target.content_max) { content.shrinkRetainingCapacity(target.content_max); } var length: [4]u8 = undefined; std.mem.writeInt(u32, &length, @intCast(content.items.len), .little); try out.appendSlice(gpa, &length); try out.appendSlice(gpa, content.items); } // The numbers. Mostly small, because that is what an index, a count or a // boolean is; occasionally anything at all, because a range's top is worth // reaching too. const values = 4 + random.uintLessThan(usize, 24); for (0..values) |_| { const v: u64 = switch (random.uintLessThan(u8, 8)) { 0 => random.int(u64), 1 => random.int(u32), else => random.uintLessThan(u64, 24), }; var eight: [8]u8 = undefined; std.mem.writeInt(u64, &eight, v, .little); try out.appendSlice(gpa, &eight); } } fn mutate(gpa: std.mem.Allocator, content: *std.ArrayList(u8), random: std.Random) !void { if (content.items.len == 0) { try content.append(gpa, random.int(u8)); return; } switch (random.uintLessThan(u8, 8)) { // A byte, replaced. The commonest useful mutation, and the one that // turns a scheme into a nearly-a-scheme. 0, 1 => content.items[random.uintLessThan(usize, content.items.len)] = random.int(u8), // A byte, replaced by one of the ones these formats are made of. 2, 3 => content.items[random.uintLessThan(usize, content.items.len)] = interesting[random.uintLessThan(usize, interesting.len)], 4 => try content.insert(gpa, random.uintLessThan(usize, content.items.len), random.int(u8)), 5 => try content.insert( gpa, random.uintLessThan(usize, content.items.len), interesting[random.uintLessThan(usize, interesting.len)], ), // A run on the end, which is how a path grows another segment. 6 => for (0..1 + random.uintLessThan(usize, 16)) |_| { try content.append(gpa, interesting[random.uintLessThan(usize, interesting.len)]); }, else => _ = content.orderedRemove(random.uintLessThan(usize, content.items.len)), } } /// The bytes these inputs are mostly made of. /// /// Four formats share this table. A URI reference is structure and payload: /// `:` `/` `?` `#` `[` `]` `@` divide it, the sub-delims live inside its /// components, and `%` with the hex digits behind it is the one escape — a byte /// that turns a segment into a percent-encoding is the most productive mutation /// there is. `.` is here twice over, for the dot segments and for hostnames. /// /// An LDAP URL adds `?` as a positional separator and the filter language /// behind it; a filesystem path adds `\` and the drive letters; and a stamp is /// binary, so the small numbers are its length prefixes, `0x80` the bit a /// continuation sets, and the base64url alphabet what its text is made of. const interesting = blk: { var set: []const u8 = ":/?#[]@"; set = set ++ "!$&'()*+,;="; set = set ++ "%%%"; set = set ++ "0123456789abcdefABCDEF"; set = set ++ "..//"; set = set ++ "\\\\|"; set = set ++ "-_~"; set = set ++ "Cc"; set = set ++ &[_]u8{ 0x00, 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x07, 0x09, 0x0f, 0x10, 0x20 }; set = set ++ &[_]u8{ 0x80, 0x81, 0x85, 0xff, 0xc0, 0x7f }; set = set ++ "sdnxn"; break :blk set; }; /// Print a failing input and write it where it can be fed back. fn report(io: std.Io, dir: []const u8, target: []const u8, input: []const u8, slices: u8) !void { show(input, slices); var name: [128]u8 = undefined; const path = std.fmt.bufPrint(&name, "{s}/{s}-{x:0>16}.bin", .{ dir, target, std.hash.Wyhash.hash(0, input), }) catch return; std.Io.Dir.cwd().createDirPath(io, dir) catch {}; var file = std.Io.Dir.cwd().createFile(io, path, .{}) catch |err| { std.debug.print("(could not write {s}: {t})\n", .{ path, err }); return; }; defer file.close(io); file.writeStreamingAll(io, input) catch {}; std.debug.print( "written to {s}, and `--input {s} --target {s}` runs it again\n", .{ path, path, target }, ); } /// The input, in hex, and then what a target actually reads out of it. /// /// The second half earns its lines: an input is a stream of answers rather than /// a file, so the bytes alone do not say what the parser was given, and that is /// the first thing anybody wants to see. A target that reads no chunk is shown /// as bytes alone, because for it there is nothing else true to say. /// /// One caveat, for a chunk read through an alphabet: this prints it as the /// input carries it, and `sliceWeightedBytes` replaces every byte the weights /// do not list with the first weight's before the target sees it. So a byte /// here that the target's table has no entry for reached the parser as that /// default. Feeding the file back with `--input` reproduces it either way. fn show(input: []const u8, slices: u8) void { std.debug.print("input, {d} bytes:\n ", .{input.len}); hex(input); var smith: Smith = .{ .in = input }; var buffer: [4096]u8 = undefined; for (0..slices) |i| { const content = buffer[0..smith.slice(&buffer)]; std.debug.print("chunk {d}, {d} bytes:\n ", .{ i, content.len }); hex(content); std.debug.print(" as text: |{s}|\n", .{content}); } } fn hex(bytes: []const u8) void { for (bytes, 0..) |b, i| { if (i != 0 and i % 32 == 0) std.debug.print("\n ", .{}); std.debug.print(" {x:0>2}", .{b}); } std.debug.print("\n", .{}); } /// Watch for an iteration that never ends. fn watchdog(io: std.Io) void { while (true) { std.Io.sleep(io, .fromMilliseconds(500), .awake) catch return; const started = watch.started_ms.load(.acquire); if (started == 0) continue; const elapsed = nowMs(io) - started; if (elapsed < @as(i64, watch.timeout_s) * 1000) continue; std.debug.print( "\n{s}: no answer after {d} seconds, which is a hang\n", .{ watch.target, @divTrunc(elapsed, 1000) }, ); show(watch.input, watch.slices); var name: [128]u8 = undefined; const path = std.fmt.bufPrint(&name, "{s}/{s}-hang-{x:0>16}.bin", .{ watch.dir, watch.target, std.hash.Wyhash.hash(0, watch.input), }) catch std.process.exit(3); std.Io.Dir.cwd().createDirPath(io, watch.dir) catch {}; if (std.Io.Dir.cwd().createFile(io, path, .{})) |file| { defer file.close(io); file.writeStreamingAll(io, watch.input) catch {}; std.debug.print("written to {s}\n", .{path}); } else |_| {} std.process.exit(3); } }