squallfuzz: targeted fuzzing of the user's own code
job
pick one function that handles untrusted input, write a small harness for it, fuzz it with coverage feedback, and turn each unique crash into a finding with a minimal input.
gap it targets
- evidence (public record): the common open coverage-guided fuzzers need a hand-written harness and leave crashing inputs as loose files to triage, and the best known one is AGPL.
- hypothesis: starting from a sinkmark or hullscan finding and writing the harness for that function makes fuzzing usable for people who would never set it up. not measured.
scope gate (do this before any packet)
- read
keelsec.scope.toml in the repo root. if it is missing, stop and ask the user to create it. never write it yourself.
- the target must be listed there, and the user must have confirmed in this session that they own it.
- refuse, even if listed: cloud metadata and link-local addresses (
169.254.0.0/16 including 169.254.169.254 and 169.254.170.2, fd00:ec2::254, 100.100.100.200, metadata.google.internal, metadata.azure.com), and any host that resolves to one of them. resolve the name first and check the IP, so a DNS trick cannot point you there.
- refuse production unless the entry says
allow_production = true, which only the user may write.
- if any check fails, stop with "refused by scope" and send nothing.
example scope file:
[[target]]
name = "staging"
url = "https://staging.example-owned.dev"
proof = "http-token" # local | compose | http-token | dns-txt
allow_active = false
max_rps = 5
for local fuzzing, the "target" is a function in the user's repo. the gate still applies to anything the harness would send over the network: harnesses must not open sockets.
inputs
- a repo path and a target function, or a finding that names one.
method
- pick the target: a function that parses bytes or strings from outside (file formats, request bodies, config). prefer ones sinkmark flagged.
- write a harness file in
fuzz/ that calls the function with one input and catches only expected errors. it must not touch the network, write outside a temp dir, or call os.system.
- seed corpus: 5 to 20 small valid inputs taken from the repo's own tests or fixtures.
- run with what is installed:
atheris (python), cargo fuzz, go test -fuzz, or libFuzzer if present. if nothing is installed, write a simple random-mutation loop with coverage from sys.monitoring (python 3.12) and say it is a weaker substitute.
- time box: 10 minutes by default, CPU limited, in a container or a throwaway venv.
- for each crash: dedupe by top three stack frames, minimize the input, save it under
fuzz/crashes/<hash>, and write a finding.
what counts as a finding
- an uncaught exception type that the function does not document, a hang over 5 seconds, memory growth over 1 GB, or a sanitizer report.
output
{"command":"squallfuzz","rule_id":"ks.fuzz.uncaught-exception","kind":"fuzz","severity":"medium","confidence":"high","location":{"path":"app/parsers/csv_import.py","start_line":88},"evidence":"IndexError on 3-byte input, saved as fuzz/crashes/a91c.bin","sources":["squallfuzz"],"status":"open"}
today vs later
- today: this skill plus whatever fuzz engine the language already has.
- once the keelsec engine exists:
keelsec squallfuzz --from-finding <id> --minutes 10.
stop and scope
- only the user's own code. never fuzz a remote service. never run harnesses outside a sandbox or temp dir.
1---2name: squallfuzz3description: "Use when a specific parser, decoder, or input-handling function in the user's own code should be stress-tested with generated inputs, starting from a static finding, with a harness written for it and crashes turned into findings."4metadata:5 source: https://skillmd.com/skills/codejunkie99/squallfuzz6---78# squallfuzz: targeted fuzzing of the user's own code910## job11pick one function that handles untrusted input, write a small harness for it, fuzz it with coverage feedback, and turn each unique crash into a finding with a minimal input.1213## gap it targets14- evidence (public record): the common open coverage-guided fuzzers need a hand-written harness and leave crashing inputs as loose files to triage, and the best known one is AGPL.15- hypothesis: starting from a sinkmark or hullscan finding and writing the harness for that function makes fuzzing usable for people who would never set it up. not measured.1617## scope gate (do this before any packet)181. read `keelsec.scope.toml` in the repo root. if it is missing, stop and ask the user to create it. never write it yourself.192. the target must be listed there, and the user must have confirmed in this session that they own it.203. refuse, even if listed: cloud metadata and link-local addresses (`169.254.0.0/16` including `169.254.169.254` and `169.254.170.2`, `fd00:ec2::254`, `100.100.100.200`, `metadata.google.internal`, `metadata.azure.com`), and any host that resolves to one of them. resolve the name first and check the IP, so a DNS trick cannot point you there.214. refuse production unless the entry says `allow_production = true`, which only the user may write.225. if any check fails, stop with "refused by scope" and send nothing.2324example scope file:25```toml26[[target]]27name = "staging"28url = "https://staging.example-owned.dev"29proof = "http-token" # local | compose | http-token | dns-txt30allow_active = false31max_rps = 532```33for local fuzzing, the "target" is a function in the user's repo. the gate still applies to anything the harness would send over the network: harnesses must not open sockets.3435## inputs36- a repo path and a target function, or a finding that names one.3738## method391. pick the target: a function that parses bytes or strings from outside (file formats, request bodies, config). prefer ones sinkmark flagged.402. write a harness file in `fuzz/` that calls the function with one input and catches only expected errors. it must not touch the network, write outside a temp dir, or call `os.system`.413. seed corpus: 5 to 20 small valid inputs taken from the repo's own tests or fixtures.424. run with what is installed: `atheris` (python), `cargo fuzz`, `go test -fuzz`, or libFuzzer if present. if nothing is installed, write a simple random-mutation loop with coverage from `sys.monitoring` (python 3.12) and say it is a weaker substitute.435. time box: 10 minutes by default, CPU limited, in a container or a throwaway venv.446. for each crash: dedupe by top three stack frames, minimize the input, save it under `fuzz/crashes/<hash>`, and write a finding.4546## what counts as a finding47- an uncaught exception type that the function does not document, a hang over 5 seconds, memory growth over 1 GB, or a sanitizer report.4849## output50```json51{"command":"squallfuzz","rule_id":"ks.fuzz.uncaught-exception","kind":"fuzz","severity":"medium","confidence":"high","location":{"path":"app/parsers/csv_import.py","start_line":88},"evidence":"IndexError on 3-byte input, saved as fuzz/crashes/a91c.bin","sources":["squallfuzz"],"status":"open"}52```5354## today vs later55- today: this skill plus whatever fuzz engine the language already has.56- once the keelsec engine exists: `keelsec squallfuzz --from-finding <id> --minutes 10`.5758## stop and scope59- only the user's own code. never fuzz a remote service. never run harnesses outside a sandbox or temp dir.