Agent Police Department v1.0.0 MVP

2026-06-14 13:18:56 +00:00
commit 672e9ef17c
30 changed files with 7619 additions and 0 deletions
@@ -0,0 +1,154 @@
+# SPEC.md — Agent Police Department (Chrome Extension)
+
+## Product Identity
+- **Name**: Agent Police Department
+- **Tagline**: A police dashboard for your team's AI coding agents
+- **Slug**: `agent-police-department-claude-code-agent-governan`
+- **Form**: Chrome Extension (Manifest V3)
+- **Tech Tier**: Simple
+
+## Problem Statement
+Teams adopting AI coding agents (Claude Code, Cursor, GitHub Copilot, etc.) lack visibility and governance. 65% of enterprises had security incidents from AI agents by April 2026. Only 30% have comprehensive governance. Small teams (5–50 devs) are priced out of enterprise tools ($10+/seat) and find open-source CLI tools too hard to use.
+
+## Solution
+A lightweight Chrome extension that provides real-time visibility into AI coding agent activity, audit trails, and policy violation alerts — all running locally in the browser without a backend server.
+
+## MVP Scope (v1.0)
+
+### Core Features
+1. **Agent Activity Monitor**
+   - Content scripts detect AI agent interactions on Claude.ai, GitHub, and ChatGPT
+   - Captures: tool use, file access, API calls, code generation events
+   - Timestamps every event with URL context
+
+2. **Policy Engine (6 Detectors)**
+   - Permission Bypass: agent accesses files outside allowed scope
+   - Out-of-Scope: agent performs tasks beyond its mandate
+   - Self-Permissioning: agent attempts to modify its own permissions
+   - Disallowed Tools: agent uses blacklisted tools/APIs
+   - Redundant Operations: repeated identical actions
+   - Off-Task: agent drifts from assigned task
+
+3. **Real-Time Dashboard (Popup)**
+   - Active session count and status
+   - Per-agent activity feed (last 50 events)
+   - Violation alerts with severity (Low / Medium / High / Critical)
+   - Team risk score (0–100)
+   - Compliance status indicator
+
+4. **Audit Log**
+   - Local storage with 7-day retention
+   - Searchable by agent, URL, severity, detector type
+   - Export to JSON/CSV
+   - Hash-chained integrity verification (tamper-evident)
+
+5. **Policy Management**
+   - Default policy YAML loaded on install
+   - User can edit rules via popup UI
+   - Rule types: allowed domains, allowed tools, file patterns, rate limits
+
+### Architecture
+```
+manifest.json (V3)
+├── background.js (service worker)
+│   ├── Event collector
+│   ├── Policy engine
+│   ├── Audit log storage
+│   └── Alert dispatcher
+├── content_script.js
+│   ├── Claude.ai detector
+│   ├── GitHub detector
+│   └── ChatGPT detector
+├── popup.html + popup.js + popup.css
+│   ├── Dashboard UI
+│   ├── Policy editor
+│   └── Audit log viewer
+├── options.html + options.js
+│   └── Advanced settings
+├── lib/
+│   ├── detectors.js (6 violation detectors)
+│   ├── policy.js (rule engine)
+│   ├── audit.js (storage + integrity)
+│   └── hash.js (sha256 chain)
+├── default_policy.yaml
+└── tests/
+    ├── detectors.test.js
+    ├── policy.test.js
+    └── audit.test.js
+```
+
+### Tech Stack
+- Chrome Extension Manifest V3
+- Vanilla JavaScript (no build step required for MVP)
+- Chrome Storage API (local)
+- Web Crypto API (SHA-256 for integrity)
+- Jest for unit tests
+- ESLint for linting
+
+### Data Model
+```json
+{
+  "event": {
+    "id": "uuid",
+    "timestamp": "ISO8601",
+    "agent": "claude-code|cursor|copilot|chatgpt",
+    "url": "https://claude.ai/chat/...",
+    "type": "tool_use|file_access|code_generation|api_call|permission_request",
+    "tool": "read_file|edit_file|bash|api_request",
+    "target": "file_path_or_endpoint",
+    "outcome": "allowed|denied|violation",
+    "severity": "info|low|medium|high|critical"
+  },
+  "violation": {
+    "id": "uuid",
+    "event_id": "uuid",
+    "detector": "permission_bypass|out_of_scope|...",
+    "rule_triggered": "rule_id",
+    "severity": "low|medium|high|critical",
+    "message": "human readable explanation",
+    "timestamp": "ISO8601"
+  },
+  "policy": {
+    "version": 1,
+    "rules": [
+      {
+        "id": "rule_1",
+        "type": "allowed_domains",
+        "enabled": true,
+        "params": { "domains": ["github.com", "claude.ai", "api.openai.com"] }
+      },
+      {
+        "id": "rule_2",
+        "type": "disallowed_tools",
+        "enabled": true,
+        "params": { "tools": ["eval", "exec", "shell"] }
+      }
+    ]
+  }
+}
+```
+
+### Build Requirements
+- `npm test` must pass (Jest)
+- `npm run lint` must pass (ESLint)
+- Anti-skeleton: every function has real implementation
+- No placeholder returns, no TODOs in shipped code
+- Secret scan: no API keys, credentials, or tokens in source
+
+### Distribution
+- Chrome Web Store (free tier)
+- GitHub release with built `.zip`
+- Source code at https://git.bunbunlabs.com/bunbun/agent-police-department-claude-code-agent-governan
+
+### Future Roadmap (post-MVP)
+- Team sync via cloud backend
+- Slack/Discord alerts
+- GitHub PR annotations
+- SSO integration
+- SIEM export (Splunk/Datadog)
+- Mobile push notifications
+
+## Verdict
+- **Buildable**: Yes — Chrome extension, no backend required
+- **Gated**: No — local-only for MVP, no server/DB/auth needed
+- **Category**: Chrome Extension