@samahlstrom/forge-cli 0.1.0

package/templates/addons/compliance-hipaa/files/hipaa-checks.sh

@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# hipaa-checks.sh — HIPAA compliance scanning for forge projects
+# Checks for PHI leaks, auth gaps, and encryption issues
+
+RESULTS_FILE=".forge/state/hipaa-results.json"
+PASS=0
+FAIL=0
+WARN=0
+FINDINGS=()
+
+mkdir -p "$(dirname "$RESULTS_FILE")"
+
+# --- Helpers ---
+
+log()  { echo "[hipaa] $*"; }
+finding() {
+  local severity="$1" file="$2" line="$3" rule="$4" detail="$5"
+  FINDINGS+=("{\"severity\":\"${severity}\",\"file\":\"${file}\",\"line\":${line},\"rule\":\"${rule}\",\"detail\":\"${detail}\"}")
+  if [ "$severity" = "fail" ]; then
+    FAIL=$((FAIL + 1))
+  else
+    WARN=$((WARN + 1))
+  fi
+}
+
+# --- Check 1: PHI in log statements ---
+
+log "Checking for PHI in log statements..."
+
+# Patterns that suggest logging PHI fields
+PHI_LOG_PATTERNS=(
+  'console\.\(log\|error\|warn\|info\|debug\).*\(patient\|ssn\|dob\|dateOfBirth\|diagnosis\|mrn\|medicalRecord\|socialSecurity\)'
+  'logger\.\(info\|warn\|error\|debug\).*\(patient\|ssn\|dob\|dateOfBirth\|diagnosis\|mrn\|medicalRecord\|socialSecurity\)'
+)
+
+for pattern in "${PHI_LOG_PATTERNS[@]}"; do
+  while IFS=: read -r file line _match; do
+    [ -z "$file" ] && continue
+    finding "fail" "$file" "$line" "phi-in-logs" "Potential PHI logged — review this log statement"
+  done < <(grep -rn "$pattern" --include='*.ts' --include='*.js' --include='*.svelte' --include='*.py' . 2>/dev/null | head -50 || true)
+done
+
+# --- Check 2: PHI in URLs / route params ---
+
+log "Checking for PHI in URL patterns..."
+
+URL_PHI_PATTERNS=(
+  'patient[Ii]d.*params\|params.*patient[Ii]d'
+  'ssn.*query\|query.*ssn'
+  'dob.*searchParams\|searchParams.*dob'
+  '\$page\.params.*\(patient\|ssn\|dob\|mrn\)'
+)
+
+for pattern in "${URL_PHI_PATTERNS[@]}"; do
+  while IFS=: read -r file line _match; do
+    [ -z "$file" ] && continue
+    finding "fail" "$file" "$line" "phi-in-url" "Potential PHI in URL parameter"
+  done < <(grep -rn "$pattern" --include='*.ts' --include='*.js' --include='*.svelte' . 2>/dev/null | head -50 || true)
+done
+
+# --- Check 3: PHI in browser storage ---
+
+log "Checking for PHI in browser storage usage..."
+
+STORAGE_PATTERNS=(
+  'localStorage\.set.*\(patient\|ssn\|dob\|diagnosis\|mrn\)'
+  'sessionStorage\.set.*\(patient\|ssn\|dob\|diagnosis\|mrn\)'
+  'indexedDB.*\(patient\|ssn\|dob\|diagnosis\|mrn\)'
+)
+
+for pattern in "${STORAGE_PATTERNS[@]}"; do
+  while IFS=: read -r file line _match; do
+    [ -z "$file" ] && continue
+    finding "fail" "$file" "$line" "phi-in-storage" "Potential PHI in browser storage"
+  done < <(grep -rn "$pattern" --include='*.ts' --include='*.js' --include='*.svelte' . 2>/dev/null | head -50 || true)
+done
+
+# --- Check 4: Unprotected endpoints ---
+
+log "Checking for endpoints without auth guards..."
+
+# Look for API endpoints / server routes missing auth checks
+if [ -d "src/routes" ]; then
+  while IFS= read -r file; do
+    if ! grep -q 'locals\.\(user\|session\|auth\)\|getSession\|requireAuth\|authenticate\|verifyToken\|event\.locals' "$file" 2>/dev/null; then
+      finding "warn" "$file" 0 "no-auth-guard" "Server endpoint may lack authentication — verify manually"
+    fi
+  done < <(find . -path '*/routes/*' \( -name '+server.ts' -o -name '+server.js' \) -not -path '*/node_modules/*' 2>/dev/null | head -100)
+fi
+
+# --- Check 5: Wildcard Firestore rules ---
+
+log "Checking Firestore security rules..."
+
+RULES_FILES=$(find . -name 'firestore.rules' -o -name '*.rules' -not -path '*/node_modules/*' 2>/dev/null || true)
+for rules_file in $RULES_FILES; do
+  while IFS=: read -r _ line _match; do
+    [ -z "$line" ] && continue
+    finding "fail" "$rules_file" "$line" "wildcard-rules" "Overly permissive Firestore rule — never allow unrestricted access to PHI"
+  done < <(grep -n 'allow.*:.*if true\|allow.*:.*if request\.auth != null' "$rules_file" 2>/dev/null || true)
+done
+
+# --- Check 6: HTTP (non-TLS) API calls ---
+
+log "Checking for non-HTTPS API calls..."
+
+while IFS=: read -r file line _match; do
+  [ -z "$file" ] && continue
+  # Skip localhost and test files
+  if echo "$_match" | grep -q 'localhost\|127\.0\.0\.1\|0\.0\.0\.0'; then
+    continue
+  fi
+  finding "fail" "$file" "$line" "no-tls" "HTTP (non-TLS) API call detected — use HTTPS"
+done < <(grep -rn "fetch(['\"]http:" --include='*.ts' --include='*.js' --include='*.svelte' . 2>/dev/null | grep -v node_modules | grep -v '\.test\.' | head -50 || true)
+
+# --- Check 7: Secrets in code ---
+
+log "Checking for hardcoded secrets..."
+
+SECRET_PATTERNS=(
+  'password\s*=\s*["\x27][^"\x27]\{8,\}'
+  'api[_-]\?key\s*=\s*["\x27][A-Za-z0-9]\{20,\}'
+  'secret\s*=\s*["\x27][^"\x27]\{8,\}'
+  'PRIVATE.KEY'
+)
+
+for pattern in "${SECRET_PATTERNS[@]}"; do
+  while IFS=: read -r file line _match; do
+    [ -z "$file" ] && continue
+    finding "warn" "$file" "$line" "hardcoded-secret" "Possible hardcoded secret — use environment variables or secret manager"
+  done < <(grep -rn "$pattern" --include='*.ts' --include='*.js' --include='*.svelte' --include='*.py' --include='*.env*' . 2>/dev/null | grep -v node_modules | grep -v '\.test\.' | grep -v '\.example' | head -50 || true)
+done
+
+# --- Check 8: Semgrep HIPAA rules (if available) ---
+
+if command -v semgrep > /dev/null 2>&1; then
+  log "Running semgrep HIPAA rules..."
+  semgrep --config "p/hipaa" --json --quiet . 2>/dev/null > /tmp/forge-semgrep-hipaa.json || true
+
+  SEMGREP_COUNT=$(jq '.results | length' /tmp/forge-semgrep-hipaa.json 2>/dev/null || echo "0")
+  if [ "$SEMGREP_COUNT" -gt 0 ]; then
+    log "Semgrep found ${SEMGREP_COUNT} HIPAA findings"
+    FAIL=$((FAIL + SEMGREP_COUNT))
+    # Merge semgrep findings
+    while IFS= read -r sg_finding; do
+      FINDINGS+=("$sg_finding")
+    done < <(jq -c '.results[] | {severity:"fail",file:.path,line:.start.line,rule:.check_id,detail:.extra.message}' /tmp/forge-semgrep-hipaa.json 2>/dev/null || true)
+  fi
+else
+  log "Semgrep not installed — skipping advanced HIPAA rules (install with: pip install semgrep)"
+fi
+
+# --- Passed checks ---
+
+# Count passes for checks that found no issues
+TOTAL_CHECKS=8
+PASS=$((TOTAL_CHECKS - (FAIL > 0 ? 1 : 0) - (WARN > 0 ? 1 : 0)))
+[ "$PASS" -lt 0 ] && PASS=0
+
+# --- Write results ---
+
+FINDINGS_JSON=$(printf '%s,' "${FINDINGS[@]}" 2>/dev/null | sed 's/,$//')
+[ -z "$FINDINGS_JSON" ] && FINDINGS_JSON=""
+
+cat > "$RESULTS_FILE" <<EOF
+{
+  "addon": "compliance-hipaa",
+  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "summary": {
+    "total_checks": ${TOTAL_CHECKS},
+    "pass": $((TOTAL_CHECKS - (FAIL > 0 ? 1 : 0) - (WARN > 0 ? 1 : 0))),
+    "fail": ${FAIL},
+    "warn": ${WARN}
+  },
+  "findings": [${FINDINGS_JSON}]
+}
+EOF
+
+log "Results written to ${RESULTS_FILE}"
+log "Summary: ${FAIL} failures, ${WARN} warnings"
+
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1

