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