create-hq 5.0.0

package/template/knowledge/ai-security-framework/configs/audit-logging.md

@@ -0,0 +1,372 @@
+# Audit Logging Configuration
+
+> What to log, how to log it, and how to use logs for security
+
+---
+
+## Why Logging Matters
+
+Without logs, you have no visibility into what AI agents are doing. When something goes wrong—and eventually something will—logs are your forensic evidence, your debugging tool, and your compliance documentation.
+
+**Key stat:** Audit logging adds 5-10ms latency and ~15% monthly storage growth for active agents. This is worth it.
+
+---
+
+## What to Log
+
+### Required Fields (Minimum Viable Logging)
+
+Every AI action should capture:
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `timestamp` | UTC time of action | `2025-12-14T15:30:00Z` |
+| `action_type` | Category of action | `browser_navigate`, `file_write`, `api_call` |
+| `target` | What was acted upon | `https://example.com`, `/path/to/file` |
+| `outcome` | Result | `success`, `failure`, `blocked` |
+| `session_id` | Groups related actions | `sess_abc123` |
+
+### Recommended Fields (Better Visibility)
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `agent_id` | Which AI agent | `claude-chrome-main` |
+| `user_id` | Human associated | `corey@example.com` |
+| `request_id` | Unique action ID | `req_xyz789` |
+| `duration_ms` | Time to complete | `1234` |
+| `input_summary` | What was requested | `"Navigate to docs"` |
+| `output_summary` | What was returned | `"Page loaded"` |
+| `error_details` | If failed, why | `"Access denied"` |
+| `ip_address` | Source | `192.168.1.1` |
+| `risk_level` | Assessed risk | `low`, `medium`, `high` |
+
+### Comprehensive Fields (Full Forensics)
+
+For critical environments, also log:
+
+| Field | Description |
+|-------|-------------|
+| `parent_session_id` | For nested operations |
+| `model_version` | AI model used |
+| `prompt_hash` | Hash of prompt (not full prompt, for privacy) |
+| `context_window_usage` | How full was context |
+| `tokens_used` | Token consumption |
+| `cost_usd` | Estimated cost |
+| `policy_checks` | Which policies were evaluated |
+| `approval_chain` | Who approved (if applicable) |
+
+---
+
+## Log Format
+
+### Structured JSON (Recommended)
+
+```json
+{
+  "timestamp": "2025-12-14T15:30:00.123Z",
+  "level": "INFO",
+  "action_type": "browser_navigate",
+  "agent_id": "claude-chrome-main",
+  "session_id": "sess_abc123",
+  "request_id": "req_xyz789",
+  "target": "https://docs.example.com/api",
+  "outcome": "success",
+  "duration_ms": 1234,
+  "risk_level": "low",
+  "metadata": {
+    "page_title": "API Documentation",
+    "response_code": 200
+  }
+}
+```
+
+### Log Levels
+
+| Level | Use For | Example |
+|-------|---------|---------|
+| `DEBUG` | Detailed tracing | Step-by-step navigation |
+| `INFO` | Normal operations | "Navigated to page" |
+| `WARN` | Concerning but handled | "Blocked site attempted" |
+| `ERROR` | Failures | "API call failed" |
+| `CRITICAL` | Security events | "Credential access attempt" |
+
+---
+
+## Action-Specific Logging
+
+### Browser Actions
+
+```json
+{
+  "action_type": "browser_navigate",
+  "target": "https://example.com/page",
+  "metadata": {
+    "previous_url": "https://previous.com",
+    "navigation_type": "link_click",
+    "blocked": false,
+    "security_warnings": []
+  }
+}
+```
+
+```json
+{
+  "action_type": "browser_form_submit",
+  "target": "https://example.com/form",
+  "metadata": {
+    "form_id": "contact-form",
+    "fields_filled": ["name", "email", "message"],
+    "sensitive_fields": false
+  }
+}
+```
+
+### File Operations
+
+```json
+{
+  "action_type": "file_write",
+  "target": "/workspace/document.md",
+  "metadata": {
+    "file_size_bytes": 1234,
+    "content_hash": "sha256:abc123...",
+    "previous_hash": "sha256:xyz789...",
+    "backup_created": true
+  }
+}
+```
+
+### API Calls
+
+```json
+{
+  "action_type": "api_call",
+  "target": "https://api.service.com/endpoint",
+  "metadata": {
+    "method": "POST",
+    "response_code": 200,
+    "request_size_bytes": 500,
+    "response_size_bytes": 1200,
+    "cost_estimate_usd": 0.001
+  }
+}
+```
+
+### Security Events
+
+```json
+{
+  "action_type": "security_block",
+  "target": "https://banking.example.com",
+  "outcome": "blocked",
+  "metadata": {
+    "block_reason": "financial_site_blocklist",
+    "policy_matched": "browser-security-001",
+    "original_instruction": "check account balance",
+    "alert_generated": true
+  }
+}
+```
+
+---
+
+## Storage and Retention
+
+### Where to Store
+
+| Option | Pros | Cons | Best For |
+|--------|------|------|----------|
+| Local files | Simple, fast | Limited search, scale | Development |
+| Cloud storage (S3) | Durable, cheap | Query overhead | Archival |
+| Log service (Datadog) | Search, alerts | Cost | Production |
+| SIEM (Splunk) | Security focus | Complex, expensive | Enterprise |
+
+### Retention Policy
+
+| Log Type | Retention | Reason |
+|----------|-----------|--------|
+| Debug logs | 7 days | High volume, low value |
+| Info logs | 30 days | Operational visibility |
+| Warn logs | 90 days | Trend analysis |
+| Error logs | 1 year | Debugging, compliance |
+| Critical/Security | 7 years | Legal, forensics |
+
+### Storage Estimate
+
+```
+Active AI agent:
+- 1,000 actions/day
+- ~500 bytes/action (JSON)
+- = 500KB/day
+- = 15MB/month
+- = 180MB/year
+
+Multiply by number of active agents.
+```
+
+---
+
+## Log Integrity
+
+### Why It Matters
+
+Logs are useless if they can be tampered with. An attacker who compromises your system will try to cover their tracks.
+
+### Protections
+
+1. **Append-only storage**: Use write-once storage where possible
+2. **Cryptographic signing**: Sign log entries
+3. **Segregated storage**: Store logs where AI agents can't access them
+4. **Hash chaining**: Each entry includes hash of previous entry
+
+### Simple Hash Chain Example
+
+```json
+{
+  "entry_id": 1001,
+  "timestamp": "2025-12-14T15:30:00Z",
+  "previous_hash": "sha256:abc123...",
+  "entry_hash": "sha256:def456...",
+  "data": { ... }
+}
+```
+
+If any entry is modified, the chain breaks and tampering is detected.
+
+---
+
+## Alerting
+
+### What Should Trigger Alerts
+
+| Event | Severity | Action |
+|-------|----------|--------|
+| Blocked site access attempt | Medium | Log + review daily |
+| Credential access attempt | Critical | Immediate notification |
+| Unusual action volume | Medium | Automated + manual review |
+| Failed security check | High | Immediate notification |
+| Error rate spike | Medium | Investigate within 1 hour |
+
+### Alert Configuration Example
+
+```yaml
+alerts:
+  - name: credential_access
+    condition: action_type == "credential_access"
+    severity: critical
+    notify:
+      - sms: "+1-555-0123"
+      - email: "security@example.com"
+    throttle: 1 per minute
+
+  - name: blocked_navigation
+    condition: action_type == "browser_navigate" AND outcome == "blocked"
+    severity: medium
+    notify:
+      - slack: "#ai-security"
+    throttle: 10 per hour
+
+  - name: high_volume
+    condition: count(session_id) > 100 per 5 minutes
+    severity: high
+    notify:
+      - email: "ops@example.com"
+```
+
+---
+
+## Querying Logs
+
+### Common Queries
+
+**All actions in a session:**
+```sql
+SELECT * FROM logs
+WHERE session_id = 'sess_abc123'
+ORDER BY timestamp;
+```
+
+**Security events last 24 hours:**
+```sql
+SELECT * FROM logs
+WHERE level = 'CRITICAL'
+AND timestamp > NOW() - INTERVAL 24 HOUR;
+```
+
+**Failed actions by type:**
+```sql
+SELECT action_type, COUNT(*) as failures
+FROM logs
+WHERE outcome = 'failure'
+AND timestamp > NOW() - INTERVAL 7 DAY
+GROUP BY action_type
+ORDER BY failures DESC;
+```
+
+**Unusual patterns (potential attack):**
+```sql
+SELECT session_id, COUNT(*) as actions,
+       COUNT(DISTINCT action_type) as variety
+FROM logs
+WHERE timestamp > NOW() - INTERVAL 1 HOUR
+GROUP BY session_id
+HAVING actions > 50 OR variety > 10;
+```
+
+---
+
+## Implementation Checklist
+
+### Phase 1: Basic Logging
+
+- [ ] Implement minimum required fields
+- [ ] Log to local JSON files
+- [ ] Set up daily log rotation
+- [ ] Manual daily review process
+
+### Phase 2: Enhanced Logging
+
+- [ ] Add recommended fields
+- [ ] Move to centralized storage
+- [ ] Set up basic alerting
+- [ ] Weekly review process
+
+### Phase 3: Production Logging
+
+- [ ] Add comprehensive fields
+- [ ] Implement log integrity (signing/chaining)
+- [ ] Configure automated alerting
+- [ ] Integrate with security monitoring
+
+---
+
+## Quick Reference
+
+### Log Every Time
+
+```
+✓ AI navigates to a URL
+✓ AI reads or writes a file
+✓ AI makes an API call
+✓ AI sends any communication
+✓ AI is blocked from an action
+✓ AI encounters an error
+✓ Human approves/denies request
+```
+
+### Log Entry Checklist
+
+```
+□ Timestamp (UTC)
+□ Action type
+□ Target
+□ Outcome
+□ Session ID
+□ Agent ID
+□ Risk level (if applicable)
+□ Error details (if failure)
+```
+
+---
+
+*Related: [Core Principles](../docs/01-core-principles.md) | [Kill Switches](kill-switches.md)*

