agentguard-security

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

pip install agentguard-security

Requires Python 3.10+. No runtime dependencies.

Quick setup

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:

agentguard status

What it blocks

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:

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.

agentguard approve approve-pip-install

To change the expiry window:

AGENTGUARD_APPROVE_TTL=120 agentguard approve approve-pip-install

Audit log

Set AGENTGUARD_AUDIT_LOG to enable structured JSONL logging of every decision:

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:

agentguard audit
agentguard audit --last 50
agentguard audit --blocked-only

Compliance reports

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

# 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:

agentguard dashboard
agentguard dashboard --hours 48

SIEM integration

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

# 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:

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:

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:

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

Export it and AgentGuard signs every new entry:

export AGENTGUARD_LOG_KEY=e3b0c44298fc1c149afb...

Verify the log at any time:

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:

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:

{
  "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:

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:

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

Environment variable reference

Command reference

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.