FuzzUEr generates a UEFI harness for an EDK2 tree, builds that tree's OVMF with AddressSanitizer, fuzzes the protocol and SMI handlers behind it, and triages what reports. It ships as a GitHub Action so an edk2 project can run that in its own CI, and as a set of scripts for doing the same thing at a terminal. The fuzzing backend is either TSFFS on Simics or LibAFL-QEMU; the action always uses QEMU.
This is not a badge to add to a repository on a whim. It is an action for a project that already runs firmware CI on machines it controls.
- It needs a dedicated self-hosted Linux x64 runner. A hosted runner has neither the disk nor the job time for it. There is no hosted path.
- The first run on a cold machine is hours, not minutes. It builds LLVM 15 from source, installs Intel Simics and builds a QEMU through libafl. Later runs cost seconds, because every bootstrap step checks for its own output before doing anything.
- The first checkout is a ~24 GB fetch, and the machine wants ~100 GB free.
- It builds exactly one platform. OVMF X64, from
OvmfPkg/OvmfPkgX64.dscat-a X64 -t CLANGSAN. No other DSC, architecture or toolchain is built, whatever else your tree ships. If your branch'sOvmfPkgX64.dscdoes not build, there is nothing here to fuzz. - It writes to your repository by default.
open-issuesdefaults totrue: a candidate triage attributes to firmware code is filed as an issue in the repository whose tree was fuzzed, and afuzzuer-evidencebranch is pushed there for those issues to link into. So the job needspermissions: {issues: write, contents: write}, and a token that can only read will fuzz, report, and then fail to file in a step log while the job stays green. Setopen-issues: falseto leave findings in the artifact only. - A finding is a candidate, not a defect.
results/findings.mdis the triage of one sweep: four reports were defects in EDK2, and one class of 24 was not -- unrelated modules all reporting the same faulting address, which turned out to be the harness's own argument buffer.fail-on-findingsis off by default for that reason. SECURITY.md says what a candidate is and is not. - A full sweep of one tree is most of a working day. Measured: 6.5 to 11.5 hours,
depending on parallelism. There is a
qualify-onlymode that is about eight minutes, and it is what you should run first. Once a sweep has run,triage-onlyre-reads its campaigns with the current triage code in about ten seconds -- so a change to how findings are clustered, filtered or filed is checked against real data without fuzzing again.
If any of that is a surprise rather than a cost you were expecting, this is the wrong tool for the job you have.
| why | ||
|---|---|---|
| runner | self-hosted, Linux x64, labelled self-hosted, linux, x64 |
nothing else is built or tested. scripts/setup_gh_runner.sh registers one with those labels |
| dedicated to this | one sweep, not shared with other jobs | campaigns compete for the box with each other already; the driver's boot timeout scales with jobs for that reason, and a campaign reporting zero executions is usually contention rather than a broken harness |
| Docker | a daemon this user can talk to | every build and every campaign is a container. The user must be in the docker group; checks.yml fails the run on docker version rather than letting a sweep discover it an hour in |
sudo |
once, at runner registration | setup_gh_runner.sh installs the runner as a systemd service. Without sudo it registers and then has no service, which looks like total failure |
| cores | 16 or more | nothing enforces a count. jobs defaults to a quarter of the cores with a floor of 4, and cores (per firmware build) to a quarter capped at 8 -- below 16 the defaults stop telling machines apart. Every measurement in this README is from a 72-core runner |
| RAM | ~2 GiB per concurrent campaign, and a bootstrap peak | each campaign boots one QEMU at FIRNESS_MEMORY, default 2048 MB, so the default jobs on a 72-core box is 18 guests and ~36 GiB of guest memory alone. The bootstrap is the other peak: it builds LLVM 15 at NJOBS=$(nproc) and clang/lld link steps want roughly 2 GB each, so set NJOBS lower on a smaller box rather than meeting the OOM killer |
| disk | ~100 GB free | breakdown below |
| first run | hours | LLVM 15 from source, the Simics packages, and QEMU through libafl |
python3, git |
on the runner itself | the action runs scripts/fuzz_edk2.py directly, not inside a container. Standard library only; nothing to pip install |
| an Intel Simics licence | only for the Simics/TSFFS backend | the action never starts Simics -- it fuzzes under QEMU -- but the base image installs Simics anyway and there is no build flag to skip it. See THIRD-PARTY.md |
Where the ~100 GB goes, measured on this runner rather than estimated:
| the recursive clone | ~24 GB. edk2 vendors OpenSSL, which vendors its own corpora |
fuzzuer-base (LLVM 15 and Simics) |
26.5 GB |
fuzzuer-ci and fuzzuer-fuzzer on top of it |
~4 GB more; most layers are shared with the base |
| one campaign image per ref fuzzed | ~2.5 GB each on top of fuzzuer-ci |
| a run's worktree, build output and results | single-digit GB |
This README used to say ~100 GB in one place and ~60 GB in another. Neither was wrong: 60 GB
was the Docker side once the clone existed. Budget 100 GB, and expect Docker to hold
considerably more than that over time -- campaign containers are removed as they finish, but
rebuilt images leave untagged layers behind that only docker image prune clears.
A repository-scoped runner serves only that repository. One registered against the
FuzzUEr repository will not pick up a job in your edk2 repository: the job sits in Queued,
nothing explains why, and there is no failed run to notice. Pass the repository URL
explicitly:
scripts/setup_gh_runner.sh <registration-token> https://github.com/acme/edk2-platformAn organisation URL (https://github.com/<org>, no repository) registers one runner for
every repository in the org, which is usually what you want for more than one edk2 tree. One
extra step comes with it: org runners belong to a runner group, and a group can be limited to
selected repositories, with the same silent Queued as the symptom. Check Organisation
Settings -> Actions -> Runner groups.
Either way, confirm Settings -> Actions -> Runners shows one idle before trusting a
schedule. A workflow with no runner never starts and leaves no failed run behind.
examples/fuzzuer.yml is a complete working workflow -- dispatch
inputs, a weekly schedule, the artifact upload and a job summary. Copy it into
.github/workflows/, change the repository: to wherever FuzzUEr lives, and run it once by
hand with qualify_only on. Cut down to the parts that matter:
permissions:
issues: write # the action files findings here
contents: write # and pushes the fuzzuer-evidence branch they link into
jobs:
fuzz:
runs-on: [self-hosted, linux, x64]
timeout-minutes: 720
steps:
- uses: actions/checkout@v4 # your tree
with: {path: edk2, fetch-depth: 0}
- uses: actions/checkout@v4 # FuzzUEr, with its submodules
with: {repository: <you>/FuzzUEr, path: fuzzuer, submodules: true, fetch-depth: 0}
- id: fuzz
uses: ./fuzzuer
with:
source: edk2
qualify-only: true # every stage except the fuzzing: ~8 minutes
- if: always()
uses: actions/upload-artifact@v4
with: {name: fuzzuer, path: "${{ steps.fuzz.outputs.results }}"}fetch-depth: 0 on both, and submodules: true rather than recursive, are both
load-bearing -- docs/private-edk2.md says why each one bites.
docs/private-edk2.md is the full walkthrough, including the other shape: a dispatch workflow run from FuzzUEr against a repository you name, which adds nothing at all to your edk2 repo.
git clone --recurse-submodules <this repo> && cd FuzzUEr
scripts/bootstrap_runner.sh # once per machine; hours when cold
python3 scripts/fuzz_edk2.py --ref edk2-stable202511 --skip-fuzz--skip-fuzz is the qualify form: it ports, builds, checks the instrumentation, discovers
the targets and makes the sanitizer catch a planted error, without spending a fuzzing
budget. Drop it for a real campaign.
Required, and then the ones that change what a run means:
| input | default | |
|---|---|---|
source |
— | required; path to your edk2 checkout, relative to the workspace or absolute. It has to be a git checkout: the ref is taken from git history, so a tarball will not do |
ref |
the checked-out commit | tag, branch or SHA inside that checkout |
budget |
600 |
seconds of fuzzing per target, counted from the harness being reached |
qualify-only |
false |
every stage except the fuzzing. Minutes instead of hours; run this first |
targets |
everything discovered | space separated protocol names. Everything is 242 to 250 across the versions in the table below |
jobs |
a quarter of the cores, floor 4 | targets fuzzed at once |
boot-timeout |
scales with jobs |
seconds a target may spend booting to the harness. Raise it before concluding a harness is broken |
fail-on-findings |
false |
fail the step when triage reports candidates. Off by default: a candidate is something to read, and a sweep that goes red on the first one stops reporting the rest |
fail-on-degraded |
false |
fail the step when a stage comes back degraded -- it did its job, but not for every target, such as a sweep where four campaigns of 243 lost their boot to a timeout. Off by default for the same reason as fail-on-findings, and a stronger one: no full-size sweep on record has ever come back without a degraded stage, so failing on it means a job that is red every week and a report nobody opens |
out |
$RUNNER_TEMP/fuzzuer-run/results/fuzz-<ref> |
where the artifacts go. Outside the workspace on purpose: the pipeline writes a git worktree and a docker build context, and putting those where actions/checkout owns files left the next job unable to check out at all -- it ended up with no .git. The runner wipes $RUNNER_TEMP when the job ends, so set this if you want a copy on the box as well as in the artifact |
token |
— | clones FuzzUEr's own repository when GitHub delivered the action as an archive, which it does for any uses: owner/FuzzUEr@ref. Needed only when FuzzUEr itself is private |
bootstrap |
true |
build the images if the runner lacks them. Idempotent, and seconds on a warm runner -- but hours on a cold one. Set false for a runner you prepared with scripts/bootstrap_runner.sh |
open-issues |
true |
file one issue per candidate in the fuzzed repository. See the warning at the top of this file |
max-issues |
50 |
stop after this many new issues, worst severity first. 0: no limit |
findings-token |
the job token | needed when source is a different repository: Issues: write and Contents: write on that one |
smm |
false |
build with SMM_REQUIRE=TRUE, so the image has an SMM core for SMI handlers to answer |
smi |
false |
also fuzz the SMI handlers discovery found; implies smm. Not yet end to end -- see SMI fuzzing |
standalone-mm |
false |
with smm, the StandaloneMM model rather than PiSmmCore |
bench |
false |
build the SanBench drivers into the campaign firmware, so the benchmark's own protocols get fuzzed. The detects stage scores them on every run regardless -- see Ground truth |
cores |
a quarter of the box, capped at 8 | cores per firmware build. Small on purpose: edk2 builds race at high -j |
extra-defines |
— | extra -D macros for every firmware build, passed last so they override the action's own |
extra-build-options |
[BuildOptions] lines appended to the platform DSC, one per line; an entry with no = becomes CLANGSAN CC_FLAGS. For a tree that needs a relaxation clang wants and GCC does not |
|
extra-pcds |
— | extra --pcd overrides, same form and same precedence |
port-from |
the bundled port | a tree that carries its own sanitizer port. Pointing this at a vendor tree that has none makes every file fail to apply |
port-base |
derived | the commit the port's patches were written against |
All eight:
| output | |
|---|---|
bugs |
path to bugs.md, the triaged table. Empty when triage did not run |
reproducers |
directory of the inputs that triggered a finding, collected per protocol. Empty when there were none |
results |
the directory holding run.json, bugs.md, presence.csv and the per-campaign logs. Point upload-artifact at this |
issues |
space separated URLs of the issues this run filed |
issues-filed |
how many it filed, not counting ones already open |
issues-tracked |
how many of this run's candidates already had an issue |
candidates |
candidate bugs triage attributed to firmware code. Empty, not 0, on a qualify-only run: triage did not run, and "0 candidates" would read as a clean sweep when nothing was fuzzed |
stages |
passed/total, counting only the stages that ran: 11/11 for qualify-only, 13/13 for a full run |
degraded |
true when a stage did its job but not for every target; empty otherwise. The run also emits a ::warning:: naming the stage and what it saw |
| what | how long |
|---|---|
qualify-only on a warm runner |
~8 minutes, 11 stages. Measured on a branch of clean edk2-stable202605 with one package added |
the action's defaults -- one tree, every target discovered, budget: 600 |
6.5 to 11.5 hours. results/fuzz-master-fixed is 243 targets in 6.5 h; results/sweep-v2 is 245 in 10.9 h. Same runner, so the spread is parallelism and boot contention, not the budget |
| one campaign, wall clock | 16 to 42 minutes in the sweeps stored under results/, against budgets of 600 to 900 seconds. The budget starts when the harness is reached, so the instrumented boot and the contention around it are on top of it |
the weekly four-version sweep in fuzz-edk2.yml |
~16 h, which is why its timeout-minutes is 1440 |
| a cold runner, before any of the above | hours, once |
timeout-minutes has to cover the slow case. A job killed mid-sweep has a partial report
already written, which reads as merely incomplete rather than as cut short.
This tool was developed as part of a research project and the paper called FuzzUEr: Enabling Fuzzing of UEFI Interfaces that is NDSS 25 and can be found here.
This repo is responsible for fuzzing the EDK2 UEFI through the use of a harness UEFI application that is reposible for creating well formed inputs to pass to other drivers. The tool generates the harness for TSFFS automatically. Everything has been configured to run within Docker containers to make it easier to use and more portable. FuzzUEr has 3 main components:
Firness and the sanitizer instrumentation both take the original firmware image as input and output the generated harness and instrumented firmware image with ASan, respectively.
There are are only two things that you will need to do in order to run the system: create a shared folder for the input firmware and the input file descibing the protocols to harness. For our experiments we have all of the source code already added as submodules within the eval_source directory.
And then you can add the input file containing the target functions, for example:
[Protocols]
// EFI_IP4_PROTOCOL
gEfiIp4ProtocolGuid:GetModeData
gEfiIp4ProtocolGuid:Configure
gEfiIp4ProtocolGuid:Groups
gEfiIp4ProtocolGuid:Routes
gEfiIp4ProtocolGuid:Transmit
gEfiIp4ProtocolGuid:Receive
gEfiIp4ProtocolGuid:Cancel
gEfiIp4ProtocolGuid:Poll
This file is already included in the eval_source directory.
A new docker container can be created by running the following commands. Clone with the
submodules first -- the image COPYs firness/, tsffs/ and qemu/ out of the checkout, so
on a plain git clone the build stops on a COPY error naming a path you never touched:
git clone --recurse-submodules <this repo>
cd FuzzUEr
docker build -t fuzzuer-image .
docker run -it -v ./eval_source/:/input fuzzuer-image
See Requirements for what this costs: ~100 GB of disk and a first build of
hours, because it compiles LLVM 15 from source and installs the Simics packages.
scripts/bootstrap_runner.sh does the same work and is idempotent, so prefer it if you
intend to run the pipeline rather than the container by hand.
And then you can run everything with the helper script firness.py:
python firness.py -h
-i, --input INPUT Input directory with the source files, or the input file
for a single run
-s, --src SRC Path to the source directory with edk2 and input.txt
-a, --analyze Run the static analysis tool
-g, --generate Generate the harness
-f, --fuzz Run the fuzzer
-e, --eval Evaluate the results of the static analysis tool
-t, --timeout N Fuzzing budget in seconds, counted from the moment the
harness is reached, not from simics startup
--backend BACKEND Fuzzer the generated harness targets:
tsffs (default) | qemu | nyx | none
--smi Fuzz SMI handlers instead of protocols
--sw-smi With --smi: raise software SMIs by writing the ports
rather than by filling a comm buffer
--max-steps N Calls chained per fuzzing iteration
--seed-corpus DIR Start the corpus from a previous campaign's
--snapshot Restore projects/example/booted.ckpt instead of booting
--make-snapshot Boot once, write booted.ckpt, then stop
--reproduce Replay a saved test case instead of fuzzing
--testcase FILE Test case to replay with --reproduce
-g matters more than it looks: -f on its own fuzzes whatever harness is already
built into the image, not the one just generated for the protocol you asked for.
This is an example of running the system with the eval_source directory:
# build the docker image
docker build -t fuzzuer-image .
# run the docker image
docker run -it -v ./eval_source/:/input fuzzuer-image
# run the firness.py script
python firness.py -i /input/input.txt -s /input
This will automatically generate the compilation database, analyze the source code, generate the harness, compile the firmware and harness, and then run the fuzzer. Note: it will run the fuzzer indefinitely, so make sure to CTRL+C to stop it. The results will be in the /workspace/firness_output directory, where the most recent harness is in a folder called Firness but all generated harness are stored based on time they are generated.
The harness targets one of two machines. They answer different questions, so the choice is not just taste.
| Simics / TSFFS | QEMU | |
|---|---|---|
| ASan instrumentation | yes | yes |
| a sanitizer report becomes a counted solution | yes | yes |
| protocols installed by the platform | see note | 89 of 246 on OvmfPkgX64 |
| speed | not re-measured | peak-rate median 7.0 exec/s, throughput median 1.76 |
Both numbers in that last row once read "~0.17 exec/s" and "~7.4 exec/s", and the prose below the table called QEMU forty times faster. Neither claim survives: the QEMU figure was the top of its range rather than a typical campaign, and a later Simics measurement put Simics ahead by roughly an order of magnitude on the protocols the two share.
The figure in the table is the per-campaign median of the exec/sec LibAFL itself reports,
taken from results/sweep-v2 (110 campaigns with a non-zero rate). Reproduce it with
python3 - <<'EOF'
import glob, os, re, statistics
pat = re.compile(r'exec/sec:\s*([0-9.]+)')
rates = []
for c in glob.glob('results/sweep-v2/campaigns/*'):
f = os.path.join(c, 'qemu', 'run.txt')
if not os.path.isfile(f):
continue
best = max([float(v) for v in pat.findall(open(f, errors='replace').read())] or [0])
if best:
rates.append(best)
print(len(rates), statistics.median(rates), min(rates), max(rates))
EOFTake the maximum rate a campaign reported, not the last line: LibAFL starts a fresh
client whose first heartbeat reads 0.000, so reading the tail reports zero for a campaign
that ran fine. Sweeps differ by more than an order of magnitude, and not by date. By this same method
results/fuzz-master (2026-09-16) medians 23.6 over its 215 campaigns,
results/fuzz-master-fixed 21.1 over 235, results/fuzz-master-icount 8.97 over 239, and
results/sweep-census (2026-10-03) medians 1.35 over 85 -- the slowest of them is the
newest, and it postdates both FastSnapshotManager (2026-09-11) and the icount default
(2026-09-18). What sets sweep-census apart is how little it ran: 25065 executions in total,
a median of 12 per campaign against the 600s it was given, so its rates describe that sweep
and not the backend. Quote a sweep that fuzzed, and name it.
A peak rate is also not a throughput. The figure above is the median of each campaign's
peak heartbeat rate. Dividing each campaign's final executions: by the budget it was
given -- counted from the harness being hit, and the measured window lands within a few
percent of it -- puts sweep-v2 at a median of 1.76 exec/s against the 7.0 above. The same
division gives 29.1 for fuzz-master (300s), 10.9 for fuzz-master-fixed and 8.25 for
fuzz-master-icount (900s each), and 0.02 for sweep-census. Budgets are not uniform across
the stored sweeps, so a rate quoted without its budget is not comparable to another. Treat the comparison as open until both are measured in the
same week on the same protocols -- only 66 protocols exist on both backends, so outside
that set the comparison is between platform builds, not between backends.
With ASAN_FUZZER=qemu, AsanLib emits the LibAFL crash handshake when it reports, and that
is now confirmed end to end rather than inferred. In one benchmark campaign the firmware
emitted 3628 FWSAN: interface reports and 3283 FWSAN: double-fetch reports, and LibAFL
recorded exactly 6911 objectives -- every report became a counted solution. Reports are also
parsed out of the serial capture into crashes.csv and attributed to a module, so a finding
is actionable whether or not it escalated.
A caveat that still holds: most objectives in a typical campaign are crashes and timeouts
rather than escalated sanitizer reports, so an objective count is not a bug count. Group by
return IP and read the Module column -- scripts/bug_report.py does both.
Pick with --backend. The backend is compiled into the harness, so it has to be set
at generation time (-g --backend qemu), not just at fuzzing time.
# generate and fuzz under QEMU
python firness.py -i /input/input.txt -s /input -a -g -f --backend qemu
Two QEMU helpers stand on their own:
# does the harness load and reach HARNESS_START at all? (stock QEMU, no fuzzer)
./scripts/qemu_smoke.sh path/to/Firness.efi
# fuzz it under LibAFL-QEMU, for 600 seconds by default
./scripts/qemu_fuzz.sh path/to/Firness.efi [seconds]
qemu_smoke.sh is a real test rather than a demo because the two backends give
opposite, unambiguous answers: a --backend none build runs to completion, while a
--backend qemu build raises #UD on the four magic bytes that stock QEMU cannot
decode. Either answer appearing for the wrong build means the backend never reached
the compiler.
Simics is what the paper used; QEMU needs no licence, which is the reason to reach for it. See the table above on speed -- the old "forty times faster" claim does not hold. The whole path, from nothing to a campaign:
1. Build the firmware with ASan and the QEMU backend. ASAN_FUZZER=qemu is what makes
a finding reach the fuzzer rather than only the log.
export WORKSPACE=$PWD/eval_source/edk2 EDK_TOOLS_PATH=$WORKSPACE/BaseTools
export CONF_PATH=$WORKSPACE/Conf CLANGSAN_BIN=/path/to/llvm/bin/
cd $WORKSPACE && make -C BaseTools && source edksetup.sh
build -a X64 -b DEBUG -t CLANGSAN -p OvmfPkg/OvmfPkgX64.dsc \
-D ASAN_SCOPE=per-module -D ASAN_FUZZER=qemu \
-D FIRNESS_QEMU_CRASH=TRUE \
-D NETWORK_IP6_ENABLE=TRUE -D NETWORK_HTTP_BOOT_ENABLE=TRUE
FIRNESS_QEMU_CRASH=TRUE is not optional in practice. It is what sets
FIRNESS_LIBAFL_CRASH_ON_EXCEPTION, so a guest fault ends the iteration instead of dead
looping until the boot timeout -- without it a campaign that finds a crash looks exactly
like one whose firmware never reached the harness. The two NETWORK_* defines decide
whether the IPv6 and HTTP protocols are installed at all, so they change which targets the
census finds rather than just how fast the run goes. scripts/fuzz_edk2.py passes all three
on every build, which is why its results and a hand-built tree's can disagree.
ASAN_SCOPE=per-module is the gentler scope and a reasonable first build; full is what the
pipeline uses and what every number in this README was measured on.
2. Build the fuzzer. It compiles its own QEMU, so the first build is long.
cd Harness/qemu_fuzzer && cargo build --release
3. Generate a harness for the QEMU backend. The backend is compiled in, so it has to be chosen at generation time.
python scripts/firness.py -i /input/input.txt -s /input -a -g --backend qemu
4. Check it loads before spending a campaign on it.
OVMF_CODE=.../OVMF_CODE.fd ./scripts/qemu_smoke.sh .../Firness.efi
5. Fuzz it.
export FIRNESS_OVMF_CODE=$WORKSPACE/Build/OvmfX64/DEBUG_CLANGSAN/FV/OVMF_CODE.fd
export FIRNESS_OVMF_VARS=$WORKSPACE/Build/OvmfX64/DEBUG_CLANGSAN/FV/OVMF_VARS.fd
export FIRNESS_TIMEOUT=60
./scripts/qemu_fuzz.sh .../Firness.efi 600
Three of these are easy to get wrong, and each fails quietly:
FIRNESS_OVMF_CODEis not optional. Left unset the fuzzer runs the distribution OVMF, which has no ASan in it at all. The campaign then reports crashes and timeouts only and looks like a clean target; that is what "objectives: 0" meant here for a whole afternoon. The script warns about it now.FIRNESS_TIMEOUTdefaults to 10 seconds, which an instrumented boot can exceed. Every iteration then ends as a timeout, and a real crash is indistinguishable from one. If every input is an objective and the corpus stays empty, raise it before believing anything.- The emulator is linked into the fuzzer, so it has no data directory and looks for its
roms relative to the working directory.
qemu_fuzz.shnow finds the bridge checkout'spc-biositself; if it cannot, setFIRNESS_QEMU_BIOS_DIR.
To confirm the reporting path end to end rather than trusting it, fuzz AsanSelfTest.efi
instead of a harness. Seeded with a first byte of 0 it commits a heap overflow and the
fuzzer records an objective about a second after the boot; seeded with 4 it does the same
allocation correctly and produces nothing but a timeout.
scripts/fuzz_edk2.py takes a ref and goes as far as a bug report. It is what the
GitHub workflow runs, once per version.
scripts/bootstrap_runner.sh # once per machine
python3 scripts/fuzz_edk2.py --ref edk2-stable202511
Thirteen stages, each printing PASS, WARN or FAIL with what it saw. The run stops at the first failure, because every stage after one would report a number that looks like a result. WARN is the third outcome -- the stage did its job, but not for every target it was asked about, such as a sweep where four campaigns of 243 lost their boot to a timeout. That does not stop the run, because the campaigns that did fuzz are what it exists to report on. The exit code says which happened: 0 all passed, 2 degraded, 1 a stage failed.
| stage | what it answers |
|---|---|
ready |
are the images and the builder container here |
fetch |
is the ref real, and checked out |
submodules |
edk2 vendors its dependencies; three separate build failures name none of them |
port |
did the sanitizer integration apply, and how much of it merged cleanly |
vendor |
defects the vendor branch ships, repaired and named -- a branch can leave a library class unresolvable for OvmfPkg and still ship, and that fails AutoGen before a line compiles |
sync |
the ported tree is in the builder container, and it has an OvmfPkg/OvmfPkgX64.dsc to build |
build |
did the firmware build |
instrumented |
do modules actually carry __asan_load/__asan_store -- "applied" is not "instrumented" |
discover |
protocols from headers, SMI handlers from registration call sites |
image |
a campaign image holding this tree, so the harness is built from the version under test |
detects |
does the sanitizer report a deliberate error in this build's own firmware |
fuzz |
the campaigns, and how many reached the harness |
triage |
cluster, separate the harness and the PCI hole from the firmware, name a driver |
--skip-fuzz stops after detects, which is the useful form for asking "does this
version port, build and report at all" without spending a fuzzing budget. It reports 11
stages rather than 13, because fuzz and triage are recorded as skipped rather than as
passes -- a qualify run that claimed 13/13 would be claiming it fuzzed.
Two stages exist because of what they caught. image is there because campaigns
generate and build their harness from the tree inside the image: without a per-version
image, every version in a matrix is fuzzed against whichever edk2 the image shipped and
the result is filed under the ref the matrix named. detects builds the tree a second
time with -D ASAN_FUZZER=none, because under the LibAFL backend the runtime reports by
executing a custom instruction that is an invalid opcode outside LibAFL -- the guest dies
in CpuDxe before BDS launches the self test, which looks exactly like firmware with no
bugs in it.
.github/workflows/fuzz-edk2.yml runs the bootstrap and then the driver over a list of
refs, and writes one table saying which stages each version passed.
It needs a self-hosted runner labelled self-hosted, linux, x64. Register one with:
scripts/setup_gh_runner.sh <registration-token> # Settings -> Actions -> Runners
scripts/bootstrap_runner.sh # then the images, once per machine
Without a runner the schedule has nothing to execute on and never starts -- and there is
no failed run to notice either, so check Settings -> Actions -> Runners shows one idle
before trusting the weekly sweep.
The first run on a cold machine builds LLVM 15 from source, installs the Simics packages,
and builds QEMU through libafl -- hours, not minutes. Every bootstrap step checks for its
own output first, so later runs cost seconds. Requirements has the disk
breakdown; the short version is ~30 GB for the images, ~2.5 GB more per version fuzzed, and
considerably more than that held by Docker over time, because campaign containers are
removed as they finish but rebuilt images leave untagged layers that only
docker image prune clears.
Run it manually once with qualify_only before trusting a full sweep: 11 stages, a few
minutes, and it exercises everything except the fuzzing. The default four-version matrix is
~16 hours at a 600-second budget, which is where timeout-minutes: 1440 comes from -- the
old 720 would have killed the job a third of the way through the second version, with the
first version's report already written.
docs/private-edk2.md is the walkthrough, and it holds CI-critical
detail this file only summarises: a dispatch workflow that reads a repository you name, or a
workflow file for your own edk2 repo that calls this one as an action. Both go through the
same scripts/fuzz_edk2.py, and neither writes to the tree under test -- the sanitizer
port is applied to a throwaway worktree of your ref. The repository, as against the tree,
does get written to by default: see open-issues above.
examples/fuzzuer.yml is the whole workflow, ready to copy.
permissions:
issues: write # open-issues defaults to true, and files them here
contents: write # and pushes the fuzzuer-evidence branch they link into
# ...
steps:
- uses: ./fuzzuer # after checking this repo out with submodules, fetch-depth 0
with:
source: edk2 # your tree
qualify-only: true # every stage except the fuzzing: ~8 minutesVerified by fuzzing a branch of clean edk2-stable202605 with one package added, through
--source with its own origin: 11/11 stages, the port applying 21 clean and 8 resolved,
260/260 modules instrumented, 244 protocols and 16 SMI handlers discovered, and the self test
provoking a double free, three store reports and a length-driven overread in that tree's own
firmware. That run used a throwaway fixture outside the repository, so there is no artifact
under results/ for it -- reproduce it against any tree of your own with
python3 scripts/fuzz_edk2.py --ref <your-branch> --source /path/to/your/edk2 --skip-fuzzEvery upstream stable tag from edk2-stable202305 to edk2-stable202608, and master.
These are tianocore's own commits -- edk2-stable202505 here is 6951dfe7d59d, which is
what git ls-remote https://github.com/tianocore/edk2.git returns for that tag. For each
one the port applies with nothing unresolved, the firmware builds, the built modules carry
ASan checks, and the self test catches a double free, an overflow, an underflow, a
use-after-free and a length-driven overread in that version's own firmware.
Read the table below as a record of runs that happened, not as a guarantee that is
maintained. The weekly sweep in .github/workflows/fuzz-edk2.yml re-tests four refs --
edk2-stable202502, edk2-stable202505, edk2-stable202511 and master -- because four
at a 600-second budget is already ~16 hours. Every other row is a one-off that is not
revisited, so a regression on, say, edk2-stable202402 would not be caught here. If you
care about a specific version, qualify it yourself: that is one command and about eight
minutes.
| version | port | instrumented | protocols found |
|---|---|---|---|
| edk2-stable202305 | 29 clean, 0 resolved | 218/220 | 249 |
| edk2-stable202308 | 28 clean, 1 resolved | 218/220 | 250 |
| edk2-stable202311 | 27 clean, 2 resolved | 220/222 | 250 |
| edk2-stable202402 | 25 clean, 4 resolved | 218/220 | 244 |
| edk2-stable202405 | 25 clean, 4 resolved | 222/224 | 247 |
| edk2-stable202408 | 24 clean, 5 resolved | 228/230 | 247 |
| edk2-stable202411 | 23 clean, 6 resolved | 228/228 | 248 |
| edk2-stable202502 | 22 clean, 7 resolved | 248/248 | 248 |
| edk2-stable202505 | 19 clean, 9 resolved | 236/236 | 247 |
| edk2-stable202508 | 19 clean, 9 resolved | 242/242 | 245 |
| edk2-stable202511 | 19 clean, 9 resolved | 242/242 | 243 |
| edk2-stable202602 | 19 clean, 9 resolved | 242/242 | 242 |
| edk2-stable202605 | 20 clean, 8 resolved | 244/244 | 243 |
| edk2-stable202608 | 20 clean, 8 resolved | 246/246 | 244 |
| master | 21 clean, 8 resolved | 262/262 | 245 |
The "resolved" column is how many of the port's 30 modified files needed a conflict resolved rather than merging outright, and it tracks distance from the commit the port sits on: nothing to resolve on the tags nearest it, nine on the ones furthest away.
None of this makes the next release safe by assumption. Each of the versions above
needed something, and the something was different every time -- a toolchain flag edk2
added, a build rule section it split, a firmware volume it moved, a driver it now ships
itself. What the port does is fail loudly on each: port refuses to leave a conflict
unresolved, instrumented counts the modules that actually carry ASan checks rather than
trusting the build, and detects makes the sanitizer catch a deliberate error in the
firmware it just built.
A campaign on 202505 reaches the harness and fuzzes: 53,234 iterations over 919 edges for EFI_BLOCK_IO_PROTOCOL in a 300 second budget, and the triage names a finding by module, file and line.
Everything is in one include. Set two defines above [LibraryClasses] in the
platform DSC and pull it in:
[Defines]
DEFINE ASAN_SCOPE = per-module # off | per-module | full
DEFINE ASAN_FUZZER = tsffs # tsffs | qemu | none
!include MdeModulePkg/Include/Dsc/Asan.dsc.inc
Both are overridable from the build command line, so one tree builds every variant:
build -a X64 -b DEBUG -t CLANGSAN -p OvmfPkg/OvmfPkgX64.dsc \
-D ASAN_SCOPE=full -D ASAN_FUZZER=qemu -D FD_SIZE_IN_KB=8192
The platform still has to reserve the shadow region and publish gAsanInfoGuid from
PEI. Without that HOB AsanLib deactivates itself, and every instrumented access
becomes a no-op that looks exactly like a clean run. OvmfPkg/PlatformPei/MemDetect.c
is the worked example.
python3 uefi_asan/apply_asan.py --to <edk2 tree>
That is the whole of it. --from names the tree the integration is taken from and
defaults to eval_source/edk2 beside this repository; --base is the commit that
integration sits on and is known to the tool. scripts/fuzz_edk2.py calls exactly this,
so the workflow and a person at a terminal apply the sanitizer the same way.
The tool lives with the sanitizer rather than with the pipeline because that is what it is: the way to put this sanitizer on an edk2, not something one harness does privately. It applies 81 added files and three-way merges 30 modified ones, then repairs what the merge cannot know about -- a toolchain flag this edk2 has added, a build rule section it has split, a firmware volume it has moved, a driver it now ships itself. It refuses to leave a conflict unresolved rather than producing a tree that builds and is not instrumented.
The sanitizer is five libraries, two headers and a patch. Against a clean upstream checkout:
# 1. the libraries and headers, copied in
cp -r uefi_asan/AsanLib <edk2>/MdeModulePkg/Library/
cp -r uefi_asan/AsanLibNull <edk2>/MdeModulePkg/Library/
cp -r uefi_asan/AsanRuntimeLib <edk2>/MdeModulePkg/Library/
cp -r uefi_asan/AsanMemoryLib <edk2>/MdePkg/Library/
cp -r uefi_asan/AsanMemoryLibRepStr <edk2>/MdePkg/Library/
cp uefi_asan/Asan.h <edk2>/MdeModulePkg/Include/Library/
cp uefi_asan/AsanInfo.h <edk2>/MdeModulePkg/Include/Guid/
# 2. the patch, which is the part that touches upstream files
patch -p1 --forward --batch --binary -d <edk2> < uefi_asan/asan.patch
scripts/firness.py does both of these itself; the manual form is for a tree it does not
manage. The patch touches the toolchain definition (BaseTools/Conf/tools_def.template
adds the CLANGSAN toolchain, build_rule.template adds the SANITIZER build rule and
its nasm command), the DXE and SMM cores so the allocator can poison and quarantine
(Core/Dxe/Mem/Page.c, Mem/Pool.c, Core/PiSmmCore), and a few call sites.
Then, per platform:
- Declare the HOB guid.
gAsanInfoGuidhas to be inMdeModulePkg.decunder[Guids]. The patch adds it; check it survived a merge. - Include the DSC fragment and set the two defines, as above.
- Reserve the shadow and publish the HOB from PEI. This is the one part that is
genuinely platform specific, and the one whose absence is silent: without the HOB
AsanLib deactivates itself and every instrumented access becomes a no-op.
OvmfPkg/PlatformPei/MemDetect.c(AsanInitializeShadowMemory) is 20 lines and is the model -- reserveLowMemory >> 3bytes at0x5000000, zero it, andBuildGuidDataHob (&gAsanInfoGuid, ...). - Resolve
AsanLibfor every module type the platform builds. A core INF that calls into the runtime --DxeMain,PiSmmCore,BootScriptExecutorDxe-- consumes the class by name, so a platform that resolves it for only some phases stops with "Instance of library class [AsanLib] is not found". - Build with
-t CLANGSAN, and pointCLANGSAN_BINat a clang whose ASan pass matches the runtime's expectations. Clang 15 is what this tree is built and tested with.
Then run AsanSelfTest before trusting a single result.
per-module instruments nothing until a module opts in, which keeps the image inside
a 4MB flash. Give the module's entry in [Components]:
MdeModulePkg/Universal/HiiDatabaseDxe/HiiDatabaseDxe.inf {
<BuildOptions>
*_CLANGSAN_X64_SAN_FLAGS == $(ASAN_SAN_FLAGS)
<LibraryClasses>
AsanLib|MdeModulePkg/Library/AsanLib/AsanLib.inf
NULL|MdeModulePkg/Library/AsanLib/AsanLib.inf
BaseMemoryLib|MdePkg/Library/AsanMemoryLibRepStr/AsanMemoryLibRepStr.inf
}
full instruments every DXE phase module -- 265 of 277 on OVMF against 3 at
per-module -- which is what finds an error whose allocation and access are in
different drivers. It roughly triples the image, so it needs -D FD_SIZE_IN_KB=8192.
Three rules that are easy to get wrong, each of which cost a debugging cycle:
- The runtime is pinned uninstrumented in its sources, not in the build files. A
DSC global
SAN_FLAGS ==overrides an INF[BuildOptions]outright, and edk2 builds a library instance once, so[Components]cannot reach it either. The AsanLib and AsanMemoryLib sources carryno_sanitizepragmas instead, which also means they hold under whatever flags a platform sets. - Stack instrumentation is per-module on purpose. The compiler writes frame
redzones inline and unconditionally, past AsanLib's range guard, so a module whose
stack falls outside the mapped shadow corrupts memory.
fulltherefore adds-mllvm -asan-stack=0globally. Nothing is lost for cross-module work: a stack frame never outlives the function that owns it. SAN_FLAGSis replaced with==, never appended with=.build_ruleputs it afterCC_FLAGS, so a-fno-sanitizeinCC_FLAGShas no effect.
AsanSelfTest commits deliberate errors and says what it expects, so a silent ASan is
distinguishable from a clean run. Put it on an ESP and boot it:
./scripts/make_esp.sh Build/OvmfX64/DEBUG_CLANGSAN/X64/AsanSelfTest.efi esp.img
A working image reports the overflow, the underflow and the use-after-free with shadow
FA/FD, reports the double free, and stays silent on the control case.
Nothing downstream means anything until a deliberate error has been seen caught, and a
sanitizer that reports nothing looks exactly like firmware with no bugs in it. Two sets of
drivers exist for that. Both are gated behind SAN_BENCH/FW_SAN in the DSC and the FDF
alike, so neither is in a firmware that was not asked for them.
AsanSelfTest is the small one: five heap classes in a UEFI application, exercised on every
pipeline run by the detects stage. It proves the shadow is mapped and the runtime reports.
What it cannot prove is that a separately built and separately instrumented driver reports
when reached through a protocol call, which is the path a campaign actually exercises.
SanBenchDxe is the larger one, and that is the path it covers. It publishes two protocols
whose members each hide a fault behind a condition an input has to satisfy, and
SanBenchDrive calls each one from an application:
| class | what it is | detected |
|---|---|---|
| heap-buffer-overflow | copy past a fixed allocation | yes |
| heap-buffer-underflow | read one entry below a table | yes |
| tlv-overread | header read from a blob too small to hold it | yes |
| size-overflow | wrapped Count * sizeof |
yes |
| use-after-free | read through a released slot | yes |
| double-free | release the same slot twice | yes |
| foreign-pointer | dereference a region the driver does not own | yes (FWSAN) |
| double-fetch | untrusted word read twice in one call | yes (FWSAN) |
| stale-interface | read through an uninstalled interface | yes (FWSAN) |
| variable-size-trusted | GetVariable reissued into a known-small buffer |
yes (FWSAN) |
| boot-service-after-exit | a boot service called after ExitBootServices | not attemptable |
Score it with one boot per class, which is the only way the two destructive cases do not take the rest of the run with them:
python3 scripts/bench_cases.py --code OVMF_CODE.fd --vars OVMF_VARS.fd \
--app SanBenchDrive.efi --out cases --roms /workspace/qemu_fwEleven of eleven scorable classes are detected, measured rather than asserted --
results/bench-scoreboard.md is the run. The twelfth, boot-service-after-exit, needs the
runtime phase and an application under BDS is by definition before it, so it is reported
"not scorable here" rather than counted as a miss: a benchmark that hides its own gaps is
worth less than one that names them.
The eleven include a control case on correct code, which passes by staying silent. It
is not in the table above because it is not a bug class, but it is the one that makes the
other ten mean anything -- a runtime that reports on the control is reporting on everything,
and ten detections would look identical. The remaining blind spot is stack memory: the build
carries -mllvm -asan-stack=0 because enabling stack instrumentation faults the boot in
CpuDxe, so a stack overread of any shape is invisible.
The detects stage scores all eleven on every run and fails the stage on a class that
regressed. It did not always: the probe asked for these drivers only under --bench, which
action.yml defaults to false and no workflow sets, so the most capable ground truth in the
tree had never run in CI while three workflows uploaded a bench_cases.log nothing wrote.
The probe now carries them unconditionally. That build replaces only the probe firmware, so
it cannot put a positive control in front of the fuzzer.
--bench (the action's bench input) is now about the campaign firmware: it builds these
drivers into the image the fuzzer drives, so the benchmark's protocols are discovered and
fuzzed like any other target. That is a different question from "does this build report",
and it is still off by default.
ASan and UBSan find memory errors. Four classes matter in firmware and are invisible to both, because the memory involved is perfectly valid:
- foreign-region access -- a dereference into flash, the legacy BIOS window, or any
region the calling driver does not own. The shape of an SMM callout. Regions are registered
by
FwSanDxeand checked before the shadow lookup, because flash has no shadow. - double fetch -- a word read twice from memory something outside the firmware can still change between the two reads. Validate with one read, use another.
- stale interface -- a read through a protocol interface after it has been uninstalled.
FwSanDxehooksUninstallProtocolInterfaceand poisons the storage. - variable-size-trusted --
GetVariablereissued into a destination already known to be too small.
A harness declares which buffers are untrusted around each call, which is what gives the
double-fetch check something to watch; without that a double fetch is just two ordinary
reads. Findings are emitted in the same shape ASan uses, so they reach crashes.csv and
triage with a module and a return IP rather than being narration only.
This found a real one: UefiDevicePathLib reads a caller-supplied device path node's Type
and SubType twice within one ConvertDevicePathToText call --
DevicePathUtilities.c:130 and :152.
Each of these asserts something a passing build does not:
| script | what it asserts |
|---|---|
detect_check.py |
a deliberate error is still reported, and the correct case is not |
bench_cases.py |
all eleven benchmark classes, one boot each |
harness_check.py |
every requested protocol member is generated and dispatchable |
asan_sync_check.py |
the two copies of the sanitizer have not drifted |
input_check.py |
the guest actually received the testcase, not just its length |
protocol_presence.py |
which protocols the firmware installs, so absent ones are skipped |
build_sweep.sh |
every harness links with the real toolchain |
verify_all.sh runs the ones that do not need a campaign. scripts/fuzz_edk2.py gates on
detect_check, the benchmark, the presence census and input_check as pipeline stages.
--smi targets SMI handlers instead of protocols. The harness writes the buffer into
the SMM Core private data and raises the SMI, which is what SmmCommunicationCommunicate
does; a plain write to the command port dispatches on whatever the last DXE caller left
behind.
A handler is reached one of two ways and a harness can only drive the one it was built for, so there are two targets.
| target | how a handler is addressed | what the fuzzer controls |
|---|---|---|
DiscoveredSmi |
a GUID in an EFI_SMM_COMMUNICATE_HEADER |
the comm buffer: its length and every field of the handler's parameter block |
DiscoveredSwSmi |
a command byte registered on EFI_SMM_SW_DISPATCH2_PROTOCOL |
the data byte at port 0xB3, and which registered command byte goes to port 0xB2 |
The second is --smi --sw-smi. Writing 0xB2 from ring 0 is the software SMI, the most
exposed SMM entry point on real hardware, and no comm-buffer harness can produce it: a
handler on the software dispatch protocol has no GUID and no caller buffer at all -- the
dispatcher builds its EFI_MM_SW_CONTEXT from the two port reads. Before this target
existed, every such handler was reported as unharnessable, which is true of the comm-buffer
channel and reads as a statement about the firmware.
The command byte comes from discovery and is confined to it. scripts/discover_smi.py --sw-output finds every SwSmiInputValue assignment that feeds a dispatch Register call,
resolves it through the tree's own #defines, and writes DiscoveredSwSmi.txt with the
byte beside the handler and the registration it was read out of. The harness writes nothing
else, and that is a safety property rather than a tuning choice: port 0xB2 is shared with
the platform. ICH9_APM_CNT_CPU_HOTPLUG (0x04) reaches CpuHotplugSmm, whose error paths
CpuDeadLoop() inside SMM and take the guest with them, and 0x00 is what OVMF's own
SmmControl2 Trigger writes for every SmmCommunicate. A byte nothing registered reaches
no handler either way -- both dispatchers log No handler for SMI value and return -- so a
sweep of 0..255 buys no coverage and can forfeit a campaign's whole budget.
Most registrations in edk2 proper are written SwContext.SwSmiInputValue = (UINTN)-1, which
asks the dispatcher for the next free byte at registration time. There is no static
answer to that, so those handlers are counted, named in smi-handler-inventory.json with
their channel, and left out of the target list rather than guessed at. On the EVAL-1 tree
that is one target (B2SmiDispatchHandle, 0xB4, OvmfPkg/B2SmiDispatch/B2SmiDispatch.c:238)
out of seven registrations -- counted per registration and not per handler name, because
SecurityPkg registers PhysicalPresenceCallback and MemoryClearCallback from
Tcg2Smm.c and again from TcgSmm.c, and a count keyed by name reported five.
Upstream this target is empty, and for a reason earlier than the command byte.
OvmfPkgX64.dsc builds no producer of EFI_SMM_SW_DISPATCH2_PROTOCOL on edk2-master or
on eval_source/edk2: the only one in edk2 is UefiPayloadPkg/PchSmiDispatchSmm, which
that platform does not include, and none of the four drivers that register on the protocol
is in the build either. EVAL-1 adds both, under its own SMM_SUPPORT define. So discovery
writes no DiscoveredSwSmi.txt upstream -- and because an absent request file is also what
a discovery that never ran leaves behind, it writes DiscoveredSwSmi.absent instead,
carrying the census and one reason per registration. The verdict line
(software SMI channel: N of M registration(s) addressable) is printed either way, and
scripts/sw_smi_census_check.py asserts the count, the note and the one case that could
cost a guest: a handler name claimed by two registrations at two different bytes is dropped
rather than resolved to either.
scripts/sw_smi_check.py asserts the discovery, the confinement, the port order -- the data
byte first, because writing 0xB2 is what raises the SMI -- and that IoLib survives the
INF's library pruning, which drops every class the emitted harness never calls.
Driving SMI handlers is not yet end to end, but the harness generates. It did not used
to: the generator needs smi-function-guid-map.json, the C++ analyser builds that from the
campaign image's compilation database, and that database was baked from a build with no SMM
modules -- so no handler registration was in it and the map came back null. That was fixed
by building the image's database with the SMM defines, and verified on an EVAL-1 tree,
analyser plus generator with no boot: a map of 10 entries, Generated Harness, Compiled Harness. A null map still appears on a protocol run, where nothing asked for the SMI
analysis; do not read one as the failure above.
What remains is downstream of generation, and it is the same wall protocol targets hit on
an SMM image: no campaign on an SMM_REQUIRE build has reached a harness. Measured 0
of 4 campaigns and 0 iterations, with the guest stopping in late BDS right after
[Bds]UnregisterKeyNotify, SMM itself healthy at 554 dispatches, and the same firmware
booting past that point under the detect probe -- which is what rules out SMM, the disk and
the boot order as the cause. So --smi will generate a harness and then report nothing
until that is fixed.
Under QEMU an SMM core needs fuzz_edk2.py --smm. SMM_REQUIRE defaults to FALSE in
OvmfPkgX64.dsc, so a default build contains no SMM core and no handlers -- measured, zero
SMM modules -- while the guest is already started with q35,smm=on. The machine has SMM and
the firmware does not use it, so an SMI harness has nothing to talk to. --smm sets
SMM_REQUIRE=TRUE; add --standalone-mm to get the StandaloneMM model instead of
PiSmmCore, which is what installs EFI_MM_COMMUNICATION3_PROTOCOL. On the Simics path this
does not arise, because that backend boots a different image which has SMM already.
Verified on edk2-stable202502, the same version built both ways:
| default | --smm |
|
|---|---|---|
| firmware | FV 62% full | FV 65% full |
| modules carrying ASan checks | 248/248 | 276/276 |
| SMM modules in the image | 0 | 45 |
| SMI handlers discovered | 17 | 17 |
The handler count does not move because discovery is static analysis of the source -- those 17
were always found. It is a lower bound: discovery matches registration call sites, so a
handler registered through a function pointer held in a structure is not found
(scripts/discover_smi.py says so, and firness/firness/SmiFunctionAnalysis.h:78 carries the
same gap as a TODO). A tree with more handlers than this reports is expected, not a defect. What --smm changes is that there is now an SMM core and a set of
handlers in the image for them to be driven against.
One limit worth stating plainly: the 28 added modules resolve AsanLibNull, so they carry
instrumentation whose handlers are no-ops. --smm makes SMI fuzzing reach real SMM code; it
does not yet give memory-safety detection inside SMM. Doing that needs a shadow mapping
reachable from SMRAM, which is a separate piece of work.
Two things had to be fixed before that build worked, and both are worth knowing if you port this elsewhere:
- The sanitizer attaches
AsanLibper component in[Components], whileSAN_FLAGSinstruments at the toolchain level. Any flag that adds components therefore produces modules that are instrumented with no runtime behind them, and the link fails on undefined__asan_init/__asan_load*. The four SMM/MM module types now resolveAsanLibNull-- Null, not the real one, because SMM runs in SMRAM behind its own page tables and cannot reach the shadow. - The port carries a DEBUG trace into
MdeModulePkg/Core/PiSmmCore/PiSmmCore.cthat named a local variable upstream has since removed, so a DEBUG build of a newer edk2 failed withuse of undeclared identifier 'IsOverUnderflow'. Fixed by printing only the value that exists in both shapes. It was briefly written up as an upstream defect and is not one -- clean upstream has no such trace. Seeresults/findings.mdfor why that mattered and how to avoid the same mistake with carried patches.
--host linux emits the same harness as a kernel module, so handlers can be driven from
a running OS rather than from DXE. It reads the firmware's FirnessSmmInfo variable out
of /sys/firmware/efi/efivars for the addresses it needs.
python firness/harness_generator/main.py --smi --host linux --backend none \
--edk2 eval_source/edk2 -i eval_source/evalset/SmiTest.txt \
-sm <cache>/smi-function-guid-map.json ... -o out/
Build the module against the guest's kernel, then load it:
insmod firness_smi.ko comm_phys=$COMM comm_size=$COMMSZ \
bufptr_phys=$BUFPTR bufsize_phys=$BUFSZ smi_port=$PORT target=2
insmod answering -ENODEV is the designed path: the work happens in module init and
the module unloads itself. target=<n> picks one handler; without a fuzzer attached the
input is all zeroes, so the choice byte is always 0 and only the first handler is ever
reached.
Cross handler state. chain=<n> calls n handlers before the iteration ends, so one
runs against whatever the previous one left behind. That is the only way to reach a bug
where a handler stores something -- a length, an NVRAM variable -- that a different handler
later trusts; with one call per iteration the second handler never sees the first one's
state. target then steps rather than pins, so chain=4 target=0 dispatches handlers
0, 1, 2, 3 in order, which is deterministic without a fuzzer attached.
Two limits worth knowing before reading anything into a chained run:
- With
--backend noneevery generated length field reads zero, so the handlers reject the buffer and no state actually crosses. A chain only carries data with a fuzzer supplying non-empty messages. - SMM code is not instrumented.
Asan.dsc.incexcludesSMM_COREandDXE_SMM_DRIVER, because SMM needs its own shadow and its own runtime and that is not wired up. A memory error inside a handler is therefore not an ASan finding here; what surfaces is an ASSERT, a crash or a timeout, which is how the VarCheckPolicy defect was found.
Three things that are not obvious:
- The guest usually has no toolchain and no kernel headers. Cross-build the
.koagainst matching headers (the vermagic has to match exactly), strip it, and hand it to the guest as a raw disk rather than installing a compiler in the target. - X64 plus SMM needs
-global ICH9-LPC.disable_s3=1, or OVMF asserts inPlatform.cbefore any driver runs. - Start from a fresh
OVMF_VARScopy each run. Reusing a written one lands the guest in the UEFI Shell, because the earlier boot rewrote the boot order.
scripts/guest_run.py drives the whole thing over the guest's serial console and can
capture the firmware debug port with --fw-log, which is the only place OVMF's DEBUG
output goes:
python scripts/guest_run.py --code OVMF_CODE.fd --vars VARS.fd --disk guest.qcow2 \
--extra-disk ko.img --script run.sh --fw-log fw.log
To confirm a handler really ran rather than just an SMI being raised, look for the SMM
core's dispatch line in --fw-log. Success means a handler registered for that GUID
executed; Not Found means none was:
SmmCore: dispatch 2A3CFEBD-27E8-4D0A-8B79-D688C2A3E1C0 len 0 -> Success
A protocol harness calls a protocol member with fuzzed arguments. That reaches the API
surface of the network stack and almost none of its parsing: what Dhcp4Dxe, Mtftp4Dxe
and UefiPxeBcDxe spend their code on is bytes that arrived from somewhere else, and
nothing was ever on the other end of the wire.
scripts/net_peer.py is that other end -- a server whose every reply is built from an
input file. QEMU's socket netdev hands the guest's NIC straight to a process, so this
needs no tap device, no root and no host networking:
-netdev socket,id=n0,connect=127.0.0.1:5555 -device virtio-net-pci,netdev=n0
It speaks ARP, ICMP, DHCP and TFTP -- enough to PXE boot a UEFI guest. Run it by hand to watch an exchange:
python3 scripts/net_peer.py --port 5555 --serve-file some.efi
A healthy run prints the whole boot: DHCP DISCOVER -> OFFER, DHCP REQUEST -> ACK,
ARP who-has, TFTP RRQ, then TFTP transfer complete, 29 block(s). The guest then
executes what it was handed, so a real application in --serve-file puts the PE loader
and everything that application touches in range as well.
scripts/net_fuzz.py is the loop around it:
python3 scripts/net_fuzz.py --code OVMF_CODE.fd --vars OVMF_VARS.fd \
--serve-file some.efi --iterations 20 --mutate 8 --mutate-labels DATA
--mutate-labels picks which replies to corrupt -- OFFER, ACK, OACK, DATA -- and
choosing it is most of the skill:
| target | reaches | what a run looks like |
|---|---|---|
DATA |
TFTP block handling, then the PE loader | 232 mutations into a 40KB image, start failed: Unsupported |
OFFER,ACK |
the DHCP option parser | exchange completes, PXE gives up expanding the boot path |
OACK |
option negotiation | the transfer aborts before a block is sent |
Three things that took a measurement each to get right:
- The BOOTP header is 236 bytes, not 240. Four bytes of padding in front of the magic cookie is enough for the client to reject the offer and go back to DISCOVER, which looks exactly like a guest that cannot see the server.
- TFTP needs a fresh server port per transfer. RFC 1350 gives each transfer its own
TID and the client sends its ACKs there; answering from port 69 got one DATA out and
never an ACK back. PXE also asks for
blksize/tsize, which want an OACK first. - Corrupt the payload, not the framing. Mutations in the BOOTP header or in an OACK
end the exchange before the parser under test runs, so the DHCP replies protect their
first 236 bytes and
--mutate-labels DATAis the default.
net_fuzz.py takes a baseline with no mutations before it starts and counts only
reporting sites beyond it. An instrumented boot raises the same 23 every time, so a run
that counted reports would call every iteration a finding -- the same trap as
Triage below.
A campaign's solution count is not a bug count. Most reports are the harness, not the firmware, so check the module a report is attributed to before chasing it:
python scripts/triage_crashes.py
python scripts/symbolize.py # raw addresses -> module names
Group reports by return IP first. A single site dominating the count is a scanner or a loop rather than N bugs.
results/bugs-qemu.md and results/bugs-simics.md are generated from the report stream, so
a row there is a report and not a defect. results/findings.md is the hand-written other
half: the reports that were read back to source, with the four that are defects in EDK2
written up, and the 24 that are not recorded so they are not re-triaged. A defect that never
trips a sanitizer -- a hang, say -- can only appear in that file.
| LICENSE | MIT, for this repository's own code. Note that its copyright line names no legal entity, which THIRD-PARTY.md flags as an open question |
| THIRD-PARTY.md | the eight submodules and what they are licensed under, including the GPL-2.0 QEMU, the Intel binary-only material in edk2-non-osi, and the Simics licence this tool does not grant you |
| SECURITY.md | how to report a vulnerability in FuzzUEr, and -- separately -- why a finding it produces is a candidate rather than a confirmed vulnerability |
| CONTRIBUTING.md | what this project treats as evidence for a change |
| docs/private-edk2.md | running it against your own edk2 in CI, in detail |
| examples/fuzzuer.yml | a complete consumer workflow, ready to copy |
