# 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