AI agent least privilege, enforced at PR time

Least privilege you can review

Traditional least privilege lives in IAM roles and API keys. An AI agent adds a layer above that: the tools it may call, the scopes those tools carry, and the policies that put a human between the agent and an irreversible action. If that layer is implicit — whatever the runtime happens to return — nobody can review it, and it drifts. Shipgate makes it explicit and checks five dimensions of it on every pull request: declared scopes, an approval policy for high-risk tools, a confirmation policy for customer-touching ones, idempotency evidence for retried writes, and bounded blast radius.

The checks behind those dimensions are in the check catalog: SHIP-AUTH-MANIFEST-BROAD-SCOPE and SHIP-ACTION-WILDCARD-SCOPE for wildcard or admin-like scopes, SHIP-POLICY-APPROVAL-MISSING (critical) for financial, destructive, infrastructure, or code-exec risk without an approval policy, SHIP-POLICY-CONFIRMATION-MISSING, SHIP-SIDEFX-IDEMPOTENCY-MISSING, SHIP-SCOPE-PROHIBITED-TOOL-PRESENT for tools that overlap declared prohibited actions, and SHIP-SCOPE-TOOLKIT-UNBOUNDED plus the diff-aware SHIP-VERIFY-CAPABILITY-SCOPE-BROADENED for toolkits mounted, or re-mounted, without an allowlist.

Policy-as-code

The manifest is the claim: shipgate.yaml declares tool sources, permissions.scopes, approval and confirmation tool lists, prohibited actions, and idempotency policy. Organization rules layer on top as declarative YAML policy packs — data, not Python plugins — declared under checks.policy_packs or passed with --policy-pack. Rules match on risk tags, source types, environment targets, and missing controls; carry their own severity and block flag; can be integrity-pinned with sha256; and can attach owner, reviewers, and approval routing metadata that travels with each finding.

What a least-privilege finding looks like, from the bundled support-refund demo fixture (not a customer system):

Decision: blocked

1. stripe.create_refund lacks a declared approval policy
2. stripe.create_refund lacks idempotency evidence
3. Manifest declares broad permission scopes

The same fixture also surfaces an unbounded stripe.create_refund.amount parameter (blast radius), a wildcard_mcp_tools.* surface that makes review incomplete, and a gmail.send_customer_email tool that overlaps a prohibited external-communication action without a matching confirmation policy. Each finding names the tool, the missing control, and the remediation.

Commands

Gate the PR — the capability delta between base and head, with the verdict in agent-handoff.json (gate.merge_verdict, then controller), verifier.json as the authoritative substrate, and report.json → release_decision.decision as the gate:

agents-shipgate verify --workspace . --config shipgate.yaml --base origin/main --head HEAD --ci-mode advisory --format json

Check the working tree boundary locally, or from inside a coding agent (swap --agent claude-code or --agent cursor as needed):

shipgate check --agent codex --workspace . --format codex-boundary-json

Audit standing grants — the permissions your coding-agent host already holds outside any PR — then baseline them and alert on host-grant drift (exit 20):

shipgate audit --host --json --out agents-shipgate-reports/host-grants.json
shipgate audit --host --save-baseline
shipgate audit --host --drift --fail-on-drift

Honest limits

Declared surfaces only. Every check is a static check over the manifest, tool exports, source AST, and host config. Capability that is never declared or discoverable is flagged as unreviewable where possible, not inferred.
Static evidence, not runtime proof. An approval policy in the manifest is a reviewed claim that the control exists; enforcing it at call time is your runtime's job.
Humans hold the pen on policy. Approval, confirmation, idempotency, and broad-scope assertions are human-authority decisions; Shipgate surfaces them and refuses to let the generating agent self-approve them, but it does not decide them for you.
Pre-1.0 beta. Detection accuracy is still being validated and no precision or recall figures are published yet.

FAQ

What does least privilege mean for an AI agent?

A declared, reviewable capability surface: every tool the agent can call is named and schemaed, scopes are the narrowest that work, high-risk actions carry approval or confirmation policies, retries carry idempotency evidence, and blast radius is bounded. Least privilege becomes a property you can diff in a pull request instead of a value statement.

How do I write policy-as-code for agent permissions?

Declare the agent's tools, scopes, and policies in a shipgate.yaml manifest, then add organization rules as declarative YAML policy packs under checks.policy_packs (or --policy-pack on the CLI). Pack rules use an org namespace such as ORG-*, can block release, can be pinned by sha256, and can carry owner and reviewer routing metadata.

Does Agents Shipgate run my agent or call an LLM to decide?

No. Checks are deterministic and static: no agent execution, no LLM calls, no MCP connections, no network access, and no telemetry in the default path. The same input always produces the same verdict.

What blocks a merge versus what just needs review?

The single gate is report.json release_decision.decision: blocked, review_required, insufficient_evidence, or passed. verifier.json projects it into a merge verdict for PRs and agents; no surface computes a second verdict. Critical gaps such as a financial tool with no approval policy block; broad-but-arguable findings route to human review.

Can a coding agent approve its own scope expansion?

No. Approval policies, confirmation policies, idempotency claims, broad scopes, and prohibited-action exceptions are human-authority assertions, and edits to the release gate itself are trust-root changes that route to human review. A coding agent may apply mechanical fixes and re-run the verifier, but it cannot self-approve policy.

Is the refund example on this page real customer data?

No. It is the bundled support-refund demo fixture that ships with Agents Shipgate, used to show what findings look like. Agents Shipgate is pre-1.0 beta and detection accuracy is still being validated; no precision or recall figures are published.

Least privilege for AI agents, checked on every PR.