refactor: Move specifications to docs directory
- Move football-spec.md to docs/football-spec.md - Move project-spec.md to docs/project-spec.md 💘 Generated with Crush Assisted-by: GLM-4.6 via Crush <crush@charm.land>
This commit is contained in:
952
docs/football-spec.md
Normal file
952
docs/football-spec.md
Normal file
@@ -0,0 +1,952 @@
|
||||
# KNEL-Football - 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
|
||||
|
||||
KNEL-Football 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.
|
||||
|
||||
**Copyright © 2026 Known Element Enterprises LLC**
|
||||
**License: GNU Affero General Public License v3.0 only**
|
||||
|
||||
## Target System Profile
|
||||
|
||||
### Operating System
|
||||
- **Base OS**: Debian 13.3.0 (Trixie) stable release
|
||||
- **Architecture**: amd64
|
||||
- **Kernel**: Latest stable kernel with security patches
|
||||
- **Secure Boot**: UEFI only with measured boot, custom keys included
|
||||
|
||||
### Desktop Environment
|
||||
- **Window Manager**: IceWM (minimal configuration)
|
||||
- **Display Manager**: LightDM with privacy enhancements, usernames hidden
|
||||
- **Theme**: Minimal, secure default configuration
|
||||
- **Boot Mode**: UEFI only, no Legacy BIOS support
|
||||
|
||||
### Core Applications
|
||||
- **Remote Desktop**: Remmina
|
||||
- **VPN**: WireGuard tools with zbar for QR code scanning
|
||||
- **Text Editor**: Mousepad
|
||||
- **Test Suite**: In-ISO validation tests (command line execution)
|
||||
- **No Package Management**: apt, dpkg, aptitude, synaptic disabled/removed
|
||||
|
||||
### 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
|
||||
|
||||
3. **QR Code Import**
|
||||
- Target: Scan WireGuard QR code and update config
|
||||
- Execution: `pkexec /usr/local/bin/scan-wireguard-qr.sh`
|
||||
- Icon: Camera/QR 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 (US/Chicago timezone, US English keyboard)
|
||||
- Software package selection
|
||||
- Password complexity enforcement
|
||||
- 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
|
||||
- Package management tools disabled with `chmod -x` and `chattr +i`
|
||||
- Test suite included in ISO for post-install validation
|
||||
|
||||
## 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 Level 3** - Entry point to tier0 infrastructure supporting ITAR/SECRET systems
|
||||
- **FedRAMP LI-SaaS** - For RackRental.net federal government product
|
||||
- **STIG** - DISA STIG for Debian (adapt Debian 11 STIG for Debian 13)
|
||||
- **CIS Benchmarks** - CIS Benchmark for Debian Linux (baseline security controls)
|
||||
|
||||
### 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 (CIS + STIG)
|
||||
- Password policy enforcement (CIS + STIG)
|
||||
- Audit daemon configuration (STIG)
|
||||
- Service hardening (CIS + STIG)
|
||||
- Network security implementation (STIG)
|
||||
- Logging and monitoring (STIG)
|
||||
- Package management disabling (custom requirement)
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
knel-football/
|
||||
├── README.md # Project documentation
|
||||
├── COMPLIANCE.md # Compliance matrix
|
||||
├── LICENSE # Project license
|
||||
├── run.sh # Host wrapper script
|
||||
├── Dockerfile # Build/test container
|
||||
├── .dockerignore # Docker ignore rules
|
||||
├── .gitignore # Git ignore rules (exclude ISO files)
|
||||
├── 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
|
||||
# KNEL-Football ISO Builder - Host Wrapper
|
||||
# This script orchestrates the Docker-based build process
|
||||
# Copyright © 2026 Known Element Enterprises LLC
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
# Configuration variables
|
||||
readonly DOCKER_IMAGE="knel-football-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 KNEL-Football secure 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 KNEL-Football 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
|
||||
# KNEL-Football 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"]
|
||||
```
|
||||
|
||||
### Package Management Security
|
||||
|
||||
#### config/hooks/installed/disable-package-management.sh
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Disable package management after installation
|
||||
set -euo pipefail
|
||||
|
||||
echo "Disabling package management..."
|
||||
|
||||
# Remove execute permissions from package management tools
|
||||
chmod -x /usr/bin/apt /usr/bin/apt-get /usr/bin/dpkg
|
||||
chmod -x /usr/bin/apt-cache /usr/bin/apt-key /usr/bin/dpkg-deb
|
||||
chmod -x /usr/bin/dpkg-query /usr/bin/dpkg-split /usr/bin/dpkg-trigger
|
||||
|
||||
# Make immutable
|
||||
chattr +i /usr/bin/apt /usr/bin/apt-get /usr/bin/dpkg
|
||||
chattr +i /usr/bin/apt-cache /usr/bin/apt-key /usr/bin/dpkg-deb
|
||||
chattr +i /usr/bin/dpkg-query /usr/bin/dpkg-split /usr/bin/dpkg-trigger
|
||||
|
||||
# Remove package metadata directories
|
||||
rm -rf /var/lib/apt/* /var/lib/dpkg/*
|
||||
|
||||
# Create immutable empty directories to prevent recreation
|
||||
mkdir -p /var/lib/apt /var/lib/dpkg
|
||||
chattr +i /var/lib/apt /var/lib/dpkg
|
||||
|
||||
echo "Package management disabled successfully."
|
||||
```
|
||||
|
||||
### 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/knel-football.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/qr-code-import.sh
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Install QR code scanning tools for WireGuard
|
||||
set -euo pipefail
|
||||
|
||||
echo "Installing QR code scanning tools..."
|
||||
|
||||
# Install zbar for QR code scanning
|
||||
apt-get update
|
||||
apt-get install -y zbar-tools python3-pil
|
||||
apt-get clean
|
||||
|
||||
# Create QR code scanning script
|
||||
cat > /usr/local/bin/scan-wireguard-qr.sh << 'EOF'
|
||||
#!/bin/bash
|
||||
# Scan WireGuard QR code and update configuration
|
||||
set -euo pipefail
|
||||
|
||||
# Check if webcam is available
|
||||
if ! ls /dev/video* >/dev/null 2>&1; then
|
||||
echo "Error: No webcam device found"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Create temporary file for QR data
|
||||
qr_data=$(mktemp)
|
||||
trap "rm -f $qr_data" EXIT
|
||||
|
||||
# Scan QR code
|
||||
echo "Scanning QR code..."
|
||||
zbarcam --raw --prescale=320x240 /dev/video0 > "$qr_data" &
|
||||
zbar_pid=$!
|
||||
|
||||
# Wait for user to stop scanning
|
||||
echo "Press Enter to stop scanning..."
|
||||
read -r
|
||||
kill $zbar_pid 2>/dev/null || true
|
||||
|
||||
# Parse QR data and update WireGuard config
|
||||
if [[ -s "$qr_data" ]]; then
|
||||
# Validate QR data format (basic WireGuard format)
|
||||
if grep -q "private_key\|endpoint\|allowed_ips" "$qr_data"; then
|
||||
# Backup existing config
|
||||
if [[ -f "/etc/wireguard/wg0.conf" ]]; then
|
||||
cp /etc/wireguard/wg0.conf "/etc/wireguard/wg0.conf.bak.$(date +%Y%m%d_%H%M%S)"
|
||||
fi
|
||||
|
||||
# Convert QR data to WireGuard config format
|
||||
python3 << 'PYTHON_EOF' "$qr_data"
|
||||
import sys
|
||||
import re
|
||||
|
||||
qr_data = sys.argv[1]
|
||||
|
||||
# Simple QR to WireGuard config conversion
|
||||
config_lines = ["[Interface]"]
|
||||
private_key = ""
|
||||
address = ""
|
||||
|
||||
for line in open(qr_data):
|
||||
if "private_key=" in line.lower():
|
||||
private_key = line.strip()
|
||||
elif "address=" in line.lower():
|
||||
address = line.strip()
|
||||
|
||||
if private_key:
|
||||
config_lines.append(f"PrivateKey = {private_key.split('=')[1].strip()}")
|
||||
if address:
|
||||
config_lines.append(f"Address = {address.split('=')[1].strip()}")
|
||||
|
||||
# Add basic peer template
|
||||
config_lines.append("")
|
||||
config_lines.append("[Peer]")
|
||||
config_lines.append("# Add PublicKey, Endpoint, and AllowedIPs manually")
|
||||
|
||||
print("\n".join(config_lines))
|
||||
PYTHON_EOF
|
||||
|
||||
echo "QR code scanned successfully. Please edit /etc/wireguard/wg0.conf to complete configuration."
|
||||
else
|
||||
echo "Error: Invalid WireGuard QR code format"
|
||||
exit 1
|
||||
fi
|
||||
else
|
||||
echo "Error: No QR code data captured"
|
||||
exit 1
|
||||
fi
|
||||
EOF
|
||||
|
||||
chmod +x /usr/local/bin/scan-wireguard-qr.sh
|
||||
|
||||
# Create desktop shortcut
|
||||
mkdir -p /usr/share/applications
|
||||
cat > /usr/share/applications/scan-wireguard-qr.desktop << EOF
|
||||
[Desktop Entry]
|
||||
Name=Import WireGuard QR Code
|
||||
Comment=Scan QR code to import WireGuard configuration
|
||||
Exec=pkexec /usr/local/bin/scan-wireguard-qr.sh
|
||||
Icon=camera-web
|
||||
Terminal=true
|
||||
Type=Application
|
||||
Categories=Network;System;
|
||||
EOF
|
||||
|
||||
echo "QR code scanning tools installed successfully."
|
||||
```
|
||||
|
||||
### 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}/knel-football.iso"
|
||||
else
|
||||
echo "Error: ISO file not generated"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Generate checksum
|
||||
cd "$OUTPUT_DIR"
|
||||
sha256sum "knel-football.iso" > "knel-football.iso.sha256"
|
||||
cd - > /dev/null
|
||||
|
||||
echo "ISO build completed successfully."
|
||||
echo "Output: ${OUTPUT_DIR}/knel-football.iso"
|
||||
}
|
||||
|
||||
# Main execution
|
||||
main() {
|
||||
echo "Starting KNEL-Football secure 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 KNEL-Football 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 the KNEL-Football 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 Level 3, FedRAMP LI-SaaS, and STIG requirements.
|
||||
|
||||
**Copyright © 2026 Known Element Enterprises LLC**
|
||||
**License: GNU Affero General Public License v3.0 only**
|
||||
|
||||
The project structure and component specifications are designed to meet all stated requirements while maintaining security, flexibility, and maintainability through rigorous testing and documentation.
|
||||
54
docs/project-spec.md
Normal file
54
docs/project-spec.md
Normal file
@@ -0,0 +1,54 @@
|
||||
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.
|
||||
Reference in New Issue
Block a user