Metadata-Version: 2.4
Name: agentguard-security
Version: 0.1.0
Summary: A safety layer that lets developers use AI coding agents at work without triggering security alerts
Author: AgentGuard Contributors
License: Apache-2.0
Project-URL: Homepage, https://github.com/buildwithIntelligence/AgentGuard
Project-URL: Issues, https://github.com/buildwithIntelligence/AgentGuard/issues
Keywords: claude,cursor,ai-agent,security,guardrails
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"

# AgentGuard

A safety layer that lets developers use AI coding agents at work without triggering corporate security alerts.

## The problem

AI coding agents like Claude Code and Cursor are powerful — but they sometimes issue shell commands that look identical to malware to corporate security tools: downloading files from the internet, reading credential files, or executing scripts. This causes real incidents: security alerts, laptop lockdowns, and IT investigations.

AgentGuard sits between the agent and your shell, blocking dangerous commands while letting normal development work through uninterrupted. Every decision is logged so security teams get a reviewable audit trail instead of emergency alerts.

## Install

```bash
pip install agentguard-security
```

Requires Python 3.10+. No runtime dependencies.

## Quick setup

```bash
agentguard init
```

This writes the hook configuration into `.claude/settings.json` in your project directory. AgentGuard starts intercepting agent commands immediately — no restart needed.

To verify the hook is active:

```bash
agentguard status
```

## What it blocks

| Category | Examples | Decision |
|---|---|---|
| External downloads | `curl -o`, `wget`, `certutil -urlcache`, PowerShell IWR | BLOCK |
| Data exfiltration | `curl -d @file`, `curl -T`, `curl -F file=@...` | BLOCK |
| Secret file access | `cat .env`, `cat ~/.aws/credentials` | BLOCK |
| Environment harvest | `env \| curl`, `printenv \| grep secret` | BLOCK |
| Agent config tampering | `echo x > .claude/settings.json`, `cp ... .cursor/` | BLOCK |
| Code execution via download | `curl https://... \| bash` | BLOCK |
| MCP destructive operations | `mcp__*__delete`, `mcp__*__execute`, `mcp__*__drop` | BLOCK |
| Privilege escalation | `sudo apt install` | BLOCK |
| Chmod executable | `chmod +x`, `chmod 755` | REQUIRE APPROVAL |
| Script execution | `bash script.sh`, `powershell -File ...` | REQUIRE APPROVAL |
| Package install | `pip install`, `npm install` | REQUIRE APPROVAL |
| MCP write operations | `mcp__*__write`, `mcp__*__push`, `mcp__*__create` | REQUIRE APPROVAL |

`REQUIRE APPROVAL` commands are blocked with a plain-English explanation and a one-line instruction for how to unblock them. Developers never need to understand the underlying security rule.

To see all active rules:

```bash
agentguard rules
agentguard rules --category secret-access
agentguard rules --decision block
```

## Allowing a command once

When AgentGuard blocks a command with `REQUIRE APPROVAL`, it prints:

```
To allow this once: agentguard approve <rule-id>
```

Run that command in your terminal, then re-run the agent. The approval token expires after 60 seconds and is consumed on first use.

```bash
agentguard approve approve-pip-install
```

To change the expiry window:

```bash
AGENTGUARD_APPROVE_TTL=120 agentguard approve approve-pip-install
```

## Audit log

Set `AGENTGUARD_AUDIT_LOG` to enable structured JSONL logging of every decision:

```bash
export AGENTGUARD_AUDIT_LOG=~/.agentguard/audit.jsonl
```

Each entry includes `timestamp`, `decision`, `tool_name`, `command`, `rule_id`, `category`, `description`, `hostname`, and `user`. The log never contains secrets — only the commands the agent attempted.

View recent entries:

```bash
agentguard audit
agentguard audit --last 50
agentguard audit --blocked-only
```

## Compliance reports

Export the audit log as a compliance report for your security team:

```bash
# Human-readable summary
agentguard report

# CSV for Excel or SIEM import
agentguard report --format csv --output report.csv

# JSON for dashboards or scripting
agentguard report --format json

# Filter by date range
agentguard report --from 2024-01-01 --to 2024-01-31
```

## Terminal dashboard

View a live summary of the last 24 hours:

```bash
agentguard dashboard
agentguard dashboard --hours 48
```

## SIEM integration

Forward audit entries to a SIEM webhook (Splunk HEC, Datadog Logs, or any HTTP endpoint):

