agentguard-security 0.1.0

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

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

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:

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

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.