Bun Bun
104 lines
2.5 KiB
Markdown
104 lines
2.5 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
## Usage
|
|
|
|
### 1. Initialize a permission manifest
|
|
|
|
```bash
|
|
npx . init permission-manifest.json
|
|
```
|
|
|
|
### 2. Start watching a project directory
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
npx . report --dir ./cpo-audit
|
|
```
|
|
|
|
Or export as JSON:
|
|
|
|
```bash
|
|
npx . report --dir ./cpo-audit --json --output report.json
|
|
```
|
|
|
|
### 4. Log manual actions
|
|
|
|
```bash
|
|
npx . log --manifest permission-manifest.json --type file --action "fs.write" --target "src/main.ts" --agent-id "manual"
|
|
```
|
|
|
|
### 5. Check audit status
|
|
|
|
```bash
|
|
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
|