docs: move PRD.md and SDLC.md to docs/ subdirectory
Consolidate all documentation files under docs/ directory. Update AGENTS.md and README.md to reflect new file locations. 💘 Generated with Crush Assisted-by: GLM-5 via Crush <crush@charm.land>
This commit is contained in:
Charles N Wyble
338
docs/SDLC.md
Normal file
338
docs/SDLC.md
Normal file
@@ -0,0 +1,338 @@
|
||||
# KNEL-Football Secure OS - Software Development Lifecycle (SDLC)
|
||||
|
||||
**Version:** 1.0
|
||||
**Status:** Active
|
||||
**Last Updated:** 2026-02-17
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This document defines the mandatory Software Development Lifecycle (SDLC) for the KNEL-Football Secure OS project. As a **critical infrastructure project** supporting CMMC/FedRAMP/ITAR compliance, we maintain zero tolerance for security defects and require strict adherence to these processes.
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Security First
|
||||
- Every change must preserve or enhance security
|
||||
- No shortcuts, no exceptions, no "temporary" bypasses
|
||||
- All code is security-critical code
|
||||
|
||||
### 2. Test-Driven Development (TDD)
|
||||
- **Red → Green → Refactor** - Mandatory workflow
|
||||
- No code without tests
|
||||
- No merge without passing tests
|
||||
|
||||
### 3. Defense in Depth
|
||||
- Multiple layers of verification
|
||||
- Automated + manual review
|
||||
- Build-time + runtime validation
|
||||
|
||||
---
|
||||
|
||||
## Test-Driven Development (TDD) Workflow
|
||||
|
||||
### Mandatory TDD Process
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ TDD WORKFLOW │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. RED: Write a failing test │
|
||||
│ ┌─────────────────────────────────────────────────┐ │
|
||||
│ │ • Write test FIRST (before implementation) │ │
|
||||
│ │ • Test MUST fail initially │ │
|
||||
│ │ • Run: ./run.sh test:<suite> │ │
|
||||
│ │ • Confirm test fails for RIGHT reason │ │
|
||||
│ └─────────────────────────────────────────────────┘ │
|
||||
│ ↓ │
|
||||
│ 2. GREEN: Write minimal code to pass │
|
||||
│ ┌─────────────────────────────────────────────────┐ │
|
||||
│ │ • Write MINIMUM code to make test pass │ │
|
||||
│ │ • Do not over-engineer │ │
|
||||
│ │ • Run: ./run.sh test:<suite> │ │
|
||||
│ │ • Confirm test passes │ │
|
||||
│ └─────────────────────────────────────────────────┘ │
|
||||
│ ↓ │
|
||||
│ 3. REFACTOR: Improve code quality │
|
||||
│ ┌─────────────────────────────────────────────────┐ │
|
||||
│ │ • Clean up implementation │ │
|
||||
│ │ • Remove duplication │ │
|
||||
│ │ • Improve readability │ │
|
||||
│ │ • Run: ./run.sh test (ALL tests must pass) │ │
|
||||
│ └─────────────────────────────────────────────────┘ │
|
||||
│ ↓ │
|
||||
│ REPEAT AS NEEDED │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### TDD Rules
|
||||
|
||||
1. **Rule 1**: You MUST write a failing test before writing implementation code
|
||||
2. **Rule 2**: You MUST NOT write more implementation than needed to pass the test
|
||||
3. **Rule 3**: You MUST run ALL tests after refactoring
|
||||
|
||||
### Test Execution Commands
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
./run.sh test
|
||||
|
||||
# Run specific test suites
|
||||
./run.sh test:unit # Unit tests only
|
||||
./run.sh test:integration # Integration tests only
|
||||
./run.sh test:security # Security/compliance tests only
|
||||
|
||||
# Run linting (shellcheck)
|
||||
./run.sh lint
|
||||
```
|
||||
|
||||
### Test Coverage Requirements
|
||||
|
||||
| Category | Minimum Coverage | Target |
|
||||
|----------|------------------|--------|
|
||||
| Security functions | 100% | 100% |
|
||||
| Encryption setup | 100% | 100% |
|
||||
| Password policy | 100% | 100% |
|
||||
| Firewall rules | 100% | 100% |
|
||||
| Build scripts | 80% | 95% |
|
||||
| Utility functions | 80% | 90% |
|
||||
|
||||
---
|
||||
|
||||
## Pre-Commit Checklist
|
||||
|
||||
**Before committing ANY change, verify:**
|
||||
|
||||
- [ ] All tests pass: `./run.sh test`
|
||||
- [ ] Lint passes with zero warnings: `./run.sh lint`
|
||||
- [ ] Security tests pass: `./run.sh test:security`
|
||||
- [ ] Code follows existing style
|
||||
- [ ] Commit message follows conventional format
|
||||
- [ ] No secrets, credentials, or sensitive data in commit
|
||||
|
||||
---
|
||||
|
||||
## Code Quality Standards
|
||||
|
||||
### Shell Script Standards
|
||||
|
||||
1. **Zero Shellcheck Warnings**
|
||||
- All shell scripts MUST pass shellcheck with zero warnings
|
||||
- No exceptions, no suppressions without documented justification
|
||||
- Run: `./run.sh lint`
|
||||
|
||||
2. **Strict Mode**
|
||||
- All scripts MUST use: `set -euo pipefail`
|
||||
- No uninitialized variables
|
||||
- No unset variable access
|
||||
|
||||
3. **Error Handling**
|
||||
- All errors must be handled explicitly
|
||||
- Use `|| true` only when failure is expected and acceptable
|
||||
- Log all errors with context
|
||||
|
||||
4. **Security Conventions**
|
||||
- Quote all variables: `"$variable"`
|
||||
- Use `[[ ]]` for tests (not `[ ]`)
|
||||
- Avoid `eval` and other code injection vectors
|
||||
- Never log secrets or credentials
|
||||
|
||||
### Documentation Standards
|
||||
|
||||
1. **Code Comments**
|
||||
- Explain WHY, not WHAT
|
||||
- Reference requirements (e.g., "PRD FR-006: Key-based auth only")
|
||||
- Document security implications
|
||||
|
||||
2. **Function Documentation**
|
||||
```bash
|
||||
# Function: configure_ssh
|
||||
# Purpose: Configure SSH server with security hardening
|
||||
# Requirements: PRD FR-006 (Key-Based Authentication Only)
|
||||
# Security: Disables password auth per NIST guidelines
|
||||
configure_ssh() {
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Git Workflow
|
||||
|
||||
### Branch Strategy
|
||||
|
||||
```
|
||||
main (protected)
|
||||
│
|
||||
├── feature/<feature-name> # New features
|
||||
├── fix/<bug-name> # Bug fixes
|
||||
├── security/<issue-name> # Security fixes (priority)
|
||||
└── docs/<doc-name> # Documentation updates
|
||||
```
|
||||
|
||||
### Commit Message Format
|
||||
|
||||
```
|
||||
<type>: <subject>
|
||||
|
||||
<body (optional)>
|
||||
|
||||
<footer (optional)>
|
||||
|
||||
💘 Generated with Crush
|
||||
|
||||
Assisted-by: <AI-Model> via Crush <crush@charm.land>
|
||||
```
|
||||
|
||||
**Types:**
|
||||
- `feat`: New feature
|
||||
- `fix`: Bug fix
|
||||
- `security`: Security vulnerability fix
|
||||
- `docs`: Documentation changes
|
||||
- `test`: Test additions/modifications
|
||||
- `refactor`: Code refactoring
|
||||
- `chore`: Maintenance tasks
|
||||
|
||||
**Example:**
|
||||
```
|
||||
security: disable SSH password authentication
|
||||
|
||||
PRD FR-006 requires key-based authentication only.
|
||||
PasswordAuthentication was incorrectly set to 'yes',
|
||||
violating the security requirement.
|
||||
|
||||
Fixes: SSH config now uses PasswordAuthentication no
|
||||
|
||||
💘 Generated with Crush
|
||||
|
||||
Assisted-by: GLM-4.7 via Crush <crush@charm.land>
|
||||
```
|
||||
|
||||
### Merge Requirements
|
||||
|
||||
- [ ] All tests pass
|
||||
- [ ] Zero lint warnings
|
||||
- [ ] At least one approval (for team projects)
|
||||
- [ ] No unresolved conversations
|
||||
- [ ] Branch up to date with main
|
||||
|
||||
---
|
||||
|
||||
## Security Review Process
|
||||
|
||||
### When Security Review is Required
|
||||
|
||||
1. Any change to:
|
||||
- Encryption configuration
|
||||
- Password policy
|
||||
- Firewall rules
|
||||
- SSH configuration
|
||||
- Authentication mechanisms
|
||||
- Kernel module blacklists
|
||||
|
||||
2. Any change touching files in:
|
||||
- `config/hooks/installed/`
|
||||
- `config/hooks/live/`
|
||||
- `src/security-hardening.sh`
|
||||
- `src/firewall-setup.sh`
|
||||
|
||||
### Security Review Checklist
|
||||
|
||||
- [ ] Change aligns with PRD requirements
|
||||
- [ ] No security regressions introduced
|
||||
- [ ] Complies with NIST SP 800-53 controls
|
||||
- [ ] Complies with NIST SP 800-111 (encryption)
|
||||
- [ ] Complies with CIS Benchmarks
|
||||
- [ ] Audit logging covers the change
|
||||
- [ ] Documentation updated
|
||||
|
||||
---
|
||||
|
||||
## Compliance Mapping
|
||||
|
||||
### NIST SP 800-53 Control Mapping
|
||||
|
||||
| Control | Implementation | Test |
|
||||
|---------|----------------|------|
|
||||
| AC-3 (Access Enforcement) | SSH key-only auth | `test:security` |
|
||||
| AU-2 (Audit Events) | auditd rules | `test:security` |
|
||||
| SC-13 (Crypto Protection) | LUKS2 encryption | `test:security` |
|
||||
| SC-28 (Data at Rest) | Full disk encryption | `test:security` |
|
||||
|
||||
### Compliance Test Execution
|
||||
|
||||
```bash
|
||||
# Run compliance-focused tests
|
||||
./run.sh test:security
|
||||
|
||||
# Run encryption-specific tests
|
||||
./run.sh test:encryption
|
||||
|
||||
# Run full compliance verification
|
||||
./run.sh test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Release Process
|
||||
|
||||
### Pre-Release Checklist
|
||||
|
||||
- [ ] All tests pass (78 tests: 63 pass, 15 skip for libvirt)
|
||||
- [ ] Zero lint warnings
|
||||
- [ ] Security review complete
|
||||
- [ ] Documentation updated
|
||||
- [ ] CHANGELOG updated
|
||||
- [ ] Version bump in applicable files
|
||||
|
||||
### Build Verification
|
||||
|
||||
```bash
|
||||
# Build ISO
|
||||
./run.sh iso
|
||||
|
||||
# Verify checksums
|
||||
cd output/
|
||||
sha256sum -c knel-football-secure.iso.sha256
|
||||
md5sum -c knel-football-secure.iso.md5
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Incident Response
|
||||
|
||||
### Security Vulnerability Found
|
||||
|
||||
1. **STOP** - Do not commit the vulnerable code
|
||||
2. **DOCUMENT** - Create issue tracking the vulnerability
|
||||
3. **FIX** - Implement fix following TDD process
|
||||
4. **VERIFY** - All tests pass, security tests pass
|
||||
5. **REVIEW** - Security review of the fix
|
||||
6. **RELEASE** - Expedited release if critical
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- **PRD.md** - Product Requirements Document
|
||||
- **AGENTS.md** - Agent Behavior Guidelines
|
||||
- **README.md** - Project overview and commands
|
||||
- **docs/TEST-COVERAGE.md** - Test suite documentation
|
||||
- **docs/VERIFICATION-REPORT.md** - Verification results
|
||||
|
||||
---
|
||||
|
||||
## Version History
|
||||
|
||||
| Version | Date | Changes |
|
||||
|---------|------|---------|
|
||||
| 1.0 | 2026-02-17 | Initial SDLC document |
|
||||
|
||||
---
|
||||
|
||||
**This SDLC is MANDATORY for all changes to this project.**
|
||||
|
||||
**Copyright © 2026 Known Element Enterprises LLC**
|
||||
**License: GNU Affero General Public License v3.0 only**
|
||||
Reference in New Issue
Block a user