Scope per-tool permissions to least privilege
An agent inherits whatever the process allows, so a write bug becomes a write-anywhere bug. Grant permissions per tool, scoped to the exact resource, and keep the default deny.
Procedure
- Enumerate the run's tools and, for each, the single resource it needs:
db_read -> customers (SELECT),file_write -> out/report.csv. - Write the grant list explicitly; anything absent is denied. Default-deny, allow by exception.
- Scope filesystem access to a subtree and a mode:
out/:rw,src/:ro. Never grant/or$HOME. - Scope database access to schema verbs:
SELECTfor readers,INSERTon one table for writers — neverALLorGRANT. - Scope network egress to named hosts when the tool only needs a few:
api.internal:443, not0.0.0.0/0. - Give each tool its own credential with the least role, not a shared admin token that every tool can borrow.
- Re-derive the grant list per run from the brief; do not copy last run's permissions wholesale.
- Audit weekly: list grants actually exercised from the action log and remove the ones never used.
- Treat a permission error as a design signal, not an obstacle to widen away — decide whether the step should exist.
Pitfalls
- Granting
sudoor a root token "so the agent is not blocked", which removes every other control at once. - Sharing one credential across tools, so an audit cannot tell which tool did what.
- Scoping to a directory but forgetting mode, giving read-only tasks the ability to delete.
- Copying a previous run's broader grants because re-deriving them is tedious.
- Leaving a grant in place after the tool is retired, accumulating latent access.
- Widening a scope to fix one denied call instead of fixing the call's resource target.
Verification
python3 tools/audit_grants.py runs/grants.json notes/action.log
# fails on any exercised path outside the declared scope, and lists unused grants for removal
Report each tool, its declared scope, and any access the run attempted outside it.