ci(fuzz): compile the harnesses, and refuse the extern that hid the bugs

[Kartikey1306]

Stacked on #99. #99 repairs the five harnesses in tests/fuzz/; this stops the
same class coming back, in the two places it can.

Why it came back-able

Nothing compiles them. tests/fuzz/ is behind EBLDR_BUILD_FUZZ, which
defaults OFF, and no job set it. That is the whole reason three harnesses
could name functions that exist nowhere in the repository —
eos_bootctl_parse, eos_recovery_parse_packet, eos_fw_update_init and
friends — and sit there unnoticed. A harness that is not built cannot fail to
build.

The extern is still legal. All four defects came from a hand-written
prototype standing in for an #include. An extern is a promise the compiler
is obliged to believe and has no way to check, which is why the fourth was
invisible even to a compiler: fuzz_image_verify declared

extern int eos_image_parse_header(const void *flash_base, size_t flash_len);

against a real int eos_image_parse_header(uint32_t addr, eos_image_header_t *out).
It linked. It ran. It fuzzed nothing.

What this adds

fuzz-build job (Fuzz Harness Build)	builds every harness with clang under EBLDR_BUILD_FUZZ=ON, then smoke-runs each for five seconds. EBLDR_BUILD_TESTS=ON too — tests/fuzz is added from tests/CMakeLists.txt, so the fuzz option alone builds nothing and the job would pass having compiled no harness at all. It does not fuzz; a campaign belongs in a scheduled workflow.
tests/unit/test_fuzz_harnesses.py	every harness is built by a CMake target, links eboot_core, defines LLVMFuzzerTestOneInput, and declares no prototypes of its own.

The two halves catch different failures and neither subsumes the other: the
guard is static and stops the pattern being written at all; the job is a
compiler, and catches a signature that drifts under a harness that already
includes the right header.

Mutation-checked:

mutation	fails
restore one extern prototype	test_no_harness_declares_its_own_prototypes
delete one add_executable	test_every_harness_is_built

The job paid for itself on its first run

Not a hypothetical. The first time these harnesses ran under real libFuzzer —
this job, on this PR — fuzz_recovery_protocol trapped in six seconds on

base=0xFFFFDBDB  slot_size=0x0001DBDB  offset=0  len=9253

a write covering [0xFFFFDBDB, 0xFFFFFFFF]: 9253 bytes ending on the last
addressable byte, every one of them inside 32 bits, so accepting it is correct.
The harness's oracle was asserting on base + offset + len > 0xFFFFFFFF — the
address one past the end — where eos_recovery_write_in_range() correctly
bounds the last byte written, exactly as its own final line says:
if ((uint32_t)len - 1u > UINT32_MAX - (base + offset)). The function was
right and the harness reported the opposite. Fixed in #99 as bbf4e89.

That is the case for keeping both halves. The static guard could never have
found an off-by-one inside an oracle — it is a real #include calling a real
function with the right types. Only executing it under a coverage-driven fuzzer
could, and until this job existed nothing did.

Verification

item	result
pytest tests/unit	PASS — 26 passed, 1 skipped
ctest	PASS — 21/21
all 5 harnesses build, link and run	PASS — see caveat

On this head the Fuzz Harness Build job is green in CI, along with the
other 24 checks.

Locally the job could not be run: Apple clang ships no libclang_rt.fuzzer, so
-fsanitize=fuzzer will not link on this host. Each of #99's five harnesses was
instead compiled and linked against eboot_core with a stand-in driver under
-fsanitize=address,undefined and run over ~20k pseudo-random inputs plus every
length from 0 to 200 — all five clean. That covers symbol resolution and harness
logic but not the libFuzzer link or its coverage-guided mutation, which is
precisely the gap that found the oracle bug above. CI is the only place that
runs.

Merge order

