least-privilege tool grants for agents

least-privilege tool grants for agents

TL;DR

Give each agent the smallest tool set that completes its task, for the shortest time it needs it, and nothing else. Write the grants down as a matrix, default to deny, expire them automatically, and re-certify on a schedule. Permission creep in agents looks exactly like permission creep in humans, except the agent never complains about missing access until it silently works around it.

least-privilege tool grants for agents

Use this when

• You are granting an agent access to tools, APIs, or data
• A new capability is being added to an existing agent
• An audit asks who (or what) can do which actions
• An agent's task changes and its old grants no longer fit
• You are designing the permission model for an agent platform

Not for this skill when

• The question is about human user roles and RBAC
• You are configuring OS or container-level isolation (see sandboxing skill)
• The agent calls no tools at all
• You need a formal access certification for compliance auditors

Steps

1. Write the grant matrix before granting anything

For each agent and task, list the exact tools, the actions allowed on each, and the data scope. "Read access to the tickets API for queue Q" beats "API access".

cat [HOME]/...

Expected: the file exists, names agents, tools, actions, and scopes, and has an owner and review date. Grants that live only in someone's head do not exist.

2. Default deny, then add narrowly

Start from zero permissions and add only what the task demonstrably needs. "It might need write later" is not a grant; it is a future request to file later.

Expected: a new agent deployment starts with no tools and gains them one reviewed grant at a time. The review trail shows each addition with its justification.

3. Separate read, write, and destructive actions

Read, create, update, and delete are different grants. An agent that summarizes tickets needs read; the one that closes them needs the close action explicitly, scoped to the right queue.

Expected: the matrix distinguishes action classes per tool, and a read-only agent demonstrably cannot perform writes in testing.

4. Time-box grants to the task lifetime

Permissions should expire when the task ends: per-run grants for one-shot jobs, short leases for ongoing work. Permanent grants are the ones nobody remembers approving.

Expected: grants carry expiry, and an expired grant fails closed in testing. The renewal process is lightweight enough that people use it instead of asking for permanent.

5. Re-certify on a schedule

Review the matrix quarterly or on every incident: does each agent still need each grant, is the scope still right, did the task change. Remove what is unused without ceremony.

grep -c "grant" [HOME]/...

Expected: the count trends down or stays flat over time, never silently up. Each review is logged with what changed and why.

6. Test the boundaries, not just the happy path

For each agent, attempt the adjacent forbidden action in a dry run: the read-only agent tries a write, the scoped agent tries outside its scope. The denials are the proof the matrix is real.

Expected: boundary tests exist and pass, and they run in CI so a config change cannot silently widen access.

Variant: agents with tiered capabilities

Some agents need broad read plus narrow write. Model that as two grant sets with different expiry and approval paths rather than one mushy "power user" grant that nobody understands.

Variant: break-glass access

For incidents, allow temporary elevation with a ticket reference, a short TTL, full logging, and automatic revocation. Break-glass that nobody can find during the incident will be bypassed; break-glass without logging will be abused.

Variant: third-party agent platforms

When the platform controls the tool surface, your grants are the platform's permission settings plus your own policy layer. Audit both, because the platform default is usually broader than you think.

Why this happens

Granting feels productive and restricting feels like friction, so every agent accumulates permissions "just in case" until its access resembles an admin's. Unlike humans, agents do not get phished for credentials they do not have, which means every unnecessary grant is pure risk with no upside. Least privilege is the only control that shrinks the blast radius before anything goes wrong.

Edge cases and pitfalls

• Agents that hit denials sometimes reframe the request to dodge the policy ("summarize" becomes "summarize and file"); monitor for grant-shaped workarounds.
• Scope creep via broad reads: a read grant on "tickets" quietly becomes PII access when tickets contain PII; scope to fields, not just endpoints, where it matters.
• Shared service accounts blur which agent did what; prefer per-agent identities so the audit trail names names.
• Emergency grants issued verbally never get revoked; require them in the matrix within 24 hours or they auto-expire.
• Overly tight grants push users to shadow agents with no controls at all; keep the request process fast.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_ZBi2tlTAjtzaYepsaneIEg