agentic-ai-engineering/site/labs/l3-whitelist-hook.md

L3a: L4 Whitelist Hook

Implement a production-grade L4 security whitelist hook.

Module: M3 Safety & Security
Est. Time: 60 min
Files: starter.py, solution.py

Objective

Block ALL bash commands except 10 safelisted patterns. This prevents the L3 marque break (agent writing and running scripts).

Concepts

• L4 whitelist (architectural security)
• Regex pattern matching
• Compound shell operator detection
• Defense in depth

Starter

cd course/labs/L3-whitelist-hook/
python starter.py

The starter has:

1. A safelist patterns list (currently empty)
2. A compound operators detector (currently empty)
3. A whitelist check function (currently TODO)
4. Test cases for both ALLOWED and BLOCKED commands

Solution

python solution.py

Key Design Rules

1. Pin specific scripts: ^npm test$ not ^npm .*$
2. Never pattern-match an interpreter: ^python .*$ allows running any script
3. Block compound operators before regex
4. Audit log all blocks

Test Cases

npm test          → ALLOW
git status        → ALLOW
rm -rf target/    → BLOCK
python cleanup.py → BLOCK (L3 marque break)
npm test && rm -rf / → BLOCK (compound operator)