package/templates/addons/compliance-hipaa/files/hipaa-context.md

@@ -0,0 +1,91 @@
+# HIPAA Compliance Context
+
+This context overlay applies to all agents working on code in this project. The codebase handles Protected Health Information (PHI) and must comply with the HIPAA Security Rule and Privacy Rule.
+
+## PHI Field Rules
+
+PHI includes any individually identifiable health information: names, dates of birth, medical record numbers, diagnoses, treatment records, SSNs, email addresses, phone numbers, IP addresses (when linked to a patient), and any combination of fields that could identify a patient.
+
+### Absolute Rules (Never Violate)
+
+1. **Never log PHI.** No patient names, DOBs, MRNs, diagnoses, or identifiers in `console.log`, `console.error`, `logger.*`, or any logging output. Use opaque identifiers (e.g., hashed IDs) in logs.
+
+2. **Never store PHI in client-side state** that persists beyond the session. No `localStorage`, `sessionStorage`, `IndexedDB`, or cookies containing PHI. In-memory state (e.g., Svelte stores) is acceptable only during an active authenticated session.
+
+3. **Never include PHI in URLs.** No patient identifiers in route params, query strings, or URL fragments. Use opaque tokens that resolve server-side.
+
+4. **Never expose PHI in browser storage.** This includes service worker caches, browser history entries, and `window.name`.
+
+5. **Encrypt PHI at rest.** Firestore data containing PHI must use encrypted fields or be stored in collections with server-side encryption enabled. Backups must be encrypted.
+
+6. **Encrypt PHI in transit.** All API calls must use HTTPS. Verify TLS configuration. No HTTP fallbacks.
+
+7. **Minimum Necessary principle.** Only fetch and display the PHI fields required for the current operation. Do not load full patient records when only a name is needed.
+
+8. **Audit all PHI access.** Every read/write of PHI must produce an audit log entry with: who accessed it, when, what was accessed, and why (purpose/context).
+
+## Authentication Requirements
+
+- All endpoints serving PHI require authentication
+- Sessions must time out after 15 minutes of inactivity
+- Re-authentication required for sensitive operations (viewing full records, exporting data)
+- Multi-factor authentication required for administrative access
+- Failed login attempts must be logged and rate-limited
+- Password requirements: minimum 12 characters, complexity rules enforced
+
+## Authorization Patterns
+
+- Role-based access control (RBAC) for all PHI access
+- Principle of least privilege: default deny, explicit grants
+- Provider-patient relationships must be verified before granting access
+- Administrative overrides must be logged and auditable
+- Authorization checks happen server-side, never client-only
+- Firestore security rules must enforce access control at the document level
+
+## Session Security
+
+- Session tokens must be cryptographically random, minimum 128 bits
+- Bind sessions to client fingerprint (IP + user-agent) where feasible
+- Invalidate sessions on password change
+- Provide explicit logout that clears all session artifacts
+- No session data in URLs
+
+## Secret Management
+
+- No secrets in source code, environment files committed to VCS, or client bundles
+- Use environment variables or a secret manager (e.g., GCP Secret Manager)
+- Rotate secrets on a schedule and after any suspected compromise
+- API keys for PHI-serving endpoints must be scoped and rotatable
+
+## Firestore Security Rules
+
+When writing or modifying Firestore security rules for PHI collections:
+
+- Require `request.auth != null` on all PHI documents
+- Validate `request.auth.token` claims for role-based access
+- Use `resource.data` checks to enforce ownership/relationship constraints
+- Never use wildcard rules (`allow read, write: if true`) on PHI collections
+- Log rule denials for security monitoring
+
+## Encryption Requirements
+
+- AES-256 for data at rest
+- TLS 1.2+ for data in transit
+- Field-level encryption for highly sensitive PHI (SSN, full medical records)
+- Key management via cloud KMS; never store encryption keys alongside encrypted data
+- Key rotation policy: at least annually, immediately after suspected compromise
+
+## Code Review Checklist
+
+When reviewing code that touches PHI, verify:
+
+- [ ] No PHI in log statements
+- [ ] No PHI in URLs or query parameters
+- [ ] No PHI in client-side persistent storage
+- [ ] Authentication required on all PHI endpoints
+- [ ] Authorization checks are server-side
+- [ ] Minimum necessary data fetched
+- [ ] Audit logging present for PHI access
+- [ ] Error responses do not leak PHI
+- [ ] Input validation prevents injection attacks
+- [ ] HTTPS enforced, no mixed content