```bash
# Generic JSON
agentguard forward --url https://siem.corp.com/ingest --token $SIEM_TOKEN

# Splunk HTTP Event Collector
agentguard forward --url https://splunk:8088/services/collector --format splunk --token $HEC_TOKEN

# Datadog Logs API
agentguard forward --url https://http-intake.logs.datadoghq.com/api/v2/logs --format datadog --token $DD_API_KEY

# Send only blocked/flagged events, most recent 200
agentguard forward --url https://... --blocked-only --last 200

# Preview the payload without sending
agentguard forward --dry-run --format splunk
```

Environment variables for persistent configuration:

```bash
export AGENTGUARD_SIEM_URL=https://splunk.corp.com:8088/services/collector
export AGENTGUARD_SIEM_TOKEN=<token>
```

Add `AGENTGUARD_TEAM` and `AGENTGUARD_ORG` to tag every audit entry with your team and organisation — useful for filtering in a shared SIEM:

```bash
export AGENTGUARD_TEAM=backend
export AGENTGUARD_ORG=acme-corp
```

## Log integrity (SOC2)

Sign every audit entry with HMAC-SHA256 so tampering is detectable. Generate a key once:

```bash
python3 -c "import secrets; print(secrets.token_hex(32))"
# → e3b0c44298fc1c149afb...
```

Export it and AgentGuard signs every new entry:

```bash
export AGENTGUARD_LOG_KEY=e3b0c44298fc1c149afb...
```

Verify the log at any time:

```bash
agentguard verify-log
# Exits 0 if all signed entries are valid.
# Exits 1 and lists tampered entries if any signature fails.
```

Pass the key explicitly if it is not in the environment:

```bash
agentguard verify-log --key e3b0c44298fc1c149afb...
```

Unsigned entries (written before the key was set) are reported as `Unsigned` and not treated as failures.

## Team policy customisation

Security teams can disable default rules or add custom org-specific rules with a JSON policy file:

```json
{
  "disable_rules": ["approve-pip-install"],
  "add_rules": [
    {
      "id": "block-internal-secret-api",
      "description": "Blocked: access to the internal secrets API endpoint.",
      "pattern": "secrets\\.corp\\.example\\.com",
      "decision": "block",
      "category": "custom"
    }
  ]
}
```

Point AgentGuard at the file:

```bash
export AGENTGUARD_POLICY=/path/to/agentguard-policy.json
```

Or host it on an internal server — AgentGuard fetches it on startup with a 5-minute cache and falls back to the cached copy if the network is unavailable:

```bash
export AGENTGUARD_POLICY=https://policy.corp.example.com/agentguard.json
```

## Environment variable reference

| Variable | Description |
|---|---|
| `AGENTGUARD_AUDIT_LOG` | Path to the JSONL audit log file |
| `AGENTGUARD_POLICY` | Path or HTTPS URL to a JSON policy file |
| `AGENTGUARD_LOG_KEY` | Hex key for HMAC-SHA256 log signing (SOC2) |
| `AGENTGUARD_TEAM` | Team name added to every audit entry |
| `AGENTGUARD_ORG` | Organisation name added to every audit entry |
| `AGENTGUARD_APPROVE_TTL` | Approval token lifetime in seconds (default: 60) |
| `AGENTGUARD_SIEM_URL` | SIEM webhook URL for `agentguard forward` |
| `AGENTGUARD_SIEM_TOKEN` | Bearer token for `agentguard forward` |

## Command reference

| Command | Description |
|---|---|
| `agentguard init` | Write hook config into `.claude/settings.json` |
| `agentguard status` | Show hook status, rule counts, and audit log path |
| `agentguard rules` | List all active rules (filterable by category or decision) |
| `agentguard audit` | Tail the audit log in a table view |
| `agentguard approve <rule-id>` | Write a one-shot approval token (expires in 60s) |
| `agentguard report` | Export a compliance report (table / CSV / JSON) |
| `agentguard dashboard` | Terminal summary of events in the last N hours |
| `agentguard forward` | POST audit entries to a SIEM webhook |
| `agentguard verify-log` | Verify HMAC signatures on all signed log entries |
| `agentguard version` | Print the installed version |

## Security design

- **Fail-open**: if AgentGuard itself errors, it allows the command through and logs the exception to stderr. It will never lock you out of your own machine.
- **Zero runtime dependencies**: stdlib only — nothing to supply-chain attack.
- **Timing-safe comparisons**: log signature verification uses `hmac.compare_digest` to prevent timing attacks.
- **No telemetry**: AgentGuard never phones home. Network access is only used when `AGENTGUARD_POLICY` is set to an HTTPS URL or `agentguard forward` is run explicitly.
- **Path traversal prevention**: approval token rule IDs are validated against `^[a-z][a-z0-9-]*$` before use as file names.
