Initial MVP: AI Agent Permission Guard — sandbox and audit AI agent actions with configurable policies

2026-06-18 06:30:32 +00:00
commit 6d9b37ede7
16 changed files with 1386 additions and 0 deletions
@@ -0,0 +1,127 @@
+# 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
+
+```bash
+npm install -g ai-agent-permission-guard
+```
+
+Or run directly with `npx`:
+
+```bash
+npx ai-agent-permission-guard --policy policies/readonly.json -- node my-agent.js
+```
+
+## Usage
+
+```bash
+# 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.
+
+```json
+{
+  "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:
+
+```json
+{
+  "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:
+
+```json
+{"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