package/templates/addons/compliance-hipaa/manifest.yaml

@@ -0,0 +1,15 @@
+name: compliance-hipaa
+description: "HIPAA compliance checks, PHI detection, and security controls"
+version: 1
+patches:
+  forge_yaml:
+    verification.security.enabled: true
+    addons:
+      - "+compliance-hipaa"
+files:
+  - source: hipaa-context.md
+    target: .forge/addons/hipaa-context.md
+  - source: hipaa-checks.sh
+    target: .forge/addons/hipaa-checks.sh
+post_install:
+  - "pip install semgrep 2>/dev/null || echo 'Install semgrep for full HIPAA scanning: pip install semgrep'"

package/templates/addons/compliance-soc2/files/soc2-checks.sh

@@ -0,0 +1,232 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# soc2-checks.sh — SOC2 compliance scanning for forge projects
+# Verifies audit logging, access controls, and change management practices
+
+RESULTS_FILE=".forge/state/soc2-results.json"
+PASS=0
+FAIL=0
+WARN=0
+FINDINGS=()
+
+mkdir -p "$(dirname "$RESULTS_FILE")"
+
+# --- Helpers ---
+
+log()  { echo "[soc2] $*"; }
+finding() {
+  local severity="$1" file="$2" line="$3" rule="$4" detail="$5"
+  FINDINGS+=("{\"severity\":\"${severity}\",\"file\":\"${file}\",\"line\":${line},\"rule\":\"${rule}\",\"detail\":\"${detail}\"}")
+  if [ "$severity" = "fail" ]; then
+    FAIL=$((FAIL + 1))
+  else
+    WARN=$((WARN + 1))
+  fi
+}
+
+# --- Check 1: Audit logging presence ---
+
+log "Checking for audit logging infrastructure..."
+
+HAS_AUDIT=false
+AUDIT_PATTERNS=("auditLog\|audit_log\|AuditLog" "createAuditEntry\|logAudit\|writeAuditLog" "audit.*collection\|audit.*table")
+
+for pattern in "${AUDIT_PATTERNS[@]}"; do
+  if grep -rq "$pattern" --include='*.ts' --include='*.js' --include='*.py' . 2>/dev/null; then
+    HAS_AUDIT=true
+    break
+  fi
+done
+
+if [ "$HAS_AUDIT" = false ]; then
+  finding "fail" "project" 0 "no-audit-logging" "No audit logging infrastructure detected — SOC2 requires comprehensive audit trails"
+else
+  PASS=$((PASS + 1))
+  log "  Audit logging infrastructure found"
+fi
+
+# --- Check 2: Auth on server endpoints ---
+
+log "Checking server endpoints for authentication..."
+
+UNPROTECTED=0
+if [ -d "src/routes" ]; then
+  while IFS= read -r file; do
+    if ! grep -q 'locals\.\(user\|session\|auth\)\|getSession\|requireAuth\|authenticate\|verifyToken\|event\.locals\|isAuthenticated' "$file" 2>/dev/null; then
+      finding "warn" "$file" 0 "endpoint-no-auth" "Server endpoint may lack authentication guard"
+      UNPROTECTED=$((UNPROTECTED + 1))
+    fi
+  done < <(find . -path '*/routes/*' \( -name '+server.ts' -o -name '+server.js' \) -not -path '*/node_modules/*' 2>/dev/null | head -100)
+fi
+
+if [ "$UNPROTECTED" -eq 0 ]; then
+  PASS=$((PASS + 1))
+  log "  All server endpoints appear to have auth guards"
+fi
+
+# --- Check 3: No secrets in code ---
+
+log "Checking for hardcoded secrets..."
+
+SECRET_HITS=0
+SECRET_PATTERNS=(
+  'password\s*=\s*["\x27][^"\x27]\{8,\}'
+  'api[_-]\?key\s*=\s*["\x27][A-Za-z0-9]\{20,\}'
+  'secret\s*=\s*["\x27][^"\x27]\{8,\}'
+  'PRIVATE.KEY.*BEGIN'
+  'token\s*=\s*["\x27][A-Za-z0-9]\{30,\}'
+)
+
+for pattern in "${SECRET_PATTERNS[@]}"; do
+  while IFS=: read -r file line _match; do
+    [ -z "$file" ] && continue
+    finding "fail" "$file" "$line" "hardcoded-secret" "Possible hardcoded secret — use environment variables or secret manager"
+    SECRET_HITS=$((SECRET_HITS + 1))
+  done < <(grep -rn "$pattern" --include='*.ts' --include='*.js' --include='*.py' --include='*.env*' . 2>/dev/null | grep -v node_modules | grep -v '\.test\.\|\.spec\.\|\.example\|\.sample' | head -50 || true)
+done
+
+if [ "$SECRET_HITS" -eq 0 ]; then
+  PASS=$((PASS + 1))
+  log "  No hardcoded secrets detected"
+fi
+
+# --- Check 4: Change management — branch protection evidence ---
+
+log "Checking change management practices..."
+
+if git rev-parse --is-inside-work-tree > /dev/null 2>&1; then
+  # Check if there are direct commits to main (not merge commits)
+  DIRECT_COMMITS=$(git log --first-parent --no-merges --oneline main 2>/dev/null | head -10 | wc -l | tr -d ' ')
+  if [ "$DIRECT_COMMITS" -gt 3 ]; then
+    finding "warn" ".git" 0 "direct-commits-to-main" "Found ${DIRECT_COMMITS} direct (non-merge) commits on main — use PRs for all changes"
+  else
+    PASS=$((PASS + 1))
+    log "  Change management: main branch uses merge commits (PRs)"
+  fi
+
+  # Check for unsigned commits (optional but recommended)
+  UNSIGNED=$(git log --format='%G?' -10 2>/dev/null | grep -c 'N' || true)
+  if [ "$UNSIGNED" -gt 5 ]; then
+    finding "warn" ".git" 0 "unsigned-commits" "Most recent commits are unsigned — consider requiring commit signing"
+  fi
+else
+  finding "warn" "." 0 "no-git" "Not a git repository — cannot verify change management"
+fi
+
+# --- Check 5: Error handling — no internal details leaked ---
+
+log "Checking for leaked internal details in error responses..."
+
+ERROR_LEAK_PATTERNS=(
+  'res\.\(status\|json\).*stack\|stack.*res\.\(status\|json\)'
+  'response.*error\.message\|error\.message.*response'
+  'catch.*res\..*500.*err\.\(message\|stack\)'
+)
+
+LEAK_HITS=0
+for pattern in "${ERROR_LEAK_PATTERNS[@]}"; do
+  while IFS=: read -r file line _match; do
+    [ -z "$file" ] && continue
+    finding "warn" "$file" "$line" "error-info-leak" "Error response may expose internal details — sanitize before sending to client"
+    LEAK_HITS=$((LEAK_HITS + 1))
+  done < <(grep -rn "$pattern" --include='*.ts' --include='*.js' . 2>/dev/null | grep -v node_modules | grep -v '\.test\.\|\.spec\.' | head -30 || true)
+done
+
+if [ "$LEAK_HITS" -eq 0 ]; then
+  PASS=$((PASS + 1))
+  log "  No obvious error info leaks detected"
+fi
+
+# --- Check 6: HTTPS enforcement ---
+
+log "Checking for non-HTTPS API calls..."
+
+HTTP_HITS=0
+while IFS=: read -r file line _match; do
+  [ -z "$file" ] && continue
+  if echo "$_match" | grep -q 'localhost\|127\.0\.0\.1\|0\.0\.0\.0'; then
+    continue
+  fi
+  finding "fail" "$file" "$line" "no-tls" "HTTP (non-TLS) API call — use HTTPS"
+  HTTP_HITS=$((HTTP_HITS + 1))
+done < <(grep -rn "fetch(['\"]http:" --include='*.ts' --include='*.js' --include='*.svelte' . 2>/dev/null | grep -v node_modules | grep -v '\.test\.\|\.spec\.' | head -50 || true)
+
+if [ "$HTTP_HITS" -eq 0 ]; then
+  PASS=$((PASS + 1))
+  log "  All API calls use HTTPS"
+fi
+
+# --- Check 7: Dependency vulnerabilities ---
+
+log "Checking for known dependency vulnerabilities..."
+
+if [ -f "package-lock.json" ] || [ -f "yarn.lock" ]; then
+  AUDIT_OUTPUT=$(npm audit --json 2>/dev/null || true)
+  VULN_COUNT=$(echo "$AUDIT_OUTPUT" | jq '.metadata.vulnerabilities.high + .metadata.vulnerabilities.critical' 2>/dev/null || echo "0")
+  if [ "$VULN_COUNT" -gt 0 ] 2>/dev/null; then
+    finding "fail" "package.json" 0 "vulnerable-deps" "${VULN_COUNT} high/critical dependency vulnerabilities found — run npm audit fix"
+  else
+    PASS=$((PASS + 1))
+    log "  No high/critical dependency vulnerabilities"
+  fi
+elif [ -f "requirements.txt" ]; then
+  if command -v pip-audit > /dev/null 2>&1; then
+    pip-audit -r requirements.txt --format json 2>/dev/null > /tmp/forge-pip-audit.json || true
+    PY_VULNS=$(jq 'length' /tmp/forge-pip-audit.json 2>/dev/null || echo "0")
+    if [ "$PY_VULNS" -gt 0 ]; then
+      finding "fail" "requirements.txt" 0 "vulnerable-deps" "${PY_VULNS} Python dependency vulnerabilities found"
+    else
+      PASS=$((PASS + 1))
+    fi
+  else
+    finding "warn" "requirements.txt" 0 "no-dep-audit" "pip-audit not installed — cannot check Python dependencies"
+  fi
+fi
+
+# --- Check 8: Semgrep SOC2-relevant rules ---
+
+if command -v semgrep > /dev/null 2>&1; then
+  log "Running semgrep security rules..."
+  semgrep --config "p/security-audit" --json --quiet . 2>/dev/null > /tmp/forge-semgrep-soc2.json || true
+
+  SEMGREP_COUNT=$(jq '.results | length' /tmp/forge-semgrep-soc2.json 2>/dev/null || echo "0")
+  if [ "$SEMGREP_COUNT" -gt 0 ]; then
+    log "Semgrep found ${SEMGREP_COUNT} security findings"
+    while IFS= read -r sg_finding; do
+      FINDINGS+=("$sg_finding")
+      FAIL=$((FAIL + 1))
+    done < <(jq -c '.results[] | {severity:"fail",file:.path,line:.start.line,rule:.check_id,detail:.extra.message}' /tmp/forge-semgrep-soc2.json 2>/dev/null || true)
+  else
+    PASS=$((PASS + 1))
+    log "  Semgrep: no security findings"
+  fi
+else
+  log "Semgrep not installed — skipping advanced security rules (install with: pip install semgrep)"
+fi
+
+# --- Write results ---
+
+FINDINGS_JSON=$(printf '%s,' "${FINDINGS[@]}" 2>/dev/null | sed 's/,$//')
+[ -z "$FINDINGS_JSON" ] && FINDINGS_JSON=""
+
+TOTAL=$((PASS + FAIL + WARN))
+
+cat > "$RESULTS_FILE" <<EOF
+{
+  "addon": "compliance-soc2",
+  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "summary": {
+    "total_checks": ${TOTAL},
+    "pass": ${PASS},
+    "fail": ${FAIL},
+    "warn": ${WARN}
+  },
+  "findings": [${FINDINGS_JSON}]
+}
+EOF
+
+log "Results written to ${RESULTS_FILE}"
+log "Summary: ${PASS} passed, ${FAIL} failures, ${WARN} warnings"
+
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1

