docs: Add comprehensive documentation structure
- Add architecture.md with system architecture details - Add COMPLIANCE.md with compliance matrix - Add security-model.md with security specifications - Add prompts-cache.md for AI prompt history 💘 Generated with Crush Assisted-by: GLM-4.6 via Crush <crush@charm.land>
This commit is contained in:
231
docs/architecture.md
Normal file
231
docs/architecture.md
Normal file
@@ -0,0 +1,231 @@
|
||||
# KNEL-Football System Architecture
|
||||
|
||||
## Overview
|
||||
|
||||
KNEL-Football implements a secure, containerized build system for creating a highly compliant Debian 13 ISO with strict security requirements.
|
||||
|
||||
**Copyright © 2026 Known Element Enterprises LLC**
|
||||
**License: GNU Affero General Public License v3.0 only**
|
||||
|
||||
## Architecture Diagram
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Development Environment │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ Host System (Restricted) │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
|
||||
│ │ Git │ │ Docker │ │ Libvirt │ │
|
||||
│ │ (VCS) │ │ (Builder) │ │ (Virtualization) │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Build Container │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ knel-football-builder:latest (Docker Image) │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Build Environment │ │
|
||||
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
||||
│ │ │ live-build │ │ debootstrap │ │ shellcheck │ │ │
|
||||
│ │ │ (ISO) │ │ (Bootstrap) │ │ (Linting) │ │ │
|
||||
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
|
||||
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
||||
│ │ │ bats │ │ nftables │ │ auditd │ │ │
|
||||
│ │ │ (Testing) │ │ (Firewall) │ │ (Auditing) │ │ │
|
||||
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Test Suite │ │
|
||||
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
||||
│ │ │ Unit Tests │ │Integration │ │Security │ │ │
|
||||
│ │ │ │ │ Tests │ │ Tests │ │ │
|
||||
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Build Process │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ Live-build Configuration │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ config/ │ │
|
||||
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
||||
│ │ │ config │ │ preseed.cfg │ │Package Lists│ │ │
|
||||
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
|
||||
│ │ ┌─────────────────────────────────────────────────────┐ │ │
|
||||
│ │ │ hooks/ │ │ │
|
||||
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │
|
||||
│ │ │ │ live hooks │ │installed │ │ includes │ │ │ │
|
||||
│ │ │ └─────────────┘ │ hooks │ └─────────────┘ │ │ │
|
||||
│ │ │ └─────────────┘ │ │ │
|
||||
│ │ └─────────────────────────────────────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Output Artifacts │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ KNEL-Football ISO │ │
|
||||
│ │ ┌─────────────────────────────────────────────────┐ │ │
|
||||
│ │ │ Secure Debian 13 System │ │ │
|
||||
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────┐ │ │ │
|
||||
│ │ │ │ IceWM (WM) │ │ LightDM │ │ WireGuard│ │ │ │
|
||||
│ │ │ └─────────────┘ │ (Display) │ │ (VPN) │ │ │ │
|
||||
│ │ │ └─────────────┘ └─────────┘ │ │ │
|
||||
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────┐ │ │ │
|
||||
│ │ │ │ Remmina │ │ Mousepad │ │PCManFM │ │ │ │
|
||||
│ │ │ │ (RDP) │ │ (Editor) │ │(File Mgr)│ │ │ │
|
||||
│ │ │ └─────────────┘ └─────────────┘ └─────────┘ │ │ │
|
||||
│ │ └─────────────────────────────────────────────────────┘ │ │
|
||||
│ │ ┌─────────────────────────────────────────────────────┐ │ │
|
||||
│ │ │ Security Features │ │ │
|
||||
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────┐ │ │ │
|
||||
│ │ │ │ Firewall │ │ WiFi/Bluetooth│ │ Auditd │ │ │ │
|
||||
│ │ │ │ (nftables) │ │ Blacklisted │ │(Logging)│ │ │ │
|
||||
│ │ │ └─────────────┘ └─────────────┘ └─────────┘ │ │ │
|
||||
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────┐ │ │ │
|
||||
│ │ │ │ SSH Security│ │ Password │ │USB Mount│ │ │ │
|
||||
│ │ │ │ Hardening │ │ Policy │ │Support │ │ │ │
|
||||
│ │ │ └─────────────┘ └─────────────┘ └─────────┘ │ │ │
|
||||
│ │ └─────────────────────────────────────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Components
|
||||
|
||||
### Host System
|
||||
|
||||
The host system is intentionally restricted to prevent build tool contamination:
|
||||
|
||||
- **Git** - Version control for all source code and configurations
|
||||
- **Docker** - Container runtime for isolated build environment
|
||||
- **Libvirt** - Virtualization for ISO testing (optional)
|
||||
|
||||
### Build Container
|
||||
|
||||
The Docker container provides a clean, reproducible build environment:
|
||||
|
||||
- **Base System** - Debian 13.3-slim minimal base
|
||||
- **Build Tools** - live-build, debootstrap, squashfs-tools
|
||||
- **Security Tools** - nftables, auditd, rsyslog
|
||||
- **Testing Framework** - bats-core with support libraries
|
||||
|
||||
### Build Process
|
||||
|
||||
The ISO build process uses live-build with extensive customization:
|
||||
|
||||
1. **Bootstrap Phase** - Minimal Debian base system creation
|
||||
2. **Configuration Phase** - Package installation and system configuration
|
||||
3. **Hook Execution** - Security hardening and customization
|
||||
4. **Image Creation** - Final ISO generation
|
||||
|
||||
### Output System
|
||||
|
||||
The resulting ISO provides a secure, compliant operating system:
|
||||
|
||||
- **Minimal Desktop** - IceWM with essential applications
|
||||
- **Network Security** - WireGuard-only access with dynamic firewall
|
||||
- **System Hardening** - Comprehensive security configuration
|
||||
- **Compliance** - CMMC Level 3, FedRAMP, STIG, CIS compliant
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Source to Build
|
||||
|
||||
1. **Developer** pushes code changes to Git repository
|
||||
2. **Docker** builds container image with all dependencies
|
||||
3. **Run Script** orchestrates the build process
|
||||
4. **Live-build** creates ISO from configuration
|
||||
5. **Tests** validate the build process and output
|
||||
|
||||
### Build to Deployment
|
||||
|
||||
1. **ISO Generation** - Creates secure, bootable image
|
||||
2. **Testing** - Validates security and functionality
|
||||
3. **Distribution** - Secure delivery to end users
|
||||
4. **Installation** - Manual setup by privileged users
|
||||
5. **Configuration** - VPN setup and customization
|
||||
|
||||
## Security Architecture
|
||||
|
||||
### Isolation
|
||||
|
||||
- **Container Isolation** - Build process isolated from host
|
||||
- **Network Isolation** - No general internet access
|
||||
- **Service Isolation** - Minimal running services
|
||||
- **User Isolation** - Privilege separation
|
||||
|
||||
### Immutable Infrastructure
|
||||
|
||||
- **Source Controlled** - All configuration in version control
|
||||
- **Containerized Builds** - Reproducible build environment
|
||||
- **Immutable OS** - Package management disabled
|
||||
- **Verified Boot** - Secure boot with measured components
|
||||
|
||||
### Defense in Depth
|
||||
|
||||
- **Multiple Security Layers** - Network, system, application, access
|
||||
- **Fail-Safe Defaults** - Secure by default configuration
|
||||
- **Comprehensive Auditing** - Complete system activity logging
|
||||
- **Compliance Validation** - Automated compliance checking
|
||||
|
||||
## Quality Assurance
|
||||
|
||||
### Test-Driven Development
|
||||
|
||||
1. **Test First** - Tests written before implementation
|
||||
2. **100% Coverage** - All code and configurations tested
|
||||
3. **Automated Testing** - Continuous test execution
|
||||
4. **Multiple Test Types** - Unit, integration, security tests
|
||||
|
||||
### Continuous Validation
|
||||
|
||||
1. **Linting** - Code quality and style checking
|
||||
2. **Security Scanning** - Vulnerability assessment
|
||||
3. **Compliance Testing** - Framework validation
|
||||
4. **Performance Testing** - Resource usage validation
|
||||
|
||||
## Deployment Architecture
|
||||
|
||||
### Build Deployment
|
||||
|
||||
1. **Source Repository** - All code and configurations
|
||||
2. **Build Environment** - Containerized build system
|
||||
3. **CI/CD Pipeline** - Automated build and test
|
||||
4. **Artifact Repository** - ISO storage and distribution
|
||||
|
||||
### System Deployment
|
||||
|
||||
1. **ISO Distribution** - Secure delivery mechanism
|
||||
2. **Installation Process** - Manual setup by authorized users
|
||||
3. **Configuration** - VPN and security customization
|
||||
4. **Monitoring** - Ongoing security and compliance validation
|
||||
|
||||
## Maintenance Architecture
|
||||
|
||||
### Updates
|
||||
|
||||
1. **Source Updates** - Configuration changes through version control
|
||||
2. **Security Updates** - Through controlled ISO rebuilds
|
||||
3. **Compliance Updates** - Framework requirement changes
|
||||
4. **Documentation Updates** - Continuous documentation maintenance
|
||||
|
||||
### Monitoring
|
||||
|
||||
1. **Build Monitoring** - Build process health and success rates
|
||||
2. **Security Monitoring** - Vulnerability and threat monitoring
|
||||
3. **Compliance Monitoring** - Continuous compliance validation
|
||||
4. **Performance Monitoring** - Resource usage and performance
|
||||
|
||||
---
|
||||
|
||||
**Copyright © 2026 Known Element Enterprises LLC**
|
||||
**License: GNU Affero General Public License v3.0 only**
|
||||
|
||||
This architecture document is maintained as part of the KNEL-Football project and is updated when system components or processes change.
|
||||
Reference in New Issue
Block a user