From a97974cfd5666539242f6e184b877fcc9af43e09 Mon Sep 17 00:00:00 2001 From: Charles N Wyble Date: Wed, 21 Jan 2026 09:16:25 -0500 Subject: [PATCH] docs: rename SECURE_DEBIAN_SPEC.md to football-spec.md - Updated filename to match project naming convention - No content changes, only renamed file --- football-spec.md | 791 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 791 insertions(+) create mode 100644 football-spec.md diff --git a/football-spec.md b/football-spec.md new file mode 100644 index 0000000..3909c3c --- /dev/null +++ b/football-spec.md @@ -0,0 +1,791 @@ +# Secure Debian 13 ISO - Technical Specification Document + +## Table of Contents +1. [Project Overview](#project-overview) +2. [Target System Profile](#target-system-profile) +3. [Installation Automation](#installation-automation) +4. [Development Environment & Constraints](#development-environment--constraints) +5. [Quality Assurance & Testing](#quality-assurance--testing) +6. [Compliance Requirements](#compliance-requirements) +7. [Project Structure](#project-structure) +8. [Component Specifications](#component-specifications) +9. [Implementation Roadmap](#implementation-roadmap) + +## Project Overview + +This project aims to build a highly secure, compliant Debian 13 (Trixie) installation ISO using a strict Docker-based workflow with Test-Driven Development methodology. The resulting ISO will be a minimal, hardened system with restricted networking and specific security configurations. + +## Target System Profile + +### Operating System +- **Base OS**: Debian 13 (Trixie) +- **Architecture**: amd64 +- **Kernel**: Latest stable kernel with security patches + +### Desktop Environment +- **Window Manager**: IceWM (minimal configuration) +- **Display Manager**: LightDM with privacy enhancements +- **Theme**: Minimal, secure default configuration + +### Core Applications +- **Remote Desktop**: Remmina +- **VPN**: WireGuard tools +- **Text Editor**: Mousepad +- **File Manager**: PCManFM + +### Security Configuration + +#### Network Restrictions +- **WiFi**: Permanently disabled via kernel module blacklist +- **Bluetooth**: Permanently disabled via kernel module blacklist +- **General Internet**: Disabled by default +- **Allowed Traffic**: WireGuard tunnel traffic only + +#### Firewall Configuration +- **Default Policy**: Deny all inbound and outbound traffic +- **Allowed Outbound**: UDP traffic to WireGuard endpoint only +- **Dynamic Configuration**: Parse `/etc/wireguard/wg0.conf` to extract endpoint +- **Implementation**: nftables with iptables compatibility layer + +#### Authentication & Privacy +- **Auto-login**: Disabled +- **Display Manager**: Hide usernames in login screen +- **User Management**: Manual user creation with sudo group membership + +### User Workflow Requirements + +#### USB Mount Support +- Automatic detection and mounting of USB storage devices +- Support for common filesystems (ext4, FAT32, NTFS) +- Proper permissions for configuration file copying + +#### Desktop Shortcuts +1. **WireGuard Configuration Editor** + - Target: `/etc/wireguard/wg0.conf` + - Execution: `pkexec mousepad /etc/wireguard/wg0.conf` + - Icon: WireGuard branded icon + +2. **VPN Configuration Apply** + - Target: Apply configuration and update firewall + - Execution: `pkexec /usr/local/bin/apply-vpn-config.sh` + - Icon: Network/VPN branded icon + +## Installation Automation + +### Build Process +- **Tool**: `live-build` for ISO generation +- **Base Image**: Debian 13 (Trixie) netinst +- **Customization**: Config hooks for security hardening + +### Preseed Configuration +- **File**: `config/preseed.cfg` +- **Automated Items**: + - Localization settings + - Software package selection + - Timezone configuration + - Keyboard layout +- **Manual Items**: + - Disk partitioning + - Root password setup + - Non-root user creation (auto-added to sudo group) + +## Development Environment & Constraints + +### Host System Restrictions +- **Forbidden Tools**: + - Make (no build automation) + - Python (no scripting language) + - Ruby (no scripting language) + - Any build tools directly on host +- **Allowed Tools**: + - `docker` (container runtime) + - `git` (version control) + - `libvirt` (virtualization tools: virt-install, virsh) + +### Container-Based Workflow +- **Single Entry Point**: `run.sh` wrapper script +- **Build Environment**: Docker container with all dependencies +- **Build Tools Inside Container**: + - `live-build` + - `debootstrap` + - `bats-core` + - `shellcheck` + - Security hardening tools + +### File Permissions +- All generated files owned by invoking user +- Docker volume mounts with proper UID/GID mapping +- No root-owned output files + +## Quality Assurance & Testing + +### Test-Driven Development +- **Methodology**: Tests written before implementation +- **Test Coverage**: 100% mandatory coverage +- **Test Types**: + - Unit tests for logic components + - Integration tests for ISO generation + - Security validation tests + +### Testing Framework +- **Primary Tool**: `bats-core` (Bash Automated Testing System) +- **Linting**: `shellcheck` for all shell scripts +- **Code Standards**: Strict mode with `set -euo pipefail` + +### Test Organization +``` +tests/ +├── unit/ # Unit tests for individual functions +├── integration/ # Integration tests for complete workflows +├── security/ # Security validation tests +└── fixtures/ # Test data and mocks +``` + +## Compliance Requirements + +### Standards Framework +- **CMMC** (Cybersecurity Maturity Model Certification) +- **FedRAMP** (Federal Risk and Authorization Management Program) +- **STIG** (Security Technical Implementation Guide) +- **CIS Benchmarks** (Center for Internet Security) + +### Compliance Documentation +- **Matrix Document**: `COMPLIANCE.md` +- **Mapping**: STIG IDs and CIS controls to build hooks +- **Validation**: Automated compliance verification tests + +### Key Compliance Areas +- Filesystem hardening +- Password policy enforcement +- Audit daemon configuration +- Service hardening +- Network security implementation +- Logging and monitoring + +## Project Structure + +``` +secure-debian-iso/ +├── README.md # Project documentation +├── COMPLIANCE.md # Compliance matrix +├── LICENSE # Project license +├── run.sh # Host wrapper script +├── Dockerfile # Build/test container +├── .dockerignore # Docker ignore rules +├── config/ # live-build configuration +│ ├── preseed.cfg # Installation automation +│ ├── package-lists/ # Software package selections +│ ├── hooks/ # Build hooks +│ │ ├── live/ # Live system hooks +│ │ └── installed/ # Post-installation hooks +│ └── includes/ # File inclusions +├── src/ # Build scripts +│ ├── build-iso.sh # Main ISO build script +│ ├── security-hardening.sh # Security configurations +│ ├── firewall-setup.sh # Dynamic firewall configuration +│ └── compliance-check.sh # Compliance validation +├── tests/ # Test suite +│ ├── unit/ # Unit tests +│ ├── integration/ # Integration tests +│ ├── security/ # Security tests +│ └── fixtures/ # Test fixtures +├── docs/ # Documentation +│ ├── architecture.md # System architecture +│ ├── security-model.md # Security model +│ └── user-guide.md # User documentation +└── output/ # Generated ISO files +``` + +## Component Specifications + +### run.sh (Host Wrapper) + +```bash +#!/bin/bash +# Secure Debian ISO Builder - Host Wrapper +# This script orchestrates the Docker-based build process + +set -euo pipefail + +# Configuration variables +readonly DOCKER_IMAGE="secure-debian-builder:latest" +readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +readonly OUTPUT_DIR="${SCRIPT_DIR}/output" + +# Create output directory if it doesn't exist +mkdir -p "${OUTPUT_DIR}" + +# Function to show usage +usage() { + echo "Usage: $0 [command]" + echo "Commands:" + echo " build Build the secure ISO" + echo " test Run all tests" + echo " lint Run linting checks" + echo " clean Clean build artifacts" + echo " shell Interactive shell in build container" + exit 1 +} + +# Main execution logic +main() { + local command="${1:-build}" + + case "${command}" in + build) + echo "Building secure Debian ISO..." + docker run --rm \ + -v "${SCRIPT_DIR}:/workspace" \ + -v "${OUTPUT_DIR}:/workspace/output" \ + -u "$(id -u):$(id -g)" \ + "${DOCKER_IMAGE}" \ + /workspace/src/build-iso.sh + ;; + test) + echo "Running test suite..." + docker run --rm \ + -v "${SCRIPT_DIR}:/workspace" \ + -u "$(id -u):$(id -g)" \ + "${DOCKER_IMAGE}" \ + bats -r /workspace/tests/ + ;; + lint) + echo "Running linting checks..." + docker run --rm \ + -v "${SCRIPT_DIR}:/workspace" \ + -u "$(id -u):$(id -g)" \ + "${DOCKER_IMAGE}" \ + shellcheck /workspace/src/*.sh /workspace/config/hooks/*/*.sh + ;; + clean) + echo "Cleaning build artifacts..." + rm -rf "${OUTPUT_DIR:?}"/* + ;; + shell) + echo "Starting interactive shell..." + docker run --rm -it \ + -v "${SCRIPT_DIR}:/workspace" \ + -v "${OUTPUT_DIR}:/workspace/output" \ + -u "$(id -u):$(id -g)" \ + "${DOCKER_IMAGE}" \ + bash + ;; + *) + usage + ;; + esac +} + +main "$@" +``` + +### Dockerfile (Build/Test Environment) + +```dockerfile +# Secure Debian ISO Builder - Dockerfile +# Multi-stage build for security hardening + +# Base stage +FROM debian:trixie-slim AS base + +# Set environment variables +ENV DEBIAN_FRONTEND=noninteractive +ENV LANG=C.UTF-8 + +# Install base dependencies +RUN apt-get update && apt-get install -y \ + ca-certificates \ + gnupg \ + curl \ + wget \ + git \ + && apt-get clean && rm -rf /var/lib/apt/lists/* + +# Builder stage +FROM base AS builder + +# Install build dependencies +RUN apt-get update && apt-get install -y \ + live-build \ + debootstrap \ + squashfs-tools \ + xorriso \ + grub-pc-bin \ + grub-efi-amd64-bin \ + mtools \ + dosfstools \ + && apt-get clean && rm -rf /var/lib/apt/lists/* + +# Install testing dependencies +RUN apt-get update && apt-get install -y \ + bats \ + shellcheck \ + nftables \ + iptables \ + && apt-get clean && rm -rf /var/lib/apt/lists/* + +# Install additional security tools +RUN apt-get update && apt-get install -y \ + auditd \ + rsyslog \ + && apt-get clean && rm -rf /var/lib/apt/lists/* + +# Create workspace directory +WORKDIR /workspace + +# Set proper permissions +RUN groupadd -r builder && useradd -r -g builder builder +RUN chown -R builder:builder /workspace +USER builder + +# Default command +CMD ["/bin/bash"] +``` + +### Tests Structure + +#### tests/unit/firewall_test.bats +```bash +#!/usr/bin/env bats +# Unit tests for firewall configuration + +load 'test_helper/bats-support/load' +load 'test_helper/bats-assert/load' + +@test "parse wireguard endpoint from config" { + # Create test configuration + cat > /tmp/test-wg0.conf << EOF +[Interface] +PrivateKey = testkey +Address = 10.0.0.2/24 + +[Peer] +PublicKey = testpubkey +Endpoint = 192.168.1.100:51820 +AllowedIPs = 0.0.0.0/0 +EOF + + # Test parsing function + source src/firewall-setup.sh + result=$(parse_endpoint /tmp/test-wg0.conf) + assert_equal "$result" "192.168.1.100:51820" +} + +@test "generate nftables rules for wireguard" { + source src/firewall-setup.sh + rules=$(generate_nftables_rules "192.168.1.100:51820") + assert_regex "$rules" "udp.*192.168.1.100.*51820" +} +``` + +#### tests/integration/iso_build_test.bats +```bash +#!/usr/bin/env bats +# Integration tests for ISO build process + +load 'test_helper/bats-support/load' +load 'test_helper/bats-assert/load' + +@test "live-build configuration is valid" { + run lb config + assert_success +} + +@test "build process completes without errors" { + run src/build-iso.sh + assert_success + [ -f "output/secure-debian.iso" ] +} + +@test "generated ISO contains required packages" { + # Mount ISO and verify package list + # This would involve mounting the ISO and checking package lists + skip "ISO mounting test implementation needed" +} +``` + +#### tests/security/compliance_test.bats +```bash +#!/usr/bin/env bats +# Security compliance tests + +load 'test_helper/bats-support/load' +load 'test_helper/bats-assert/load' + +@test "wifi modules are blacklisted" { + run bash -c "grep -r 'blacklist' /etc/modprobe.d/ | grep -E '(wifi|wireless|cfg80211)'" + assert_success +} + +@test "bluetooth modules are blacklisted" { + run bash -c "grep -r 'blacklist' /etc/modprobe.d/ | grep -E '(bluetooth|btusb)'" + assert_success +} + +@test "firewall default policy is deny" { + run nft list ruleset + assert_output --partial 'policy drop' +} +``` + +### config/hooks/live/security-hardening.sh + +```bash +#!/bin/bash +# Security hardening hook for live system +set -euo pipefail + +echo "Applying security hardening..." + +# Blacklist WiFi modules +cat > /etc/modprobe.d/blacklist-wifi.conf << EOF +# WiFi module blacklisting +blacklist cfg80211 +blacklist mac80211 +blacklist brcmfmac +blacklist iwlwifi +blacklist ath9k +blacklist rt73usb +EOF + +# Blacklist Bluetooth modules +cat > /etc/modprobe.d/blacklist-bluetooth.conf << EOF +# Bluetooth module blacklisting +blacklist btusb +blacklist bluetooth +blacklist btrtl +blacklist btintel +blacklist btbcm +EOF + +# Configure auditd +systemctl enable auditd +cat > /etc/audit/rules.d/audit.rules << EOF +# Audit rules for security compliance +-w /etc/passwd -p wa -k identity +-w /etc/shadow -p wa -k identity +-w /etc/sudoers -p wa -k identity +-w /etc/ssh/sshd_config -p wa -k sshd_config +-w /var/log/audit/ -p wa -k log_audit +-w /var/log/secure -p wa -k log_secure +-w /etc/wireguard/ -p wa -k wireguard_config +EOF + +# Configure password policy +cat > /etc/security/pwquality.conf << EOF +# Password quality requirements +minlen = 14 +dcredit = -1 +ucredit = -1 +lcredit = -1 +ocredit = -1 +difok = 4 +maxrepeat = 3 +usercheck = 1 +dictcheck = 1 +EOF + +echo "Security hardening completed." +``` + +### config/hooks/live/firewall-setup.sh + +```bash +#!/bin/bash +# Dynamic firewall setup hook +set -euo pipefail + +# Function to parse WireGuard endpoint +parse_wg_endpoint() { + local wg_config="/etc/wireguard/wg0.conf" + + if [[ ! -f "$wg_config" ]]; then + echo "Error: WireGuard config not found at $wg_config" + return 1 + fi + + grep -oP 'Endpoint = \K[0-9.]+:[0-9]+' "$wg_config" || { + echo "Error: Could not parse endpoint from WireGuard config" + return 1 + } +} + +# Function to generate nftables rules +generate_nftables_rules() { + local endpoint="$1" + local ip="${endpoint%:*}" + local port="${endpoint#*:}" + + cat << EOF +#!/usr/sbin/nft -f +# Secure firewall rules for WireGuard-only access +flush ruleset + +table inet filter { + chain input { + type filter hook input priority 0; policy drop + iif lo accept comment "Accept loopback" + icmp type echo-request accept comment "Accept ping" + } + + chain forward { + type filter hook forward priority 0; policy drop + } + + chain output { + type filter hook output priority 0; policy drop + oif lo accept comment "Accept loopback" + udp dport "$port" ip daddr "$ip" accept comment "Allow WireGuard traffic" + icmp type echo-request accept comment "Allow ping" + } +} +EOF +} + +# Main setup +echo "Setting up dynamic firewall..." + +if [[ -f "/etc/wireguard/wg0.conf" ]]; then + endpoint=$(parse_wg_endpoint) + if [[ -n "$endpoint" ]]; then + generate_nftables_rules "$endpoint" > /etc/nftables.conf + systemctl enable nftables + echo "Firewall configured for endpoint: $endpoint" + else + echo "Warning: Could not parse WireGuard endpoint, using default deny policy" + fi +else + echo "Warning: WireGuard config not found, using default deny policy" +fi + +echo "Firewall setup completed." +``` + +### src/build-iso.sh + +```bash +#!/bin/bash +# Main ISO build script +set -euo pipefail + +# Configuration variables +readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +readonly PROJECT_ROOT="$(dirname "$SCRIPT_DIR")" +readonly OUTPUT_DIR="${PROJECT_ROOT}/output" +readonly CONFIG_DIR="${PROJECT_ROOT}/config" + +# Function to validate environment +validate_environment() { + echo "Validating build environment..." + + # Check for required tools + local required_tools=("lb" "debootstrap" "mksquashfs") + for tool in "${required_tools[@]}"; do + if ! command -v "$tool" > /dev/null 2>&1; then + echo "Error: Required tool '$tool' not found" + exit 1 + fi + done + + # Verify configuration directory + if [[ ! -d "$CONFIG_DIR" ]]; then + echo "Error: Configuration directory not found at $CONFIG_DIR" + exit 1 + fi + + echo "Environment validation successful." +} + +# Function to prepare build environment +prepare_build() { + echo "Preparing build environment..." + + # Create output directory + mkdir -p "$OUTPUT_DIR" + + # Initialize live-build configuration + lb clean --purge + lb config + + echo "Build environment prepared." +} + +# Function to build ISO +build_iso() { + echo "Building secure Debian ISO..." + + # Execute live-build + lb build + + # Move output files to output directory + if [[ -f "binary.hybrid.iso" ]]; then + mv "binary.hybrid.iso" "${OUTPUT_DIR}/secure-debian.iso" + else + echo "Error: ISO file not generated" + exit 1 + fi + + # Generate checksum + cd "$OUTPUT_DIR" + sha256sum "secure-debian.iso" > "secure-debian.iso.sha256" + cd - > /dev/null + + echo "ISO build completed successfully." + echo "Output: ${OUTPUT_DIR}/secure-debian.iso" +} + +# Main execution +main() { + echo "Starting secure Debian ISO build..." + + validate_environment + prepare_build + build_iso + + echo "Build process completed successfully!" +} + +main "$@" +``` + +### src/security-hardening.sh + +```bash +#!/bin/bash +# Security hardening script +set -euo pipefail + +# Function to configure system security +configure_system_security() { + echo "Configuring system security..." + + # Disable unnecessary services + systemctl disable cups + systemctl disable avahi-daemon + systemctl disable bluetooth + + # Secure SSH configuration + cat > /etc/ssh/sshd_config << EOF +# SSH Security Configuration +Protocol 2 +PermitRootLogin no +PasswordAuthentication yes +PubkeyAuthentication yes +PermitEmptyPasswords no +ChallengeResponseAuthentication no +X11Forwarding no +MaxAuthTries 3 +ClientAliveInterval 300 +ClientAliveCountMax 2 +EOF + + # Configure system limits + cat > /etc/security/limits.d/security.conf << EOF +# System security limits +* hard core 0 +* soft nproc 1024 +* hard nproc 2048 +EOF + + echo "System security configured." +} + +# Function to configure filesystem security +configure_filesystem_security() { + echo "Configuring filesystem security..." + + # Set secure permissions on sensitive files + chmod 600 /etc/shadow + chmod 600 /etc/gshadow + chmod 644 /etc/passwd + chmod 644 /etc/group + + # Configure sticky bit on world-writable directories + chmod +t /tmp + chmod +t /var/tmp + + echo "Filesystem security configured." +} + +# Function to verify compliance +verify_compliance() { + echo "Verifying compliance..." + + # Check that WiFi modules are blacklisted + if ! grep -q "blacklist cfg80211" /etc/modprobe.d/blacklist-wifi.conf; then + echo "Error: WiFi modules not properly blacklisted" + exit 1 + fi + + # Check that Bluetooth modules are blacklisted + if ! grep -q "blacklist btusb" /etc/modprobe.d/blacklist-bluetooth.conf; then + echo "Error: Bluetooth modules not properly blacklisted" + exit 1 + fi + + # Check firewall configuration + if ! systemctl is-enabled nftables > /dev/null 2>&1; then + echo "Error: Firewall not properly enabled" + exit 1 + fi + + echo "Compliance verification successful." +} + +# Main execution +main() { + echo "Starting security hardening..." + + configure_system_security + configure_filesystem_security + verify_compliance + + echo "Security hardening completed successfully!" +} + +main "$@" +``` + +## Implementation Roadmap + +### Phase 1: Project Setup and Testing Infrastructure +1. Create project structure +2. Set up Docker build environment +3. Implement test framework with bats-core +4. Create initial unit tests for core functions + +### Phase 2: Core Build System +1. Implement basic live-build configuration +2. Create preseed configuration for automated installation +3. Develop build scripts with error handling +4. Implement test coverage for build process + +### Phase 3: Security Hardening +1. Implement kernel module blacklisting +2. Configure dynamic firewall system +3. Develop security hardening scripts +4. Create security compliance tests + +### Phase 4: Desktop Environment and Applications +1. Configure IceWM window manager +2. Set up LightDM with privacy mode +3. Install and configure required applications +4. Create desktop shortcuts for VPN management + +### Phase 5: Compliance and Documentation +1. Implement compliance matrix +2. Map STIG and CIS controls to configurations +3. Create comprehensive documentation +4. Perform final integration testing + +### Phase 6: Validation and Release +1. Complete end-to-end testing +2. Perform security audit +3. Generate release documentation +4. Create user guide and deployment instructions + +## Conclusion + +This specification provides a comprehensive blueprint for building a secure, compliant Debian 13 ISO using a Docker-based workflow with Test-Driven Development methodology. The implementation will result in a minimal, hardened system with strict network restrictions and compliance with CMMC, FedRAMP, and STIG requirements. + +The project structure and component specifications are designed to meet all stated requirements while maintaining security, flexibility, and maintainability through rigorous testing and documentation. \ No newline at end of file