create-hq 6.0.0 → 10.0.0

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

@@ -1,372 +0,0 @@
-# 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

@@ -1,354 +0,0 @@
-# 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)*