Skip to content

Latest commit

 

History

History
126 lines (99 loc) · 5.68 KB

README.md

File metadata and controls

126 lines (99 loc) · 5.68 KB

Fuzzing

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.

Layout

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

Targets

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

What counts as a finding

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, or ZeroDivisionError)
  • an exception outside the narrow malformed-input allowlist (ValueError, UnicodeDecodeError, and the documented truncated-Mach-O struct.error)
  • a report that is None or carries a status outside {ok, timeout, error}

Reproducing a CI finding

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.

Running locally (Linux x86_64 only)

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.

Corpus coverage

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

Memory errors in capstone

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>