package/templates/addons/compliance-soc2/files/soc2-context.md

@@ -0,0 +1,147 @@
+# SOC2 Compliance Context
+
+This context overlay applies to all agents working on code in this project. The codebase must meet SOC2 Type II Trust Services Criteria across Security, Availability, Processing Integrity, Confidentiality, and Privacy.
+
+## Access Control (CC6)
+
+### Authentication
+
+- All user-facing endpoints require authentication
+- Service-to-service calls use short-lived tokens or mutual TLS
+- No shared accounts or credentials
+- Password policy: minimum 12 characters, complexity enforced, no reuse of last 12 passwords
+- MFA required for all administrative and production access
+- SSO integration required for enterprise users where available
+
+### Authorization
+
+- Role-based access control (RBAC) enforced server-side
+- Principle of least privilege: users get minimum permissions for their role
+- Privilege escalation requires approval and is logged
+- API keys are scoped to specific resources and operations
+- Regularly review and revoke unused access grants
+- Document all roles and their permission boundaries
+
+### Session Management
+
+- Session timeout after 30 minutes of inactivity (15 minutes for admin sessions)
+- Sessions invalidated on logout, password change, and role change
+- Concurrent session limits enforced where appropriate
+- Session tokens are cryptographically random, not guessable
+
+## Audit Logging (CC7)
+
+### What to Log
+
+Every security-relevant event must produce a structured audit log entry:
+
+- **Authentication events**: login, logout, failed login, MFA challenge, password change
+- **Authorization events**: access granted, access denied, privilege escalation
+- **Data events**: create, read, update, delete of sensitive records
+- **Admin events**: configuration changes, user management, role changes
+- **System events**: deployments, restarts, error spikes, health check failures
+
+### Log Format
+
+Each audit log entry must include:
+
+- `timestamp` (ISO 8601, UTC)
+- `actor` (user ID or service identity)
+- `action` (what was done)
+- `resource` (what was affected)
+- `result` (success/failure)
+- `ip_address` (source IP)
+- `context` (additional relevant metadata)
+
+### Log Protection
+
+- Audit logs are append-only; never delete or modify in place
+- Logs stored in a separate system/collection from application data
+- Log retention: minimum 1 year
+- Logs must not contain secrets, passwords, tokens, or PII beyond user IDs
+- Alerting on log tampering or gaps
+
+## Change Management (CC8)
+
+### Code Changes
+
+- All changes go through pull requests with at least one reviewer
+- CI/CD pipeline must pass before merge (tests, lint, type checks)
+- No direct commits to main/production branches
+- Commit messages reference the ticket/issue being addressed
+- Changes to security-sensitive code require security-aware reviewer
+
+### Deployment
+
+- All deployments are automated via CI/CD
+- No manual production deployments
+- Deployment artifacts are immutable and versioned
+- Rollback procedure documented and tested
+- Deployment logs captured for audit trail
+
+### Infrastructure Changes
+
+- Infrastructure as Code (IaC) for all environments
+- Infrastructure changes go through the same review process as code
+- Environment parity: staging mirrors production configuration
+- Secrets rotated on schedule and after incidents
+
+## Data Protection (CC6.1)
+
+### Encryption
+
+- Data at rest: AES-256 or equivalent
+- Data in transit: TLS 1.2+ for all connections
+- Database connections use TLS
+- Backup encryption required
+- Key management via cloud KMS
+
+### Data Classification
+
+- Classify data by sensitivity: public, internal, confidential, restricted
+- Apply controls proportional to classification
+- Document data flows showing where each classification level is stored and transmitted
+- Data retention policies enforced per classification
+
+### Data Disposal
+
+- Secure deletion when data retention period expires
+- Cryptographic erasure acceptable for encrypted data
+- Document disposal procedures and evidence
+
+## Availability (CC9)
+
+### Uptime
+
+- Define and monitor SLA targets
+- Health check endpoints for all services
+- Automated alerting on downtime or degradation
+- Incident response runbook documented
+
+### Disaster Recovery
+
+- Backup frequency: at least daily for critical data
+- Backup restoration tested quarterly
+- Recovery Time Objective (RTO) and Recovery Point Objective (RPO) documented
+- Multi-region or multi-zone deployment for critical services
+
+### Capacity
+
+- Monitor resource utilization (CPU, memory, storage, network)
+- Auto-scaling configured where applicable
+- Capacity planning reviewed quarterly
+
+## Code Review Checklist
+
+When reviewing code for SOC2 compliance, verify:
+
+- [ ] Authentication required on all endpoints
+- [ ] Authorization checks are server-side with least privilege
+- [ ] Audit logging present for security-relevant operations
+- [ ] Audit logs do not contain secrets or excessive PII
+- [ ] Error responses do not leak internal details
+- [ ] Input validation prevents injection attacks
+- [ ] HTTPS enforced, no mixed content
+- [ ] Secrets managed via environment variables or secret manager
+- [ ] Change goes through standard PR review process
+- [ ] Tests cover the new functionality

package/templates/addons/compliance-soc2/manifest.yaml

@@ -0,0 +1,15 @@
+name: compliance-soc2
+description: "SOC2 compliance checks — audit logging, access control, and change management evidence"
+version: 1
+patches:
+  forge_yaml:
+    verification.security.enabled: true
+    addons:
+      - "+compliance-soc2"
+files:
+  - source: soc2-context.md
+    target: .forge/addons/soc2-context.md
+  - source: soc2-checks.sh
+    target: .forge/addons/soc2-checks.sh
+post_install:
+  - "pip install semgrep 2>/dev/null || echo 'Install semgrep for full SOC2 scanning: pip install semgrep'"