ai-agentguard 0.1.0

Security monitor for AI coding agents — detect hook RCE, MCP poisoning, and API key theft before they execute

AgentGuard

Security scanner for AI coding agents -- catch RCE, MCP poisoning, and API key theft before they strike.

Claude Code CVE-2025-59536 gave attackers remote code execution through a single settings.json file. CVE-2026-21852 showed how poisoned MCP servers can hijack agent communications. 73% of AI deployments have prompt injection vulnerabilities (OWASP). No monitoring tool existed for individual developers. So we built one.

Quick Start

pip install agentguard
agentguard scan .

  Shield  AgentGuard Security Scan
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  [+] File Integrity        OK    (12 files, 0 changes)
  [+] Process Monitor       OK    (no suspicious processes)
  [!] Environment Security  WARN  (.env is world-readable)
  [X] Hooks Audit           CRIT  (dangerous curl in hooks)
  [+] MCP Audit             OK    (2 servers, all verified)
  [+] Secret Scanner        OK    (0 exposed keys)
  [+] Code Scanner          OK    (0 dangerous patterns)
  [+] Network Monitor       OK    (all connections normal)
  [+] Git Monitor           OK    (no unauthorized changes)
  [+] DB Integrity          OK    (3 databases healthy)
  [+] Dependency Audit      OK    (all pinned, 0 vulns)

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Score: 85/100 | CVSS: 9.0 (Critical)
  1 critical, 1 warning, 9 passed

  Run `agentguard fix` to auto-fix 1 issue.

What It Catches

Threat	Check	Detects
Hook RCE	hooks	Malicious commands in .claude/settings.json hooks (CVE-2025-59536)
MCP Poisoning	mcp_servers	Unauthorized MCP servers, enableAllProjectMcpServers bypass (CVE-2026-21852)
API Theft	env_security	ANTHROPIC_BASE_URL hijacking, exposed .env files
Crypto Mining	suspicious_processes	XMRig, CGMiner, and 12+ miner signatures
Secret Exposure	secrets	Hardcoded API keys in source and git history
Backdoor Ports	network_connections	Connections to ports 4444, 1337, 31337, etc.
Code Injection	dangerous_code	eval(), exec(), os.system() in project code
File Tampering	file_integrity	SHA256 baseline comparison for critical files
Git Anomalies	git_status	Unauthorized changes to protected files
DB Corruption	db_integrity	SQLite PRAGMA integrity_check
Dep Vulns	dependencies	pip-audit integration + unpinned versions

Why This Exists

AI coding agents (Claude Code, Cursor, Copilot, Windsurf) execute code on your machine with broad filesystem and network access. A single malicious file in a cloned repository can:

• Execute arbitrary commands via hook RCE (pre/post tool call hooks)
• Intercept all agent traffic via poisoned MCP servers
• Steal API keys by redirecting ANTHROPIC_BASE_URL to an attacker's proxy
• Mine cryptocurrency using your CPU while you code
• Exfiltrate secrets from .env files, git history, and log files

AgentGuard is the first security scanner purpose-built for this threat model.

Features

• Zero dependencies -- stdlib only, installs in seconds
• 11 security checks -- from file integrity to AI-specific threats
• Auto-fix -- agentguard fix repairs safe issues automatically
• CVSS scoring -- industry-standard severity ratings (0.0-10.0)
• Baseline tracking -- SHA256 hash comparison over time via SQLite
• Python API -- from agentguard import Guard; Guard().scan()
• CI/CD ready -- JSON output, exit codes (0=ok, 1=warn, 2=critical)
• Cross-agent -- works with Claude Code, Cursor, Copilot, and more

Usage

CLI

# Scan current project
agentguard scan .

# Scan specific path
agentguard scan /path/to/project

# Run specific checks only
agentguard scan . --checks hooks,mcp_servers

# JSON output for CI/CD
agentguard scan . --json

# Initialize file hash baselines
agentguard init

# Auto-fix safe issues
agentguard fix

# Preview fixes without making changes
agentguard fix --dry-run

# Show version
agentguard version

Python API

from agentguard import Guard

