Bun Bun
128 lines
3.0 KiB
Markdown
128 lines
3.0 KiB
Markdown
# 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
|