<<<<<<< HEAD

capscope

Capability auditor for AI agents.

LLM agents (LangChain, OpenAI function-calling, MCP servers) are wired into real infrastructure — 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.

capscope scans your agent's tool 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 capscope tools.json

capscope — 3 tool(s) scanned

[CRITICAL] CAP101 — Secret read + network egress (exfiltration path)
  tool:     sync_credentials_to_webhook
  evidence:
    network_egress           ✔ description contains 'webhook', description contains 'endpoint'
    read_secrets             ✔ description contains 'API key', description contains 'vault'

  This tool can both read sensitive values and make outbound network calls.
  An agent with this tool, if prompt-injected, has everything needed to
  exfiltrate credentials to an attacker-controlled endpoint.

  refs: owasp-llm-top10 · CAP101 v1

Summary: 2 critical, 1 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 touching your infrastructure directly.

capscope applies the same combination-based analysis to agent tool definitions, in seconds, with zero configuration.

Install

npm install --save-dev capscope

Or run without installing:

npx capscope tools.json

Usage

CLI

capscope tools.json                           # auto-detects format
capscope agent.ts                             # TypeScript source file
capscope tools.yaml --format=langchain        # explicit format
capscope tools.json --output=json             # machine-readable output
capscope tools.json --fail-on=critical        # exit 1 for CI pipelines
capscope tools.json --ignore=CAP101,CAP302    # suppress specific rules
capscope tools.json --rules ./company-rules/  # load custom rule packs

Supported file types: .json · .yaml · .yml · .ts · .tsx · .js · .jsx

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

As a library

import { analyze } from "capscope";
import { parseOpenAiTools } from "capscope";

const tools = parseOpenAiTools(myToolDefinitions);
const report = analyze(tools);

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

for (const finding of report.findings) {
  console.log(finding.ruleId, finding.severity, finding.tool);
  for (const ev of finding.evidence) {
    console.log(" ", ev.capability, ev.signals);
  }
}

CI pipeline (GitHub Actions)

- name: Audit agent capability combinations
  run: npx capscope ./config/agent-tools.json --fail-on=high

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

Suppressions

If your team has reviewed a finding and accepted the risk, suppress it without disabling the rule for everyone:

Via config file (capscope.config.json in your project root):

{
  "ignore": [
    {
      "rule": "CAP101",
      "tool": "internal_sync_tool",
      "reason": "Internal webhook only — reviewed by security team 2025-08-01"
    }
  ]
}

Via CLI flag (blanket, useful in CI overrides):

capscope tools.json --ignore=CAP101

How it works

Your tool definitions (JSON / YAML / TypeScript / JS)
          │
          ▼
    ┌─────────────┐
    │   Parsers   │  Reads the file format
    └──────┬──────┘
           │  NormalizedTool[]
           ▼
    ┌─────────────┐
    │  Classifier │  Scans name + description + parameters
    └──────┬──────┘  with heuristics → capability evidence
           │  ClassifiedTool[] with evidence signals
           ▼
    ┌─────────────┐
    │ Rule Engine │  Loads YAML rule packs, checks combinations
    └──────┬──────┘
           │  RuleMatch[] with evidence + confidence
           ▼
    ┌─────────────┐
    │  Reporter   │  Outputs text / JSON with evidence strings
    └─────────────┘

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). Every match produces an evidence signal explaining why the capability was detected.

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 plain-English descriptions and evidence strings, so a non-security engineer understands why it's flagged, not just that it's flagged.

Rule set

Rules live as standalone YAML files in the rules/ directory — community contributions welcome.

| ID | Combination | Severity | Category | |---|---|---|---| | CAP101 | Secret read + network egress | Critical | Exfiltration | | CAP201 | File write + code execution | Critical | Remote Execution | | CAP202 | Code execution + network egress | Critical | Remote Execution | | CAP102 | Secret read + external communication | High | Exfiltration | | CAP301 | Database write + delete | High | Destructive | | CAP601 | Financial action + external comms | High | Financial | | CAP302 | Unscoped delete action | Medium | Destructive |

Rule ID ranges (reserved)

| Range | Category | |---|---| | CAP100–CAP199 | Exfiltration | | CAP200–CAP299 | Remote Execution | | CAP300–CAP399 | Destructive Actions | | CAP400–CAP499 | Identity & Auth Abuse | | CAP500–CAP599 | Memory & Persistence | | CAP600–CAP699 | Financial | | CAP900–CAP999 | Experimental / Community |

Custom rule packs

Write your own rules as YAML files and load them with --rules:

# company-rules/CAP901-custom.yaml
id: CAP901
version: 1
title: "Internal policy: no PII access + external comms"
severity: high
category: exfiltration
requires:
  - database_read
  - external_communication
description: >
  Company policy prohibits tools that can read user PII and also
  communicate externally without explicit data handling approval.

capscope tools.json --rules ./company-rules/

Extension points

capscope exposes stable interfaces for building custom parsers and adapters:

import type { IFileParser, IFrameworkAdapter } from "capscope";

// Custom file format parser
const myParser: IFileParser = {
  extensions: [".toml"],
  async parse(filePath) {
    // return NormalizedTool[]
  },
};

// Custom framework adapter
const myAdapter: IFrameworkAdapter = {
  name: "crewai",
  detect: (raw) => Array.isArray((raw as any)?.agents),
  normalize: (raw) => { /* return NormalizedTool[] */ },
};

Migrating from agent-perm-audit

capscope is the successor to agent-perm-audit. The public API is identical:

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

| Old | New | |---|---| | agent-perm-audit tools.json | capscope tools.json | | import { auditAuto } from "agent-perm-audit" | import { analyze } from "capscope" | | Rule ID AGT001 | Rule ID CAP101 |

Limitations

This is heuristic, keyword-based analysis of tool metadata — not runtime enforcement or static analysis of tool 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 capability heuristics or adding new rules are very welcome.

Roadmap

• [ ] Python AST parser (v0.3.0)
• [ ] Recursive directory scanning: capscope . (v0.4.0)
• [ ] .capscopeignore support (v0.4.0)
• [ ] HTML report output (v0.3.0)
• [ ] GitHub Action (capscope-action) (v0.5.0)
• [ ] SARIF output for GitHub Code Scanning (v0.5.0)
• [ ] Policy engine: --policy company-policy.yaml (v0.5.0)
• [ ] VS Code extension (v1.0.0)

Contributing

See CONTRIBUTING.md. Adding a new capability signal or rule is intentionally designed to be a 5-minute contribution.

Security

See SECURITY.md for vulnerability reporting guidelines.

License

MIT © Chakradhar Somisetty

capscope

2c42b0ff4d721e30dd8fe419443146ec9b528c02