agent-perm-audit

Least-privilege auditor for AI agent tool permissions.

LLM agents (LangChain, OpenAI function-calling, MCP servers) are wired into real infrastructure now — databases, shells, payment APIs, secret stores. Nobody checks whether an agent's tool list is over-privileged the way we've checked IAM roles for a decade.

agent-perm-audit scans your agent's tool/function definitions and flags dangerous capability combinations — a single tool that can both read secrets and reach the network, or both write files and execute code — the exact shape of a real exfiltration or RCE path.

npx agent-perm-audit tools.json

agent-perm-audit — 2 tool(s) analyzed

[CRITICAL] AGT001 — Secret read + network egress (exfiltration path)
  tool: sync_credentials_to_webhook
  capabilities: read_secrets, network_egress
  This tool can both read sensitive values (secrets/tokens/credentials) and
  make outbound network calls. An agent with this single tool, if
  prompt-injected or misled, has everything needed to exfiltrate
  credentials to an attacker-controlled endpoint.

[CRITICAL] AGT002 — File system write + code execution (RCE surface)
  tool: run_and_save_script
  capabilities: file_system_write, code_execution
  ...

Summary: 2 critical, 0 high, 0 medium, 0 low

Why this exists

IAM security matured around one idea: least privilege. A role that can both read S3 and assume any role is a bigger risk than either permission alone. Nobody applies that lens to AI agents yet, even though a single overprivileged tool can let a prompt-injected agent exfiltrate secrets, run arbitrary code, or make irreversible changes — with no attacker needing to touch your infra directly.

This tool applies that same combination-based analysis to agent tool definitions, in ~5 seconds, with zero configuration.

Install

npm install --save-dev agent-perm-audit

Usage

CLI

agent-perm-audit tools.json                          # auto-detects format
agent-perm-audit tools.json --format=openai           # explicit format
agent-perm-audit tools.json --json                    # machine-readable output
agent-perm-audit tools.json --fail-on=critical         # exit 1 for CI pipelines

Supported formats: openai (function-calling tools/functions arrays), langchain (serialized tool exports), mcp (MCP tools/list responses).

As a library

import { auditAuto } from "agent-perm-audit";

const report = auditAuto(myToolDefinitions, "openai");

console.log(report.summary);
// { critical: 1, high: 0, medium: 1, low: 0 }

CI pipeline (GitHub Actions)

- name: Audit agent tool permissions
  run: npx agent-perm-audit ./config/agent-tools.json --fail-on=high

Fails the build before an overprivileged tool combination ever reaches production.

How it works

1. Classify — each tool's name, description, and parameter schema are scanned against capability heuristics (network_egress, read_secrets, code_execution, file_system_write, database_write, delete_action, financial_action, external_communication, and more).
2. Correlate — a rules engine checks each tool for known-dangerous combinations of capabilities on the same tool, not just individual capabilities in isolation.
3. Report — findings are ranked critical → low, with a plain-English explanation of the actual risk, so a non-security engineer on the team understands why it's flagged.

Current rule set

| ID | Combination | Severity | |---|---|---| | AGT001 | Secret read + network egress | Critical | | AGT002 | File write + code execution | Critical | | AGT006 | Code execution + network egress | Critical | | AGT003 | Database write + delete | High | | AGT004 | Financial action + external comms | High | | AGT005 | Secret read + external comms | High | | AGT007 | Unscoped delete action | Medium |

Limitations

This is heuristic, keyword-based analysis of tool metadata — not runtime enforcement or static analysis of your tool's implementation code. A tool named helper with a vague description can hide risky behavior this won't catch. Treat findings as a starting point for review, not a guarantee of safety. PRs improving the capability heuristics or adding new rules are very welcome.

Roadmap

• [ ] Confidence scoring per finding (based on how many signals matched)
• [ ] Support for Anthropic tool-use / Claude Agent SDK schema
• [ ] Custom rule definitions via config file
• [ ] SARIF output for GitHub code scanning integration

License

MIT