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.jsonfile. 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_URLto an attacker's proxy - Mine cryptocurrency using your CPU while you code
- Exfiltrate secrets from
.envfiles, 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 fixrepairs 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
- Auto-detect -- finds your project root (git or cwd) and discovers files
- Check registry -- runs 11 independent security checks in sequence
- CVSS scoring -- each finding gets a CVSS 3.1 severity score (0.0-10.0)
- Baseline comparison -- compares file hashes against stored baselines
- Report -- aggregates results with pass/warn/critical status per check
- 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.
Metadata
Release files for ai-agentguard 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ai_agentguard-0.1.0.tar.gz | 46.9 kB | Without provenance | Details for ai_agentguard-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ai_agentguard-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for ai_agentguard-0.1.0-py3-none-any.whl |
Total release size: 106.2 kB
Release files / ai_agentguard-0.1.0.tar.gz
| Download URL | ai_agentguard-0.1.0.tar.gz |
|---|---|
| Size | 46.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e583c17500b0df67a137aed9eb7180f959a342839d8c263c90584ca975b3abe2
|
|
BLAKE2b-256 checksum How to use checksums |
33a3258f7737aa1a199ae0161bdc33d16cdb68ef5806435db6b87f3cc035bc17
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Release files / ai_agentguard-0.1.0-py3-none-any.whl
| Download URL | ai_agentguard-0.1.0-py3-none-any.whl |
|---|---|
| Size | 59.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1ae87edf40f60549305a852e9289344c7067ee4cf55f31bd3d5e5b4da77a4165
|
|
BLAKE2b-256 checksum How to use checksums |
da3f33ee78c5e7ab485f87d336ac682b6f0e65af345f2af3fc04b4af694b19e8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Security for ai-agentguard 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.