package/template/knowledge/ai-security-framework/configs/kill-switches.md

@@ -0,0 +1,354 @@
+# Kill Switch Patterns
+
+> Emergency controls to stop AI agents when things go wrong
+
+---
+
+## Why Kill Switches Matter
+
+In September 2025, researchers discovered that some advanced AI models were actively resisting shutdown attempts. While current tools are far from that level, the principle remains: you need the ability to stop AI agents immediately, reliably, and completely.
+
+**The Rule:** If you can't stop it in under 60 seconds, you don't have control.
+
+---
+
+## Kill Switch Hierarchy
+
+### Level 1: Soft Stop (Graceful)
+- Complete current action, then stop
+- Preserve state for review
+- Allow cleanup operations
+- **Use when:** Non-urgent concern, want to investigate
+
+### Level 2: Hard Stop (Immediate)
+- Terminate current action mid-execution
+- Preserve logs but not state
+- No cleanup
+- **Use when:** Suspicious behavior observed
+
+### Level 3: Emergency Stop (Nuclear)
+- Kill all processes
+- Revoke all tokens
+- Disconnect all sessions
+- **Use when:** Active compromise suspected
+
+---
+
+## Implementation Patterns
+
+### Pattern 1: Session Termination
+
+**What it does:** Ends the current AI session immediately.
+
+**Claude in Chrome:**
+```
+1. Chrome Task Manager: Shift + Esc
+2. Find Claude-related processes
+3. Click "End process"
+```
+
+**Claude Code:**
+```bash
+# Find Claude processes
+ps aux | grep -i claude
+
+# Kill specific process
+kill -9 <PID>
+
+# Kill all Claude processes
+pkill -f claude
+```
+
+**Any browser-based AI:**
+```
+1. Close all tabs: Cmd/Ctrl + Shift + W
+2. Force quit browser: Cmd + Option + Esc (Mac) / Alt + F4 (Windows)
+```
+
+### Pattern 2: Token Revocation
+
+**What it does:** Invalidates all AI access tokens immediately.
+
+**GitHub:**
+```
+Settings → Developer Settings → Personal Access Tokens
+→ Find AI token → Revoke
+```
+
+**Google/Gmail:**
+```
+Security → Third-party apps with account access
+→ Find AI app → Remove Access
+```
+
+**Slack:**
+```
+Apps → Manage → [AI App] → Remove App
+```
+
+**AWS:**
+```bash
+# Deactivate IAM access key
+aws iam update-access-key \
+  --user-name ai-agent \
+  --access-key-id AKIA... \
+  --status Inactive
+
+# Or delete it entirely
+aws iam delete-access-key \
+  --user-name ai-agent \
+  --access-key-id AKIA...
+```
+
+### Pattern 3: Network Isolation
+
+**What it does:** Cuts AI's network access.
+
+**Local firewall (Mac):**
+```bash
+# Block all outbound from specific app
+sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /Applications/Chrome.app
+sudo /usr/libexec/ApplicationFirewall/socketfilterfw --blockapp /Applications/Chrome.app
+```
+
+**Local firewall (Linux):**
+```bash
+# Block outbound for user
+sudo iptables -A OUTPUT -m owner --uid-owner ai-user -j DROP
+```
+
+**Router level:**
+- Log into router admin
+- Block device MAC address
+- Or: Unplug network cable (simplest)
+
+### Pattern 4: Circuit Breaker (Automated)
+
+**What it does:** Automatically triggers kill switch based on conditions.
+
+**Example implementation:**
+```python
+class CircuitBreaker:
+    def __init__(self, threshold=10, window_seconds=60):
+        self.threshold = threshold
+        self.window = window_seconds
+        self.events = []
+
+    def record_event(self, event_type):
+        now = time.time()
+        self.events.append((now, event_type))
+
+        # Clean old events
+        self.events = [(t, e) for t, e in self.events
+                       if now - t < self.window]
+
+        # Check threshold
+        if len(self.events) >= self.threshold:
+            self.trip()
+
+    def trip(self):
+        logger.critical("Circuit breaker tripped!")
+        self.kill_all_agents()
+        self.revoke_all_tokens()
+        self.send_alert()
+```
+
+**Trigger conditions:**
+- Error rate exceeds threshold
+- Unusual action patterns
+- Access to blocked resources
+- Spending limit reached
+- Manual trigger
+
+---
+
+## Quick Reference Card
+
+Print this and keep it accessible:
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║                    AI KILL SWITCH QUICK CARD                   ║
+╠═══════════════════════════════════════════════════════════════╣
+║                                                               ║
+║  IMMEDIATE BROWSER STOP                                       ║
+║  ─────────────────────                                        ║
+║  Mac:     Cmd + Option + Esc → Force Quit Browser             ║
+║  Windows: Ctrl + Shift + Esc → End Task                       ║
+║  Chrome:  Shift + Esc → Kill Process                          ║
+║                                                               ║
+║  CLOSE ALL TABS                                               ║
+║  ─────────────────────                                        ║
+║  Mac:     Cmd + Shift + W                                     ║
+║  Windows: Ctrl + Shift + W                                    ║
+║                                                               ║
+║  KILL CLI PROCESSES                                           ║
+║  ─────────────────────                                        ║
+║  pkill -f claude                                              ║
+║  pkill -f "ai-agent"                                          ║
+║                                                               ║
+║  TOKEN REVOCATION                                             ║
+║  ─────────────────────                                        ║
+║  GitHub:  Settings → Tokens → Revoke                          ║
+║  Google:  Security → Third-party apps → Remove                ║
+║  AWS:     IAM → Users → Security credentials → Deactivate     ║
+║                                                               ║
+║  NETWORK CUTOFF                                               ║
+║  ─────────────────────                                        ║
+║  • Unplug ethernet / Disable WiFi                             ║
+║  • Router: Block device                                       ║
+║                                                               ║
+║  CONTACTS                                                     ║
+║  ─────────────────────                                        ║
+║  Primary:   _______________________                           ║
+║  Security:  _______________________                           ║
+║  Cloud:     _______________________                           ║
+║                                                               ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## Emergency Procedures by Scenario
+
+### Scenario: AI Navigating to Suspicious Sites
+
+1. **Soft stop:** Close the specific tab
+2. **If continues:** Force quit browser
+3. **Review:** Check browser history
+4. **Assess:** What pages were accessed?
+5. **Action:** Block suspicious domains
+
+### Scenario: AI Attempting Unauthorized Access
+
+1. **Hard stop:** Kill browser process immediately
+2. **Revoke:** All AI tokens for affected services
+3. **Log:** Preserve all audit logs
+4. **Investigate:** What was accessed/attempted?
+5. **Rotate:** Credentials that may be compromised
+
+### Scenario: Suspected Prompt Injection Attack
+
+1. **Hard stop:** Kill all AI processes
+2. **Isolate:** Don't let AI process more content
+3. **Preserve:** Screenshot/capture the malicious content
+4. **Review:** What actions did AI take after exposure?
+5. **Report:** Notify AI provider if appropriate
+
+### Scenario: AI Acting on Compromised Credentials
+
+1. **Emergency stop:** Kill everything
+2. **Revoke:** ALL credentials AI has accessed
+3. **Change:** Passwords for critical accounts
+4. **Review:** Audit logs for unauthorized actions
+5. **Notify:** Affected parties if data exposed
+
+### Scenario: Unknown/Unexplained AI Behavior
+
+1. **Pause:** Don't kill immediately
+2. **Observe:** What exactly is it doing?
+3. **Log:** Record the behavior
+4. **Soft stop:** Complete current action, then halt
+5. **Investigate:** Review logs and context
+
+---
+
+## Testing Your Kill Switches
+
+### Weekly Test (5 minutes)
+
+1. Verify you can close all AI tabs in <10 seconds
+2. Confirm browser task manager is accessible
+3. Check that you know where token revocation is
+
+### Monthly Test (15 minutes)
+
+1. Practice full browser force-quit
+2. Test one token revocation and re-creation
+3. Verify network isolation method works
+4. Time your emergency stop (should be <60 seconds)
+
+### Quarterly Drill (30 minutes)
+
+1. Full emergency scenario simulation
+2. Practice all kill switch levels
+3. Verify all documentation is current
+4. Update quick reference card if needed
+
+---
+
+## Automated Kill Switch Configuration
+
+### Spending Limits
+
+```yaml
+limits:
+  api_spending:
+    daily_max_usd: 10
+    action: pause_and_alert
+
+  token_usage:
+    hourly_max: 100000
+    action: hard_stop
+```
+
+### Behavioral Triggers
+
+```yaml
+triggers:
+  blocked_site_attempts:
+    threshold: 3
+    window: 60_seconds
+    action: soft_stop
+
+  error_rate:
+    threshold: 50_percent
+    window: 5_minutes
+    action: soft_stop
+
+  credential_access:
+    threshold: 1
+    action: hard_stop
+```
+
+### Time-Based Controls
+
+```yaml
+schedules:
+  allowed_hours:
+    start: "08:00"
+    end: "18:00"
+    timezone: "America/Denver"
+    outside_hours: soft_stop
+
+  max_session_duration:
+    minutes: 120
+    action: soft_stop
+```
+
+---
+
+## Post-Kill-Switch Actions
+
+### After Any Kill Switch Activation
+
+1. **Document:** Why was it triggered?
+2. **Preserve:** All logs from the session
+3. **Assess:** Was this a real threat or false positive?
+4. **Update:** Security controls if needed
+5. **Resume:** Only after investigation complete
+
+### Resumption Checklist
+
+Before restarting AI agents:
+
+- [ ] Root cause identified
+- [ ] Logs preserved
+- [ ] Security controls updated (if needed)
+- [ ] Fresh session (no contaminated context)
+- [ ] Credentials rotated (if suspicious)
+- [ ] Team notified (if applicable)
+
+---
+
+*Related: [Audit Logging](audit-logging.md) | [Core Principles](../docs/01-core-principles.md)*