firmware-guard-audit
Static-code audit for the Coldcard-class "defined-but-zero guard macro" firmware bug. Scans C/C++ firmware source for `#ifndef X_ENABLE` guards protecting hardware-RNG init when the same X_ENABLE is defined elsewhere as `0` (guard is silent while the feature is disabled). Also flags symbol-name aliasing hints where a hardware and a software function share a name and the linker silently picks the fallback. Triggers on 'firmware audit', 'MicroPython RNG', 'MICROPY_HW_ENABLE_RNG', 'ifndef guard', 'linker fallback', 'Coldcard firmware'.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-09
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- firmware-guard-audit
- metadata
- { "subdomain": "crypto-hw", "when_to_use": "firmware source audit for hardware-RNG init, MicroPython port review, defined-but-zero macro guard, weak-symbol linker fallback for RNG, Coldcard-shaped bugs", "upstream_ref": "Coldcard incident 2026-07-05 (Mk2/Mk3 firmware 4.4.1 through 4.1.9, Mk4/Q pre-5.4.0 or Edge pre-6.6.66)" }
- description
- Static-code audit for the Coldcard-class "defined-but-zero guard macro" firmware bug. Scans C/C++ firmware source for `#ifndef X_ENABLE` guards protecting hardware-RNG init when the same X_ENABLE is defined elsewhere as `0` (guard is silent while the feature is disabled). Also flags symbol-name aliasing hints where a hardware and a software function share a name and the linker silently picks the fallback. Triggers on 'firmware audit', 'MicroPython RNG', 'MICROPY_HW_ENABLE_RNG', 'ifndef guard', 'linker fallback', 'Coldcard firmware'.
02 资源文件 1
- 脚本firmware_guard_audit.py10.9 KB
03 SKILL.md 正文
Firmware Guard-Macro Audit Skill
You are looking for the Coldcard-class firmware bug: a preprocessor guard
protecting hardware-RNG initialization fires "the setting isn't set" when
in fact the setting IS set — to zero. The guard reads #ifndef X_ENABLE,
sees X_ENABLE is defined, stays quiet, and the firmware builds without
the hardware RNG. Meanwhile a same-named software-fallback function
happens to satisfy the linker for the symbol the crypto library asks
for, so the build succeeds and the wallet ships. Nothing crashes.
Nothing warns. Every seed the wallet generates for the next four years
is enumerable from device-serial + timer state.
This skill runs OFFLINE against source files the owner or vendor supplies. It never patches source; it emits findings for a human to review + patch. No sandbox, no bash, no network egress required.
Threat model (Coldcard 2026-07-05 postmortem)
- Root cause A —
#ifndefwhere#ifis required. A guard that fires on presence-of-macro instead of truth-of-macro silently disables the feature whenever the config file says#define X 0. - Root cause B — same-symbol-name aliasing. The crypto library
asks for
rng_get()(or similar). The hardware driver exportshw_rng_get(). The MicroPython software fallback exportsrng_get(). Linker picks the fallback; no warning, no error. - Root cause C — the fallback is seeded ONCE per boot from device-stable values (OSC serial, SYSTICK ticks, RTC) instead of from a hardware entropy source. Once one seed is known the entire wallet's history is derivable.
Signals this skill matches
HIGH — defined-but-zero guard around hardware RNG init:
// somewhere in board config:
#define MICROPY_HW_ENABLE_RNG (0)
// somewhere in RNG driver:
#ifndef MICROPY_HW_ENABLE_RNG
hw_rng_init(); // <-- never runs, because the macro IS defined
#endif
HIGH — same-name RNG symbol exported by both hw and fallback:
hw/rng.c: uint8_t rng_get(void) { return read_trng_register(); }
soft/rng.c: uint8_t rng_get(void) { return lcg_next(); }
(Weak-symbol variant, __attribute__((weak)), is even worse — no error
at link time even without -Wl,--allow-multiple-definition.)
MEDIUM — build system quietly links a soft//fallback/ path when
hw/ build is disabled (Makefile / CMake OBJECTS conditional lists,
Kconfig depends on chains, MicroPython port SRC_QSTR selection).
Workflow
1. Load the firmware source tree from findings/crypto-hw/<utc>-audit/src/.
Require a provenance.json naming the vendor, product line, firmware
version, and source commit hash.
2. Run the audit:
python firmware_guard_audit.py --src <path> --pretty
Emits one JSON finding with severity, matches (file:line), and
the specific rule that fired.
3. For any HIGH finding, cite the exact snippet in the postmortem
under the "Technical root cause" section (see
../rng-entropy-audit/references/hardware-wallet-postmortem-template.md).
4. Cross-check against a known-vulnerable-firmware version range table
in the postmortem template. If the firmware being audited falls in
the Coldcard-published range (Mk2/Mk3: 4.4.1 through 4.1.9 [note
the descending numbering is intentional per Coldcard's release
scheme]; Mk4/Q: pre-5.4.0; Edge: pre-6.6.66), auto-escalate to
HIGH regardless of code match.
What NOT to do
- Do NOT patch the source. Findings are advisory; the fix belongs to the vendor or the owner's firmware pinning workflow.
- Do NOT publish the source tree or any diff externally. The skill runs offline against source you have permission to read.
- Do NOT confuse this with a runtime audit. This skill sees the
STATIC pattern; whether the pattern actually causes the hardware
RNG to be skipped at runtime requires the
rng-entropy-auditskill on a captured RNG sample from the built firmware. Both together give a HIGH-confidence verdict. - Do NOT run this skill on binary firmware — you need source. For
binary-only cases, escalate to the
reverserspecialist agent.
04 同仓库更多 Skills
wps-pixie-dust
WPS Pixie-Dust offline nonce attack (reaver -K / pixiewps) and fallback online PIN brute (bully) to recover the AP's WPA PSK without capturing a handshake.
wpa3-sae
WPA3-SAE transition-mode downgrade (DragonShift), SSID Confusion CVE-2023-52424, Dragonblood side-channels, and SAE captive-portal credential recovery against WPA3-Personal networks.
wpa2-psk
WPA/WPA2-PSK handshake capture via targeted deauth + PMKID (no deauth required) + offline hashcat cracking. The most common consumer/SMB encryption mode in 2026.
wpa-enterprise-eap
WPA/WPA2/WPA3-Enterprise (802.1X/EAP) rogue-RADIUS evil-twin for MSCHAPv2 capture, GTC downgrade, and PEAP relay. MSCHAPv2 capture equals a NetNTLM hash — the primary wireless on-ramp to Active Directory.
krack-fragattacks
KRACK key-reinstallation (CVE-2017-13077..13082) and FragAttacks fragmentation/aggregation flaws (CVE-2020-24586..24588, CVE-2020-26139..26147) against legacy or embedded 802.11 supplicants with poor patch cadence.
evil-twin-karma
Evil-twin rogue AP with KARMA/Mana PNL-probe response, captive-portal credential capture, and post-association MITM for PSK/open networks. Distinct from wpa-enterprise-eap which targets 802.1X.