After #99 (head bbf4e89), which is after #94 — master does not compile
without it. Nothing here touches tests/fuzz/*.c, so there is no overlap with
#99's diff.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 89.18919% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
tests/unit/test_fuzz_harnesses.py	89.18%	2 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!

[srpatcha]

Review — eBoot#101 "ci(fuzz): compile the harnesses, and refuse the extern that hid the bugs"

head: e2bb1f9 author: Kartikey1306 ci: pass (25 checks, Fuzz Harness Build green)

Verdict: This is the right shape for the problem — a job that compiles what was never compiled, plus a static guard so the pattern that hid it cannot come back. Both work. I ran the guard against master's tests/fuzz/ and it fails naming all five hand-written extern declarations; against this head all five of its tests pass. Two things to fix: the guard has one obvious bypass, and half of fuzz_fw_update's inputs are discarded by the sim-flash geometry before any code under test runs.

This PR is #99 plus one commit (e2bb1f9f); the harness rewrites are reviewed under #99.

Findings

#	Severity	File:line	Finding	Recommended fix
1	Medium	tests/unit/test_fuzz_harnesses.py:38–40	EXTERN_FUNCTION_RE anchors on ^\s*extern\s+, so it only catches declarations that spell extern. A file-scope function declaration has external linkage without it, and the compiler cannot check either one across translation units — they are the same defect. Verified: I dropped a harness containing int eos_image_parse_header(const void *flash_base, size_t flash_len); (the exact wrong signature from the original bug, minus the keyword) into tests/fuzz/ and test_no_harness_declares_its_own_prototypes passed. The module docstring at :20 claims "these tests refuse the pattern, so the sixth cannot be written", which is stronger than what the regex does.	Drop extern\s+ from the pattern and exclude static and LLVMFuzzerTestOneInput instead — i.e. reject any file-scope function declaration ending in ; that is not static and not the entry point. Then re-run against master's tree to confirm it still catches all five, and against the bare-prototype probe.
2	Medium	tests/fuzz/fuzz_sim_flash.h:23,55	Slot B does not exist. FUZZ_FLASH_SIZE is 0x10000 while .slot_b_addr = 0xC000, .slot_b_size = 0x8000 spans 0xC000–0x14000, i.e. 32 KiB past the end of fuzz_flash[], so every erase or write covering it is rejected by fuzz_flash_erase/fuzz_flash_write at :35,:41. fuzz_fw_update.c:42 picks the slot from the input (selector & 1), so half the corpus dies at eos_fw_update_begin. Measured over 20,000 inputs: slot A tried 10,071, began 10,071; slot B tried 9,929, began 0. Half the fuzzing budget of that harness buys nothing, and the A/B asymmetry the harness exists to explore is never explored.	#define FUZZ_FLASH_SIZE (128 * 1024), or shrink the slots to 0x2000 each. Either way the Fuzz Harness Build job should not report an execution count as if it were coverage — a per-harness "reached the code N times" counter would have caught this and would have caught #100's two dead harnesses too.
3	Low	tests/unit/test_fuzz_harnesses.py:89–95	test_every_harness_defines_the_entry_point asserts the string LLVMFuzzerTestOneInput appears anywhere in the file, comments included. Every harness in the tree mentions it in prose, so a file that only discusses the entry point without defining it would pass.	Match a definition: re.search(r'\bLLVMFuzzerTestOneInput\s*\([^)]*\)\s*\{', text).
4	Low	.github/workflows/ci.yml (fuzz-build, smoke-run step)	-max_total_time=5 with no -seed makes this a nondeterministic required check: whether it goes red depends on what coverage-guided search finds in five seconds on that runner. That is exactly how this job earned its place — it found the real off-by-one in #99's recovery oracle in six seconds, which 500k random local inputs never hit — but as a per-PR gate it means an unrelated PR can be blocked by a pre-existing defect discovered that day, with no reproducible run behind it.	Keep the build on every PR; pin the smoke run (-seed=1 -runs=100000) and put the open-ended campaign in nightly.yml. Also add fuzz-build to #90's CI Gate needs: list — #90's test_gate_covers_every_job_that_runs_on_a_pull_request will fail loudly otherwise, which is the guard working, but whichever of #90/#101 lands second has to do it.

Worth keeping exactly as written, because these are the two ways this job could have become a check that cannot fail and both are closed: EBLDR_BUILD_TESTS=ON alongside EBLDR_BUILD_FUZZ=ON (without it tests/fuzz/ is never added from tests/CMakeLists.txt and the job passes having compiled nothing), and the explicit ${#harnesses[@]} -eq 0 failure with nullglob. test_every_harness_is_built and test_every_harness_links_the_library_under_test cover the CMake side of the same question statically, and test_there_are_harnesses_to_check stops the glob-matched-nothing vacuity — that last one is the check most suites in this position forget.

Architecture conformance

Conforms. Tier 1 Foundation (§21); the change is .github/, tests/fuzz/ and tests/unit/, with no runtime dependency and no include pointing up a tier (§5.1). This is the concrete mechanism behind .ai/security.md's "every externally reachable parser … gets fuzz coverage, not just unit tests" and its ctest --no-tests=error rule generalised: a suite that silently collected nothing is a failed check reported as green, and this PR closes that for tests/fuzz/ in two independent ways (a job that compiles, and a static guard that runs without clang or cmake). §8's "trusted computing base minimal and auditable" is the reason it belongs in eBoot rather than in a shared CI template.

Proposed changes

1. Widen EXTERN_FUNCTION_RE to any non-static file-scope function declaration, and re-run it against master's tests/fuzz/ and against a bare-prototype probe.
2. FUZZ_FLASH_SIZE (128 * 1024) so slot B is real, then re-measure fuzz_fw_update's per-slot begin counts.
3. Match a definition, not a mention, in test_every_harness_defines_the_entry_point.
4. Pin the smoke-run seed; add fuzz-build to #90's gate.
5. Land with #99, and close #100 (its fuzz_bootctl and fuzz_fw_update read no input at all — see that review).

Not checked

• libFuzzer link and run: NOT RUN here. All six harnesses compile at this head; this host has no libFuzzer/ASan runtime (libclang_rt.fuzzer.a, libclang_rt.asan.a absent), so none links. The Fuzz Harness Build check is green per gh pr checks 101, but I did not fetch the job log, so the claim that these harnesses have now been linked and run under libFuzzer rests on the check status and the author's comment, not on output I read.
• The reported red-then-green history of this job: not reproduced. The off-by-one analysis on #99 is consistent with the code I read (core/recovery.c:270 bounds the last written byte; the oracle now matches at fuzz_recovery_protocol.c:50), but I did not run the crashing input under libFuzzer.
• My reach-through numbers are not libFuzzer numbers. They come from a plain gcc driver calling LLVMFuzzerTestOneInput in a loop over pseudo-random inputs. That is sound for finding 2 — a rejected erase is rejected regardless of how the input was chosen — and it is not a statement about what coverage-guided search would find.
• test_fuzz_harnesses.py was run without pytest. No pytest on this host; I imported the module and called each test_* function directly. Same assertions, but I did not verify it under the runner CI uses, and codecov reports 4 lines/partials in that file uncovered.
• ctest: NOT RUN on this head. The core/ed25519_verify.c, include/eos_image.h and tests/unit/test_ed25519.c parts of the diff are #94's commit (f704d87f), reviewed under #94/#98.
• The local clone does not have e2bb1f9f; everything above is from a gh api tarball snapshot at that sha.

---

Automated architecture review of e2bb1f9f5f6e — scheduled, model claude-opus-5, checked against the EmbeddedOS Master Design v2.0. Advisory only: this reviewer never approves, requests changes, or merges. Reply here to discuss or push back — a wrong finding is a bug worth reporting.