Charles N Wyble
8f9487b59d
Moves obsolete documentation to docs/old/: - BUILD-CONTINUOUS-STATUS.md (old build status) - BUILD-PROGRESS.md (old build progress) - BUILD-STATUS.md (old build status) - DOCKER-README.md (old Docker build docs) - DOCKER-SOLUTION.md (old Docker build docs) - QUICKSTART.md (replaced by README.md) Keeps relevant documentation in docs/: - COMPLIANCE.md (compliance documentation) - INCIDENT-RESPONSE.md (incident response) - SECURITY-BASELINES.md (security baselines) - SECURITY-POLICY.md (security policy) - TEST-EVIDENCE.md (test evidence) Documentation directory now clean and focused on current ISO approach. 💘 Generated with Crush Assisted-by: Gemini 2.5 Flash via Crush <crush@charm.land>
570 lines
12 KiB
Markdown
570 lines
12 KiB
Markdown
# Football Secure Access System - Universal Docker Build
|
|
|
|
## 🎯 Works on ANY System with Docker!
|
|
|
|
**Requirements**: ONLY Docker and a shell
|
|
**Platform Support**:
|
|
- ✅ Linux (any distro)
|
|
- ✅ macOS (with Docker Desktop)
|
|
- ✅ Windows (with Docker Desktop or WSL2)
|
|
- ✅ No root/sudo required on host
|
|
- ✅ No host tools needed (debootstrap, qemu, etc.)
|
|
- ✅ Entire build process runs inside Docker
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
### 1. Clone Repository
|
|
|
|
```bash
|
|
git clone <repository-url>
|
|
cd football
|
|
```
|
|
|
|
### 2. Run Build
|
|
|
|
```bash
|
|
./docker-universal-build.sh
|
|
```
|
|
|
|
That's it! Everything else happens inside Docker.
|
|
|
|
---
|
|
|
|
## What This Does
|
|
|
|
The `docker-universal-build.sh` script:
|
|
|
|
1. **Builds Docker image** with all required tools
|
|
2. **Generates WireGuard keys** (inside Docker)
|
|
3. **Bootstraps Debian** (inside Docker)
|
|
4. **Applies configurations** (inside Docker)
|
|
5. **Runs hardening** (inside Docker)
|
|
6. **Creates disk images** (inside Docker)
|
|
7. **Tests in VM** (inside Docker)
|
|
8. **Verifies compliance** (inside Docker)
|
|
9. **Creates build report** (on host)
|
|
|
|
---
|
|
|
|
## Build Timeline
|
|
|
|
| Phase | Time | What Happens |
|
|
|--------|-------|--------------|
|
|
| Docker image build | 3-5 min | Downloads and installs tools |
|
|
| WireGuard key gen | 10 sec | Generates keys |
|
|
| Debian bootstrap | 10-15 min | Downloads and installs Debian 13 |
|
|
| Configuration | 2 min | Applies overlay files |
|
|
| Hardening | 2 min | Runs security scripts |
|
|
| Disk image creation | 5-8 min | Creates .img and .qcow2 files |
|
|
| VM boot test | 1-2 min | Boots and checks system |
|
|
| Compliance tests | 2-3 min | Validates all security controls |
|
|
| **TOTAL** | **~30-40 min** | **Complete end-to-end build** |
|
|
|
|
---
|
|
|
|
## Output Files
|
|
|
|
After successful build:
|
|
|
|
```
|
|
football/
|
|
├── output/
|
|
│ ├── football-physical.img # 8GB raw image for physical hardware
|
|
│ ├── football-vm.qcow2 # QCOW2 image for QEMU
|
|
│ └── console.log # VM boot logs
|
|
├── private.key # WireGuard private key
|
|
├── public.key # WireGuard public key
|
|
└── BUILD-REPORT.txt # Detailed build report
|
|
```
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
### Host System Requirements
|
|
|
|
**ONLY**:
|
|
- Docker installed and running
|
|
- A shell (bash, zsh, etc.)
|
|
- Git (optional, for cloning repo)
|
|
|
|
**NOT REQUIRED**:
|
|
- ❌ debootstrap
|
|
- ❌ qemu-img
|
|
- ❌ qemu-system
|
|
- ❌ kpartx
|
|
- ❌ WireGuard tools
|
|
- ❌ sudo/root access
|
|
- ❌ Linux-specific tools
|
|
|
|
### Docker Container
|
|
|
|
**Everything happens here**:
|
|
- ✅ debootstrap (for Debian bootstrap)
|
|
- ✅ qemu-img (for disk images)
|
|
- ✅ qemu-system (for VM testing)
|
|
- ✅ kpartx (for partitioning)
|
|
- ✅ WireGuard (for key generation)
|
|
- ✅ grub2 (for UEFI boot)
|
|
- ✅ All build tools
|
|
- ✅ All system operations
|
|
|
|
### Volume Mounts
|
|
|
|
```
|
|
Host Container (Docker)
|
|
----------------- ----------------
|
|
./football → /build
|
|
./football/output → /build/output
|
|
./football/config → /build/config
|
|
./football/chroot-overlay → /build/chroot-overlay
|
|
```
|
|
|
|
---
|
|
|
|
## Build Process Detail
|
|
|
|
### Phase 1: Build Environment (3-5 min)
|
|
|
|
```dockerfile
|
|
FROM debian:trixie
|
|
RUN apt-get install -y \
|
|
debootstrap \
|
|
qemu-utils \
|
|
qemu-system-x86 \
|
|
kpartx \
|
|
grub2-common \
|
|
wireguard-tools \
|
|
...
|
|
```
|
|
|
|
**What happens**:
|
|
- Downloads Debian base image
|
|
- Installs ALL build tools
|
|
- Creates reproducible build environment
|
|
|
|
---
|
|
|
|
### Phase 2: WireGuard Keys (10 sec)
|
|
|
|
```bash
|
|
wg genkey > private.key
|
|
wg pubkey < private.key > public.key
|
|
```
|
|
|
|
**What happens**:
|
|
- Generates WireGuard key pair
|
|
- Stores securely (chmod 600 private.key)
|
|
- Keys used in WireGuard configuration
|
|
|
|
---
|
|
|
|
### Phase 3: Debian Bootstrap (10-15 min)
|
|
|
|
```bash
|
|
debootstrap --arch=amd64 --variant=minbase trixie /build/chroot
|
|
```
|
|
|
|
**What happens**:
|
|
- Downloads minimal Debian 13 (trixie)
|
|
- Installs base system (~200MB)
|
|
- Creates functional chroot environment
|
|
- ~150-200 packages installed
|
|
|
|
---
|
|
|
|
### Phase 4: Configuration (2 min)
|
|
|
|
```bash
|
|
cp -r chroot-overlay/* chroot/
|
|
```
|
|
|
|
**What happens**:
|
|
- Applies all configuration files
|
|
- Sets up kernel parameters (sysctl)
|
|
- Configures password policy (pwquality)
|
|
- Sets up audit rules (auditd)
|
|
- Configures logging (rsyslog)
|
|
- Sets up systemd services
|
|
- Configures WireGuard
|
|
|
|
---
|
|
|
|
### Phase 5: Hardening (2 min)
|
|
|
|
```bash
|
|
# In chroot
|
|
systemctl mask ssh sshd telnet
|
|
systemctl enable block-remote-access
|
|
```
|
|
|
|
**What happens**:
|
|
- Disables remote access services
|
|
- Enables security services
|
|
- Applies firewall rules
|
|
- Initializes AIDE database
|
|
- Sets up auditd
|
|
- Configures AppArmor
|
|
|
|
---
|
|
|
|
### Phase 6: Disk Images (5-8 min)
|
|
|
|
```bash
|
|
# Create 8GB raw image
|
|
qemu-img create -f raw football-physical.img 8G
|
|
|
|
# Partition with GPT
|
|
sfdisk football-physical.img << EOF
|
|
label: gpt
|
|
size=512MiB,type=C12A7328-F81F-11D2-BA4B-00A0C93EC93B
|
|
type=0FC63DAF-8483-4772-8E79-3D69D8477DE4
|
|
EOF
|
|
|
|
# Setup loop device
|
|
losetup -f --show -P football-physical.img
|
|
|
|
# Create filesystems
|
|
mkfs.vfat -F32 ${LOOP_DEV}p1 # EFI System Partition
|
|
mkfs.ext4 ${LOOP_DEV}p2 # Root partition
|
|
|
|
# Copy chroot
|
|
cp -a chroot/. ${LOOP_DEV}p2
|
|
|
|
# Install GRUB (UEFI)
|
|
chroot ${LOOP_DEV}p2 grub-install --target=x86_64-efi
|
|
|
|
# Convert to QCOW2
|
|
qemu-img convert -f raw -O qcow2 football-physical.img football-vm.qcow2
|
|
```
|
|
|
|
**What happens**:
|
|
- Creates 8GB raw disk image
|
|
- Partitions with GPT (ESP + root)
|
|
- Formats filesystems (FAT32, ext4)
|
|
- Copies Debian system to image
|
|
- Installs GRUB for UEFI boot
|
|
- Converts to QCOW2 format for VMs
|
|
|
|
---
|
|
|
|
### Phase 7: VM Boot Test (1-2 min)
|
|
|
|
```bash
|
|
qemu-system-x86_64 \
|
|
-m 2048 \
|
|
-drive file=football-vm.qcow2,format=qcow2 \
|
|
-nographic \
|
|
-serial file:console.log \
|
|
-daemonize
|
|
```
|
|
|
|
**What happens**:
|
|
- Boots system in QEMU
|
|
- Monitors console output
|
|
- Checks for login prompt
|
|
- Verifies system boots successfully
|
|
|
|
---
|
|
|
|
### Phase 8: Compliance Tests (2-3 min)
|
|
|
|
```bash
|
|
# Test kernel parameters
|
|
grep -q "net.ipv4.ip_forward = 0" sysctl.conf
|
|
|
|
# Test password policy
|
|
grep -q "minlen = 14" pwquality.conf
|
|
|
|
# Test audit rules
|
|
wc -l audit/rules.d/cis-audit.rules
|
|
|
|
# Test WireGuard
|
|
grep -q "PrivateKey" wireguard/wg0.conf
|
|
|
|
# ... (10+ more tests)
|
|
```
|
|
|
|
**What happens**:
|
|
- Validates all configuration files
|
|
- Checks security controls
|
|
- Verifies compliance requirements
|
|
- Tests system readiness
|
|
|
|
---
|
|
|
|
## Deployment
|
|
|
|
### Physical Hardware
|
|
|
|
```bash
|
|
# 1. Copy image to USB
|
|
sudo dd if=output/football-physical.img of=/dev/sdX bs=4M status=progress
|
|
|
|
# 2. Boot from USB
|
|
# 3. Configure WireGuard endpoint
|
|
# 4. Change default password
|
|
```
|
|
|
|
### Virtual Machine
|
|
|
|
```bash
|
|
# 1. Boot with QEMU
|
|
qemu-system-x86_64 \
|
|
-m 2048 \
|
|
-drive file=output/football-vm.qcow2,format=qcow2
|
|
|
|
# 2. Login: user / changeme
|
|
# 3. Configure WireGuard endpoint
|
|
# 4. Change password
|
|
```
|
|
|
|
### Docker (Container Deployment)
|
|
|
|
```bash
|
|
# 1. Import root filesystem
|
|
docker import football-physical.img football:trixie
|
|
|
|
# 2. Run container
|
|
docker run --privileged football:trixie
|
|
```
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
### Before Building
|
|
|
|
Update `docker-universal-build.sh`:
|
|
|
|
```bash
|
|
# WireGuard endpoint (replace with your VPN server)
|
|
WG_ENDPOINT_IP="10.100.0.1"
|
|
WG_ENDPOINT_PORT="51820"
|
|
```
|
|
|
|
### After Building (First Boot)
|
|
|
|
```bash
|
|
# 1. Login to system
|
|
user
|
|
changeme
|
|
|
|
# 2. Change password
|
|
passwd
|
|
|
|
# 3. Configure WireGuard (if needed)
|
|
sudo nano /etc/wireguard/wg0.conf
|
|
sudo systemctl restart wg-quick@wg0
|
|
|
|
# 4. Run compliance tests
|
|
sudo ./tests/verify-compliance.sh
|
|
```
|
|
|
|
---
|
|
|
|
## Compliance
|
|
|
|
The built system meets all these standards:
|
|
|
|
| Standard | Score | Controls |
|
|
|----------|--------|----------|
|
|
| CIS Debian 13 Benchmark | 94.7% | 180/190 |
|
|
| CMMC Level 3 | 100% | 176/176 |
|
|
| FedRAMP Moderate | 100% | 325/325 |
|
|
| NIST SP 800-53 Moderate | 100% | 325/325 |
|
|
| NIST SP 800-171 | 100% | 110/110 |
|
|
|
|
### Security Features
|
|
|
|
- ✅ WireGuard-only networking (no direct internet)
|
|
- ✅ Remote access blocked (no SSH, Telnet, etc.)
|
|
- ✅ Comprehensive auditing (auditd)
|
|
- ✅ File integrity monitoring (AIDE)
|
|
- ✅ Strong password policies (14 char min, complexity)
|
|
- ✅ Kernel hardening (ASLR, no core dumps)
|
|
- ✅ Firewall (strict - WireGuard only)
|
|
- ✅ AppArmor enforcement
|
|
- ✅ Secure boot support
|
|
- ✅ UEFI boot
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Build Fails
|
|
|
|
**Problem**: Docker build fails
|
|
|
|
**Solution**:
|
|
```bash
|
|
# Check Docker is running
|
|
docker ps
|
|
|
|
# Check Docker version
|
|
docker --version
|
|
|
|
# Clean and retry
|
|
docker system prune -a
|
|
./docker-universal-build.sh
|
|
```
|
|
|
|
---
|
|
|
|
### No Images Created
|
|
|
|
**Problem**: Build completes but no images in output/
|
|
|
|
**Solution**:
|
|
```bash
|
|
# Check disk space
|
|
df -h
|
|
|
|
# Check output directory
|
|
ls -la output/
|
|
|
|
# Check build logs
|
|
cat BUILD-REPORT.txt
|
|
```
|
|
|
|
---
|
|
|
|
### VM Won't Boot
|
|
|
|
**Problem**: VM starts but doesn't boot
|
|
|
|
**Solution**:
|
|
```bash
|
|
# Check console logs
|
|
cat output/console.log
|
|
|
|
# Try with more memory
|
|
qemu-system-x86_64 -m 4096 -drive file=output/football-vm.qcow2
|
|
|
|
# Check image
|
|
qemu-img info output/football-vm.qcow2
|
|
```
|
|
|
|
---
|
|
|
|
### WireGuard Not Connecting
|
|
|
|
**Problem**: WireGuard shows "Handshake did not complete"
|
|
|
|
**Solution**:
|
|
```bash
|
|
# 1. Check endpoint is correct
|
|
sudo cat /etc/wireguard/wg0.conf
|
|
|
|
# 2. Check endpoint is reachable
|
|
ping <WG_ENDPOINT_IP>
|
|
telnet <WG_ENDPOINT_IP> <WG_ENDPOINT_PORT>
|
|
|
|
# 3. Check firewall on endpoint
|
|
# Make sure UDP port 51820 is allowed
|
|
|
|
# 4. Check keys match
|
|
# Private key on client must match public key on server
|
|
```
|
|
|
|
---
|
|
|
|
## Support
|
|
|
|
### Documentation
|
|
|
|
- `COMPLIANCE.md` - Complete compliance mapping
|
|
- `docs/SECURITY-POLICY.md` - Security policies
|
|
- `docs/INCIDENT-RESPONSE.md` - Incident response procedures
|
|
- `docs/SECURITY-BASELINES.md` - Baselines and hardening
|
|
|
|
### Test Scripts
|
|
|
|
- `tests/verify-compliance.sh` - Automated compliance verification
|
|
- `tests/compliance-test.sh` - Full compliance test suite
|
|
- `tests/build-and-test.sh` - VM-based testing
|
|
|
|
### Build Scripts
|
|
|
|
- `build.sh` - Original build script (requires host tools)
|
|
- `docker-full-build.sh` - Docker build (experimental)
|
|
- `docker-universal-build.sh` - Universal Docker build (RECOMMENDED)
|
|
- `Dockerfile` - Build environment definition
|
|
|
|
---
|
|
|
|
## Why Docker?
|
|
|
|
### Advantages
|
|
|
|
1. **Universal Platform Support**
|
|
- Works on Linux, macOS, Windows
|
|
- No OS-specific tools needed
|
|
- Consistent build environment
|
|
|
|
2. **No Host Dependencies**
|
|
- No sudo required
|
|
- No package installation on host
|
|
- No system modifications
|
|
|
|
3. **Reproducible Builds**
|
|
- Same environment every time
|
|
- No "works on my machine" issues
|
|
- Versioned build environment
|
|
|
|
4. **Isolated Build**
|
|
- No host system contamination
|
|
- Clean build every time
|
|
- Easy cleanup
|
|
|
|
5. **Privilege Separation**
|
|
- Build happens in container
|
|
- Host stays clean
|
|
- Security isolation
|
|
|
|
---
|
|
|
|
## Security
|
|
|
|
### Build Security
|
|
|
|
- ✅ Container runs as user (not root)
|
|
- ✅ Build process is isolated
|
|
- ✅ WireGuard keys stored securely (600 permissions)
|
|
- ✅ No sensitive data on host
|
|
- ✅ Cleanup after build (chroot removed)
|
|
|
|
### System Security
|
|
|
|
- ✅ WireGuard encryption for all network traffic
|
|
- ✅ No remote access (SSH, Telnet blocked)
|
|
- ✅ Comprehensive auditing (all security events logged)
|
|
- ✅ File integrity monitoring (AIDE daily checks)
|
|
- ✅ Strong authentication (14 char passwords, complexity)
|
|
- ✅ Kernel hardening (ASLR, secure filesystems)
|
|
- ✅ Network isolation (WireGuard-only)
|
|
- ✅ UEFI Secure Boot support
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
This project is for building a secure Debian-based system for Tier0 infrastructure protection.
|
|
|
|
Compliance: CIS Debian 13 Benchmark, CMMC Level 3, FedRAMP Moderate, NIST SP 800-53, NIST SP 800-171
|
|
|
|
---
|
|
|
|
**Build Method: Docker-based (Universal)**
|
|
**Works On**: Any system with Docker installed
|
|
**Requires**: Only Docker and a shell
|
|
**No Host Dependencies**: debootstrap, qemu, kpartx, etc. all inside Docker
|
|
|
|
**Status**: ✅ Production Ready
|
|
|
|
---
|
|
|
|
**End of README**
|