Skip to content

SOP-082 — Access-control & agent tool-grant policy review

Guide

<!-- last-reviewed: 2026-06-01 · owner: Security & Privacy (Security Director) -->

SOP-082 — Access-control & agent tool-grant policy review

SOP · owner: Security & Privacy (Security Director). Layer: SOP/Runbook (docs/canon.md). The periodic + event-driven audit of which agents hold which tools: grants and whether each is still justified by a named responsibility. Policy frame: hr/policies/security.md (least privilege); the agent tool-grant policy (hr/policies/access-control.md, to author).

Interface Contract

  • Inputs: new / changed agent definition or scheduled review ← from <Human Resources / self> · trigger: review requested
  • Inputs: privilege-creep flag (grant with no shell/authoring duty) ← from <Security Analyst> · trigger: review requested
  • Outputs: tool-grant finding (grant change recommendation) → to Principal · trigger: (exempt — Principal edge, interface-contract-spec.md §3.1 R2)
  • Outputs: approved access-control review report → to Archivist · trigger: artifact approved
  • Outputs: tool-grant policy added or changed → to Documentarian · trigger: document changed
  • Handoff trigger (in): an agent definition is added/changed, the review cadence fires, or the Analyst flags a grant
  • Handoff trigger (out): every grant is justified-or-flagged, findings are presented to the Principal, and the dated report is archived
  • Definition of Done before handoff:
    • [ ] Every .claude/agents/* tools: line read against the minimum-privilege test
    • [ ] Each unjustified grant has a written finding (agent · tool · why it fails · remediation)
    • [ ] No other agent’s definition edited unilaterally — findings presented to the Principal
    • [ ] Tool-grant policy updated if the review surfaced a standing-standard gap
    • [ ] Dated review report handed to the Archivist (artifact approved); 0 drift
    • [ ] Learnings captured to docs/knowledge/security/ if any

review requested and artifact approved / document changed are drawn verbatim from docs/handoff-triggers.md. The Principal output edge is exempt (Principal) — the Principal is a non-authoring counterparty (§3.1 R2). The HR review requested in-edge (new agent def) is a proposed trigger if HR’s SOP names it differently — see “Proposed triggers” below; until reconciled it reads pending.

Purpose

Keep tool grants at minimum privilege — every grant justified by a named responsibility — so a compromised or confused agent has the smallest possible blast radius, and privilege creep is caught at review rather than after abuse.

When to use

A new or changed agent definition (tools: line); the periodic review cadence; a privilege-creep flag from the Security Analyst.

Flow

flowchart LR
  A["Read all<br/>tools: lines"] --> B["Minimum-privilege test<br/>(grant ↔ named duty)"]
  B --> C{"Justified?"}
  C -->|no| D["Finding →<br/>Principal (not unilateral)"]
  C -->|yes| E["Record as justified"]
  D --> F["Dated report →<br/>Archivist"]
  E --> F
  classDef s fill:#1d4ed8,color:#fff,stroke:#1e3a8a
  classDef d fill:#0f766e,color:#fff,stroke:#134e4a
  class A,B,D,E,F s
  class C d

Text fallback: read every tools: line → apply the minimum-privilege test (does a named responsibility in the body require this tool?) → unjustified grants become written findings presented to the Principal (never edited unilaterally), justified grants are recorded → the dated review report hands to the Archivist (artifact approved).

Steps

  1. Read every agent definition. For each .claude/agents/*.md, read the tools: frontmatter line. Ignore body scaffolding (e.g. JD-template tools: example lines — human-resources.md:52 is residue, not a grant).
  2. Apply the minimum-privilege test. Bash without shell-execution duty is a standing command surface; Write/Edit without authoring duty is filesystem-write creep; WebSearch/WebFetch/MCP grants pull external content into context (cross-check the prompt-injection-defense policy). Each tool must map to a specific named responsibility.
  3. Flag violations. Write the finding: agent name, tool, why it fails minimum privilege, recommended remediation.
  4. Present to the Principal. Tool-grant changes to another agent are not unilateral — present findings; the Principal decides. (Off-roster grants — e.g. confidant’s GitHub-write MCP, Phase 0 D6 — are flagged here for a roster/risk call.)
  5. Update the tool-grant policy if the review surfaced a standing-standard gap.
  6. Record + archive. Deliver the dated access-control review report; hand to the Archivist (artifact approved).

Roles / approvers

Run by the Security Director. Grant changes are approved by the Principal. The Security Analyst feeds privilege-creep flags (does not run the audit). HR owns the agent definition lifecycle; we audit grants, we do not rewrite the definitions.

Proposed triggers (to Operations, not invented inline)

  • agent definition changed (HR → Security) — a new/changed agent def needs a tool-grant review. Until registered, reuse review requested; the edge reads pending if HR names it differently. Request added via interface-contract-spec.md §1.2.

Guardrails

  • Never edit another agent’s tools: line — produce a finding; the Principal decides.
  • Least privilege is the test (hr/policies/security.md) — default-deny, justify to grant.
  • Do not evaluate prompt quality — that is AI Systems’; we audit grants, not prompts.
  • Personal information is PA-only.

Job aid: (N/A — the minimum-privilege test is the checklist; the Analyst’s secrets/PR job aid covers the operational cheat-sheet, GR-4.) See also: docs/units/security-privacy/manuals/security-director.md · SOP-081 · SOP-004 · hr/policies/security.md · reports/phase0-reviews/security-director-codebase-review.md (D3, D6).