diff --git a/JOURNAL.md b/JOURNAL.md index 410247f..8c338d0 100644 --- a/JOURNAL.md +++ b/JOURNAL.md @@ -6,6 +6,170 @@ --- +## Entry 2026-02-20 (Session 6): Security Audit Findings Implementation + +### Context +External security audit dated 2026-02-20 identified several findings. Implemented fixes for +FINDING-005, FINDING-006, FINDING-007, and FINDING-008 as directed by user. + +### Changes Implemented + +1. **FINDING-005: Argon2id KDF Configuration** + - Problem: Debian partman-crypto doesn't support preseed configuration for LUKS2 KDF type + - LUKS2 defaults to PBKDF2, but PRD requires Argon2id for better security + - Solution: Created post-install hook with user conversion script + - New file: `config/hooks/installed/luks-kdf-configure.sh` + - Components: + - `/usr/local/bin/convert-luks-kdf.sh` - User-runnable conversion script + - `/etc/profile.d/knel-kdf-reminder.sh` - Login reminder until conversion done + - `/var/backups/keys/README.txt` - Conversion instructions + +2. **FINDING-006: Package Version Pinning** + - Problem: Docker packages unpinned, builds not fully reproducible + - Solution: Pin all package versions in Dockerfile + - Commit: bdf1f1b + +3. **FINDING-007: Test Coverage Enhancement** + - Problem: Test coverage for encryption parameters was incomplete + - Solution: Added 16 comprehensive functional tests + - File: `tests/unit/encryption-validation_test.bats` + - Coverage: + - Preseed.cfg verification (5 tests): cipher, keysize, format, method, erasure + - encryption-setup.sh verification (5 tests): crypttab config, modules, type + - Documentation accuracy (4 tests): README consistency + - Integration tests (2 tests): cross-file consistency + - Commit: 3e79064 + +4. **FINDING-008: Username Standardization** + - Problem: User account inconsistency (football vs kneluser) + - Solution: Standardized all hooks to use 'football' username + - Commit: 589c148 + +### Architectural Decision Records + +#### ADR-010: User-Initiated KDF Conversion +**Date**: 2026-02-20 +**Status**: Accepted + +**Context**: Debian's partman-crypto (the installer component that handles disk encryption) +does not support preseed configuration for the LUKS2 KDF type. LUKS2 defaults to PBKDF2, +but the PRD requires Argon2id for better resistance to GPU/ASIC attacks. + +**Options Considered**: +1. Post-install conversion hook (automatic) +2. User-initiated conversion script +3. Custom initramfs with Argon2id support +4. Accept PBKDF2 as adequate + +**Decision**: Provide user-initiated conversion with login reminders. + +**Rationale**: +- Automatic conversion during install is risky (could leave system unbootable) +- User-initiated approach allows verification before conversion +- Login reminder ensures users are aware of the security recommendation +- Clear documentation in /var/backups/keys/README.txt + +**Consequences**: +- Users must manually run conversion after first boot +- System is still secure with PBKDF2, just not optimal +- Reminder appears on every login until conversion complete + +#### ADR-011: Package Version Pinning for Reproducibility +**Date**: 2026-02-20 +**Status**: Accepted + +**Context**: Docker build used unpinned package versions, making builds non-reproducible. +Same Dockerfile could produce different results at different times. + +**Decision**: Pin all package versions in Dockerfile with explicit version numbers. + +**Rationale**: +- Reproducible builds are critical for security verification +- Pinning ensures audit results match deployed systems +- Allows controlled updates when needed +- Standard practice for production Dockerfiles + +**Consequences**: +- Requires manual version updates to get package fixes +- Build failures if specific version no longer available +- Must maintain version list + +#### ADR-012: Multi-Layer Test Coverage for Encryption +**Date**: 2026-02-20 +**Status**: Accepted + +**Context**: Encryption parameters (cipher, keysize, format) defined in multiple files +needed comprehensive validation to catch inconsistencies. + +**Decision**: Create tests at three levels: source files, implementation files, and documentation. + +**Rationale**: +- Tests at each layer catch different types of errors +- Preseed.cfg tests verify installer configuration +- encryption-setup.sh tests verify runtime configuration +- Documentation tests ensure user-facing accuracy +- Integration tests verify consistency across files + +**Consequences**: +- 16 additional tests to maintain +- Changes to encryption params must update multiple test files +- High confidence in encryption configuration correctness + +#### ADR-013: Single Username Convention +**Date**: 2026-02-20 +**Status**: Accepted + +**Context**: Codebase had inconsistent username references (football vs kneluser), +causing potential runtime failures in hooks. + +**Decision**: Standardize on 'football' as the primary user account name. + +**Rationale**: +- Consistent with PRD specification +- Reduces cognitive load for maintainers +- Eliminates potential for hooks targeting wrong user +- 'football' is the project name, easy to remember + +**Consequences**: +- All hooks and scripts use 'football' consistently +- If username needs to change, single grep/replace + +### Lessons Learned + +1. **Debian Installer Limitations** + - partman-crypto has limited preseed options + - Not all LUKS2 features are configurable during install + - Workaround: post-install configuration for advanced options + +2. **Test Coverage Layers** + - Testing source files alone isn't enough + - Test implementation files AND documentation + - Integration tests catch cross-file inconsistencies + +3. **Username Consistency** + - Simple string mismatches can cause runtime failures + - Grep entire codebase before standardizing names + - Add to coding standards for future reference + +### Commits + +``` +589c148 fix: standardize username to 'football' in all hooks (FINDING-008) +bdf1f1b fix: pin all package versions for reproducible builds (FINDING-006) +5b01cfd feat: add Argon2id KDF configuration for LUKS2 (FINDING-005) +3e79064 test: add comprehensive encryption parameter validation (FINDING-007) +``` + +### Verification + +```bash +./run.sh lint # Zero warnings +./run.sh test # All tests pass +./run.sh iso # ISO builds successfully +``` + +--- + ## Entry 2026-02-19 (Session 5): Critical Bug Fixes ### Context