# Squallfuzz

> 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.

- Skill: `codejunkie99/squallfuzz` (Agent Skill)
- Install (CLI): `npx get-skill add codejunkie99/squallfuzz`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codejunkie99/squallfuzz/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: codejunkie99 (https://skillmd.com/u/codejunkie99)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/codejunkie99/squallfuzz

---


# 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)
1. read `keelsec.scope.toml` in the repo root. if it is missing, stop and ask the user to create it. never write it yourself.
2. the target must be listed there, and the user must have confirmed in this session that they own it.
3. 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.
4. refuse production unless the entry says `allow_production = true`, which only the user may write.
5. if any check fails, stop with "refused by scope" and send nothing.

example scope file:
```toml
[[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
1. pick the target: a function that parses bytes or strings from outside (file formats, request bodies, config). prefer ones sinkmark flagged.
2. 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`.
3. seed corpus: 5 to 20 small valid inputs taken from the repo's own tests or fixtures.
4. 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.
5. time box: 10 minutes by default, CPU limited, in a container or a throwaway venv.
6. 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
```json
{"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.

