Embedded OTA / Bootloader Toolkit
嵌入式 OTA/Bootloader 升级链路检查与打包工具。审计侧静态扫描升级代码的防砖漏洞(每条附可直接粘贴的修复代码):跳转 APP 未重定位中断向量表(VTOR)、跳转前未关中断、未校验 APP 有效性、升级数据无 CRC/哈希、flash 擦除地址未按页对齐、擦写期间未喂看门狗、分区地址硬编码、接收等待无超时、无防降级版本校验、升级状态未持久化、写入前未擦除、关闭看门狗后未恢复等;工具侧计算 CRC32/CRC16、算分区表并生成 .h、生成 64 字节镜像头、打包升级包 .pkg、校验包完整性。当用户要做 IAP/OTA 升级、bootloader 开发与跳转、固件打包、分区规划、远程或本地固件升级、升级后变砖跑飞死机排查、毕设要做固件升级/远程升级、需检查升级流程安全性时使用;原生支持裸机 Cortex-M/RISC-V 与 Arduino/ESP8266 框架写法(认 ArduinoOTA、Update、ESPhttpUpdate、ESP.wdt*、Serial.*、delay、millis)。已配套 190 项测试(145 审计 + 45 工具)。
Embedded OTA / Bootloader Upgrade Toolkit
Two tools, one goal: never brick a device during firmware upgrade.
ota_audit.py— audit side: statically scans upgrade code and reports brick-vulnerable spots by severity (no compiling, no hardware)ota_tool.py— tool side: CRC, 64-byte image header generation, partition layout,.pkgpacking, verification
Platform coverage: the auditor targets the full Cortex-M family (ST STM32 / GD32 / CH32 / APM32 / Nordic nRF5x / NXP / Renesas RA...), RISC-V, and the Arduino / ESP8266 framework layer (ESP32 built with Arduino uses vocabulary entirely different from ESP-IDF — adapted separately). Rule signals recognize ST HAL, GD32 FMC, Nordic nrfx, ESP-IDF, Zephyr, MCUboot, Arduino/ESP8266 and generic naming. The tool side (ota_tool.py) is pure byte arithmetic, completely MCU-agnostic. See "Platform Applicability" below.
When to Use It
- Dead on first interrupt after upgrade: forgot
SCB->VTORrelocation before jumping to APP — all APP interrupts land in the bootloader vector table. Rule 1. - Bricked by banked upgrades: jumping with an empty/half-flashed APP partition — instant HardFault. Rule 3.
- "Boots but misbehaves": received data written to flash without verification — transmission errors became firmware. Rule 4.
- Watchdog kills upgrade mid-flash: multi-second erase/write without feeding the dog — every failure is another brick chance. Rule 6.
- "Upgrade succeeded but firmware is broken": NOR flash can only write 1-to-0; writing a page without erasing first corrupts it. Rule 14.
- Don't know what goes in the header: an industrially adequate 64-byte image header format + generator + verifier.
30-Second Demo
Feed in a realistic IAP jump + upgrade write:
/* bootloader.c */
#define APP_BASE 0x08008000
void iap_load_app(void) {
typedef void (*app_fn)(void);
app_fn app = (app_fn)APP_BASE;
__set_MSP(*(volatile uint32_t *)APP_BASE);
app();
}
void ota_write_image(uint8_t *buf, uint32_t len) {
flash_erase(0x08008100);
flash_write(APP_BASE, buf, len);
HAL_Delay(100);
}
Audit output (score 49/100, 4 critical, 4 major, 3 minor):
| Rule | Sev | Line | Issue |
|---|---|---|---|
| R1 | CRIT | L7 | Vector table not relocated before APP jump (no SCB->VTOR anywhere) |
| R2 | CRIT | L7 | Interrupts not disabled before jump (no __disable_irq) |
| R3 | CRIT | L7 | APP validity not checked before jump (no SP/vector sanity) |
| R4 | CRIT | L13 | Upgrade data has no integrity check (flash write without CRC) |
| R5 | MAJ | L12 | Erase address 0x08008100 not 1K/2K/4K aligned |
| R7 | MAJ | L12 | Hardcoded partition address (bare 0x08xxxxxx) |
| R9 | MAJ | all | No anti-rollback version check |
| R10 | MAJ | all | Upgrade state not persisted (no resume after power loss) |
| R11 | MIN | L13 | Flash write return value unchecked |
| R12 | MIN | all | No progress output in upgrade flow |
| R13 | MIN | L14 | Hardcoded delay inside upgrade flow |
Quick Start
Audit
python ota_audit.py bootloader.c # single file
python ota_audit.py bootloader.c high # critical only
python ota_audit.py sketch.ino # Arduino sketch (.ino/.pde)
python ota_audit.py --dir ./boot # directory (.c/.h/.cpp/.hpp/.cc/.cxx/.ino/.pde)
python ota_audit.py --dir ./boot --html report.html # HTML report
python ota_audit.py --dir ./boot --fail-under 80 # CI gate: score < 80 exits 1
Exit codes: 0 = clean, 1 = findings, 2 = usage/internal error (CI friendly; --fail-under N gates by score).
Pack
# 1) CRC
python ota_tool.py crc app.bin
# 2) Partition layout (generates .h with compile-time overflow asserts)
python ota_tool.py layout --flash 256K --align 2K boot:32K app:96K app_bak:96K cfg:8K --out partition.h
# 3) Pack (bin + 64B header), also emits MCU-side header
python ota_tool.py pack app.bin -o app.pkg --addr 0x08008000 --ver 1.2.3 --hw-id 0x0001 --emit-header
# 4) Verify (expected board/address guards against cross-flashing)
python ota_tool.py verify app.pkg --hw-id 0x0001 --addr 0x08008000
Exit codes: 0 = success, 1 = verification failed, 2 = usage error.
What the tools cannot see:
references/ota-checklist.mdis the manual pre-flight checklist (power-cut / disconnect / wrong-packet fault injections), each item annotated with covering rules ([R1]...[R15]) and what must be tested on real hardware ([HIL]).
End-to-End Path for New Projects
- Plan partitions:
ota_tool.py layoutcomputes the table and generatespartition.h(with compile-time overflow asserts); bootloader and APP both take address macros from it — stop hand-writing bare addresses. - Self-audit after writing upgrade code:
ota_audit.py bootloader.c --html report.html; clear criticals to 0 and score >= 80 before flashing. Every finding ships paste-ready fix code. - Package delivery:
ota_tool.py pack app.bin --emit-headerproduces.pkg+ MCU-side parsing header. - Last step before flashing:
ota_tool.py verify app.pkg --hw-id 0x0001 --addr 0x08008000confirms package integrity and board/address match; then run the power-cut/disconnect/wrong-packet injections fromota-checklist.mdon real hardware.
Audit Rules Quick Reference (15)
| # | Sev | Rule | One-liner |
|---|---|---|---|
| 1 | CRIT | Jump without VTOR relocation | Must SCB->VTOR = APP_ADDR before jumping |
| 2 | CRIT | Interrupts not disabled before jump | Need __disable_irq() + clear NVIC pending |
| 3 | CRIT | APP validity unchecked | SP must land in SRAM, reset vector in flash |
| 4 | CRIT | No integrity check on upgrade data | Compare CRC/hash before/after flash write |
| 5 | MAJ | Erase address not page-aligned | Not a 1K/2K/4K multiple — erases the wrong page |
| 6 | MAJ | Watchdog not fed during flash | WDT enabled but not fed = guaranteed reset |
| 7 | MAJ | Hardcoded partition address | Bare 0x08xxxxxx; use partition macros |
| 8 | MAJ | Receive wait without timeout | while(!rx_done) forever — disconnect = brick |
| 9 | MAJ | No anti-rollback check | Missing version compare — vulnerable firmware can be reflashed |
| 10 | MAJ | Upgrade state not persisted | State in RAM only — lost on power cut |
| 11 | MIN | Flash write return unchecked | Write failures must not be silent |
| 12 | MIN | No progress output | Field debugging becomes guesswork |
| 13 | MIN | Hardcoded delays | Magic-number delays break on other platforms |
| 14 | MAJ | No erase seen before write | NOR is 1-to-0 only; un-erased page = corrupt |
| 15 | MAJ | Watchdog not restored after disable | Disabled WDT never re-enabled = unbootable after upgrade |
Judgment calibration (highlights):
- Upgrade-chain rules (R4, R6, R8-R15) are gated on "OTA-context keywords or jump evidence"; ordinary business code (e.g. storing config to flash) will not be spammed by upgrade rules — deliberate false-positive governance.
- Context keywords match on "previous char is not alphanumeric" rather than
: real code almost always uses underscore prefixes (esp_ota_write/nrf_dfu_flash_store/gd32_ota_apply), andsilently kills the whole rule set;quotastill won't match. - Framework-layer context additionally recognizes camelCase and dotted forms:
ArduinoOTA/ESPhttpUpdate/Update.begin(/Updater.write(— a separate case-sensitive regex (case-insensitive would swallow the lowercaseotainsidequota). A pureArduinoOTAsketch (begin in setup, handle in loop) has no standalone ota token and would score a fake 100 without this. - "Jump evidence" must be call-shaped:
__set_MSP(,jump_to_app(,((void(*)(void))addr)(),asm volatile("mov pc, ..."). A variable namedstart_appor a vector-table initializer does not count. - Cross-file suspicion downgrade: when this file lacks a step but evidence exists that an external module handles it (
#include "image.h",verify_*(), customIV[]table,*_partition_state()), report as minor tagged "verify manually — likely done externally"; without such evidence still report critical (tests cover both). - Framework-managed downgrades to notes (unscored): Arduino's erase happens inside the
Updatelibrary — structurally invisible in a sketch, so R14 emits a note instead of a finding. - R13 only flags magic delays replacing timeouts:
<50msdelays treated as yield/throttle; delays already guarded bymillis()/deadline/HAL_GetTicknot flagged; delays in Arduinoloop()are idle metronomes. - R5 (erase misalignment) and R7 (bare flash address) are generic flash hygiene: always reported, upgrade or not.
Platform Applicability (honest version)
| Layer | Applies to | Notes |
|---|---|---|
Tool side ota_tool.py | Any platform | CRC32/CRC16/MD5/SHA256, 64B header, layout math, pack/verify — pure bytes |
| Audit, architecture rules R1 R2 R3 R8 R9 R12 | All Cortex-M + RISC-V | Standard constructs: SCB->VTOR / __set_MSP / __disable_irq / CPSID i; RISC-V recognizes csrw mtvec |
| Audit, peripheral rules R4 R5 R6 R7 R11 R13 R14 R15 | Depends on platform naming | Covers ST HAL/SPL, GD32 FMC, Nordic nrfx, ESP-IDF, Zephyr/MCUboot, Arduino/ESP8266, generic naming |
| Audit, framework layer | Arduino / ESP8266 | Vocabulary entirely different from ESP-IDF — separately adapted |
Known platform limits (stated plainly):
- R7 (bare flash address) only recognizes the
0x08xxxxxxfamily (ST/GD32/CH32/APM32). nRF52 (base 0x0) and ESP32 (0x10000) will not trigger it — a miss, not a false positive. - ESP32 has no
SCB->VTORsemantics (image header + MMU boot); R1/R2/R3 don't apply and are not misreported (tested). - Framework-managed bootloaders (mbed): no jump trio in-file; notes emitted, not findings.
- Arduino audits the sketch layer only: erase/verify live in the
Updatelibrary, so R14 becomes a note andUpdate.end(true)serves as R4 evidence. "No R4/R14 on Arduino" means the sketch didn't miss it — not that the library is sound. - AVR Arduino (Uno/Nano/Mega): no self-upgrade capability — classified non-OTA, score 100 means "nothing to audit", not "code is safe".
- No "full coverage" claims: unrecognized platform API naming means rules silently don't fire (inflated score). Check the JSON
signalsfield when unsure.
Cross-platform recall was verified, not claimed: four platforms each got a deliberately broken bootloader — all caught. See the corpus section in the CN documentation (references/CHANGELOG.md) for the reproduction matrix: MCUboot/wolfBoot/Adafruit/ESP-IDF/Zephyr/mbed mature bootloaders score 100 (or 97-98 with "manual confirm"), ST's own IAP examples score 80 with real R1+R2 findings, and minimal bad samples on nRF52/ESP-IDF/RISC-V/GD32 all hit their expected rules. The famous lesson: word boundaries made the entire rule set silently fail on esp_ota_write-style underscore prefixes (fake 100s), and only real bad-sample cross-platform testing exposed it — then ArduinoOTA camelCase exposed the second variant of the same pit.
Image Header Format (64 bytes, little-endian)
| Offset | Type | Field | Notes |
|---|---|---|---|
| 0 | u32 | magic | 0x50555746 (ASCII "FWUP") |
| 4 | u16 | header_ver | format version, currently 1 |
| 6 | u16 | hw_id | hardware ID, anti cross-flash |
| 8 | u32 | fw_ver | major<<16 | minor<<8 | patch |
| 12 | u32 | load_addr | image load address |
| 16 | u32 | image_size | image bytes |
| 20 | u32 | image_crc | image CRC32 |
| 24 | u32 | header_crc | header's own CRC32 (zero this field while computing) |
| 28 | u32 | timestamp | pack UTC timestamp |
| 32 | u32 | flags | bit0=force upgrade, bit1=allow downgrade |
| 36 | u8[28] | reserved | zeros |
Note: MCU-side parsing must use OTA_HEADER_SIZE (64), never sizeof(ota_image_header_t) (struct padding varies).
Output
Audit JSON: summary{high,medium,low,total} + issues[]{rule_id,severity,line,title,description,suggestion} + notes[]{line,note} (unscored) + score (starts 100; critical -8 / major -4 / minor -1) + signals. --dir adds top5_files; --html sets html_report in the JSON.
Pack JSON: package/package_size/image/image_size/load_addr/fw_version/hw_id/image_crc32.
Reliability and Known Boundaries
- 190 test assertions (145 audit + 45 tool) all passing; every rule has positive and negative cases, including "well-formed bootloaders must score 100" anti-false-positive floor tests and regressions consolidated from real open-source code (vector-table init is not a jump, HAL function definitions don't trigger R11, flash writes inside macros don't trigger R11, menu/LED feedback counts as progress, cross-file downgrade cases, recall cases for Nordic/ESP-IDF/RISC-V/GD32, 26 Arduino/ESP8266 framework cases including "bad sketch must score >=10 points below good sketch").
- De-noising: code inside block/line comments and string literals doesn't count as signals; jumps inside inline asm (
asm volatile("mov pc, ...")) are separately extracted so de-noising doesn't kill them. - Known boundaries (deliberate): static text analysis only — no dataflow/controlflow. Cross-file division of labor reports minor "manual confirm" rather than asserting critical. R5 only checks constant erase addresses. R7 reports once per file. Pure-assembly jump files (.s/.asm) not scanned.
- Gating scope: R1-R3 only with jump evidence; R4, R6, R8-R15 gated on OTA context keywords (ota/iap/dfu/firmware/upgrade/bootloader, underscore and camel prefixes allowed) or jump evidence. R5 and R7 are generic hygiene — always reported; R7 recognizes only
0x08xxxxxx. - Does not replace on-target testing or HIL validation; upgrade-chain correctness is ultimately proven by power-cut/disconnect/wrong-packet injections on real hardware.
File Structure
embedded-ota-toolkit/
├── SKILL.md
├── ota_audit.py # audit engine (15 rules + notes + HTML report)
├── ota_tool.py # toolset (crc/layout/pack/verify)
├── references/
│ ├── CHANGELOG.md
│ └── ota-checklist.md # manual pre-flight checklist
└── tests/
├── test_ota_audit.py
└── test_ota_tool.py
Related skills
- Downloads
- Security audit
- Review
- Last updated
- 5d ago
- Current version
- v1.2.0
- License
- MIT-0
