Enforce crash-safe build policy

Add compile-time checks for silent reboot, disabled core dumps, and
disabled debugger-aware panic handling. Include regression coverage,
hardening guidance, and update Phase 8/9 project status.
This commit is contained in:
2026-09-15 20:11:40 +02:00
parent f40c09c11a
commit 436c27adb1
11 changed files with 267 additions and 30 deletions
+15 -22
View File
@@ -38,8 +38,8 @@ These constraints apply across all phases:
| 5B | Offline xterm.js WebSocket serial terminal | **Complete** |
| 6 | Authenticated SSH serial transport | **Complete** |
| 7 | Local display and button interface | **Complete** |
| 8 | Role-based users and administrative access | **In progress (8A8C complete; integrated web administration 8D planned)** |
| 9 | Security and production hardening | **Planned** |
| 8 | Role-based users and administrative access | **Complete (8D.22 accepted 2026-09-13)** |
| 9 | Security and production hardening | **In progress (9A hardware validation pending)** |
| 10 | Authenticated, rollback-capable OTA | **Planned** |
| 11 | BLE serial transport and provisioning evaluation | **Planned** |
| 12 | Advanced network integration | **Under evaluation** |
@@ -205,27 +205,20 @@ Completed implementation (8A8C target-hardware validated; 8D explicitly accep
## Current and planned phases
Phase 8 is complete for its accepted scope. Phase 9 is next **only on a separate user request**; later work remains planned or under evaluation. Optional features must not weaken completed serial and recovery paths. General release gates below remain guidance for future work, not claims that every listed fault, soak or reserve measurement was individually performed for 8D.
Phase 8 is complete for its accepted scope. Phase 9 has started at the user's request; later work remains planned or under evaluation. Optional features must not weaken completed serial and recovery paths. General release gates below remain guidance for future work, not claims that every listed fault, soak or reserve measurement was individually performed for 8D.
### Phase 9 — Security and production hardening
Harden stored credentials, boot integrity, update trust, failure diagnostics, and dependency maintenance. This phase must be staged carefully because some ESP32 eFuse operations are irreversible.
**In progress.** Harden network authentication, secret lifetimes, crash/debug exposure and operational maintenance. Secure boot and encrypted NVS are explicitly excluded by user preference. No eFuse, partition, at-rest encryption or dependency-upgrade changes are part of this first slice; no future flash/PSRAM encryption commitment is implied. Physical extraction and firmware replacement remain outside the threat model after Phase 9, and software debug restrictions do not imply physical JTAG fuse restrictions.
Planned work:
Staged work:
- Define development, test, and production security profiles.
- Enable and validate NVS encryption for Wi-Fi, HTTPS, and SSH material.
- Evaluate flash encryption and PSRAM encryption for the target hardware and threat model.
- Enable secure boot with a documented signing-key and recovery process.
- Define secret-safe core-dump handling; do not expose credentials or session material in diagnostics.
- Audit key and session-material zeroization across application, mbedTLS, wolfSSL, and wolfSSH allocations.
- Add authentication throttling, lockout/backoff, and security-event counters where appropriate.
- Review TLS/SSH algorithms, certificate policy, password policy, and browser security headers.
- Review current wolfSSL/wolfSSH and ESP-IDF security releases instead of treating integration versions as permanent pins.
- Recheck all third-party licenses and preserve source/license notices.
- Document provisioning, key rotation, factory reset, backup, recovery, and device decommissioning.
1. **9A — Crash/debug build policy and operational profiles — In progress; hardware pending.** `src/security_build_policy.c` requires `CONFIG_ESP_COREDUMP_ENABLE_TO_NONE=y` and `CONFIG_ESP_SYSTEM_PANIC_SILENT_REBOOT=y`; rejects core-dump enable/flash/UART, panic print/halt/GDBstub, runtime GDBstub and ESP/FreeRTOS debugger-aware options. `sdkconfig.defaults` makes the baseline explicit. Development/test/production use the same build baseline, not separate PlatformIO environments. Host matrix (`python3 tests/security_build_policy/run.py`) compiles the actual guard: 17 cases plus the generated-header check passed on 2026-09-15. `pio run` passed (94,196 B linked RAM / 1,828,565 B flash); target panic/recovery tests have not run. Production readiness remains pending.
2. **Next — SSH cross-connection authentication throttle.** Current SSH has three counted authentication attempts per session, reset on reconnect; HTTPS already admits five credential verifications per 60-second fixed global window. Define bounded reconnect-resistant admission/backoff, recovery and secret-free counters; test isolation from established sessions, UART0 and USB.
3. **Later — Secret-lifetime and protocol review.** Audit zeroization across application/mbedTLS/wolfSSL/wolfSSH allocations; review TLS/SSH algorithms, certificates, browser headers and password policy.
4. **Later — Maintenance and lifecycle.** Review dependency advisories and licenses without assuming pinned versions are permanently safe; document provisioning, rotation, factory reset, backup, recovery and decommissioning. OTA signing trust needs an independent policy without secure boot (Phase 10).
Security features must be validated first on expendable hardware before any irreversible production configuration is recommended.
[Security hardening](security_hardening.md) defines profiles and concrete host/build/hardware gates. Silent panic reboot removes useful crash diagnostics, not ordinary reset/boot/status information or every possible log disclosure. Raw flash/RAM/dumps remain secret-bearing, not routine diagnostic exports. Existing coredump bytes are not retroactively cleared; no secure erase is claimed. Isolated synthetic-secret debug builds require explicit reviewed source-policy changes, not a provided bypass flag.
### Phase 10 — Authenticated OTA and rollback
@@ -233,7 +226,7 @@ Use the existing dual 4 MiB application slots and `otadata` partition to add saf
Planned work:
- Accept only authenticated, integrity-checked firmware images compatible with the selected secure-boot policy.
- Accept only authenticated, integrity-checked firmware images under an independently defined OTA signing-trust policy without secure boot; define trusted-key provisioning, rotation, revocation and recovery. This cannot prevent physical firmware replacement.
- Support an update path that does not expose a plaintext management endpoint.
- Stream downloads with bounded RAM use and explicit progress/error reporting.
- Preserve serial, Wi-Fi, HTTPS, and SSH configuration across successful updates.
@@ -257,7 +250,7 @@ Planned work:
- Preserve binary transparency through explicit framing and MTU-aware partial transfers.
- Bound connections, queues, retries, and advertising behavior.
- Measure coexistence with 2.4 GHz Wi-Fi, HTTPS, WebSocket, SSH, USB CDC, and UART service.
- Store bond/provisioning data under the hardened secret-storage policy.
- Define bond/provisioning secret retention under the unencrypted-storage threat model; do not assume Phase 9 provides at-rest encryption.
- Provide UART0 controls and a physical recovery path for clearing BLE state.
BLE remains subordinate to stable Wi-Fi and serial operation; it should be omitted if coexistence or memory costs cannot be bounded acceptably.
@@ -303,10 +296,10 @@ Every phase should satisfy the following before being marked complete:
The following are not implemented merely because flash partitions or library support exist:
- NVS, flash, or PSRAM encryption.
- Secure boot or production eFuse provisioning.
- Secure boot and encrypted NVS are excluded by explicit user preference, not scheduled future enablement.
- Flash/PSRAM encryption and production eFuse provisioning are outside the current scope, with no enablement commitment.
- OTA download, image confirmation, or rollback policy.
- Core-dump collection or secret-safe core-dump processing.
- Core-dump collection or export: the supported Phase 9A baseline disables new dumps; existing partition bytes are not cleared.
- Filesystem mounting.
- SFTP, SCP, SSH `exec`, forwarding, or subsystems.