KNEL/football
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- 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
Download Patch File Download Diff File Expand all files Collapse all files

112
docs/PRD.md
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

96
docs/TEST-COVERAGE.md
View File

@@ -144,6 +144,102 @@
---
#### 8. `tests/unit/secureboot_test.bats`
**Coverage**: Secure Boot and UKI implementation in run.sh
**Tests** (70+ tests):
**Secure Boot Configuration**:
- SB_KEY_DIR variable defined
- SB_KEYS_SRC variable defined
**Key Generation Functions**:
- sb_generate_keys function defined
- Creates PK key with openssl
- Creates KEK key with openssl
- Creates db key with openssl
- Uses RSA-4096 algorithm
- Uses SHA-256 hash
- Uses 3650 day validity
**ESL (EFI Signature List) Functions**:
- sb_create_esl function defined
- Uses cert-to-efi-sig-list
- Generates UUID for ESL
**Auth File Signing Functions**:
- sb_sign_esl function defined
- Uses sign-efi-sig-list
- Includes timestamp
**UKI Build Functions**:
- uki_build function defined
- Finds kernel in chroot
- Finds initrd in chroot
- Uses EFI stub (linuxx64.efi.stub)
- Uses objcopy for bundling
- Adds .osrel section
- Adds .cmdline section
- Adds .linux section
- Adds .initrd section
**UKI Signing Functions**:
- uki_sign function defined
- Uses sbsign for signing
- Uses db key for signing
- Verifies signature with sbverify
**Secure Boot Setup Function**:
- secureboot_setup function defined
- Generates all keys
- Creates all ESL files
- Creates PK auth (self-signed)
- Creates KEK auth (signed by PK)
- Creates db auth (signed by KEK)
**Docker Build Integration**:
- get_secureboot_script function defined
- Outputs sb_docker_setup
- Outputs sb_docker_build_uki
- Outputs sb_docker_copy_keys_to_binary
**ISO Build Integration**:
- iso command includes Secure Boot hook creation
- Hook generates all keys (PK, KEK, db)
- Hook creates auth files (PK.auth, KEK.auth, db.auth)
- Hook builds UKI
- Hook signs UKI
- Hook copies keys to ISO
**Kernel Command Line Security**:
- UKI cmdline includes lockdown=confidentiality
- UKI cmdline includes module.sig_enforce=1
**Package Requirements**:
- efitools in package list
- sbsigntools in package list
- systemd-boot in package list
- binutils in package list
**VM TPM Support**:
- VM template includes TPM device
- TPM uses version 2.0
- TPM uses CRB model
**Output Verification**:
- iso command reports Secure Boot: ENABLED
- iso command reports UKI: SIGNED
- iso command reports keys location
**Requirements Covered**:
- ✅ FR-012: Secure Boot with UKI
**Compliance Standards**:
- ✅ UEFI Specification 2.3.1+
- ✅ NIST SP 800-147 (BIOS Protection)
- ✅ NIST SP 800-147B (UEFI Firmware Protection)
---
### Integration Tests (2 files)
#### 1. `tests/integration/config_test.bats`

87
docs/security-model.md
View File

@@ -23,8 +23,95 @@ The KNEL-Football security model implements a defense-in-depth approach to creat
- **UEFI-Only Boot** - No legacy BIOS support prevents boot attacks
- **Secure Boot** - Cryptographic verification of bootloader and kernel
- **Unified Kernel Image (UKI)** - Signed kernel+initramfs+cmdline bundle
- **Kernel Lockdown** - Kernel runs in confidentiality lockdown mode
- **Measured Boot** - Boot chain integrity measurement and attestation
##### Secure Boot Trust Chain
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ SECURE BOOT TRUST CHAIN │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────┐ │
│ │ UEFI Firmware │ ← Root of Trust (Hardware) │
│ └──────────┬──────────┘ │
│ │ Verifies PK signature │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ PK (Platform Key) │ ← RSA-4096, SHA-256, 3650 days │
│ │ Self-signed │ Platform owner authorization │
│ └──────────┬──────────┘ │
│ │ Signs KEK updates │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ KEK (Key Exchange) │ ← RSA-4096, SHA-256, 3650 days │
│ │ Signed by PK │ OS/key exchange authorization │
│ └──────────┬──────────┘ │
│ │ Signs db updates │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ db (Signature DB) │ ← RSA-4096, SHA-256, 3650 days │
│ │ Signed by KEK │ Allowed EFI binaries │
│ └──────────┬──────────┘ │
│ │ Verifies UKI signature │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ UKI (Unified │ ← Signed EFI binary │
│ │ Kernel Image) │ • linuxx64.efi.stub │
│ │ │ • os-release │
│ │ │ • cmdline (lockdown=confidentiality) │
│ │ │ • linux (vmlinuz) │
│ │ │ • initrd (initramfs) │
│ └──────────┬──────────┘ │
│ │ Boots with lockdown │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ Linux Kernel │ ← Kernel Lockdown Mode │
│ │ (Confidentiality) │ • module.sig_enforce=1 │
│ │ │ • No unsigned modules │
│ │ │ • No /dev/mem access │
│ │ │ • No kexec │
│ └─────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
##### Secure Boot Keys
| Key | Purpose | Algorithm | Validity |
|-----|---------|-----------|----------|
| PK (Platform Key) | Authorizes KEK updates | RSA-4096, SHA-256 | 3650 days |
| KEK (Key Exchange Key) | Authorizes db updates | RSA-4096, SHA-256 | 3650 days |
| db (Signature Database) | Signs EFI binaries | RSA-4096, SHA-256 | 3650 days |
##### UKI Components
| Section | Content | Purpose |
|---------|---------|---------|
| .osrel | /etc/os-release | OS identification |
| .cmdline | Kernel parameters | lockdown=confidentiality, module.sig_enforce=1 |
| .linux | vmlinuz-{version} | Kernel image |
| .initrd | initrd.img-{version} | Initial ramdisk |
##### Kernel Lockdown Effects
When Secure Boot is active and kernel lockdown is enabled:
- **No unsigned kernel modules** - module.sig_enforce=1
- **No /dev/mem or /dev/kmem access** - Prevents direct memory manipulation
- **No kexec** - Cannot replace running kernel
- **No hibernation to untrusted storage** - Prevents data extraction
- **No iopl/ioperm** - Restricts I/O port access
- **No MSRs from userspace** - Restricts model-specific register access
##### Secure Boot Enforcement
- **Build Time**: Keys generated, UKI signed during ISO build
- **Install Time**: Keys enrolled in UEFI firmware (setup mode)
- **Boot Time**: UEFI verifies UKI signature before boot
- **Runtime**: Kernel enforces lockdown mode restrictions
#### 2. Network Security Layer
- **Network Isolation** - No general internet access