Something went wrong. Try again.
A URI parser and formatter for Zig, modelled on Python's hyperlink package, with LDAP URLs, file: URIs and sdns:// DNS stamps beside it.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// 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, and//! `zig build test --fuzz` runs them with coverage feedback. This is the other//! half: 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, checks every input for leaks,//! and runs for a fixed count, which is what CI wants.//!//! ```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); }}