Metadata-Version: 2.4
Name: ai-agentguard
Version: 0.1.0
Summary: Security monitor for AI coding agents — detect hook RCE, MCP poisoning, and API key theft before they execute
Project-URL: Homepage, https://github.com/jeromwolf/agentguard
Project-URL: Repository, https://github.com/jeromwolf/agentguard
Project-URL: Issues, https://github.com/jeromwolf/agentguard/issues
Author-email: Kelly Wolf <jeromwolf@gmail.com>
License: Apache-2.0
License-File: LICENSE
Keywords: ai-agent,claude-code,copilot,cursor,mcp,prompt-injection,security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Provides-Extra: all
Requires-Dist: rich>=13.0; extra == 'all'
Provides-Extra: rich
Requires-Dist: rich>=13.0; extra == 'rich'
Description-Content-Type: text/markdown

# AgentGuard

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

> Claude Code [CVE-2025-59536](https://www.cvedetails.com/cve/CVE-2025-59536/) gave attackers remote code execution through a single `settings.json` file. [CVE-2026-21852](https://www.cvedetails.com/cve/CVE-2026-21852/) showed how poisoned MCP servers can hijack agent communications. 73% of AI deployments have prompt injection vulnerabilities ([OWASP](https://owasp.org/www-project-top-10-for-large-language-model-applications/)). No monitoring tool existed for individual developers. **So we built one.**

[![PyPI](https://img.shields.io/pypi/v/agentguard)](https://pypi.org/project/agentguard/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
[![Python](https://img.shields.io/pypi/pyversions/agentguard)](https://pypi.org/project/agentguard/)
[![Tests](https://img.shields.io/github/actions/workflow/status/jeromwolf/agentguard/test.yml?label=tests)](https://github.com/jeromwolf/agentguard/actions)

## Quick Start

```bash
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

```bash
# 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

```python
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)

```python
import agentguard

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

## Configuration (optional)

Create `agentguard.json` in your project root to customize:

```json
{
  "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

```yaml
- 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

```yaml
# .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](CONTRIBUTING.md) for guidelines.

```bash
# 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](LICENSE) for details.

---

Built by [Kelly Wolf](https://github.com/jeromwolf). If AgentGuard helped you catch a security issue, consider starring the repo.
