0.3.1

🛡️ AgentGuard

Preflight security auditing for AI-agent configuration and MCP — before your agent runs.

Audit your AI agents before they audit your code.

AgentGuard is an open-source CLI and GitHub Action that scans AI-agent instructions and MCP configuration for high-signal security and policy risks.

It is local, deterministic, read-only, and CI-friendly: AgentGuard does not invoke agent tools or connect to configured MCP servers during a normal scan.

Why AgentGuard?

Modern coding agents can read files, run commands, call MCP tools, access secrets, and follow large instruction files. A small configuration mistake can therefore become a security boundary problem.

AgentGuard is the preflight check that runs before the agent:

repository
   │
   ├── agent instructions
   ├── MCP configuration
   ├── provider settings
   │
   ▼
┌─────────────────────────────┐
│         AgentGuard          │
│  deterministic local audit  │
└──────────────┬──────────────┘
               │
        findings + score
               │
        ┌──────┴──────┐
        ▼             ▼
      local           CI
      review       GitHub checks

Try it in 10 seconds

python -m pip install agentconfigguard
agentguard demo

The demo is synthetic and performs no network access and no file writes.

Then scan a real repository:

agentguard scan .

Useful outputs:

agentguard scan . --json
agentguard scan . --sarif agentguard-results.sarif
agentguard scan . --html agentguard-report.html
agentguard scan . --adapters
agentguard scan . --context

What it checks

Supported agent/config markers include Claude, Codex, Cursor, Gemini, OpenCode, and MCP.

GitHub Actions

Add AgentGuard to any repository:

name: AgentGuard

on:
  push:
  pull_request:

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: atilaamorim/agentguard@v0.3.1
        with:
          path: .
          fail-on-severity: "high"

The Action can emit:

• GitHub annotations
• JSON
• SARIF
• HTML reports
• CI failure gates

It also supports policy files, baselines, and context budgets.

Current stable Action: v0.3.1. The main branch contains the upcoming v0.3.0 feature set.

Policy as code

Keep the security gate with the repository:

version: 1
fail_on_severity: high
max_context_tokens: 12000

ignore:
  - rule: AG-MCP-002
    paths:
      - "configs/local/*"

AgentGuard discovers .agentguard.yml / .agentguard.yaml automatically.

Baselines

Existing repositories can adopt AgentGuard without fixing everything at once:

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

Only findings that are not already in the baseline are returned.

Pre-commit

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

Design principles

Where AgentGuard fits

AgentGuard is deliberately a static configuration auditor, not a runtime firewall.

A clean scan is not proof that an agent, MCP server, repository, or deployment is secure. Rules are heuristic and can have false positives or false negatives.

Security regression benchmark

AgentGuard ships deterministic risky and safe fixtures under tests/fixtures/.

Run the suite locally:

pytest -q

Rules should include positive and negative regression coverage whenever practical.

Documentation

• Architecture
• Threat model
• Rule reference
• Contributing
• Security policy

Roadmap

• Local filesystem scanner
• JSON/YAML MCP inspection
• Secret detection
• Prompt-injection heuristics
• Permission-risk heuristics
• MCP trust / cleartext HTTP checks
• Dangerous capability-chain detection
• Claude / Codex / Cursor / Gemini / OpenCode detection
• JSON / SARIF / HTML output
• GitHub Action
• GitHub annotations
• Context-cost estimation
• Context budget gate
• Baseline mode
• Policy-as-code
• PyPI package metadata
• Expand provider-specific coverage
• Add more safe/risky MCP provenance cases
• Improve interactive demo and onboarding
• Add more integrations and examples

Contributing

Good starting points:

• #12 — Add more MCP provenance regression cases
• #13 — Improve AgentGuard demo and onboarding examples

Small, focused pull requests are welcome. New security rules should include regression coverage and remediation guidance.

Security issues should follow SECURITY.md.

License

MIT