AgentPolicy Guard

AgentPolicy Guard is a local-first CLI that scans repo-level AI instructions and agent configuration before AI coding agents execute them.

It looks for cost, data exposure, tool permission, routing, and policy drift risks in files such as CLAUDE.md, AGENTS.md, .cursorrules, .mcp.json, GitHub workflows, README, docs, and recent commit messages.

Why

Repo text is increasingly becoming AI agent runtime configuration. A small instruction change can affect model usage, data handling, MCP tool permissions, or how different coding assistants behave.

AgentPolicy Guard helps catch risky AI-visible instructions before they land in the main branch.

Privacy

• Runs locally by default.
• Does not upload repository content.
• Does not call an LLM.
• Does not connect to Claude, Cursor, Copilot, Codex, or other AI provider accounts.
• In GitHub Actions, it runs inside your own CI environment.

Install

npm install
npm run build
node dist/src/cli.js scan .

After publishing to npm, the intended usage is:

npx @mannaz230/agentpolicy scan .

CLI

agentpolicy scan .
agentpolicy scan . --output agentpolicy-report.md
agentpolicy scan . --format json
agentpolicy scan . --ci
agentpolicy scan . --fail-on high
agentpolicy scan . --config agentpolicy.yml
agentpolicy scan . --include "docs/**/*.md"
agentpolicy scan . --exclude "docs/archive/**"

Example

npm run build
node dist/src/cli.js scan examples/risky-repo --output agentpolicy-report.md

Example output:

AgentPolicy Guard v0.1.1

Scanned files: 6
Findings: 11

Severity Summary:
High: 6
Medium: 4
Low: 1

Default Scan Targets

• CLAUDE.md
• AGENTS.md
• .cursorrules
• .cursor/rules/**/*.mdc
• .github/copilot-instructions.md
• .windsurfrules
• .mcp.json
• mcp.json
• .vscode/mcp.json
• .cursor/mcp.json
• package.json
• .github/workflows/**/*.yml
• .github/workflows/**/*.yaml
• README.md
• **/README.md
• docs/**/*.md
• recent commit messages from git log -n 50 --pretty=format:%s

Default excludes include node_modules, .git, dist, build, coverage, .next, .cache, and vendor.

Risk Types

• Cost Risk: instructions that may encourage premium models, long context, extended thinking, or unbounded agent runs.
• Data Exposure Risk: instructions that may encourage sending customer logs, production data, screenshots, tickets, dumps, or secrets to AI tools.
• Tool Permission Risk: MCP or workflow configuration that may grant broad filesystem, shell, database, browser, email, calendar, or remote tool access.
• Policy Drift Risk: conflicting AI instruction files, including required vs optional behavior or production-data policy conflicts.
• Routing / Trigger Risk: text that may affect AI assistant routing, usage limits, or provider policy behavior.

Severity Policy

AgentPolicy Guard keeps high severity findings for strong evidence only.

• High: explicit instructions or actual agent configuration that may upload customer data, production data, database dumps, screenshots, or secrets to AI tools; filesystem MCP scoped to root; MCP shell access; or database MCP configuration that clearly references production, write/admin/root access, or embedded database credentials.
• Medium: sensitive workflows that need review, such as AI support-ticket analysis with named external LLM providers, remote MCP endpoints, browser/email/calendar/database tools without enough evidence to prove production or write access, or policy conflicts across AI instruction files.
• Low: routing, trigger, or context signals that may influence agent behavior but do not prove a dangerous configuration, such as sandbox-bypass flags mentioned in docs or multiple AI instruction files existing at once.

README and docs examples are treated carefully. Tool Permission Risk is intended to flag actual agent configuration such as .mcp.json, mcp.json, .vscode/mcp.json, .cursor/mcp.json, package.json, and workflow files. A README that merely documents an MCP setup example should not become a high severity Tool Permission finding.

Configuration

Create agentpolicy.yml in your repo root:

scan:
  include:
    - "CLAUDE.md"
    - "AGENTS.md"
    - ".cursorrules"
    - ".cursor/rules/**/*.mdc"
    - ".github/copilot-instructions.md"
    - ".mcp.json"
    - "docs/**/*.md"
  exclude:
    - "docs/archive/**"

severity:
  fail_on: high

rules:
  cost_risk: true
  data_exposure: true
  tool_permission: true
  policy_drift: true
  routing_trigger: true

allowlist:
  - id: "routing-trigger-provider-policy"
    file: "docs/vendor-notes.md"
    reason: "Documenting a known vendor incident"

GitHub Action

name: AgentPolicy Guard

on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

jobs:
  agentpolicy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 50

      - uses: rnsss/[email protected]
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          fail-on: high
          comment: true
          output: agentpolicy-report.md
          format: markdown

The Action writes the report file, logs a console summary, optionally comments on pull requests, and fails the workflow when findings meet the configured fail-on severity.

Current MVP Limits

• Rule-based scanning only.
• No LLM analysis.
• No automatic fixes.
• No login, SaaS backend, private repo ingestion, or organization management.
• Findings are conservative signals, not legal or compliance certification.