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

---

📁 PROJECT STRUCTURE

Root Level Files

/
├── run.sh                 # MAIN ENTRY POINT - All operations (build/test/lint/iso/monitor/VM)
├── Dockerfile             # Multi-stage build environment
├── PRD.md                 # Product Requirements Document
├── 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
├── PRD.md                 # Product requirements
├── AGENTS.md              # Agent guidelines (START HERE)
├── SDLC.md                # Software Development Lifecycle (READ THIS)
└── docs/                  # Detailed documentation
    ├── 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)

# 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
• Read 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

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

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

# 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

# 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

# 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

./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

# 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
• PRD.md - Product Requirements Document (detailed)

Detailed Documentation (docs/)

• 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 (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

---

🔄 SDLC WORKFLOW (Software Development Lifecycle)

Before Making Changes

1. Read relevant documentation:

   • AGENTS.md (this file) - For agent guidelines
   • PRD.md - For requirements
   • 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):

   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:

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

   git status
   git diff
   

2. Stage files:

   git add <files>
   

3. Commit with conventional message:

   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:

   git push origin main
   # Or push feature branch:
   git push origin feature/your-feature-name
   

2. Merge feature branch (if using branches):

   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. PRD.md - Requirements
4. docs/TEST-COVERAGE.md - Test details
5. docs/VERIFICATION-REPORT.md - Verification results
6. JOURNAL.md - Session history

Debug Mode

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