# Simple scan
guard = Guard()
result = guard.scan()
print(f"Score: {100 - result.critical_count * 10 - result.warning_count * 3}/100")

# Check specific issues
for check in result.checks:
    if check.status == "critical":
        print(f"CRITICAL: {check.name}: {check.details}")
        for finding in check.findings:
            print(f"  - {finding}")

# Run specific checks
result = guard.scan(checks=["hooks", "mcp_servers"])

# Initialize baselines
count = guard.init_baseline()
print(f"Saved {count} baselines")

# Auto-fix
actions = guard.fix()
for action in actions:
    print(action)

One-shot scan (no persistence)

import agentguard

result = agentguard.scan()
print(result.summary())

Configuration (optional)

Create agentguard.json in your project root to customize:

{
  "critical_files": [
    "main.py",
    "core.py",
    ".claude/settings.json"
  ],
  "watch_directories": [
    "tools",
    "plugins",
    ".claude"
  ],
  "known_mcp_servers": [
    "filesystem",
    "memory",
    "brave-search"
  ]
}

AgentGuard auto-detects most settings from your project structure. Configuration is only needed for customization.

CI/CD Integration

GitHub Actions

- name: Security scan
  run: |
    pip install agentguard
    agentguard scan . --json > security-report.json
    agentguard scan .  # exits with code 2 on critical findings

Pre-commit hook

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: agentguard
        name: AgentGuard Security Scan
        entry: agentguard scan . --checks hooks,mcp_servers,secrets
        language: python
        pass_filenames: false
        additional_dependencies: [agentguard]

Supported Agents

Agent	Hook Check	MCP Check	Config Path
Claude Code	Yes	Yes	.claude/settings.json
Cursor	Yes	Yes	.cursor/settings.json
VS Code	Yes	Partial	.vscode/settings.json
Copilot	Planned	Planned	.github/copilot
Windsurf	Planned	Planned	.windsurf/

How It Works

1. Auto-detect -- finds your project root (git or cwd) and discovers files
2. Check registry -- runs 11 independent security checks in sequence
3. CVSS scoring -- each finding gets a CVSS 3.1 severity score (0.0-10.0)
4. Baseline comparison -- compares file hashes against stored baselines
5. Report -- aggregates results with pass/warn/critical status per check
6. Auto-fix -- optionally fixes safe issues (permissions, .gitignore)

Architecture

agentguard/
  __init__.py          # Public API: Guard, scan, CheckResult, ScanResult
  _guard.py            # Guard orchestrator
  cli.py               # CLI entry point
  config.py            # Auto-detecting configuration
  core/
    result.py           # CheckResult, ScanResult dataclasses
    severity.py         # CVSS score mapping
    utils.py            # sha256, permissions, version comparison
  checks/
    __init__.py          # Check registry (ALL_CHECKS, get_check_by_name)
    file_integrity.py    # SHA256 baseline comparison
    process_monitor.py   # Crypto miner / reverse shell detection
    network_monitor.py   # Suspicious port connections
    env_security.py      # .env permissions + gitignore + hash
    git_monitor.py       # Protected file change detection
    db_integrity.py      # SQLite PRAGMA integrity_check
    secret_scanner.py    # API key regex + git history
    code_scanner.py      # eval/exec/subprocess detection
    dependency_audit.py  # pip-audit + unpinned versions
    hooks_audit.py       # Hook RCE detection (CVE-2025-59536)
    mcp_audit.py         # MCP server poisoning detection
  storage/
    tracker.py           # SQLite persistence (scans, baselines, alerts)
  notify/
    base.py              # Abstract Notifier base class
    console.py           # Console output with ANSI colours
  fix/
    auto_fix.py          # Automated remediation (permissions, gitignore)

Contributing

PRs welcome! See CONTRIBUTING.md for guidelines.

# Development setup
git clone https://github.com/jeromwolf/agentguard.git
cd agentguard
pip install -e ".[all]"
pytest tests/ -v

License

Apache-2.0. See LICENSE for details.

---

Built by Kelly Wolf. If AgentGuard helped you catch a security issue, consider starring the repo.