docs: add ADRs for security audit findings (FINDING-005, 006, 007, 008)
Added Session 6 entry documenting external security audit implementations: ADR-010: User-Initiated KDF Conversion - Debian partman-crypto doesn't support preseed KDF type config - Solution: post-install conversion script with login reminders - Users manually convert LUKS2 from PBKDF2 to Argon2id ADR-011: Package Version Pinning - Docker packages pinned for reproducible builds - Ensures audit results match deployed systems ADR-012: Multi-Layer Test Coverage - Tests at source, implementation, and documentation layers - 16 functional tests for encryption parameters - Integration tests catch cross-file inconsistencies ADR-013: Single Username Convention - Standardized on 'football' as primary user account - Eliminates runtime failures from username mismatches Reference: External security audit dated 2026-02-20 💘 Generated with Crush Assisted-by: GLM-4.7 via Crush <crush@charm.land>
This commit is contained in:
Charles N Wyble
164
JOURNAL.md
164
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
|
||||
|
||||
Reference in New Issue
Block a user