🛡️ AgentGuard

Security and context auditor for AI agents and MCP servers.

Audit your AI agents before they audit your code.

AgentGuard is an open-source CLI that scans agent instructions, MCP configuration, and project text for common security risks and produces machine-readable reports for CI.

Static and local by design: the scanner analyzes files without connecting to agents or invoking MCP tools during the audit.

What it checks

The scanner also understands common agent instruction files such as CLAUDE.md, AGENTS.md, GEMINI.md, CODEX.md, and CURSOR.md.

Quick start

For the current unreleased main branch:

git clone https://github.com/atilaamorim/agentguard.git
cd agentguard
python -m pip install -e .
agentguard scan .

The planned PyPI distribution is named agentconfigguard, while the CLI command remains agentguard for compatibility.

After the first PyPI release:

python -m pip install agentconfigguard
agentguard --version

For a development install directly from GitHub:

python -m pip install git+https://github.com/atilaamorim/agentguard.git
agentguard --version

You can also run:

python -m agentguard scan .

JSON output

agentguard scan . --json

SARIF output

SARIF works well with GitHub code-scanning workflows:

agentguard scan . --sarif agentguard-results.sarif

HTML report

agentguard scan . --html agentguard-report.html

MCP security checks

AgentGuard parses common mcpServers / MCP server configuration structures and checks for high-signal hazards:

• trust: true — flags configurations that can bypass normal tool-call confirmation.
• url: http://... (and equivalent endpoint keys) — flags unencrypted remote MCP transport.
• Capability-chain analysis — flags a server that combines untrusted input, private-data access, and outbound actions.

HTTPS endpoints are not flagged by the HTTP transport check.

Ecosystem detection

See which AI-agent ecosystems are present in a project:

agentguard scan . --adapters

AgentGuard currently recognizes Claude, Codex, Cursor, Gemini, OpenCode, and MCP configuration markers.

Context cost estimate

See which agent instruction files consume the most context:

agentguard scan . --context

Token counts are estimates based on character length, not provider-specific billing.

Context budget gate

Enforce a project-level context budget in CI:

agentguard scan . --max-context-tokens 12000

AgentGuard reports AG-CONTEXT-002 when a supported instruction file exceeds the configured budget. Token counts are estimates based on character length, not provider-specific billing.

Pre-commit

Run AgentGuard before each commit:

repos:
  - repo: https://github.com/atilaamorim/agentguard
    rev: main
    hooks:
      - id: agentguard

The hook blocks commits on high and critical findings by default. For reproducible builds, pin rev to a release tag such as v0.1.0 after the first release.

Policy as code

Add .agentguard.yml to the project root to keep CI policy with the repository:

version: 1
fail_on_severity: high
max_context_tokens: 12000
ignore:
  - rule: AG-MCP-002
    paths:
      - "configs/local/*"

The file is discovered automatically. Use --policy PATH to select another file or --no-policy to disable automatic discovery.

CLI flags take precedence over policy values.

CI severity threshold

Keep lower-severity findings visible without failing the build:

agentguard scan . --fail-on-severity high

With this setting, high and critical findings fail CI while medium and low findings remain visible in reports.

The reusable GitHub Action exposes the same control:

      - uses: atilaamorim/agentguard@main
        with:
          fail-on-severity: "high"

GitHub Actions annotations

When running in GitHub Actions, emit inline warnings and errors for findings:

agentguard scan . --github-annotations

The reusable GitHub Action enables annotations by default. Disable them when desired:

      - uses: atilaamorim/agentguard@main
        with:
          github-annotations: "false"

Baseline mode

For existing projects, create a baseline and then fail CI only when new findings appear:

agentguard scan . --write-baseline agentguard-baseline.json
agentguard scan . --baseline agentguard-baseline.json

Baseline matching uses the rule, file path, and detected evidence. Review the baseline periodically as the project changes.

GitHub Action

Use AgentGuard directly in another repository:

name: AgentGuard

on:
  push:
  pull_request:

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: atilaamorim/agentguard@main
        with:
          path: .

You can also enforce the context budget through the action:

      - uses: atilaamorim/agentguard@main
        with:
          max-context-tokens: "12000"
          fail-on-findings: "true"

The action automatically discovers .agentguard.yml in the target repository. To select a different policy file:

      - uses: atilaamorim/agentguard@main
        with:
          policy: "config/agentguard.yml"

To make findings fail the job:

      - uses: atilaamorim/agentguard@main
        with:
          fail-on-findings: "true"

Example

🛡️ AgentGuard 0.1.0

Scanning: .

Security score: 71/100
Findings: 3

HIGH     AG-SEC-001      Potential secret detected — .env:4
HIGH     AG-EXEC-001     Potential command execution capability — AGENTS.md:12
MEDIUM   AG-PROMPT-001   Prompt-injection pattern detected — CLAUDE.md:8

A non-clean scan exits with status code 1, which makes AgentGuard suitable for CI gates.

Architecture

See docs/architecture.md for the scanner flow, safety boundaries, and extension model.

Threat model

See docs/threat-model.md for scope, limitations, and false-positive guidance.

Rule reference

See docs/rules.md for the current rule catalog, severity, rationale, and remediation guidance.

Security regression benchmark

AgentGuard ships with small, deterministic MCP fixtures under tests/fixtures/.

Run the full regression suite with:

pytest -q

The benchmark intentionally includes both dangerous and safe configurations. The goal is not only to detect risky capability combinations, but also to protect against future false positives as new rules are added.

Why AgentGuard?

AI agents increasingly receive access to terminals, files, credentials, MCP tools, and large instruction files. A configuration that looks harmless to a human can create meaningful security or privacy risk.

AgentGuard aims to make that risk visible before an agent runs.

Project status

AgentGuard is an early MVP preparing for its first public v0.1.0 release. Detection is heuristic and can produce false positives or miss sophisticated attacks. It is an auditing aid, not a guarantee that an agent, MCP server, repository, or deployment is secure.

Roadmap

• Local filesystem scanner
• JSON/YAML MCP config inspection
• Secret detection
• Prompt-injection heuristics
• Permission-risk heuristics
• MCP trust-bypass detection
• MCP insecure-HTTP detection
• Dangerous capability-chain detection
• Gemini CLI persistent approval detection
• Codex full-access approval detection
• Security score
• JSON output
• SARIF output
• Reusable GitHub Action
• Context bloat detection
• GitHub Action annotations
• Ecosystem detection for Claude Code, Codex, Cursor, Gemini CLI and OpenCode
• Sanitized provider configuration fixtures for supported ecosystems
• MCP registry / server metadata checks (planned; see issue #9)
• Context-cost estimation
• Configurable context-token CI gate
• HTML report
• Baseline mode for CI
• Versioned policy-as-code configuration
• PyPI package publication for easy installation (release workflow ready; first publication pending)

Contributing

See CONTRIBUTING.md.

Security issues should follow SECURITY.md.

License

MIT