Coverage-guided fuzzing of SMDA's untrusted-input surfaces with
atheris / libFuzzer. atheris publishes no
arm64 or macOS wheels, so the fuzzers run on Linux CI only
(.github/workflows/fuzzing.yml); everything needed to reproduce a finding
works anywhere without atheris.
| File | Role |
|---|---|
targets.py |
the actual target bodies — plain Python, no atheris import |
harness.py |
atheris/libFuzzer plumbing, instruments targets.py |
fuzz_<target>.py |
one entry point per target, for libFuzzer to run |
generate_seeds.py |
builds a per-target seed corpus from the test fixtures |
smda.dict |
libFuzzer dictionary of magics, section names, report keys |
replay.py |
runs a target over files on disk, no atheris needed |
minimize.py |
delta-debugs a crashing input to a small reproducer |
prune_corpus.py |
bounds the cached corpus by file count and total size |
corpus_coverage.py |
replays a corpus under coverage.py to show which code it reaches |
| Target | Surface |
|---|---|
loaders |
MemoryFileLoader(..., map_file=True) and every accessor |
formats |
one format loader per input with isCompatible() bypassed |
disassembler |
disassembleUnmappedBuffer(), the full pipeline |
buffer |
disassembleBuffer() with fuzzer-chosen architecture/bitness/base |
report |
SmdaReport.fromDict() over fuzzer-generated JSON, plus round-trip |
synthesis |
synthesizeBinary() per format, asserting the output re-parses |
SMDA's public contract is that malformed input yields an error report, not an
exception: disassembleUnmappedBuffer() catches broadly and the loaders funnel
through reraise_non_operational_exception. The harnesses mirror that, so
ordinary parse failures are not findings. What fails a run:
- a segfault, abort, or uncaught native error in capstone/lief
- a hang (libFuzzer
-timeout) or memory blow-up (-rss_limit_mb,-malloc_limit_mb) - a programming-error exception from the stricter fuzzing oracle (
AssertionError,AttributeError,ImportError,IndexError,KeyError,MemoryError,NameError,RecursionError,ReferenceError,SyntaxError,TypeError,UnboundLocalError, orZeroDivisionError) - an exception outside the narrow malformed-input allowlist (
ValueError,UnicodeDecodeError, and the documented truncated-Mach-Ostruct.error) - a report that is
Noneor carries a status outside{ok, timeout, error}
Download the fuzz-artifacts-<target> artifact from the failed run, then:
python fuzzing/replay.py <target> artifacts/crash-*
Once confirmed, minimize it and pin it as a regression test:
python fuzzing/minimize.py <target> artifacts/crash-<hash>
See tests/fuzz_regressions/README.md for how to commit the reproducer.
Note that libFuzzer's own -merge=1 and -minimize_crash=1 are unusable under
atheris: both re-execute argv[0] to run their inner passes, which here is the
bare Python interpreter without the harness script, so they process nothing and
report zero results. minimize.py and prune_corpus.py replace them and work
on every platform.
pip install -e . && pip install atheris
python fuzzing/generate_seeds.py corpus_loaders --profile binary
python fuzzing/fuzz_loaders.py corpus_loaders -max_total_time=120 -dict=fuzzing/smda.dict
Use --profile formats / --profile buffer / --profile report /
--profile synthesis for the corresponding targets: those targets consume
selector bytes from the front of the input, and the profile prepends them.
The corpus is cached per target in CI, so coverage accumulates across runs instead of restarting from the seeds every time.
In CI each target runs one fuzzer process per runner core on a shared corpus
directory (libFuzzer's -jobs/-fork cannot be used under atheris, for the
same reason as -merge). Each worker's log is printed in its own group.
libFuzzer's cov: figure counts edges but does not say where they are. On the
weekly and manual runs, the coverage jobs replay each target's accumulated
corpus under coverage.py, and Corpus coverage summary combines them into one
table, least-reached files first, plus an HTML report artifact
(fuzz-coverage-html). A file that stays near 0% is a gap to fill with seeds or
a target. Locally, without atheris:
python fuzzing/corpus_coverage.py disassembler corpus_disassembler --report report.txt
The targets above see a memory error inside capstone only if it happens to crash
the process. On the weekly and manual runs, Fuzz with ASan capstone rebuilds
capstone with AddressSanitizer and libFuzzer edge counters and runs the buffer
and disassembler targets with atheris' asan_with_fuzzer.so preloaded, so an
out-of-bounds access in a decoder is reported where it happens, and coverage
inside capstone guides the fuzzer as well. lief is not rebuilt: compiling it from
source takes longer than the fuzzing. These targets manage only a few inputs a
second under ASan and libFuzzer replays the corpus before mutating, so the job
starts from the 400 smallest cached inputs plus the floor and seeds rather than
the whole cache.
A finding from this job reproduces only against the same instrumented build:
CC=clang CFLAGS="-fsanitize=address,fuzzer-no-link -fno-omit-frame-pointer -g -O1" \
pip install --force-reinstall --no-deps --no-binary capstone "capstone==<version>"
LD_PRELOAD="$(python -c 'import atheris; print(atheris.path())')/asan_with_fuzzer.so" \
ASAN_OPTIONS=detect_leaks=0 python fuzzing/fuzz_buffer.py artifacts/crash-<hash>