0x0000manual
Testing parsers, from one file to a thousand targets.
These chapters are my working notes on parser testing, written so I can come back to them and so others can learn from them. They start with what a parser does with its input and end with how to design an experiment across many targets. Every chapter ends with the key ideas, a five-question quiz, and three exercises on Parsarium, from warm-up to challenge, each with a hint and a solution. Your progress is saved in this browser.
0x0010chapters
- 01What a parser doesBytes come in, structure comes out. Why that step matters for testing and security, and how Parsarium organises it.
- 02Formats and grammarsHow formats are built, how a grammar and constraints describe them, and how to read a control file byte by byte.
- 03Controls and receiptsWhat it means for a parser to be verified, what a harness records, and how to read a run receipt.
- 04Choosing targetsCells, adoption ranks, parser families, and standard APIs: how to pick a target set that fits your question.
- 05Coverage feedbackHow AFL++ decides an input is interesting, how Parsarium gets that signal from eight languages, and how to read the numbers.
- 06Differential testingSend the same bytes to many parsers and compare what they say. Where they disagree is where to look.
- 07Fuzzing at scaleFrom one AFL++ campaign to hundreds: seeds, budgets, parallel runs, repetitions, and keeping track of it all.
- 08Triage and disclosureFrom a file in crashes/ to a report a maintainer can act on: reproduce, reduce, deduplicate, assess, and disclose.
- 09Designing an experimentA checklist for studies that use many parsers: question, targets, budgets, repetitions, metrics, and what to publish.
- AGlossaryThe terms used in this manual, in one place.
0x0020setup
Before the exercises.
Install the command from PyPI. You need Python 3.11 or newer; running harnesses also needs Docker with Linux amd64 and arm64 support.
$ python3 -m pip install parsarium $ parsarium list
Some exercises read files from the catalog, such as controls and receipts. They live in the folder parsarium home --path prints. Export it once per terminal, and the exercises refer to it as $PARSARIUM:
$ export PARSARIUM="$(parsarium home --path)" $ ls "$PARSARIUM"
Results go to runs/ in the folder where you run the commands. If you work from a clone of the repository instead, set PARSARIUM_HOME to the clone and the command uses it.