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.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.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
- Merged test-iso.sh and monitor-build.sh into run.sh

---

## 🔒 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

### Host System FDE - MANDATORY
**Requirement**: The host system used to build or test the ISO MUST have FDE enabled

**Why This Matters**:
- Building a secure OS on an unencrypted host creates supply chain risk
- An unencrypted test host exposes the secure OS to attacks
- Defense in depth requires protection at every layer

**Enforcement**:
- `./run.sh iso` will FAIL if host FDE not detected
- `./run.sh test:iso` commands will FAIL if host FDE not detected
- This check CANNOT be bypassed

**Detection Methods**:
- Checks for LUKS devices via `lsblk`
- Checks `/etc/crypttab` for encrypted partitions
- Checks if root filesystem is on dm-crypt device
- Checks `/sys/block/dm-*` for LUKS devices

**Implementation**:
- `run.sh` - `check_host_fde()` function

**Compliance**: Supply chain security best practice

---

## 📁 PROJECT STRUCTURE

### Root Level Files
```
/
├── run.sh                 # MAIN ENTRY POINT - All operations (build/test/lint/iso/monitor/VM)
├── Dockerfile             # Multi-stage build environment
├── README.md              # Project documentation
├── AGENTS.md              # THIS FILE - Agent guidelines
├── STATUS.md              # Manager status report (quick-glance)
├── JOURNAL.md             # AI memory - ADRs, insights, lessons (append-only)
└── .gitignore             # Git ignore patterns
```

### Documentation Files
```
├── STATUS.md              # Manager report - current status, blockers, next actions
├── JOURNAL.md             # AI memory - ADRs, patterns, lessons learned
├── AGENTS.md              # Agent guidelines (START HERE)
└── docs/                  # Detailed documentation
    ├── PRD.md             # Product Requirements Document
    ├── SDLC.md            # Software Development Lifecycle (READ THIS)
    ├── TEST-COVERAGE.md   # Test suite coverage
    ├── VERIFICATION-REPORT.md  # Compliance verification
    ├── COMPLIANCE.md      # Compliance standards
    └── security-model.md  # Security architecture
```

**STATUS.md Purpose**:
- Quick-glance project status for managers
- What's working, what's broken, current blockers
- Next actions and metrics
- Maintained by AI agent, read by humans

**JOURNAL.md Purpose**:
- Long-term memory for AI agents
- Architectural Decision Records (ADRs)
- Patterns observed, lessons learned
- APPEND-ONLY - never modify existing entries

### 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
├── system/               # System/runtime tests (VM boot, FDE, Secure Boot)
│   ├── boot_test.bats
│   ├── secureboot_test.bats
│   └── fde_test.bats
├── test_helper/          # Test utilities
│   └── common.bash
└── simple_test.bats      # Basic bats test
```

### Output
```
output/
└── knel-football-secure.iso  # 450 MB ISO (✅ BUILT AND VERIFIED)
└── knel-football-secure.iso.sha256  # SHA256 checksum
└── knel-football-secure.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 docs/PRD.md for detailed requirements
- Read docs/SDLC.md for development workflow (CRITICAL)
- 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.iso.sha256
md5sum -c knel-football-secure.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

#### 🔴 CRITICAL: AUTO-COMMIT RULE
**After completing ANY work, you MUST:**
1. Check `git status` for uncommitted changes
2. Stage all relevant changes with `git add`
3. Commit with conventional message
4. Push to remote with `git push origin main`
5. NEVER wait for user to ask "is everything committed?"

**This is NOT optional.** The user should NEVER have to ask about commits.

