Files

ReachableCEO e8a9ff8061 docs: completely rewrite AGENTS.md with comprehensive LLM agent guide

Rewrite AGENTS.md as comprehensive guide for LLM agents to be immediately productive. Add current status, mandatory security requirements, project structure, agent workflow, critical requirements, Docker-only workflow, testing coverage, key concepts, error handling, and success criteria. Provide clear quick start instructions and checklists.

💘 Generated with Crush

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

2026-01-29 10:52:58 -05:00

15 KiB

Raw Blame History

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

Read this entire AGENTS.md file (you're reading it now)
Check project status: ls -lh output/
Review current state: See STATUS section below
Understand requirements: See MANDATORY SECURITY REQUIREMENTS
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)

# 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

# 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-v1.0.0.iso.sha256
md5sum -c knel-football-secure-v1.0.0.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

✅ 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

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

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

Encryption Setup

Preseed: Configure crypto partitioning
Live Hook: Apply encryption during live session
Install Hook: Configure LUKS2 after installation
Validation Hook: Verify encryption post-install

Security Layers

Full Disk Encryption - LUKS2 (mandatory)
Password Complexity - PAM pwquality (mandatory)
Firewall - nftables (inbound SSH, outbound VPN only)
WiFi/Bluetooth - Blacklisted (permanently disabled)
SSH - WireGuard key authentication
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

AGENTS.md - This file
README.md - Quick commands
PRD.md - Requirements
RESUME.md - Build history
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-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.

15 KiB Raw Blame History