AI Agent Permission Guard

A lightweight CLI sandbox and audit tool for AI agent actions.

What It Does

AI agents (Claude Code, Cursor, GitHub Copilot, etc.) can read, write, execute, and network with minimal constraints. AI Agent Permission Guard (aapg) wraps your agent commands in a configurable permission policy that:

Intercepts file system reads/writes/deletes
Blocks unauthorized network requests
Restricts child process execution
Filters environment variable access
Audits every action to a structured log

Installation

npm install -g ai-agent-permission-guard

Or run directly with npx:

npx ai-agent-permission-guard --policy policies/readonly.json -- node my-agent.js

Usage

# Run a script with a read-only policy
aapg --policy policies/readonly.json -- node agent.js

# Run npm test with the default policy
aapg --policy policies/default.json -- npm test

# Check the audit log after a run
cat audit.log | jq .

Policy Format

Policies are JSON files that define what an AI agent is allowed to do.

{
  "name": "readonly",
  "version": "1.0.0",
  "defaultPermission": "deny",
  "filesystem": [
    {
      "path": "./**",
      "operations": ["read"],
      "permission": "allow"
    }
  ],
  "network": [
    {
      "host": "*.example.com",
      "protocols": ["https"],
      "permission": "allow"
    }
  ],
  "exec": [
    {
      "command": "node",
      "permission": "allow"
    }
  ],
  "envAllowlist": ["NODE_ENV", "PATH"],
  "auditLogPath": "./audit.log"
}

Permission Levels

allow — Permit the action
deny — Block the action (throws PermissionDeniedError)
prompt — Request user confirmation (future feature, currently allows)

Policy Fields

Field	Description
`name`	Policy name
`version`	Policy version
`defaultPermission`	Fallback when no rule matches (`allow` / `deny` / `prompt`)
`filesystem`	Array of path patterns + allowed operations
`network`	Array of host patterns + allowed protocols
`exec`	Array of command patterns
`envAllowlist`	Environment variables the agent may read
`auditLogPath`	Path to append-only NDJSON audit log

Example: Read-Only Policy

Prevent an AI agent from modifying your codebase:

{
  "name": "readonly",
  "version": "1.0.0",
  "defaultPermission": "deny",
  "filesystem": [
    { "path": "./**", "operations": ["read"], "permission": "allow" },
    { "path": "/tmp/**", "operations": ["read", "write"], "permission": "allow" }
  ],
  "network": [],
  "exec": [],
  "envAllowlist": ["NODE_ENV", "PATH", "HOME"],
  "auditLogPath": "./audit.log"
}

Audit Log Format

Each line is a JSON object:

{"timestamp":"2024-01-15T10:30:00.000Z","type":"fs:write","allowed":false,"target":"/etc/passwd","details":{"reason":"No matching rule — default permission: deny"}}

Event types: fs:read, fs:write, fs:append, fs:delete, net:request, exec:spawn, exec:exec, env:read, policy:violation.

License

MIT

3.0 KiB Raw Blame History