Bun Bun
2.5 KiB
2.5 KiB
Claude Permission Observability (cpo)
CLI observability tool for Claude Code agents. Tracks what agents are doing outside defined permissions, logs bypass attempts, and maintains compressed audit trails for building deny-lists.
Install
npm install
npm run build
Usage
1. Initialize a permission manifest
npx . init permission-manifest.json
2. Start watching a project directory
npx . watch --manifest permission-manifest.json --dir ./my-project --agent-id "claude-agent-1"
This monitors file system changes and (optionally) Claude Code state files to detect permission violations in real time.
3. Generate a violation report
npx . report --dir ./cpo-audit
Or export as JSON:
npx . report --dir ./cpo-audit --json --output report.json
4. Log manual actions
npx . log --manifest permission-manifest.json --type file --action "fs.write" --target "src/main.ts" --agent-id "manual"
5. Check audit status
npx . status --dir ./cpo-audit
Permission Manifest
The manifest defines what agents are allowed to do. Rules are evaluated in order:
| Type | Pattern | Action | Description |
|---|---|---|---|
| file | src/**/*.ts |
allow | Allow editing source files |
| file | **/*.env* |
deny | Deny access to env files |
| command | git push |
warn | Warn on git push |
| command | rm -rf / |
deny | Deny destructive rm |
| network | localhost:* |
allow | Allow local servers |
| network | api.openai.com |
warn | Warn on OpenAI API calls |
Sensitive Patterns
Paths matching sensitive patterns (e.g., .env, secrets, token) are automatically flagged as bypass_attempt even if no explicit rule matches.
Audit Trail
- JSONL format — one action per line, append-only
- Companion summary JSON for quick analysis
- Automatic rotation when size exceeds
maxTrailSize(MB)
Risk Score
The violation report calculates a risk score (0-100) based on:
- Violation density (percentage of denied actions)
- Bypass attempt rate
- Total violation count
| Score | Label |
|---|---|
| 0 | SAFE |
| 1-24 | LOW |
| 25-49 | MEDIUM |
| 50-74 | HIGH |
| 75-100 | CRITICAL |
Commands
| Command | Description |
|---|---|
init [path] |
Create a default permission manifest |
watch |
Start file system watcher |
report |
Generate violation report from audit trail |
log |
Log a manual action |
validate |
Validate a permission manifest |
status |
Show audit directory status |
License
MIT