#### ✅ DO
- **AUTO-COMMIT AND PUSH** after completing work (see CRITICAL rule above)
- Read files before editing them
- Use exact text matching (whitespace matters)
- Test after every change
- Run full test suite before committing
- **Double-check `git status` before ANY commit** - verify staged files match intent
- **Delete unused/obsolete files** when refactors or feature removals make them irrelevant
- **Quote git paths with brackets/parentheses** (e.g., `git add "src/app/[candidate]/**"`) to prevent shell glob/subshell expansion
- **Use non-interactive git rebase** - set `GIT_EDITOR=: GIT_SEQUENCE_EDITOR=:` or pass `--no-edit` to avoid opening editors
- **NEVER run destructive git operations** (`git reset --hard`, `rm`, `git checkout`/`git restore` to older commits) unless user gives explicit written instruction - treat as catastrophic
- **NEVER amend commits** (`git commit --amend`) without explicit written approval from user
- Update documentation when changing behavior
- Follow existing code style
- Use conventional commit messages
- Commit frequently with atomic changes
- Run lint checks

#### ❌ DO NOT
- **Wait for user to ask about commits** - AUTO-COMMIT ALWAYS
- 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

### Test Suite Overview (100% Coverage Targeted)
- ✅ **Unit Tests** - Comprehensive tests for all shell scripts
  - `tests/unit/run_test.bats` - Main run.sh entry point
  - `tests/unit/run_comprehensive_test.bats` - Comprehensive run.sh coverage
  - `tests/unit/security-hardening_test.bats` - Security hardening functions
  - `tests/unit/firewall-setup_test.bats` - Firewall configuration
  - `tests/unit/build-iso_comprehensive_test.bats` - ISO build orchestration
  - `tests/unit/encryption-setup_test.bats` - LUKS2 encryption setup
  - `tests/unit/encryption-validation_test.bats` - Encryption validation

- ✅ **Integration Tests** - End-to-end workflows
  - `tests/integration/config_test.bats` - Configuration validation
  - `tests/integration/e2e_test.bats` - Complete workflow testing

- ✅ **Security Tests** - Compliance and security requirements
  - `tests/security/compliance_test.bats` - Security compliance validation
  - `tests/security/compliance_comprehensive_test.bats` - Full FR-001/FR-007 coverage
  - `tests/security/encryption_comprehensive_test.bats` - Encryption configuration validation

### Test Commands
```bash
./run.sh test              # Run all tests (unit + integration + security)
./run.sh test:unit         # Unit tests only
./run.sh test:integration  # Integration tests only
./run.sh test:security     # Security/compliance tests only
./run.sh lint              # Run shellcheck on all shell scripts
```

### Test Suite Status
- ✅ **All tests passing**: 31/31 tests
- ✅ **Unit tests**: Working (12 tests)
- ✅ **Integration tests**: Working (6 tests)
- ✅ **Security tests**: Working (13 tests)
- ✅ **Test execution**: `./run.sh test`

### Test Orchestration
- **run.sh** - Main entry point for test execution
- **BATS** - Test framework (v1.11.1)
- **Direct execution** - Tests run directly via bats (no wrapper)
  - Supports: unit, integration, security, e2e, compliance, encryption, all
  - Provides colored output and pass/fail statistics
  - Orchestrates BATS test execution

### Coverage Goals
- ✅ All shell scripts have unit tests
- ✅ All configuration files are validated
- ✅ All security hooks are tested
- ✅ All mandatory requirements have compliance tests
- ✅ End-to-end workflows are tested

### Running Tests After Changes
```bash
# After any changes, run:
./run.sh lint              # Check syntax first
./run.sh test              # Run full test suite
./run.sh test:security     # Verify security requirements

# If any test fails, fix it before committing
```

---

## 📚 DOCUMENTATION FILES

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

### Detailed Documentation (docs/)
- **docs/SDLC.md** - Software Development Lifecycle
- **docs/TEST-COVERAGE.md** - Test suite coverage and details
- **docs/VERIFICATION-REPORT.md** - Verification and compliance report
- **docs/COMPLIANCE.md** - Compliance standards and requirements
- **docs/security-model.md** - Security architecture and design

---

