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

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

Browse Source 
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>
This commit is contained in:
Charles N Wyble - admin
2026-01-29 10:52:58 -05:00
parent ec1bc3eabb
commit e8a9ff8061
1 changed files with 479 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

568
AGENTS.md
View File

@@ -1,116 +1,506 @@
# KNEL-Football Secure OS - Agent Behavior Guidelines
## ⚡ CURRENT STATUS (2026-01-24 19:00 CST)
## 🚀 QUICK START FOR LLM AGENTS
### Build Running in Background
- **Status**: Active build (3rd attempt, minimal configuration)
- **Current Stage**: lb binary_chroot (creating binary filesystem for ISO)
- **Started**: 2026-01-24 18:04 CST
- **Expected Completion**: 19:00-19:15 CST (~15 min remaining)
- **Build Log**: `/tmp/knel-iso-build.log`
- **Output Directory**: `output/` (ISO will appear here when complete)
**You are an AI agent (Crush) working on this project. Start here.**
### First Actions When Starting
1. **Check if ISO is ready**: `ls -lh output/`
2. **If ISO ready**: Verify with `sha256sum -c output/*.sha256`
3. **If ISO not ready**: Monitor build with `tail -f /tmp/knel-iso-build.log`
### 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
### ⚠️ READ THIS FIRST: RESUME.md
**Current Status and Resumption Guide**: See `RESUME.md` for complete details on:
- Build status and current stage
- Working configuration (Attempt 7, minimal flags)
- Issues encountered and solutions (7 build attempts)
- Commands to monitor or restart build
- Expected output files
- Next steps after build completes
**RESUME.md is your STARTING POINT** when returning to this project.
### Quick Reference
```bash
# Check ISO status
cd /home/tsys/Projects/KNEL/football
ls -lh output/
# Monitor build if needed
tail -f /tmp/knel-iso-build.log
# Read full resumption guide
cat RESUME.md
```
### 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
---
## MANDATORY SECURITY REQUIREMENTS
## 📋 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
- **ALL systems MUST use full disk encryption with LUKS2**
**Requirement**: ALL systems MUST use full disk encryption with LUKS2
**Technical Specifications**:
- **Cipher**: AES-256-XTS (512-bit key)
- **Format**: LUKS2 with Argon2id KDF
- **Boot**: Passphrase required at every system boot
- **Security**: No backdoors, no recovery without passphrase
- **Compliance**: NIST SP 800-111, NIST SP 800-53 SC-13
- **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
- **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**:
- No common words (password, secret, admin, root, etc.)
- No sequential characters (123, abc, qwerty)
- No repeated characters (max 2 consecutive)
- At least 4 characters different from previous password
- **Enforcement**: PAM pwquality module, enforced for ALL users
- **Compliance**: NIST SP 800-63B, CIS Benchmarks
**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
---
## CRITICAL REQUIREMENTS
## 📁 PROJECT STRUCTURE
### DOCKER CONTAINER USAGE
- ALL operations MUST be performed inside Docker containers
- ONLY use Docker volumes for file operations
- NEVER create directories in user home directory (/home)
- NEVER modify host system files directly
- ONLY final artifacts may be copied to host system
### WORKSPACE MANAGEMENT
- Use /workspace (Docker volume) for all build operations
- Use /tmp for temporary files
- Use /build for intermediate build files
- ONLY final ISO and checksum files may be copied out of container
### PROHIBITED ACTIONS
- ❌ Creating directories in /home
- ❌ Modifying host system files
- ❌ Installing packages on host system
- ❌ Writing files outside Docker volumes
- ❌ Modifying user home directory structure
### REQUIRED WORKFLOW
1. Start Docker container with volumes
2. Perform ALL work inside container
3. Use only mounted volumes for file I/O
4. Copy ONLY final artifacts to host system
5. Clean up container after completion
### DOCKER VOLUME STRUCTURE
### Root Level Files
```
/workspace/ # All build operations
/build/ # Intermediate files
/tmp/ # Temporary files
/output/ # Final artifacts only
/
├── 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
```
### EXCEPTIONS
Only these files may be copied to host system:
- *.iso (final ISO files)
- *.sha256 (checksum files)
- *.md5 (checksum files)
- BUILD-REPORT.txt (build documentation)
### 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
```
## VIOLATIONS
Any violation of these requirements is CRITICAL and must be immediately corrected.
### 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.