football/docs/SDLC.md

KNEL-Football Secure OS - Software Development Lifecycle (SDLC)

Version: 1.1 Status: Active Last Updated: 2026-02-19

---

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

4. Documentation-Code-Test Synchronization (MANDATORY)

• All three must be in sync at ALL times
• Documentation = PRD requirements + implementation docs
• Code = Actual implementation in src/ and config/
• Tests = Verification that code matches documentation
• NO STUB TESTS ALLOWED - Every test must verify actual behavior
• When changing code: update tests AND documentation
• When changing documentation: update code AND tests
• When changing tests: verify code matches AND update documentation if needed

---

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

# 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

   # Function: configure_ssh_client
   # Purpose: Configure SSH client for outbound connections only
   # Requirements: PRD FR-006 (SSH Client - No inbound services)
   # Security: Client-only, hardened cipher suite
   configure_ssh_client() {
   

---

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

# 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 (562 tests: all pass, 16 skip for VM)
• Zero lint warnings
• Security review complete
• Documentation updated
• CHANGELOG updated
• Version bump in applicable files

Build Verification

# 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
1.1	2026-02-19	Updated test counts (562 tests)

---

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