## 🔑 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 (all inbound denied, outbound VPN only)
4. **WiFi/Bluetooth** - Blacklisted (permanently disabled)
5. **SSH** - Client-only (no server, outbound connections only)
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

---

## 🔄 SDLC WORKFLOW (Software Development Lifecycle)

### Before Making Changes
1. **Read relevant documentation**:
   - AGENTS.md (this file) - For agent guidelines
   - docs/PRD.md - For requirements
   - docs/SDLC.md - For development workflow
   - README.md - For quick commands
   - docs/TEST-COVERAGE.md - For test details
   - docs/VERIFICATION-REPORT.md - For verification results

2. **Create feature branch** (optional but recommended):
   ```bash
   git checkout -b feature/your-feature-name
   ```

### Making Changes
1. **Read files before editing** (Critical!)
2. **Use exact text matching** (whitespace matters)
3. **Make small, atomic changes**
4. **Follow existing code style**

### Testing Changes (MANDATORY)
**Before committing, ALWAYS run:**

```bash
# 1. Lint checks (syntax validation)
./run.sh lint

# 2. Run unit tests
./run.sh test:unit

# 3. Run integration tests
./run.sh test:integration

# 4. Run security/compliance tests
./run.sh test:security

# 5. Run full test suite
./run.sh test
```

**Test Suite Must Pass Before Committing**

### Committing Changes
1. **Review changes**:
   ```bash
   git status
   git diff
   ```

2. **Stage files**:
   ```bash
   git add <files>
   ```

3. **Commit with conventional message**:
   ```bash
   git commit -m "type: subject

   body (optional)

   💘 Generated with Crush


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


   "
   ```

   **Types**:
   - `feat`: New feature
   - `fix`: Bug fix
   - `docs`: Documentation changes
   - `test`: Test changes
   - `refactor`: Code refactoring
   - `chore`: Maintenance tasks

### After Committing
1. **Push to remote**:
   ```bash
   git push origin main
   # Or push feature branch:
   git push origin feature/your-feature-name
   ```

2. **Merge feature branch** (if using branches):
   ```bash
   git checkout main
   git merge feature/your-feature-name
   git push origin main
   ```

### SDLC Checklist
Before marking work complete:
- [ ] All tests pass (`./run.sh test`)
- [ ] Lint checks pass (`./run.sh lint`)
- [ ] Security requirements verified (`./run.sh test:security`)
- [ ] Documentation updated (if needed)
- [ ] Conventional commit message used
- [ ] Changes committed and pushed to remote

---

## 📞 GETTING HELP

### Check These First
1. **AGENTS.md** - This file
2. **README.md** - Quick commands
3. **docs/PRD.md** - Requirements
4. **docs/SDLC.md** - Development workflow
5. **docs/TEST-COVERAGE.md** - Test details
6. **docs/VERIFICATION-REPORT.md** - Verification results
7. **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-02-17
- **Status**: Build in progress, ISO being rebuilt with latest changes
- **Test Coverage**: ✅ WORKING (111 tests: 92 pass, 19 skip for libvirt)
- **Test Files**: 19 test files (1 simple, 10 unit, 2 integration, 3 security, 3 system)
- **Documentation**: Consolidated in docs/ directory
- **Root Directory**: Cleaned (AGENTS.md, README.md, PRD.md, Dockerfile, run.sh)
- **Scripts Consolidated**: test-iso.sh and monitor-build.sh merged into run.sh
- **SDLC Workflow**: Documented and enforced

### Test Suite Status
- ✅ All tests passing (111 total: 92 pass, 19 skip)
- ✅ Unit tests: Working (10 files, ~13 tests)
- ✅ Integration tests: Working (2 files, 6 tests)
- ✅ Security tests: Working (3 files, 44 tests)
- ✅ System tests: Working (3 files, 47 tests)
- ✅ Test execution: `./run.sh test`

---

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