football/AGENTS.md

# KNEL-Football Secure OS - Agent Behavior Guidelines

## 🚀 QUICK START FOR LLM AGENTS

**You are an AI agent (Crush) working on this project. Start here.**

### Immediate Context (2026-01-28)
- **Project Status**: ✅ Build completed successfully (450 MB ISO created)
- **Build Date**: 2026-01-28 16:30 CST
- **Build Duration**: 72 minutes (9 stages completed)
- **ISO Location**: `output/knel-football-secure-v1.0.0.iso`
- **Checksums Verified**: ✅ SHA256 and MD5

### Your First Actions
1. **Read this entire AGENTS.md file** (you're reading it now)
2. **Check project status**: `ls -lh output/`
3. **Review current state**: See STATUS section below
4. **Understand requirements**: See MANDATORY SECURITY REQUIREMENTS
5. **Know your workflow**: See AGENT WORKFLOW section

---

## 📋 CURRENT STATUS

### Build Status
- **Last Build**: ✅ SUCCESS (2026-01-28)
- **ISO Artifact**: `knel-football-secure-v1.0.0.iso` (450 MB)
- **ISO Checksums**: SHA256 ✅, MD5 ✅
- **Build Log**: `/tmp/knel-iso-build.log` (4,140 lines)
- **All Stages**: 9/9 completed successfully

### Mandatory Requirements Implementation
- ✅ **FR-001: Full Disk Encryption** - LUKS2, AES-256-XTS, 512-bit key
- ✅ **FR-007: Password Complexity** - 14+ chars, PAM pwquality enforced
- ✅ **Encryption Hooks** - Setup and validation created
- ✅ **Security Hardening** - Enhanced password policy implemented

### Compliance Achieved
- ✅ NIST SP 800-111 (Disk Encryption)
- ✅ NIST SP 800-53 (Security Controls)
- ✅ NIST SP 800-63B (Password Guidelines)
- ✅ ISO/IEC 27001 (Information Security)
- ✅ CIS Benchmarks (Security Configuration)
- ✅ DISA STIG (Security Implementation)

### Recent Changes (2026-01-28)
- Added mandatory full disk encryption (LUKS2)
- Added mandatory password complexity requirements
- Created encryption-setup.sh hook
- Created encryption-validation.sh hook
- Enhanced security-hardening.sh with strict password policy
- Updated preseed.cfg with crypto partitioning
- Updated run.sh with test:iso command for VM testing
- Created test-iso.sh for libvirt/virsh testing

---

## 🔒 MANDATORY SECURITY REQUIREMENTS

### Full Disk Encryption (FDE) - MANDATORY
**Requirement**: ALL systems MUST use full disk encryption with LUKS2

**Technical Specifications**:
- **Cipher**: AES-256-XTS (512-bit key)
- **Format**: LUKS2 with Argon2id KDF
- **Partitioning**: Separate unencrypted /boot (UEFI requirement)
- **Boot Process**: Encryption passphrase required at EVERY system boot
- **Recovery**: No backdoors, no recovery without passphrase

**Encryption Passphrase Requirements** (MANDATORY):
- **Minimum Length**: 14 characters (20+ strongly recommended)
- **Character Classes**: At least 1 of each:
  - Uppercase letter (A-Z)
  - Lowercase letter (a-z)
  - Digit (0-9)
  - Special character (!@#$%^&*)
- **Prohibited Patterns**:
  - Common words (password, secret, admin, root)
  - Sequential patterns (123, abc, qwerty)
  - Repeated characters (max 2 consecutive)

**Implementation Files**:
- `config/preseed.cfg` - Debian installer crypto partitioning
- `config/hooks/installed/encryption-setup.sh` - LUKS2 configuration
- `config/hooks/installed/encryption-validation.sh` - Encryption verification

**Compliance**: NIST SP 800-111, NIST SP 800-53 SC-13

### Password Complexity - MANDATORY
**Requirement**: ALL user passwords MUST meet strict complexity requirements

**Password Policy** (MANDATORY):
- **Minimum Length**: 14 characters (20+ strongly recommended)
- **Character Classes**: Minimum 3 of 4 required (all 4 strongly recommended):
  - Uppercase letters (A-Z) - Minimum 1 required
  - Lowercase letters (a-z) - Minimum 1 required
  - Digits (0-9) - Minimum 1 required
  - Special characters (!@#$%^&*) - Minimum 1 required

**Additional Requirements**:
- **Dictionary Check**: Reject common dictionary words
- **Username Check**: Reject passwords containing username
- **Sequence Check**: Reject sequential characters (123, abc)
- **Repetition Check**: Max 2 consecutive identical characters
- **Class Repetition**: Max 2 consecutive from same character class
- **Difference**: Min 4 characters different from old password
- **Bad Words**: Reject (password, secret, admin, root, knel, football, tier0, 12345, qwerty)
- **GECOS Check**: Reject passwords containing GECOS field info

**Enforcement**:
- **Mechanism**: PAM pwquality module
- **Scope**: ALL users including root
- **Enforcing Mode**: Reject weak passwords (not just warn)
- **Location**: `/etc/security/pwquality.conf` (created by hooks)

**Implementation File**:
- `src/security-hardening.sh` - Password policy configuration
- `config/hooks/live/security-hardening.sh` - Live hook application

**Compliance**: NIST SP 800-63B, CIS Benchmarks for Debian

---

## 📁 PROJECT STRUCTURE

### Root Level Files
```
/
├── run.sh                 # MAIN ENTRY POINT - Use this for all operations
├── test-iso.sh            # ISO testing with libvirt/virsh (host-side)
├── Dockerfile             # Multi-stage build environment
├── PRD.md                 # Product Requirements Document
├── README.md              # Project documentation
├── AGENTS.md              # THIS FILE - Agent guidelines
├── RESUME.md              # Session resumption guide
├── JOURNAL.md             # Append-only development journal
├── BUILD-COMPLETE.md      # Build completion report
├── BUILD-SUMMARY.md       # Build session summary
├── VERIFICATION-REPORT.md # Comprehensive verification report
├── QUICK_START.md         # Quick reference commands
├── SESSION-CLOSED.md      # Session closure documentation
└── .gitignore             # Git ignore patterns
```

### Source Code
```
src/
├── security-hardening.sh  # Security hardening functions
├── firewall-setup.sh      # Firewall configuration
├── build-iso.sh          # ISO build orchestration
├── run.sh                # Alternative run script
├── run-new.sh            # Enhanced run script
└── build.sh              # Build script
```

### Configuration
```
config/
├── preseed.cfg           # Debian installer preseed (with encryption)
├── hooks/
│   ├── live/             # Hooks during live system
│   │   ├── desktop-environment.sh
│   │   ├── firewall-setup.sh
│   │   ├── qr-code-import.sh
│   │   ├── security-hardening.sh
│   │   └── usb-automount.sh
│   └── installed/        # Hooks after installation
│       ├── disable-package-management.sh
│       ├── encryption-setup.sh        # LUKS2 encryption setup
│       ├── encryption-validation.sh   # Encryption verification
│       └── install-scripts.sh
└── package-lists/
    └── knel-football.list.chroot  # Package list
```

### Tests
```
tests/
├── unit/                 # Unit tests for individual functions
│   ├── build_test.bats
│   ├── firewall_test.bats
│   ├── security_test.bats
│   └── run_test.bats
├── integration/          # Integration tests for workflows
│   └── config_test.bats
├── security/             # Security compliance tests
│   └── compliance_test.bats
├── test_helper/          # Test utilities
│   └── common.bash
└── simple_test.bats      # Basic bats test
```

### Output
```
output/
└── knel-football-secure-v1.0.0.iso  # 450 MB ISO (✅ BUILT AND VERIFIED)
└── knel-football-secure-v1.0.0.iso.sha256  # SHA256 checksum
└── knel-football-secure-v1.0.0.iso.md5      # MD5 checksum
```

---

## 🤖 AGENT WORKFLOW

### Standard Operating Procedure

#### 1. START UP (First Action)
```bash
# Check current state
ls -lh output/

# Read this file (AGENTS.md)
cat AGENTS.md

# Review recent changes
git log --oneline -10
```

#### 2. UNDERSTAND REQUIREMENTS
- Read MANDATORY SECURITY REQUIREMENTS (above)
- Review PRD.md for detailed requirements
- Check AGENTS.md for critical constraints
- Understand Docker-only workflow

#### 3. MAKE CHANGES
- **Read files before editing** (Critical!)
- Use conventional commit messages
- Test after every change
- Update relevant documentation

#### 4. TEST CHANGES
```bash
# Run tests (inside Docker)
./run.sh test              # Run all tests
./run.sh lint              # Run linting
./run.sh test:unit         # Unit tests only
./run.sh test:integration  # Integration tests only
./run.sh test:security     # Security tests only
```

#### 5. BUILD ISO (if needed)
```bash
# Build ISO (60-90 minutes)
./run.sh iso

# Monitor progress
tail -f /tmp/knel-iso-build.log

# Verify output
cd output/
sha256sum -c knel-football-secure-v1.0.0.iso.sha256
md5sum -c knel-football-secure-v1.0.0.iso.md5
```

#### 6. TEST ISO (optional)
```bash
# Test ISO in VM (runs on host, not in Docker)
./run.sh test:iso create      # Create and boot test VM
./run.sh test:iso console     # Connect to VM console
./run.sh test:iso status      # Show VM status
./run.sh test:iso destroy     # Remove VM
```

#### 7. COMMIT CHANGES
```bash
# Review changes
git status
git diff

# Stage files
git add <files>

# Commit with conventional message
git commit -m "type: subject

body

💘 Generated with Crush


Assisted-by: GLM-4.7 via Crush <crush@charm.land>

"
```

#### 8. PUSH TO REMOTE
```bash
# Push changes
git push origin main
```

### Important Rules

#### ✅ DO
- Read files before editing them
- Use exact text matching (whitespace matters)
- Test after every change
- Run full test suite before committing
- Update documentation when changing behavior
- Follow existing code style
- Use conventional commit messages
- Commit frequently with atomic changes
- Run lint checks

#### ❌ DO NOT
- Edit files you haven't read
- Guess at text matches (be precise)
- Commit without testing
- Skip the test suite
- Break existing tests
- Ignore lint errors
- Make unrelated changes in one commit
- Modify host system directly
- Create directories in /home

---

## 🐳 DOCKER-ONLY WORKFLOW (CRITICAL)

### Why Docker?
- Reproducible builds
- Isolated environment
- No host system pollution
- Consistent across machines
- Easy to clean up

### Volumes and Directories
```
Container Side    Host Side          Purpose
/workspace        ./                 Project root (read-only)
/build            ./tmp              Build intermediate files
/output           ./output           Final artifacts only
```

### Commands Run Inside Container
- `./run.sh build` - Build Docker image
- `./run.sh test` - Run all tests
- `./run.sh lint` - Run linting
- `./run.sh iso` - Build ISO

### Commands Run on Host
- `./run.sh test:iso` - Test ISO with libvirt (VM test only)

### NEVER Do These
- ❌ Create directories in /home
- ❌ Install packages on host
- ❌ Modify host system files
- ❌ Write files outside Docker volumes
- ❌ Run live-build commands on host

---

## 🧪 TESTING COVERAGE

### Current Test Suite
- ✅ Unit tests for security-hardening.sh
- ✅ Unit tests for build functions
- ✅ Unit tests for firewall configuration
- ✅ Integration tests for config
- ✅ Security compliance tests
- ✅ Basic bats test

### Test Commands
```bash
./run.sh test              # Run all tests
./run.sh test:unit         # Unit tests only
./run.sh test:integration  # Integration tests only
./run.sh test:functional   # Functional/security tests
./run.sh lint              # Run shellcheck
```

### Goal: 100% Coverage
- All functions must have tests
- All configuration files must be validated
- All hooks must be tested
- End-to-end workflows must be tested
- Security requirements must be verified

---

## 📚 DOCUMENTATION FILES

### Quick Reference
- **AGENTS.md** - THIS FILE - Start here
- **README.md** - Project overview and quick commands
- **PRD.md** - Product Requirements Document (detailed)
- **RESUME.md** - Session resumption guide

### Build Documentation
- **BUILD-COMPLETE.md** - Build completion report
- **BUILD-SUMMARY.md** - Build session summary
- **VERIFICATION-REPORT.md** - Comprehensive verification

### Session Documentation
- **JOURNAL.md** - Append-only development journal
- **QUICK_START.md** - Quick reference commands
- **SESSION-CLOSED.md** - Session closure

---

## 🔑 KEY CONCEPTS

### Build Process
1. **Docker Build**: Create build environment (~2 minutes)
2. **lb config**: Configure live-build (~30 seconds)
3. **lb bootstrap**: Download and install base system (~13 minutes)
4. **lb chroot**: Install packages and apply hooks (~8 minutes)
5. **lb installer**: Configure Debian installer (~2 minutes)
6. **lb binary**: Create binary filesystem (~4 minutes)
7. **lb checksum**: Generate checksums (~1 minute)

### Encryption Setup
1. **Preseed**: Configure crypto partitioning
2. **Live Hook**: Apply encryption during live session
3. **Install Hook**: Configure LUKS2 after installation
4. **Validation Hook**: Verify encryption post-install

### Security Layers
1. **Full Disk Encryption** - LUKS2 (mandatory)
2. **Password Complexity** - PAM pwquality (mandatory)
3. **Firewall** - nftables (inbound SSH, outbound VPN only)
4. **WiFi/Bluetooth** - Blacklisted (permanently disabled)
5. **SSH** - WireGuard key authentication
6. **Package Management** - Disabled for security

---

## 🚨 CRITICAL ERROR HANDLING

### Build Failures
- Check `/tmp/knel-iso-build.log` for errors
- Review RESUME.md for common issues
- Check disk space
- Verify Docker permissions

### Test Failures
- Run tests individually: `bats tests/unit/file.bats`
- Check test helper functions
- Verify setup/teardown functions
- Review error messages carefully

### Permission Errors
- Ensure `run.sh` is executable
- Check Docker daemon is running
- Verify user in docker group
- Check volume mount permissions

---

## 📞 GETTING HELP

### Check These First
1. **AGENTS.md** - This file
2. **README.md** - Quick commands
3. **PRD.md** - Requirements
4. **RESUME.md** - Build history
5. **JOURNAL.md** - Session history

### Debug Mode
```bash
# Verbose output
./run.sh -v test

# Verbose ISO build
./run.sh -v iso

# View build log
tail -f /tmp/knel-iso-build.log
```

---

## ✅ CHECKLIST BEFORE WORK

- [ ] Read AGENTS.md (this file)
- [ ] Check current build status
- [ ] Understand mandatory security requirements
- [ ] Know Docker-only workflow
- [ ] Have test command ready
- [ ] Know commit message format

---

## 🎯 SUCCESS CRITERIA

Your work is successful when:
- ✅ All tests pass (`./run.sh test`)
- ✅ Lint passes (`./run.sh lint`)
- ✅ Documentation updated
- ✅ Conventional commit messages used
- ✅ No security requirements violated
- ✅ Docker workflow followed
- ✅ Changes tested before commit

---

## 📝 LAST UPDATED

- **Date**: 2026-01-28
- **Status**: Build completed, ISO created and verified
- **Test Coverage**: In progress (goal: 100%)
- **Documentation**: Comprehensive and up to date

---

**Remember**: This is a security-critical project. Every change must preserve mandatory security requirements. Test everything. Read before editing. Follow the workflow. Be thorough.