Initial MVP: Claude Permission Observability CLI tool
This commit is contained in:
Bun Bun
@@ -0,0 +1,6 @@
|
||||
node_modules/
|
||||
dist/
|
||||
*.log
|
||||
.verdict
|
||||
cpo-audit/
|
||||
.DS_Store
|
||||
@@ -0,0 +1,103 @@
|
||||
# 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
|
||||
@@ -0,0 +1,83 @@
|
||||
{
|
||||
"name": "claude-agent-observability",
|
||||
"version": "1.0.0",
|
||||
"rules": [
|
||||
{
|
||||
"type": "file",
|
||||
"pattern": "src/**/*.ts",
|
||||
"action": "allow",
|
||||
"description": "Allow editing source files"
|
||||
},
|
||||
{
|
||||
"type": "file",
|
||||
"pattern": "tests/**/*.ts",
|
||||
"action": "allow",
|
||||
"description": "Allow editing test files"
|
||||
},
|
||||
{
|
||||
"type": "file",
|
||||
"pattern": "**/*.env*",
|
||||
"action": "deny",
|
||||
"description": "Deny access to env files"
|
||||
},
|
||||
{
|
||||
"type": "file",
|
||||
"pattern": "**/.ssh/**",
|
||||
"action": "deny",
|
||||
"description": "Deny access to SSH keys"
|
||||
},
|
||||
{
|
||||
"type": "file",
|
||||
"pattern": "**/.aws/**",
|
||||
"action": "deny",
|
||||
"description": "Deny access to AWS credentials"
|
||||
},
|
||||
{
|
||||
"type": "command",
|
||||
"pattern": "git push",
|
||||
"action": "warn",
|
||||
"description": "Warn on git push"
|
||||
},
|
||||
{
|
||||
"type": "command",
|
||||
"pattern": "rm -rf /",
|
||||
"action": "deny",
|
||||
"description": "Deny destructive rm commands"
|
||||
},
|
||||
{
|
||||
"type": "command",
|
||||
"pattern": "rm -rf ~",
|
||||
"action": "deny",
|
||||
"description": "Deny home directory deletion"
|
||||
},
|
||||
{
|
||||
"type": "network",
|
||||
"pattern": "localhost:*",
|
||||
"action": "allow",
|
||||
"description": "Allow local development servers"
|
||||
},
|
||||
{
|
||||
"type": "network",
|
||||
"pattern": "api.openai.com",
|
||||
"action": "warn",
|
||||
"description": "Warn on OpenAI API calls"
|
||||
}
|
||||
],
|
||||
"defaultAction": "warn",
|
||||
"compression": {
|
||||
"enabled": true,
|
||||
"maxTrailSize": 50,
|
||||
"retentionDays": 30
|
||||
},
|
||||
"sensitivePatterns": [
|
||||
".env",
|
||||
"secrets",
|
||||
"password",
|
||||
"token",
|
||||
"key",
|
||||
"credential",
|
||||
"private",
|
||||
"apikey",
|
||||
"secret_key"
|
||||
]
|
||||
}
|
||||
Generated
+286
@@ -0,0 +1,286 @@
|
||||
{
|
||||
"name": "ai-agent-permission-observability-for-cl",
|
||||
"version": "0.1.0",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "ai-agent-permission-observability-for-cl",
|
||||
"version": "0.1.0",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@types/node": "^25.9.3",
|
||||
"chokidar": "^3.6.0",
|
||||
"commander": "^12.1.0",
|
||||
"minimatch": "^10.0.0"
|
||||
},
|
||||
"bin": {
|
||||
"claude-permission-observability": "dist/index.js",
|
||||
"cpo": "dist/index.js"
|
||||
},
|
||||
"devDependencies": {
|
||||
"typescript": "^5.5.0"
|
||||
}
|
||||
},
|
||||
"node_modules/@types/node": {
|
||||
"version": "25.9.3",
|
||||
"resolved": "https://registry.npmjs.org/@types/node/-/node-25.9.3.tgz",
|
||||
"integrity": "sha512-603BddQMv3pUcr4U2dhujk83N2tTDVr/34wII2B6bJy6g+8WD6yUb11jszNs0gdi4PesVWl7ABt8nYMVpnLUcg==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"undici-types": ">=7.24.0 <7.24.7"
|
||||
}
|
||||
},
|
||||
"node_modules/anymatch": {
|
||||
"version": "3.1.3",
|
||||
"resolved": "https://registry.npmjs.org/anymatch/-/anymatch-3.1.3.tgz",
|
||||
"integrity": "sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw==",
|
||||
"license": "ISC",
|
||||
"dependencies": {
|
||||
"normalize-path": "^3.0.0",
|
||||
"picomatch": "^2.0.4"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">= 8"
|
||||
}
|
||||
},
|
||||
"node_modules/balanced-match": {
|
||||
"version": "4.0.4",
|
||||
"resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
|
||||
"integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==",
|
||||
"license": "MIT",
|
||||
"engines": {
|
||||
"node": "18 || 20 || >=22"
|
||||
}
|
||||
},
|
||||
"node_modules/binary-extensions": {
|
||||
"version": "2.3.0",
|
||||
"resolved": "https://registry.npmjs.org/binary-extensions/-/binary-extensions-2.3.0.tgz",
|
||||
"integrity": "sha512-Ceh+7ox5qe7LJuLHoY0feh3pHuUDHAcRUeyL2VYghZwfpkNIy/+8Ocg0a3UuSoYzavmylwuLWQOf3hl0jjMMIw==",
|
||||
"license": "MIT",
|
||||
"engines": {
|
||||
"node": ">=8"
|
||||
},
|
||||
"funding": {
|
||||
"url": "https://github.com/sponsors/sindresorhus"
|
||||
}
|
||||
},
|
||||
"node_modules/brace-expansion": {
|
||||
"version": "5.0.6",
|
||||
"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.6.tgz",
|
||||
"integrity": "sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"balanced-match": "^4.0.2"
|
||||
},
|
||||
"engines": {
|
||||
"node": "18 || 20 || >=22"
|
||||
}
|
||||
},
|
||||
"node_modules/braces": {
|
||||
"version": "3.0.3",
|
||||
"resolved": "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz",
|
||||
"integrity": "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"fill-range": "^7.1.1"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=8"
|
||||
}
|
||||
},
|
||||
"node_modules/chokidar": {
|
||||
"version": "3.6.0",
|
||||
"resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.6.0.tgz",
|
||||
"integrity": "sha512-7VT13fmjotKpGipCW9JEQAusEPE+Ei8nl6/g4FBAmIm0GOOLMua9NDDo/DWp0ZAxCr3cPq5ZpBqmPAQgDda2Pw==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"anymatch": "~3.1.2",
|
||||
"braces": "~3.0.2",
|
||||
"glob-parent": "~5.1.2",
|
||||
"is-binary-path": "~2.1.0",
|
||||
"is-glob": "~4.0.1",
|
||||
"normalize-path": "~3.0.0",
|
||||
"readdirp": "~3.6.0"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">= 8.10.0"
|
||||
},
|
||||
"funding": {
|
||||
"url": "https://paulmillr.com/funding/"
|
||||
},
|
||||
"optionalDependencies": {
|
||||
"fsevents": "~2.3.2"
|
||||
}
|
||||
},
|
||||
"node_modules/commander": {
|
||||
"version": "12.1.0",
|
||||
"resolved": "https://registry.npmjs.org/commander/-/commander-12.1.0.tgz",
|
||||
"integrity": "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA==",
|
||||
"license": "MIT",
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/fill-range": {
|
||||
"version": "7.1.1",
|
||||
"resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.1.1.tgz",
|
||||
"integrity": "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"to-regex-range": "^5.0.1"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=8"
|
||||
}
|
||||
},
|
||||
"node_modules/fsevents": {
|
||||
"version": "2.3.3",
|
||||
"resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
|
||||
"integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
|
||||
"hasInstallScript": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"darwin"
|
||||
],
|
||||
"engines": {
|
||||
"node": "^8.16.0 || ^10.6.0 || >=11.0.0"
|
||||
}
|
||||
},
|
||||
"node_modules/glob-parent": {
|
||||
"version": "5.1.2",
|
||||
"resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz",
|
||||
"integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==",
|
||||
"license": "ISC",
|
||||
"dependencies": {
|
||||
"is-glob": "^4.0.1"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">= 6"
|
||||
}
|
||||
},
|
||||
"node_modules/is-binary-path": {
|
||||
"version": "2.1.0",
|
||||
"resolved": "https://registry.npmjs.org/is-binary-path/-/is-binary-path-2.1.0.tgz",
|
||||
"integrity": "sha512-ZMERYes6pDydyuGidse7OsHxtbI7WVeUEozgR/g7rd0xUimYNlvZRE/K2MgZTjWy725IfelLeVcEM97mmtRGXw==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"binary-extensions": "^2.0.0"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=8"
|
||||
}
|
||||
},
|
||||
"node_modules/is-extglob": {
|
||||
"version": "2.1.1",
|
||||
"resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz",
|
||||
"integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==",
|
||||
"license": "MIT",
|
||||
"engines": {
|
||||
"node": ">=0.10.0"
|
||||
}
|
||||
},
|
||||
"node_modules/is-glob": {
|
||||
"version": "4.0.3",
|
||||
"resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz",
|
||||
"integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"is-extglob": "^2.1.1"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=0.10.0"
|
||||
}
|
||||
},
|
||||
"node_modules/is-number": {
|
||||
"version": "7.0.0",
|
||||
"resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz",
|
||||
"integrity": "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==",
|
||||
"license": "MIT",
|
||||
"engines": {
|
||||
"node": ">=0.12.0"
|
||||
}
|
||||
},
|
||||
"node_modules/minimatch": {
|
||||
"version": "10.2.5",
|
||||
"resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.5.tgz",
|
||||
"integrity": "sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==",
|
||||
"license": "BlueOak-1.0.0",
|
||||
"dependencies": {
|
||||
"brace-expansion": "^5.0.5"
|
||||
},
|
||||
"engines": {
|
||||
"node": "18 || 20 || >=22"
|
||||
},
|
||||
"funding": {
|
||||
"url": "https://github.com/sponsors/isaacs"
|
||||
}
|
||||
},
|
||||
"node_modules/normalize-path": {
|
||||
"version": "3.0.0",
|
||||
"resolved": "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz",
|
||||
"integrity": "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==",
|
||||
"license": "MIT",
|
||||
"engines": {
|
||||
"node": ">=0.10.0"
|
||||
}
|
||||
},
|
||||
"node_modules/picomatch": {
|
||||
"version": "2.3.2",
|
||||
"resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.2.tgz",
|
||||
"integrity": "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==",
|
||||
"license": "MIT",
|
||||
"engines": {
|
||||
"node": ">=8.6"
|
||||
},
|
||||
"funding": {
|
||||
"url": "https://github.com/sponsors/jonschlinkert"
|
||||
}
|
||||
},
|
||||
"node_modules/readdirp": {
|
||||
"version": "3.6.0",
|
||||
"resolved": "https://registry.npmjs.org/readdirp/-/readdirp-3.6.0.tgz",
|
||||
"integrity": "sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"picomatch": "^2.2.1"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=8.10.0"
|
||||
}
|
||||
},
|
||||
"node_modules/to-regex-range": {
|
||||
"version": "5.0.1",
|
||||
"resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz",
|
||||
"integrity": "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"is-number": "^7.0.0"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=8.0"
|
||||
}
|
||||
},
|
||||
"node_modules/typescript": {
|
||||
"version": "5.9.3",
|
||||
"resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
|
||||
"integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
|
||||
"dev": true,
|
||||
"license": "Apache-2.0",
|
||||
"bin": {
|
||||
"tsc": "bin/tsc",
|
||||
"tsserver": "bin/tsserver"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=14.17"
|
||||
}
|
||||
},
|
||||
"node_modules/undici-types": {
|
||||
"version": "7.24.6",
|
||||
"resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.24.6.tgz",
|
||||
"integrity": "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg==",
|
||||
"license": "MIT"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,35 @@
|
||||
{
|
||||
"name": "ai-agent-permission-observability-for-cl",
|
||||
"version": "0.1.0",
|
||||
"description": "CLI observability tool for Claude Code agents — tracks permission violations, bypass attempts, and compressed audit trails",
|
||||
"type": "module",
|
||||
"main": "dist/index.js",
|
||||
"bin": {
|
||||
"claude-permission-observability": "dist/index.js",
|
||||
"cpo": "dist/index.js"
|
||||
},
|
||||
"scripts": {
|
||||
"build": "tsc",
|
||||
"test": "node --test dist/tests/**/*.test.js",
|
||||
"watch": "tsc --watch"
|
||||
},
|
||||
"keywords": [
|
||||
"claude-code",
|
||||
"agent",
|
||||
"observability",
|
||||
"permissions",
|
||||
"audit",
|
||||
"security"
|
||||
],
|
||||
"author": "BunBun Labs",
|
||||
"license": "MIT",
|
||||
"devDependencies": {
|
||||
"typescript": "^5.5.0"
|
||||
},
|
||||
"dependencies": {
|
||||
"@types/node": "^25.9.3",
|
||||
"chokidar": "^3.6.0",
|
||||
"commander": "^12.1.0",
|
||||
"minimatch": "^10.0.0"
|
||||
}
|
||||
}
|
||||
+117
@@ -0,0 +1,117 @@
|
||||
import { appendFileSync, existsSync, mkdirSync, writeFileSync, readFileSync, statSync } from 'fs';
|
||||
import { resolve, dirname } from 'path';
|
||||
import { createHash } from 'crypto';
|
||||
import type { AgentAction, AuditTrail, PermissionManifest } from './types.js';
|
||||
|
||||
export class Auditor {
|
||||
private trailPath: string;
|
||||
private actions: AgentAction[] = [];
|
||||
private manifest: PermissionManifest;
|
||||
private startedAt: Date;
|
||||
private bypassCount = 0;
|
||||
|
||||
constructor(manifest: PermissionManifest, outputDir: string) {
|
||||
this.manifest = manifest;
|
||||
this.trailPath = resolve(outputDir, `audit-${Date.now()}.jsonl`);
|
||||
this.startedAt = new Date();
|
||||
|
||||
if (!existsSync(outputDir)) {
|
||||
mkdirSync(outputDir, { recursive: true });
|
||||
}
|
||||
}
|
||||
|
||||
log(action: AgentAction): void {
|
||||
this.actions.push(action);
|
||||
if (action.resolvedAction === 'deny' || action.type === 'bypass_attempt') {
|
||||
this.bypassCount++;
|
||||
}
|
||||
|
||||
const line = JSON.stringify({
|
||||
...action,
|
||||
timestamp: action.timestamp.toISOString(),
|
||||
});
|
||||
|
||||
appendFileSync(this.trailPath, line + '\n');
|
||||
}
|
||||
|
||||
getTrail(): AuditTrail {
|
||||
return {
|
||||
manifest: this.manifest.name,
|
||||
startedAt: this.startedAt,
|
||||
actions: [...this.actions],
|
||||
summary: {
|
||||
total: this.actions.length,
|
||||
allowed: this.actions.filter(a => a.resolvedAction === 'allow').length,
|
||||
denied: this.actions.filter(a => a.resolvedAction === 'deny').length,
|
||||
warned: this.actions.filter(a => a.resolvedAction === 'warn').length,
|
||||
bypassAttempts: this.bypassCount,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
getBypassCount(): number {
|
||||
return this.bypassCount;
|
||||
}
|
||||
|
||||
close(): AuditTrail {
|
||||
const trail = this.getTrail();
|
||||
trail.endedAt = new Date();
|
||||
|
||||
// Write summary to a companion file
|
||||
const summaryPath = this.trailPath.replace('.jsonl', '-summary.json');
|
||||
writeFileSync(summaryPath, JSON.stringify(trail, null, 2));
|
||||
|
||||
return trail;
|
||||
}
|
||||
|
||||
rotate(): string | null {
|
||||
if (!this.manifest.compression.enabled) return null;
|
||||
|
||||
try {
|
||||
const s = statSync(this.trailPath);
|
||||
const sizeMB = s.size / (1024 * 1024);
|
||||
if (sizeMB < this.manifest.compression.maxTrailSize) return null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
|
||||
// Compress by archiving current trail
|
||||
const hash = createHash('sha256').update(this.trailPath + Date.now()).digest('hex').slice(0, 8);
|
||||
const archivePath = this.trailPath.replace('.jsonl', `-${hash}.jsonl.gz`);
|
||||
return archivePath;
|
||||
}
|
||||
|
||||
static loadFromFile(path: string): AuditTrail {
|
||||
const content = readFileSync(resolve(path), 'utf-8');
|
||||
const lines = content.trim().split('\n');
|
||||
const actions: AgentAction[] = [];
|
||||
|
||||
for (const line of lines) {
|
||||
if (!line.trim()) continue;
|
||||
const parsed = JSON.parse(line);
|
||||
actions.push({
|
||||
...parsed,
|
||||
timestamp: new Date(parsed.timestamp),
|
||||
});
|
||||
}
|
||||
|
||||
const allowed = actions.filter(a => a.resolvedAction === 'allow').length;
|
||||
const denied = actions.filter(a => a.resolvedAction === 'deny').length;
|
||||
const warned = actions.filter(a => a.resolvedAction === 'warn').length;
|
||||
const bypass = actions.filter(a => a.type === 'bypass_attempt' || a.resolvedAction === 'deny').length;
|
||||
|
||||
return {
|
||||
manifest: 'unknown',
|
||||
startedAt: actions.length > 0 ? actions[0].timestamp : new Date(),
|
||||
endedAt: actions.length > 0 ? actions[actions.length - 1].timestamp : new Date(),
|
||||
actions,
|
||||
summary: {
|
||||
total: actions.length,
|
||||
allowed,
|
||||
denied,
|
||||
warned,
|
||||
bypassAttempts: bypass,
|
||||
},
|
||||
};
|
||||
}
|
||||
}
|
||||
+137
@@ -0,0 +1,137 @@
|
||||
import { readFileSync, existsSync } from 'fs';
|
||||
import { resolve } from 'path';
|
||||
import type { PermissionManifest } from './types.js';
|
||||
|
||||
const DEFAULT_MANIFEST: PermissionManifest = {
|
||||
name: 'default',
|
||||
version: '1.0.0',
|
||||
rules: [],
|
||||
defaultAction: 'warn',
|
||||
compression: {
|
||||
enabled: true,
|
||||
maxTrailSize: 50,
|
||||
retentionDays: 30,
|
||||
},
|
||||
sensitivePatterns: [
|
||||
'.env',
|
||||
'secrets',
|
||||
'password',
|
||||
'token',
|
||||
'key',
|
||||
'credential',
|
||||
'private',
|
||||
],
|
||||
};
|
||||
|
||||
export function loadManifest(path: string): PermissionManifest {
|
||||
const fullPath = resolve(path);
|
||||
if (!existsSync(fullPath)) {
|
||||
throw new Error(`Permission manifest not found: ${fullPath}`);
|
||||
}
|
||||
const content = readFileSync(fullPath, 'utf-8');
|
||||
const parsed = JSON.parse(content) as Partial<PermissionManifest>;
|
||||
|
||||
return validateManifest({
|
||||
...DEFAULT_MANIFEST,
|
||||
...parsed,
|
||||
rules: parsed.rules ?? DEFAULT_MANIFEST.rules,
|
||||
compression: {
|
||||
...DEFAULT_MANIFEST.compression,
|
||||
...parsed.compression,
|
||||
},
|
||||
sensitivePatterns: parsed.sensitivePatterns ?? DEFAULT_MANIFEST.sensitivePatterns,
|
||||
});
|
||||
}
|
||||
|
||||
export function validateManifest(manifest: PermissionManifest): PermissionManifest {
|
||||
if (!manifest.name || typeof manifest.name !== 'string') {
|
||||
throw new Error('Manifest must have a valid name');
|
||||
}
|
||||
if (!Array.isArray(manifest.rules)) {
|
||||
throw new Error('Manifest rules must be an array');
|
||||
}
|
||||
for (const rule of manifest.rules) {
|
||||
if (!['file', 'command', 'network', 'env'].includes(rule.type)) {
|
||||
throw new Error(`Invalid rule type: ${rule.type}`);
|
||||
}
|
||||
if (!['allow', 'deny', 'warn'].includes(rule.action)) {
|
||||
throw new Error(`Invalid rule action: ${rule.action}`);
|
||||
}
|
||||
if (!rule.pattern || typeof rule.pattern !== 'string') {
|
||||
throw new Error('Each rule must have a pattern string');
|
||||
}
|
||||
}
|
||||
if (!['allow', 'deny', 'warn'].includes(manifest.defaultAction)) {
|
||||
throw new Error(`Invalid defaultAction: ${manifest.defaultAction}`);
|
||||
}
|
||||
return manifest;
|
||||
}
|
||||
|
||||
export function createDefaultManifest(path: string): PermissionManifest {
|
||||
const manifest: PermissionManifest = {
|
||||
name: 'claude-agent-observability',
|
||||
version: '1.0.0',
|
||||
rules: [
|
||||
{
|
||||
type: 'file',
|
||||
pattern: 'src/**/*.ts',
|
||||
action: 'allow',
|
||||
description: 'Allow editing source files',
|
||||
},
|
||||
{
|
||||
type: 'file',
|
||||
pattern: '**/*.env*',
|
||||
action: 'deny',
|
||||
description: 'Deny access to env files',
|
||||
},
|
||||
{
|
||||
type: 'file',
|
||||
pattern: '**/.ssh/**',
|
||||
action: 'deny',
|
||||
description: 'Deny access to SSH keys',
|
||||
},
|
||||
{
|
||||
type: 'command',
|
||||
pattern: 'git push',
|
||||
action: 'warn',
|
||||
description: 'Warn on git push',
|
||||
},
|
||||
{
|
||||
type: 'command',
|
||||
pattern: 'rm -rf /',
|
||||
action: 'deny',
|
||||
description: 'Deny destructive rm commands',
|
||||
},
|
||||
{
|
||||
type: 'network',
|
||||
pattern: 'localhost:*',
|
||||
action: 'allow',
|
||||
description: 'Allow local development servers',
|
||||
},
|
||||
{
|
||||
type: 'network',
|
||||
pattern: 'api.openai.com',
|
||||
action: 'warn',
|
||||
description: 'Warn on OpenAI API calls',
|
||||
},
|
||||
],
|
||||
defaultAction: 'warn',
|
||||
compression: {
|
||||
enabled: true,
|
||||
maxTrailSize: 50,
|
||||
retentionDays: 30,
|
||||
},
|
||||
sensitivePatterns: [
|
||||
'.env',
|
||||
'secrets',
|
||||
'password',
|
||||
'token',
|
||||
'key',
|
||||
'credential',
|
||||
'private',
|
||||
'apikey',
|
||||
'secret_key',
|
||||
],
|
||||
};
|
||||
return manifest;
|
||||
}
|
||||
+188
@@ -0,0 +1,188 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
import { Command } from 'commander';
|
||||
import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
|
||||
import { resolve, dirname } from 'path';
|
||||
import { loadManifest, createDefaultManifest } from './config.js';
|
||||
import { PermissionWatcher } from './watcher.js';
|
||||
import { Auditor } from './auditor.js';
|
||||
import { Reporter, findLatestAuditTrail } from './reporter.js';
|
||||
|
||||
const pkgPath = resolve(process.cwd(), 'package.json');
|
||||
const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
|
||||
|
||||
const program = new Command();
|
||||
|
||||
program
|
||||
.name('cpo')
|
||||
.description('Claude Permission Observability — monitor agent actions against permission manifests')
|
||||
.version(pkg.version);
|
||||
|
||||
program
|
||||
.command('init')
|
||||
.description('Create a default permission manifest')
|
||||
.argument('[path]', 'Path to create manifest', './permission-manifest.json')
|
||||
.action((path: string) => {
|
||||
const manifest = createDefaultManifest(path);
|
||||
writeFileSync(resolve(path), JSON.stringify(manifest, null, 2));
|
||||
console.log(`Created permission manifest: ${path}`);
|
||||
});
|
||||
|
||||
program
|
||||
.command('watch')
|
||||
.description('Start watching a directory for agent actions')
|
||||
.requiredOption('-m, --manifest <path>', 'Path to permission manifest')
|
||||
.requiredOption('-d, --dir <path>', 'Directory to watch')
|
||||
.option('-a, --agent-id <id>', 'Agent identifier', 'claude-agent')
|
||||
.option('-o, --output <dir>', 'Output directory for audit trails', './cpo-audit')
|
||||
.option('--claude-dir <path>', 'Path to .claude state directory for enhanced monitoring')
|
||||
.option('--ignore <patterns...>', 'Additional ignore patterns')
|
||||
.action((options: Record<string, string>) => {
|
||||
const manifest = loadManifest(options.manifest);
|
||||
const auditor = new Auditor(manifest, options.output);
|
||||
const watcher = new PermissionWatcher(manifest, auditor, {
|
||||
watchDir: resolve(options.dir),
|
||||
claudeDir: options.claudeDir ? resolve(options.claudeDir) : undefined,
|
||||
agentId: options.agentId,
|
||||
ignorePatterns: options.ignore ? options.ignore.split(',') : undefined,
|
||||
});
|
||||
|
||||
watcher.start();
|
||||
|
||||
console.log(`\n[cpo] Started watching: ${resolve(options.dir)}`);
|
||||
console.log(`[cpo] Manifest: ${resolve(options.manifest)}`);
|
||||
console.log(`[cpo] Agent ID: ${options.agentId}`);
|
||||
console.log(`[cpo] Audit output: ${resolve(options.output)}`);
|
||||
console.log(`[cpo] Rules loaded: ${manifest.rules.length}`);
|
||||
console.log(`[cpo] Default action: ${manifest.defaultAction}`);
|
||||
console.log('\nPress Ctrl+C to stop.\n');
|
||||
|
||||
process.on('SIGINT', () => {
|
||||
console.log('\n[cpo] Shutting down...');
|
||||
watcher.stop();
|
||||
const trail = auditor.close();
|
||||
console.log(`\nAudit trail written: ${trail.summary.total} actions recorded`);
|
||||
console.log(` Allowed: ${trail.summary.allowed}`);
|
||||
console.log(` Denied: ${trail.summary.denied}`);
|
||||
console.log(` Warned: ${trail.summary.warned}`);
|
||||
console.log(` Bypass attempts: ${trail.summary.bypassAttempts}`);
|
||||
process.exit(0);
|
||||
});
|
||||
|
||||
process.on('SIGTERM', () => {
|
||||
watcher.stop();
|
||||
auditor.close();
|
||||
process.exit(0);
|
||||
});
|
||||
});
|
||||
|
||||
program
|
||||
.command('report')
|
||||
.description('Generate violation report from audit trail')
|
||||
.option('-i, --input <path>', 'Path to audit trail file')
|
||||
.option('-o, --output <path>', 'Path to write report')
|
||||
.option('--json', 'Output as JSON')
|
||||
.option('-d, --dir <dir>', 'Directory to scan for latest audit trail', './cpo-audit')
|
||||
.action((options: Record<string, string>) => {
|
||||
let inputPath: string | null = options.input || null;
|
||||
|
||||
if (!inputPath) {
|
||||
inputPath = findLatestAuditTrail(options.dir || './cpo-audit');
|
||||
}
|
||||
|
||||
if (!inputPath || !existsSync(inputPath)) {
|
||||
console.error('Error: No audit trail found. Run `cpo watch` first or specify --input.');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const trail = Auditor.loadFromFile(inputPath);
|
||||
const reporter = new Reporter();
|
||||
const report = reporter.generateViolationReport(trail);
|
||||
|
||||
const output = options.json
|
||||
? reporter.formatJsonReport(report)
|
||||
: reporter.formatConsoleReport(report);
|
||||
|
||||
if (options.output) {
|
||||
writeFileSync(resolve(options.output), output);
|
||||
console.log(`Report written to: ${options.output}`);
|
||||
} else {
|
||||
console.log(output);
|
||||
}
|
||||
});
|
||||
|
||||
program
|
||||
.command('log')
|
||||
.description('Log a manual action to the current audit trail')
|
||||
.requiredOption('-m, --manifest <path>', 'Path to permission manifest')
|
||||
.requiredOption('-t, --type <type>', 'Action type: file, command, network, env')
|
||||
.requiredOption('--action <action>', 'Action description')
|
||||
.requiredOption('--target <target>', 'Target of the action')
|
||||
.option('-a, --agent-id <id>', 'Agent identifier', 'manual-agent')
|
||||
.option('-o, --output <dir>', 'Output directory', './cpo-audit')
|
||||
.action(async (options: Record<string, string>) => {
|
||||
const manifest = loadManifest(options.manifest);
|
||||
const auditor = new Auditor(manifest, options.output);
|
||||
const { evaluateAction } = await import('./rules.js');
|
||||
|
||||
// Load existing trail if present
|
||||
const latest = findLatestAuditTrail(options.output);
|
||||
if (latest) {
|
||||
const existing = Auditor.loadFromFile(latest);
|
||||
for (const action of existing.actions) {
|
||||
auditor.log(action);
|
||||
}
|
||||
}
|
||||
|
||||
const action = evaluateAction(
|
||||
manifest,
|
||||
options.type as 'file' | 'command' | 'network' | 'env',
|
||||
options.target,
|
||||
options.action,
|
||||
options.agentId
|
||||
);
|
||||
auditor.log(action);
|
||||
auditor.close();
|
||||
|
||||
console.log(`Logged: ${action.resolvedAction.toUpperCase()} ${options.type} ${options.target}`);
|
||||
});
|
||||
|
||||
program
|
||||
.command('validate')
|
||||
.description('Validate a permission manifest')
|
||||
.argument('<path>', 'Path to manifest')
|
||||
.action((path: string) => {
|
||||
try {
|
||||
loadManifest(path);
|
||||
console.log('✅ Manifest is valid');
|
||||
} catch (err: unknown) {
|
||||
console.error('❌ Invalid manifest:', err instanceof Error ? err.message : String(err));
|
||||
process.exit(1);
|
||||
}
|
||||
});
|
||||
|
||||
program
|
||||
.command('status')
|
||||
.description('Show status of audit directory')
|
||||
.option('-d, --dir <dir>', 'Audit directory', './cpo-audit')
|
||||
.action(async (options: Record<string, string>) => {
|
||||
const dir = resolve(options.dir);
|
||||
if (!existsSync(dir)) {
|
||||
console.log('No audit directory found. Run `cpo watch` first.');
|
||||
return;
|
||||
}
|
||||
|
||||
const { readdirSync, statSync } = await import('fs');
|
||||
const files = readdirSync(dir).filter((f: string) => f.endsWith('.jsonl'));
|
||||
console.log(`Audit trails: ${files.length}`);
|
||||
let totalSize = 0;
|
||||
for (const f of files) {
|
||||
const s = statSync(resolve(dir, f));
|
||||
totalSize += s.size;
|
||||
console.log(` ${f} (${(s.size / 1024).toFixed(1)} KB)`);
|
||||
}
|
||||
console.log(`Total size: ${(totalSize / 1024).toFixed(1)} KB`);
|
||||
});
|
||||
|
||||
program
|
||||
.parse();
|
||||
+132
@@ -0,0 +1,132 @@
|
||||
import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
|
||||
import { resolve } from 'path';
|
||||
import type { AgentAction, AuditTrail, ViolationReport } from './types.js';
|
||||
|
||||
export class Reporter {
|
||||
generateViolationReport(trail: AuditTrail): ViolationReport {
|
||||
const violations = trail.actions.filter(
|
||||
a => a.resolvedAction === 'deny' || a.type === 'bypass_attempt'
|
||||
);
|
||||
|
||||
const ruleCounts = new Map<string, number>();
|
||||
const agentCounts = new Map<string, number>();
|
||||
|
||||
for (const v of violations) {
|
||||
const rule = v.matchedRule || 'default';
|
||||
ruleCounts.set(rule, (ruleCounts.get(rule) || 0) + 1);
|
||||
agentCounts.set(v.agentId, (agentCounts.get(v.agentId) || 0) + 1);
|
||||
}
|
||||
|
||||
const topViolatedRules = Array.from(ruleCounts.entries())
|
||||
.sort((a, b) => b[1] - a[1])
|
||||
.slice(0, 5)
|
||||
.map(([rule, count]) => ({ rule, count }));
|
||||
|
||||
const topAgents = Array.from(agentCounts.entries())
|
||||
.sort((a, b) => b[1] - a[1])
|
||||
.slice(0, 5)
|
||||
.map(([agentId, violations]) => ({ agentId, violations }));
|
||||
|
||||
// Risk score: 0-100 based on violation density + bypass rate
|
||||
const violationRate = trail.summary.total > 0
|
||||
? violations.length / trail.summary.total
|
||||
: 0;
|
||||
const bypassRate = trail.summary.total > 0
|
||||
? trail.summary.bypassAttempts / trail.summary.total
|
||||
: 0;
|
||||
const riskScore = Math.min(100, Math.round(
|
||||
(violationRate * 50) + (bypassRate * 50) + (violations.length * 2)
|
||||
));
|
||||
|
||||
return {
|
||||
timestamp: new Date(),
|
||||
manifest: trail.manifest,
|
||||
violations,
|
||||
topViolatedRules,
|
||||
topAgents,
|
||||
riskScore,
|
||||
};
|
||||
}
|
||||
|
||||
formatConsoleReport(report: ViolationReport): string {
|
||||
const lines: string[] = [];
|
||||
lines.push('');
|
||||
lines.push('╔══════════════════════════════════════════════════════════════╗');
|
||||
lines.push('║ CLAUDE PERMISSION OBSERVABILITY — VIOLATION REPORT ║');
|
||||
lines.push('╚══════════════════════════════════════════════════════════════╝');
|
||||
lines.push('');
|
||||
lines.push(`Manifest: ${report.manifest}`);
|
||||
lines.push(`Generated: ${report.timestamp.toISOString()}`);
|
||||
lines.push(`Risk Score: ${report.riskScore}/100 ${this.riskLabel(report.riskScore)}`);
|
||||
lines.push('');
|
||||
|
||||
if (report.violations.length === 0) {
|
||||
lines.push('✅ No violations detected in this audit trail.');
|
||||
} else {
|
||||
lines.push(`⚠️ ${report.violations.length} violation(s) detected`);
|
||||
lines.push('');
|
||||
|
||||
lines.push('Top Violated Rules:');
|
||||
for (const { rule, count } of report.topViolatedRules) {
|
||||
lines.push(` • ${rule}: ${count} occurrence(s)`);
|
||||
}
|
||||
lines.push('');
|
||||
|
||||
lines.push('Agents with Most Violations:');
|
||||
for (const { agentId, violations } of report.topAgents) {
|
||||
lines.push(` • ${agentId}: ${violations} violation(s)`);
|
||||
}
|
||||
lines.push('');
|
||||
|
||||
lines.push('Recent Violations (last 10):');
|
||||
const recent = report.violations.slice(-10);
|
||||
for (const v of recent) {
|
||||
const time = v.timestamp.toISOString().slice(11, 19);
|
||||
lines.push(` [${time}] ${v.type.toUpperCase().padEnd(8)} ${v.resolvedAction.toUpperCase().padEnd(5)} ${v.target}`);
|
||||
}
|
||||
}
|
||||
|
||||
lines.push('');
|
||||
lines.push('══════════════════════════════════════════════════════════════');
|
||||
lines.push('');
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
formatJsonReport(report: ViolationReport): string {
|
||||
return JSON.stringify({
|
||||
...report,
|
||||
timestamp: report.timestamp.toISOString(),
|
||||
violations: report.violations.map(v => ({
|
||||
...v,
|
||||
timestamp: v.timestamp.toISOString(),
|
||||
})),
|
||||
}, null, 2);
|
||||
}
|
||||
|
||||
private riskLabel(score: number): string {
|
||||
if (score === 0) return '[SAFE]';
|
||||
if (score < 25) return '[LOW]';
|
||||
if (score < 50) return '[MEDIUM]';
|
||||
if (score < 75) return '[HIGH]';
|
||||
return '[CRITICAL]';
|
||||
}
|
||||
}
|
||||
|
||||
export function findLatestAuditTrail(dir: string): string | null {
|
||||
if (!existsSync(dir)) return null;
|
||||
|
||||
const files = readdirSync(dir)
|
||||
.filter((f: string) => f.endsWith('.jsonl') && f.startsWith('audit-'))
|
||||
.map((f: string) => ({ name: f, path: resolve(dir, f) }));
|
||||
|
||||
if (files.length === 0) return null;
|
||||
|
||||
files.sort((a: {path: string}, b: {path: string}) => {
|
||||
const statA = statSync(a.path).mtimeMs;
|
||||
const statB = statSync(b.path).mtimeMs;
|
||||
return statB - statA;
|
||||
});
|
||||
|
||||
return files[0].path;
|
||||
}
|
||||
@@ -0,0 +1,68 @@
|
||||
import { minimatch } from 'minimatch';
|
||||
import type { PermissionManifest, PermissionRule, AgentAction } from './types.js';
|
||||
|
||||
export function evaluateAction(
|
||||
manifest: PermissionManifest,
|
||||
type: AgentAction['type'],
|
||||
target: string,
|
||||
action: string,
|
||||
agentId: string
|
||||
): AgentAction {
|
||||
const actionId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
|
||||
|
||||
// Check each rule in order
|
||||
for (const rule of manifest.rules) {
|
||||
if (rule.type !== type && rule.type !== 'env') continue;
|
||||
|
||||
const matches = minimatch(target, rule.pattern, { dot: true }) ||
|
||||
target.toLowerCase().includes(rule.pattern.toLowerCase()) ||
|
||||
action.toLowerCase().includes(rule.pattern.toLowerCase());
|
||||
|
||||
if (matches) {
|
||||
return {
|
||||
id: actionId,
|
||||
timestamp: new Date(),
|
||||
agentId,
|
||||
type,
|
||||
action,
|
||||
target,
|
||||
resolvedAction: rule.action,
|
||||
matchedRule: rule.description || rule.pattern,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
// Check sensitive patterns for implicit warnings
|
||||
for (const pattern of manifest.sensitivePatterns) {
|
||||
if (target.toLowerCase().includes(pattern.toLowerCase()) ||
|
||||
action.toLowerCase().includes(pattern.toLowerCase())) {
|
||||
return {
|
||||
id: actionId,
|
||||
timestamp: new Date(),
|
||||
agentId,
|
||||
type: 'bypass_attempt',
|
||||
action,
|
||||
target,
|
||||
resolvedAction: 'warn',
|
||||
matchedRule: `sensitive-pattern:${pattern}`,
|
||||
details: { reason: 'Accessed path matching sensitive pattern' },
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
// Default action
|
||||
return {
|
||||
id: actionId,
|
||||
timestamp: new Date(),
|
||||
agentId,
|
||||
type,
|
||||
action,
|
||||
target,
|
||||
resolvedAction: manifest.defaultAction,
|
||||
};
|
||||
}
|
||||
|
||||
export function getEffectiveRules(manifest: PermissionManifest, type?: AgentAction['type']): PermissionRule[] {
|
||||
if (!type) return manifest.rules;
|
||||
return manifest.rules.filter(r => r.type === type || r.type === 'env');
|
||||
}
|
||||
@@ -0,0 +1,267 @@
|
||||
import { test } from 'node:test';
|
||||
import assert from 'node:assert';
|
||||
import { writeFileSync, mkdirSync, rmSync, existsSync, readFileSync, readdirSync, statSync } from 'fs';
|
||||
import { resolve } from 'path';
|
||||
import { evaluateAction, getEffectiveRules } from '../rules.js';
|
||||
import { loadManifest, validateManifest, createDefaultManifest } from '../config.js';
|
||||
import { Auditor } from '../auditor.js';
|
||||
import { Reporter, findLatestAuditTrail } from '../reporter.js';
|
||||
import type { PermissionManifest, AgentAction } from '../types.js';
|
||||
|
||||
const TEST_DIR = resolve('/tmp/cpo-test-' + Date.now());
|
||||
|
||||
function setup(): void {
|
||||
if (existsSync(TEST_DIR)) {
|
||||
rmSync(TEST_DIR, { recursive: true });
|
||||
}
|
||||
mkdirSync(TEST_DIR, { recursive: true });
|
||||
}
|
||||
|
||||
function teardown(): void {
|
||||
if (existsSync(TEST_DIR)) {
|
||||
rmSync(TEST_DIR, { recursive: true });
|
||||
}
|
||||
}
|
||||
|
||||
const TEST_MANIFEST: PermissionManifest = {
|
||||
name: 'test-manifest',
|
||||
version: '1.0.0',
|
||||
rules: [
|
||||
{ type: 'file', pattern: 'src/**/*.ts', action: 'allow' },
|
||||
{ type: 'file', pattern: '**/*.env*', action: 'deny' },
|
||||
{ type: 'command', pattern: 'git push', action: 'warn' },
|
||||
{ type: 'command', pattern: 'rm -rf /', action: 'deny' },
|
||||
],
|
||||
defaultAction: 'warn',
|
||||
compression: { enabled: true, maxTrailSize: 10, retentionDays: 7 },
|
||||
sensitivePatterns: ['.env', 'secret'],
|
||||
};
|
||||
|
||||
// --- Config Tests ---
|
||||
|
||||
test('validateManifest accepts valid manifest', () => {
|
||||
assert.doesNotThrow(() => validateManifest(TEST_MANIFEST));
|
||||
});
|
||||
|
||||
test('validateManifest rejects empty name', () => {
|
||||
assert.throws(() => validateManifest({ ...TEST_MANIFEST, name: '' }), /name/);
|
||||
});
|
||||
|
||||
test('validateManifest rejects invalid rule type', () => {
|
||||
const bad = {
|
||||
...TEST_MANIFEST,
|
||||
rules: [{ type: 'invalid', pattern: 'x', action: 'allow' }],
|
||||
};
|
||||
assert.throws(() => validateManifest(bad as PermissionManifest), /Invalid rule type/);
|
||||
});
|
||||
|
||||
test('validateManifest rejects invalid action', () => {
|
||||
const bad = {
|
||||
...TEST_MANIFEST,
|
||||
rules: [{ type: 'file', pattern: 'x', action: 'invalid' }],
|
||||
};
|
||||
assert.throws(() => validateManifest(bad as PermissionManifest), /Invalid rule action/);
|
||||
});
|
||||
|
||||
test('loadManifest reads and parses JSON file', () => {
|
||||
setup();
|
||||
const path = resolve(TEST_DIR, 'manifest.json');
|
||||
writeFileSync(path, JSON.stringify(TEST_MANIFEST));
|
||||
const loaded = loadManifest(path);
|
||||
assert.equal(loaded.name, 'test-manifest');
|
||||
assert.equal(loaded.rules.length, 4);
|
||||
teardown();
|
||||
});
|
||||
|
||||
test('loadManifest throws on missing file', () => {
|
||||
assert.throws(() => loadManifest('/nonexistent/manifest.json'), /not found/);
|
||||
});
|
||||
|
||||
// --- Rules Tests ---
|
||||
|
||||
test('evaluateAction allows matching allow rule', () => {
|
||||
const action = evaluateAction(TEST_MANIFEST, 'file', 'src/main.ts', 'fs.write', 'agent-1');
|
||||
assert.equal(action.resolvedAction, 'allow');
|
||||
assert.equal(action.matchedRule, 'src/**/*.ts');
|
||||
});
|
||||
|
||||
test('evaluateAction denies matching deny rule', () => {
|
||||
const action = evaluateAction(TEST_MANIFEST, 'file', '.env.local', 'fs.read', 'agent-1');
|
||||
assert.equal(action.resolvedAction, 'deny');
|
||||
assert.equal(action.matchedRule, '**/*.env*');
|
||||
});
|
||||
|
||||
test('evaluateAction warns on default for non-matching paths', () => {
|
||||
const action = evaluateAction(TEST_MANIFEST, 'file', 'README.md', 'fs.read', 'agent-1');
|
||||
assert.equal(action.resolvedAction, 'warn');
|
||||
});
|
||||
|
||||
test('evaluateAction detects sensitive patterns as bypass', () => {
|
||||
const action = evaluateAction(TEST_MANIFEST, 'file', 'config/secrets.json', 'fs.read', 'agent-1');
|
||||
assert.equal(action.type, 'bypass_attempt');
|
||||
assert.equal(action.resolvedAction, 'warn');
|
||||
assert.ok(action.matchedRule?.includes('sensitive-pattern'));
|
||||
});
|
||||
|
||||
test('evaluateAction matches command patterns', () => {
|
||||
const action = evaluateAction(TEST_MANIFEST, 'command', 'git push origin main', 'git.push', 'agent-1');
|
||||
assert.equal(action.resolvedAction, 'warn');
|
||||
assert.equal(action.matchedRule, 'git push');
|
||||
});
|
||||
|
||||
test('evaluateAction denies dangerous commands', () => {
|
||||
const action = evaluateAction(TEST_MANIFEST, 'command', 'rm -rf /', 'rm', 'agent-1');
|
||||
assert.equal(action.resolvedAction, 'deny');
|
||||
});
|
||||
|
||||
test('getEffectiveRules returns all rules when no type filter', () => {
|
||||
const rules = getEffectiveRules(TEST_MANIFEST);
|
||||
assert.equal(rules.length, 4);
|
||||
});
|
||||
|
||||
test('getEffectiveRules filters by type', () => {
|
||||
const rules = getEffectiveRules(TEST_MANIFEST, 'command');
|
||||
assert.equal(rules.length, 2);
|
||||
assert.equal(rules[0].type, 'command');
|
||||
});
|
||||
|
||||
// --- Auditor Tests ---
|
||||
|
||||
test('Auditor logs actions and produces summary', () => {
|
||||
setup();
|
||||
const auditor = new Auditor(TEST_MANIFEST, TEST_DIR);
|
||||
auditor.log(makeAction('allow', 'file', 'src/main.ts'));
|
||||
auditor.log(makeAction('deny', 'file', '.env'));
|
||||
auditor.log(makeAction('warn', 'command', 'git push'));
|
||||
|
||||
const trail = auditor.getTrail();
|
||||
assert.equal(trail.summary.total, 3);
|
||||
assert.equal(trail.summary.allowed, 1);
|
||||
assert.equal(trail.summary.denied, 1);
|
||||
assert.equal(trail.summary.warned, 1);
|
||||
|
||||
auditor.close();
|
||||
teardown();
|
||||
});
|
||||
|
||||
test('Auditor writes JSONL to file', () => {
|
||||
setup();
|
||||
const auditor = new Auditor(TEST_MANIFEST, TEST_DIR);
|
||||
auditor.log(makeAction('allow', 'file', 'src/main.ts'));
|
||||
auditor.close();
|
||||
|
||||
const files = existsSync(TEST_DIR) ? readdirSync(TEST_DIR) : [];
|
||||
const jsonl = files.find((f: string) => f.endsWith('.jsonl'));
|
||||
assert.ok(jsonl, 'JSONL file should exist');
|
||||
teardown();
|
||||
});
|
||||
|
||||
test('Auditor.loadFromFile reads back trail', () => {
|
||||
setup();
|
||||
const auditor = new Auditor(TEST_MANIFEST, TEST_DIR);
|
||||
auditor.log(makeAction('deny', 'file', '.env'));
|
||||
auditor.close();
|
||||
|
||||
const files = readdirSync(TEST_DIR).filter((f: string) => f.endsWith('.jsonl'));
|
||||
const path = resolve(TEST_DIR, files[0]);
|
||||
const loaded = Auditor.loadFromFile(path);
|
||||
assert.equal(loaded.summary.total, 1);
|
||||
assert.equal(loaded.summary.denied, 1);
|
||||
teardown();
|
||||
});
|
||||
|
||||
test('Auditor counts bypass attempts', () => {
|
||||
setup();
|
||||
const auditor = new Auditor(TEST_MANIFEST, TEST_DIR);
|
||||
auditor.log(makeAction('deny', 'file', '.env'));
|
||||
auditor.log(makeAction('warn', 'bypass_attempt', 'secrets.txt'));
|
||||
assert.equal(auditor.getBypassCount(), 2);
|
||||
teardown();
|
||||
});
|
||||
|
||||
// --- Reporter Tests ---
|
||||
|
||||
test('Reporter generates violation report', () => {
|
||||
const trail: import('../types.js').AuditTrail = {
|
||||
manifest: 'test',
|
||||
startedAt: new Date(),
|
||||
actions: [
|
||||
makeAction('allow', 'file', 'src/main.ts'),
|
||||
makeAction('deny', 'file', '.env'),
|
||||
makeAction('deny', 'command', 'rm -rf /'),
|
||||
],
|
||||
summary: { total: 3, allowed: 1, denied: 2, warned: 0, bypassAttempts: 2 },
|
||||
};
|
||||
|
||||
const reporter = new Reporter();
|
||||
const report = reporter.generateViolationReport(trail);
|
||||
assert.equal(report.violations.length, 2);
|
||||
assert.ok(report.riskScore > 0);
|
||||
assert.equal(report.topViolatedRules.length, 2);
|
||||
});
|
||||
|
||||
test('Reporter formatConsoleReport includes headers and data', () => {
|
||||
const trail: import('../types.js').AuditTrail = {
|
||||
manifest: 'test',
|
||||
startedAt: new Date(),
|
||||
actions: [],
|
||||
summary: { total: 0, allowed: 0, denied: 0, warned: 0, bypassAttempts: 0 },
|
||||
};
|
||||
|
||||
const reporter = new Reporter();
|
||||
const report = reporter.generateViolationReport(trail);
|
||||
const output = reporter.formatConsoleReport(report);
|
||||
assert.ok(output.includes('SAFE'));
|
||||
assert.ok(output.includes('No violations'));
|
||||
});
|
||||
|
||||
test('Reporter formatJsonReport produces valid JSON', () => {
|
||||
const trail: import('../types.js').AuditTrail = {
|
||||
manifest: 'test',
|
||||
startedAt: new Date(),
|
||||
actions: [makeAction('deny', 'file', '.env')],
|
||||
summary: { total: 1, allowed: 0, denied: 1, warned: 0, bypassAttempts: 1 },
|
||||
};
|
||||
|
||||
const reporter = new Reporter();
|
||||
const report = reporter.generateViolationReport(trail);
|
||||
const json = reporter.formatJsonReport(report);
|
||||
const parsed = JSON.parse(json);
|
||||
assert.equal(parsed.violations.length, 1);
|
||||
assert.equal(parsed.riskScore, report.riskScore);
|
||||
});
|
||||
|
||||
test('findLatestAuditTrail returns most recent file', async () => {
|
||||
setup();
|
||||
writeFileSync(resolve(TEST_DIR, 'audit-1000.jsonl'), '');
|
||||
await new Promise(r => setTimeout(r, 10));
|
||||
writeFileSync(resolve(TEST_DIR, 'audit-2000.jsonl'), '');
|
||||
await new Promise(r => setTimeout(r, 10));
|
||||
writeFileSync(resolve(TEST_DIR, 'audit-3000.jsonl'), '');
|
||||
|
||||
const latest = findLatestAuditTrail(TEST_DIR);
|
||||
assert.ok(latest?.includes('audit-3000'));
|
||||
teardown();
|
||||
});
|
||||
|
||||
test('findLatestAuditTrail returns null for empty dir', () => {
|
||||
setup();
|
||||
const result = findLatestAuditTrail(TEST_DIR);
|
||||
assert.equal(result, null);
|
||||
teardown();
|
||||
});
|
||||
|
||||
// --- Helper ---
|
||||
|
||||
function makeAction(resolved: 'allow' | 'deny' | 'warn', type: AgentAction['type'], target: string): AgentAction {
|
||||
return {
|
||||
id: `test-${Date.now()}-${Math.random()}`,
|
||||
timestamp: new Date(),
|
||||
agentId: 'test-agent',
|
||||
type,
|
||||
action: `test.${type}`,
|
||||
target,
|
||||
resolvedAction: resolved,
|
||||
matchedRule: target,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,54 @@
|
||||
export interface PermissionRule {
|
||||
type: 'file' | 'command' | 'network' | 'env';
|
||||
pattern: string;
|
||||
action: 'allow' | 'deny' | 'warn';
|
||||
description?: string;
|
||||
}
|
||||
|
||||
export interface PermissionManifest {
|
||||
name: string;
|
||||
version: string;
|
||||
rules: PermissionRule[];
|
||||
defaultAction: 'allow' | 'deny' | 'warn';
|
||||
compression: {
|
||||
enabled: boolean;
|
||||
maxTrailSize: number; // in MB
|
||||
retentionDays: number;
|
||||
};
|
||||
sensitivePatterns: string[];
|
||||
}
|
||||
|
||||
export interface AgentAction {
|
||||
id: string;
|
||||
timestamp: Date;
|
||||
agentId: string;
|
||||
type: 'file' | 'command' | 'network' | 'env' | 'bypass_attempt';
|
||||
action: string;
|
||||
target: string;
|
||||
resolvedAction: 'allow' | 'deny' | 'warn' | 'unknown';
|
||||
matchedRule?: string;
|
||||
details?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
export interface AuditTrail {
|
||||
manifest: string;
|
||||
startedAt: Date;
|
||||
endedAt?: Date;
|
||||
actions: AgentAction[];
|
||||
summary: {
|
||||
total: number;
|
||||
allowed: number;
|
||||
denied: number;
|
||||
warned: number;
|
||||
bypassAttempts: number;
|
||||
};
|
||||
}
|
||||
|
||||
export interface ViolationReport {
|
||||
timestamp: Date;
|
||||
manifest: string;
|
||||
violations: AgentAction[];
|
||||
topViolatedRules: Array<{ rule: string; count: number }>;
|
||||
topAgents: Array<{ agentId: string; violations: number }>;
|
||||
riskScore: number; // 0-100
|
||||
}
|
||||
+204
@@ -0,0 +1,204 @@
|
||||
import { watch, type FSWatcher } from 'chokidar';
|
||||
import { readFileSync, existsSync } from 'fs';
|
||||
import { resolve, relative } from 'path';
|
||||
import { evaluateAction } from './rules.js';
|
||||
import { Auditor } from './auditor.js';
|
||||
import type { PermissionManifest } from './types.js';
|
||||
|
||||
export interface WatcherOptions {
|
||||
watchDir: string;
|
||||
claudeDir?: string; // Path to .claude directory or conversation logs
|
||||
agentId: string;
|
||||
ignorePatterns?: string[];
|
||||
}
|
||||
|
||||
export class PermissionWatcher {
|
||||
private watcher: FSWatcher | null = null;
|
||||
private manifest: PermissionManifest;
|
||||
private auditor: Auditor;
|
||||
private options: WatcherOptions;
|
||||
private active = false;
|
||||
|
||||
constructor(manifest: PermissionManifest, auditor: Auditor, options: WatcherOptions) {
|
||||
this.manifest = manifest;
|
||||
this.auditor = auditor;
|
||||
this.options = options;
|
||||
}
|
||||
|
||||
start(): void {
|
||||
if (this.active) {
|
||||
console.log('[cpo] Watcher already running');
|
||||
return;
|
||||
}
|
||||
|
||||
const watchPaths = [resolve(this.options.watchDir)];
|
||||
|
||||
// Also watch Claude Code state directory if provided
|
||||
if (this.options.claudeDir && existsSync(this.options.claudeDir)) {
|
||||
watchPaths.push(resolve(this.options.claudeDir));
|
||||
}
|
||||
|
||||
const ignore = [
|
||||
'**/node_modules/**',
|
||||
'**/.git/**',
|
||||
'**/dist/**',
|
||||
'**/*.log',
|
||||
...(this.options.ignorePatterns || []),
|
||||
];
|
||||
|
||||
this.watcher = watch(watchPaths, {
|
||||
ignored: ignore,
|
||||
persistent: true,
|
||||
ignoreInitial: false,
|
||||
followSymlinks: false,
|
||||
depth: 5,
|
||||
});
|
||||
|
||||
this.watcher.on('add', (path) => this.handleFileChange('add', path));
|
||||
this.watcher.on('change', (path) => this.handleFileChange('change', path));
|
||||
this.watcher.on('unlink', (path) => this.handleFileChange('unlink', path));
|
||||
this.watcher.on('addDir', (path) => this.handleFileChange('addDir', path));
|
||||
this.watcher.on('unlinkDir', (path) => this.handleFileChange('unlinkDir', path));
|
||||
|
||||
this.watcher.on('ready', () => {
|
||||
console.log(`[cpo] Watcher ready — monitoring ${watchPaths.length} path(s)`);
|
||||
});
|
||||
|
||||
this.watcher.on('error', (err) => {
|
||||
console.error('[cpo] Watcher error:', err.message);
|
||||
});
|
||||
|
||||
this.active = true;
|
||||
|
||||
// If Claude directory is watched, periodically scan for new state
|
||||
if (this.options.claudeDir) {
|
||||
this.pollClaudeState();
|
||||
}
|
||||
}
|
||||
|
||||
stop(): void {
|
||||
if (this.watcher) {
|
||||
this.watcher.close();
|
||||
this.watcher = null;
|
||||
}
|
||||
this.active = false;
|
||||
console.log('[cpo] Watcher stopped');
|
||||
}
|
||||
|
||||
isActive(): boolean {
|
||||
return this.active;
|
||||
}
|
||||
|
||||
private handleFileChange(event: string, path: string): void {
|
||||
const relativePath = relative(this.options.watchDir, path);
|
||||
const action = evaluateAction(
|
||||
this.manifest,
|
||||
'file',
|
||||
relativePath,
|
||||
`fs.${event}`,
|
||||
this.options.agentId
|
||||
);
|
||||
|
||||
this.auditor.log(action);
|
||||
|
||||
if (action.resolvedAction === 'deny') {
|
||||
console.log(`[DENY] ${event}: ${relativePath} (${action.matchedRule || 'default'})`);
|
||||
} else if (action.resolvedAction === 'warn') {
|
||||
console.log(`[WARN] ${event}: ${relativePath} (${action.matchedRule || 'default'})`);
|
||||
}
|
||||
}
|
||||
|
||||
private pollClaudeState(): void {
|
||||
if (!this.active) return;
|
||||
|
||||
// Check for .claude/messages or state files to infer command activity
|
||||
const claudeDir = resolve(this.options.claudeDir!);
|
||||
if (existsSync(claudeDir)) {
|
||||
try {
|
||||
// Look for tool use patterns in Claude state files
|
||||
const stateFiles = [
|
||||
resolve(claudeDir, 'state.json'),
|
||||
resolve(claudeDir, 'messages.json'),
|
||||
];
|
||||
|
||||
for (const stateFile of stateFiles) {
|
||||
if (existsSync(stateFile)) {
|
||||
try {
|
||||
const content = readFileSync(stateFile, 'utf-8');
|
||||
const parsed = JSON.parse(content);
|
||||
|
||||
// Detect command patterns in state
|
||||
if (parsed.messages && Array.isArray(parsed.messages)) {
|
||||
for (const msg of parsed.messages.slice(-10)) {
|
||||
if (msg.tool_use || msg.tool_calls) {
|
||||
const tools = msg.tool_use || msg.tool_calls || [];
|
||||
for (const tool of tools) {
|
||||
if (tool.name) {
|
||||
const action = evaluateAction(
|
||||
this.manifest,
|
||||
'command',
|
||||
tool.name,
|
||||
tool.name,
|
||||
this.options.agentId
|
||||
);
|
||||
this.auditor.log(action);
|
||||
|
||||
if (action.resolvedAction === 'deny') {
|
||||
console.log(`[DENY] Tool: ${tool.name} (${action.matchedRule || 'default'})`);
|
||||
} else if (action.resolvedAction === 'warn') {
|
||||
console.log(`[WARN] Tool: ${tool.name} (${action.matchedRule || 'default'})`);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
// Ignore parse errors in state files
|
||||
}
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
// Ignore errors
|
||||
}
|
||||
}
|
||||
|
||||
// Poll every 5 seconds
|
||||
setTimeout(() => this.pollClaudeState(), 5000);
|
||||
}
|
||||
|
||||
recordCommand(command: string, args: string[] = []): void {
|
||||
const fullCommand = `${command} ${args.join(' ')}`.trim();
|
||||
const action = evaluateAction(
|
||||
this.manifest,
|
||||
'command',
|
||||
fullCommand,
|
||||
fullCommand,
|
||||
this.options.agentId
|
||||
);
|
||||
this.auditor.log(action);
|
||||
|
||||
if (action.resolvedAction === 'deny') {
|
||||
console.log(`[DENY] Command: ${fullCommand} (${action.matchedRule || 'default'})`);
|
||||
} else if (action.resolvedAction === 'warn') {
|
||||
console.log(`[WARN] Command: ${fullCommand} (${action.matchedRule || 'default'})`);
|
||||
}
|
||||
}
|
||||
|
||||
recordNetworkRequest(url: string, method: string = 'GET'): void {
|
||||
const action = evaluateAction(
|
||||
this.manifest,
|
||||
'network',
|
||||
url,
|
||||
`${method} ${url}`,
|
||||
this.options.agentId
|
||||
);
|
||||
this.auditor.log(action);
|
||||
|
||||
if (action.resolvedAction === 'deny') {
|
||||
console.log(`[DENY] Network: ${method} ${url} (${action.matchedRule || 'default'})`);
|
||||
} else if (action.resolvedAction === 'warn') {
|
||||
console.log(`[WARN] Network: ${method} ${url} (${action.matchedRule || 'default'})`);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,21 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2022",
|
||||
"module": "NodeNext",
|
||||
"moduleResolution": "NodeNext",
|
||||
"lib": ["ES2022"],
|
||||
"outDir": "./dist",
|
||||
"rootDir": "./src",
|
||||
"strict": true,
|
||||
"esModuleInterop": true,
|
||||
"skipLibCheck": true,
|
||||
"forceConsistentCasingInFileNames": true,
|
||||
"declaration": true,
|
||||
"declarationMap": true,
|
||||
"sourceMap": true,
|
||||
"resolveJsonModule": true,
|
||||
"allowJs": true
|
||||
},
|
||||
"include": ["src/**/*"],
|
||||
"exclude": ["node_modules", "dist"]
|
||||
}
|
||||
Reference in New Issue
Block a user