KNEL/football
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add minimal Debian image build system with WireGuard-only networking

Browse Source 
Add complete build infrastructure for football secure access system:
- Minimal Debian base with only IceWM and Remmina
- WireGuard-only networking with strict firewall (eth0 allows only WireGuard)
- All network traffic routed through mandatory VPN tunnel
- Secure Boot enforced for physical deployments
- Zero remote access - SSH, telnet disabled and blocked
- AppArmor, auditd, and fail2ban for security hardening

Build system generates both VM (qcow2) and physical (raw) images.
WireGuard endpoint IP and port configurable via build script variables.

Includes:
- Package list with minimal dependencies
- System hardening scripts
- WireGuard client and server configuration tools
- Comprehensive documentation (README.md, QUICKSTART.md)
- systemd services for firewall enforcement
- User environment with automatic IceWM startup

💘 Generated with Crush

Assisted-by: GLM-4.7 via Crush <crush@charm.land>
This commit is contained in:
Charles N Wyble
2026-01-13 12:11:18 -05:00
parent 230c4f2d3d
commit 17dcee7e52
21 changed files with 1403 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

315
README.md
View File

@@ -1,3 +1,314 @@
# football
# Football - Minimal Debian Secure Access System
Fully self contained , very stripped and locked down Debian image intended for deployment onto physical access only system (Dell Laptop) (called football-(x) to be used for remote (RDP) access to another high security physical system (highside) which is a privileged access workstation in the KNEL server room.
Fully self-contained, stripped-down, and locked-down Debian image intended for deployment onto physical access-only systems (Dell Laptop) called football-(x). Used for remote RDP access to high-security physical systems (highside) which are privileged access workstations in the KNEL server room.
## Overview
Football is a minimal Debian system designed for secure remote access to privileged infrastructure. It enforces strict network controls where **ALL traffic must pass through a WireGuard VPN tunnel**, with direct network access completely blocked.
## Architecture
### Security Model
- **Zero remote access**: No SSH, telnet, or any inbound services
- **WireGuard-only networking**: All traffic routed through mandatory VPN tunnel
- **Secure Boot enforced**: Kernel and bootloader signatures verified
- **Minimal attack surface**: Only IceWM and Remmina installed
- **Local console only**: No remote administration capabilities
### Network Configuration
```
Physical Interface (eth0)
├─ DHCP: Allowed (for IP acquisition)
└─ WireGuard: ONLY allowed connection to configured endpoint
└─ Endpoint: WG_ENDPOINT_IP:WG_ENDPOINT_PORT (configurable)
WireGuard Interface (wg0)
└─ ALL outbound traffic
└─ VPN endpoint → PAW (Privileged Access Workstation)
```
### Firewall Rules
- **INPUT**: DROP (except lo, WireGuard keepalive, and DHCP)
- **OUTPUT**: DROP on eth0 (except to WireGuard endpoint)
- **FORWARD**: DROP
- **OUTPUT on wg0**: ACCEPT (all VPN traffic)
## Quick Start
### Prerequisites
```bash
# Install build dependencies
sudo apt-get install debootstrap qemu-utils kpartx squashfs-tools
```
### Generate WireGuard Keys
```bash
# Generate client key pair
wg genkey | tee client-private.key | wg pubkey > client-public.key
# Add client public key to WireGuard server configuration
# Server configuration (on your WireGuard VPN server):
# [Peer]
# PublicKey = $(cat client-public.key)
# AllowedIPs = 10.100.0.2/32
```
### Configure Build
Edit `build.sh` and set the following variables:
```bash
WG_ENDPOINT_IP="192.0.2.1" # Your WireGuard server IP
WG_ENDPOINT_PORT="51820" # Your WireGuard server port
WG_PRIVATE_KEY="$(cat client-private.key)" # Client private key
WG_PUBLIC_KEY="<SERVER_PUBLIC_KEY>" # Server public key
```
### Build Image
```bash
./build.sh
```
This creates:
- `output/football-physical.img` - Raw image for physical hardware
- `output/football-vm.qcow2` - QCOW2 image for virtual machines
### Deploy
#### Virtual Machine
```bash
qemu-system-x86_64 \
-m 2048 \
-drive file=output/football-vm.qcow2,format=qcow2
```
#### Physical System
1. Write raw image to USB or disk:
```bash
sudo dd if=output/football-physical.img of=/dev/sdX bs=4M status=progress
```
2. Boot system with UEFI Secure Boot enabled
3. Change default user password (`changeme`)
## Directory Structure
```
football/
├── build.sh # Main build script
├── config/
│ ├── packages.list # Minimal package list
│ ├── harden.sh # System hardening script
│ ├── secureboot.sh # Secure Boot configuration
│ └── setup-wireguard.sh # WireGuard setup script
├── chroot-overlay/ # Files copied to built system
│ ├── etc/
│ │ ├── systemd/system/ # Systemd services
│ │ ├── wireguard/ # WireGuard config templates
│ │ └── network/interfaces # Network configuration
│ └── home/user/ # User configuration
│ ├── .bashrc
│ ├── .xinitrc
│ ├── .icewm/preferences
│ └── Desktop/README.txt
└── output/ # Generated images (not in git)
```
## Security Features
### Hardening Measures
1. **Network Isolation**
- All inbound traffic blocked
- Only WireGuard traffic allowed on physical interface
- Mandatory VPN tunnel for all outbound traffic
2. **Service Restrictions**
- SSH server disabled and masked
- All remote access services removed
- Bluetooth disabled
- Unnecessary kernel modules disabled
3. **Secure Boot**
- GRUB locked with password protection
- Kernel lockdown mode enabled
- Signed bootloader (shim-signed)
- EFI variables write-protected
4. **Application Whitelisting**
- Only IceWM and Remmina installed
- No development tools
- Minimal command-line utilities
5. **System Hardening**
- AppArmor enforcing
- Fail2Ban enabled
- Auditd logging
- Core dumps disabled
- Strict umask (077)
### Firewall Rules (Detailed)
```bash
# IPv4 Rules
iptables -P INPUT DROP
iptables -P FORWARD DROP
iptables -P OUTPUT DROP
# Allow loopback
iptables -A INPUT -i lo -j ACCEPT
iptables -A OUTPUT -o lo -j ACCEPT
# Allow WireGuard to endpoint on eth0
iptables -A OUTPUT -o eth0 -d $WG_ENDPOINT_IP \
-p udp --dport $WG_ENDPOINT_PORT -j ACCEPT
iptables -A INPUT -i eth0 -s $WG_ENDPOINT_IP \
-p udp --sport $WG_ENDPOINT_PORT -j ACCEPT
# Allow DHCP on eth0
iptables -A OUTPUT -o eth0 -p udp --dport 67 -j ACCEPT
iptables -A INPUT -i eth0 -p udp --sport 67 -j ACCEPT
# Allow ALL traffic on WireGuard interface
iptables -A INPUT -i wg0 -j ACCEPT
iptables -A OUTPUT -o wg0 -j ACCEPT
```
## Usage
### Default User
- **Username**: `user`
- **Password**: `changeme` (CHANGE IMMEDIATELY!)
### Automatic Startup
1. Login triggers automatic IceWM start
2. Remmina launches automatically
3. WireGuard tunnel establishes automatically
4. Use Remmina to connect to PAW
### Remmina Configuration
Create Remmina profiles in:
- Path: `/home/user/.local/share/remmina/`
- Protocol: RDP or VNC (as needed)
- Server: PAW internal IP via WireGuard
### System Administration
**Local console access only:**
```bash
# Check WireGuard status
sudo wg show
# View firewall rules
sudo iptables -L -n -v
# Check logs
sudo journalctl -u wg-quick@wg0
sudo journalctl -u block-remote-access
```
## Troubleshooting
### WireGuard Connection Fails
1. Verify endpoint IP and port
2. Check firewall rules allow WireGuard
3. Verify keys are correctly configured
4. Check WireGuard server logs
### Network Blocked
1. Confirm WireGuard interface is up: `ip link show wg0`
2. Check firewall: `sudo iptables -L -n -v`
3. Verify WireGuard config: `sudo wg show`
### Secure Boot Issues
1. Ensure UEFI is enabled
2. Verify Microsoft UEFI CA is installed
3. Check Secure Boot status: `mokutil --sb-state`
### System Won't Boot
1. Verify UEFI boot mode (not legacy BIOS)
2. Check GRUB installation
3. Review kernel logs from boot
## Advanced Configuration
### Customizing the Build
Edit `config/packages.list` to add/remove packages
Modify `chroot-overlay/` to customize system files
### Changing Image Size
Edit `build.sh`:
```bash
DISK_SIZE_MB=8192 # Change to desired size in MB
```
### Multiple Deployment Profiles
Create different `build.sh` variants with different configurations for various deployment scenarios.
## Security Considerations
### Before Deployment
1. ✅ Generate unique WireGuard keys per deployment
2. ✅ Change default password
3. ✅ Verify Secure Boot configuration
4. ✅ Test WireGuard connection
5. ✅ Verify firewall rules
6. ✅ Configure PAW connection in Remmina
### During Operation
1. ✅ Monitor WireGuard connection
2. ✅ Review audit logs regularly
3. ✅ Keep system updated (manual, controlled updates)
4. ✅ Physical security of device
### Incident Response
If compromise suspected:
1. Isolate system physically
2. Preserve logs and memory dump
3. Contact security team
4. Destroy/rebuild system from scratch
## Compliance
This system is designed to support:
- NIST SP 800-171 controls
- CIS Benchmarks for Debian
- Zero Trust network architecture principles
- Privileged Access Management (PAM) best practices
## License
See LICENSE file.
## Support
For issues or questions:
- Contact: Infrastructure Security Team
- Location: KNEL server room
---
**WARNING**: This is a security-focused build system. Unauthorized modifications or deployments may compromise infrastructure security.