feat: enforce SDLC compliance with pre-commit hook and documentation

- Add .git/hooks/pre-commit for automatic SDLC enforcement
  - Blocks commits on lint warnings
  - Blocks commits on test failures
  - Checks test coverage for modified files
  - Warns on missing documentation updates

- Update AGENTS.md with mandatory SDLC compliance section
  - Visual workflow diagram
  - Zero tolerance policy
  - Pre-commit hook documentation

- Fix SC2012 lint warnings in run.sh (lines 74, 551)
  - Changed ls | head to find -print -quit

- Add FR-012 Secure Boot with UKI to docs/PRD.md
  - Trust chain requirements
  - Key specifications (RSA-4096, SHA-256, 3650 days)
  - Kernel lockdown requirements

- Update docs/security-model.md with Secure Boot trust chain
  - Full trust chain diagram
  - Key hierarchy
  - Kernel lockdown effects

- Update docs/TEST-COVERAGE.md with Secure Boot tests

- Add tests/unit/secureboot_test.bats (70+ tests for Secure Boot)

- Fix test bugs in build-iso and run comprehensive tests
  - Changed distribution from 'testing' to 'trixie'
  - Fixed Secure Boot key test patterns for multiline matches

💘 Generated with Crush

Assisted-by: GLM-4.7 via Crush <crush@charm.land>
This commit is contained in:
Charles N Wyble
2026-02-20 08:44:56 -05:00
parent 169362ce3d
commit 59122570a6
8 changed files with 713 additions and 43 deletions

View File

@@ -323,6 +323,83 @@ The host system used to build or test KNEL-Football ISO images MUST have full di
2. Reinstall with "Guided - use entire disk and set up encrypted LVM"
3. Or use tools like encrypt-existing-debian for in-place encryption
### FR-012: Secure Boot with Unified Kernel Image (UKI) (MANDATORY)
**Priority:** P0 (Critical)
**Status:** Required
**Description:**
The system MUST implement UEFI Secure Boot with a Unified Kernel Image (UKI) to ensure boot integrity and prevent unauthorized code execution during the boot process. This creates a complete chain of trust from firmware to the running operating system.
**Requirements:**
1. **UEFI Boot** - System MUST boot in UEFI mode (no legacy BIOS)
2. **Secure Boot Keys** - Custom PK, KEK, and db keys for signing
3. **Unified Kernel Image** - Kernel, initramfs, and cmdline bundled into single signed EFI binary
4. **Kernel Lockdown** - Kernel must be in lockdown mode when Secure Boot is active
5. **Signature Verification** - All boot components must be cryptographically signed
**Secure Boot Key Hierarchy:**
```
┌─────────────────────────────────────────────────────┐
│ Trust Chain │
├─────────────────────────────────────────────────────┤
│ │
│ UEFI Firmware (Platform Owner) │
│ │ │
│ ▼ │
│ PK (Platform Key) - RSA-4096, SHA-256 │
│ │ Signs KEK updates │
│ ▼ │
│ KEK (Key Exchange Key) - RSA-4096, SHA-256 │
│ │ Signs db updates │
│ ▼ │
│ db (Signature Database) - RSA-4096, SHA-256 │
│ │ Signs EFI binaries │
│ ▼ │
│ UKI (Unified Kernel Image) │
│ │ Signed bootloader + kernel + initramfs │
│ ▼ │
│ Operating System │
│ │
└─────────────────────────────────────────────────────┘
```
**UKI Components:**
1. **EFI Stub** - linuxx64.efi.stub for UEFI boot
2. **os-release** - Operating system identification
3. **cmdline** - Kernel command line with security parameters:
- `lockdown=confidentiality` - Kernel lockdown mode
- `module.sig_enforce=1` - Require signed kernel modules
4. **linux** - Kernel image (vmlinuz)
5. **initrd** - Initial ramdisk (initramfs)
**Key Specifications:**
- **Algorithm**: RSA-4096
- **Hash**: SHA-256
- **Validity**: 3650 days (10 years)
- **Format**: X.509 certificates, ESL (EFI Signature List)
**Secure Boot Mode:**
- **Setup Mode**: Keys can be enrolled (first boot)
- **User Mode**: Secure Boot active, only signed code boots
**Implementation:**
- Key generation during ISO build
- UKI creation with systemd-boot
- Signature with sbsigntools
- Key storage on ISO for user enrollment
**Security Properties:**
- Bootkit protection - Unauthorized bootloaders cannot execute
- Rootkit protection - Kernel integrity verified at boot
- Module signing enforcement - Only signed kernel modules load
- Chain of trust - Complete verification path from firmware to OS
**Compliance:**
- UEFI Specification 2.3.1+
- NIST SP 800-147 (BIOS Protection)
- NIST SP 800-147B (UEFI Firmware Protection)
---
## Non-Functional Requirements
@@ -402,6 +479,41 @@ The host system used to build or test KNEL-Football ISO images MUST have full di
- Storage: Keys never stored in plaintext
- Rotation: Key change support via cryptsetup
### Boot Security Layer
#### Secure Boot with UKI
- **Mode:** UEFI Secure Boot (User Mode)
- **Key Hierarchy:** PK → KEK → db → Signed UKI
- **Key Algorithm:** RSA-4096 with SHA-256
- **Validity:** 3650 days (10 years)
#### Chain of Trust
```
UEFI Firmware
▼ (verifies PK signature)
PK (Platform Key)
▼ (verifies KEK signature)
KEK (Key Exchange Key)
▼ (verifies db signature)
db (Signature Database)
▼ (verifies UKI signature)
UKI (Unified Kernel Image)
Linux Kernel (lockdown mode)
```
#### Kernel Lockdown
- **Mode:** confidentiality (strict)
- **Module Signing:** Enforced (module.sig_enforce=1)
- **Effect:** Prevents kernel module loading without valid signature
- **Effect:** Prevents /dev/mem and /dev/kmem access
- **Effect:** Blocks kexec and hibernation to untrusted storage
### Network Security Layer
#### VPN-Only Access