football/football-spec.md

Secure Debian 13 ISO - Technical Specification Document

Table of Contents

1. Project Overview
2. Target System Profile
3. Installation Automation
4. Development Environment & Constraints
5. Quality Assurance & Testing
6. Compliance Requirements
7. Project Structure
8. Component Specifications
9. 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 - all packages must be included in ISO
• Allowed Traffic: WireGuard tunnel traffic only
• Package Sources: All required packages pre-included in ISO, no external downloads during or after installation

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
• All required filesystem utilities pre-installed in ISO

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.3.0 (Trixie) netinst
• Specific ISO: debian-13.3.0-amd64-netinst.iso from official Debian mirrors
• 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)

#!/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)

# Secure Debian ISO Builder - Dockerfile
# Multi-stage build for security hardening

# Base stage
FROM debian:13.3-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

#!/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

#!/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

#!/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

#!/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

#!/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

#!/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

#!/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.