football/docs/project-spec.md

I need to initiate a new engineering project to build a highly secure, compliant Debian 13 (Trixie) installation ISO using a strict Docker-based workflow.

Please generate a detailed, technical Specification Document (in Markdown format) that outlines the requirements for this project. This document will serve as the blueprint for a Test-Driven Development (TDD) implementation.

The specification must cover the following requirements in detail:

1. Target System Profile

• OS: Debian 13 (Trixie).
• Desktop: Minimal IceWM Window Manager with LightDM Display Manager.
• Applications: Remmina, WireGuard, Mousepad, PCManFM.
• Networking: Wifi and Bluetooth must be permanently disabled (Kernel Blacklist).
• Connectivity: No general internet access. All network traffic must be routed exclusively through a WireGuard tunnel.
• Firewall: A "Deny All" default policy. The only allowed outbound traffic is UDP traffic to the specific IP/Port defined in the WireGuard configuration file. This must be dynamically configured by parsing the .conf file, not hardcoded.
• Authentication: No auto-login. Usernames must be hidden in the Display Manager (Privacy Mode).
• Workflow:
  • USB drives must be mountable to copy configurations.
  • Desktop shortcuts must exist to:
    1. Edit /etc/wireguard/wg0.conf (with root privileges via pkexec).
    2. Apply the VPN configuration and update the firewall rules dynamically.

2. Installation Automation

• The build process must utilize live-build.
• The ISO must use a preseed.cfg file to automate localization and software selection, BUT it must require manual interaction for:
  • Disk Partitioning.
  • Root Password Setup.
  • Non-root User Creation (User must be added to sudo group).

3. Development Environment & Constraints

• Host System: The host environment is restricted. NO Make, NO Python, NO Ruby, NO build tools allowed on the host.
• Allowed Tools: docker, git, libvirt (virt-install/virsh).
• Orchestration: A single shell script wrapper (run.sh) is allowed on the host to invoke Docker commands.
• Builder Container: All build tools (live-build, debootstrap) and testing tools must run inside a Docker container.
• Permissions: All output files generated by the container must be owned by the user invoking Docker (not root).

4. Quality Assurance & Testing (TDD)

• Methodology: Strict Test-Driven Development. The specification must define that tests are written before code.
• Testing Tools: bats-core for testing, shellcheck for linting.
• Coverage: 100% code coverage is mandatory (Unit tests for logic, Integration tests for ISO generation).
• Code Standards: All Bash scripts must run in Strict Mode (set -euo pipefail).

5. Compliance (CMMC / FedRAMP / STIG)

• The specification must demand the inclusion of a Compliance Matrix (COMPLIANCE.md).
• This matrix must map specific STIG IDs and CIS Benchmark controls (e.g., disabling unused filesystems, enforcing strong passwords, configuring auditd) to specific configuration hooks in the build process.

6. Output Format

• Provide the complete project structure (files and directories).
• Provide the content logic for:
  • run.sh (Host wrapper).
  • Dockerfile (Build/Test environment).
  • tests/ (BATS test structure).
  • config/hooks/live/ (Security hardening and firewall scripts).
  • src/ (Internal build scripts).

Please generate this comprehensive specification document now.