diff --git a/CHANGELOG.md b/CHANGELOG.md index 298ad37..4855442 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,32 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [Unreleased] +### Added + +- **Enterprise AI Governance section** (`guide/security/enterprise-governance.md`) — New guide covering org-level governance for teams deploying Claude Code at scale. 6 sections: (1) Local vs Shared governance split (risk matrix, decision framework); (2) AI Usage Charter — lean template covering approved tools, data classification, use case boundaries, approval matrix; (3) MCP Governance Workflow — approval pipeline (request → review → approve → deploy), YAML registry format, enforcement hook; (4) Guardrail Tiers — 4 pre-configured tiers (Starter/Standard/Strict/Regulated) with ready-to-copy `settings.json` and `CLAUDE.md` additions; (5) Policy Enforcement at Scale — config distribution, onboarding checklist, compliance audit script, role-based guardrails, CI/CD gates; (6) Audit & Compliance — what SOC2/ISO27001 auditors actually ask, audit trail setup, AI Governance Committee minimal structure. Audience: tech leads, engineering managers, security officers. Complements security-hardening.md (individual dev security) and production-safety.md (6 prod rules). + +- **MCP Registry Template** (`examples/scripts/mcp-registry-template.yaml`) — Ready-to-use YAML format for tracking approved MCP servers at org level. Includes approved/pending/denied sections, version bump policy, risk classification (LOW/MEDIUM/HIGH), data scope classification (PUBLIC/INTERNAL/CONFIDENTIAL/RESTRICTED), and expiry dates. + +- **Governance Enforcement Hook** (`examples/hooks/bash/governance-enforcement-hook.sh`) — SessionStart hook validating active MCP configuration against org's approved registry, checking deny rules for secret files, and detecting dangerous `permissions.allow` overrides. Warns without blocking (governance-first, not friction-first). + +- **AI Usage Charter Template** (`examples/scripts/ai-usage-charter-template.md`) — Org-level charter template covering approved tools, data classification (4 levels), approved/prohibited use cases, MCP server governance, code review and attribution requirements, accountability roles, incident response, and compliance mapping (SOC2/ISO27001/HIPAA/PCI DSS/GDPR). + +### Documentation + +- **`guide/roles/adoption-approaches.md`** — Added "Enterprise Rollout (50+ developers)" section with 3-phase rollout approach (Foundation/Adoption/Optimization), common rollout mistakes at scale, and pointer to enterprise-governance.md for compliance programs. + +- **`guide/ops/observability.md`** — Added "Manager Audit Checklist" section with weekly spot-check bash queries (files accessed outside project scope, destructive commands run) and a monthly compliance report script. + +- **`guide/ops/ai-traceability.md`** — Added "Evidence Collection for Auditors" subsection under §7.3 Enterprise/Compliance — practical table mapping auditor questions to evidence sources and generation commands. + +- **`guide/security/production-safety.md`** — Added cross-reference to enterprise-governance.md in See Also section. + +- **`guide/security/security-hardening.md`** — Added cross-reference to enterprise-governance.md with explicit scope boundary ("this guide = individual MCP vetting; that guide = org-level policy"), plus MCP registry template reference. + +- **`guide/README.md`** — Added enterprise-governance.md entry in Security section. + +- **`machine-readable/reference.yaml`** — Added 22 entries for enterprise governance guide, templates, and hooks. + ### Changed - **GEO/SEO optimization — llms.txt, llms-full.txt, guide meta descriptions** — Phase 1 (repo): `machine-readable/llms.txt` updated (v3.8.0→3.32.2, 87→238 templates, 9.6K→22.7K lines); `llms.txt` created at repo root (convention llmstxt.org — AI crawlers expect root); `llms-full.txt` created (~20KB: full cheatsheet, 238-template catalog, 10 Q&A FAQ); `mcp-server/content/llms.txt` synced. Phase 2 (landing): `public/llms.txt` synced, `public/llms-full.txt` created; stale root `robots.txt` (wrong sitemap URL, missing 6 AI bots) and `sitemap.xml` (6 URLs only) deleted — `public/` versions are canonical. Phase 3 (landing): JSON-LD counts fixed (113→238 in `examples/index.astro`, description sync in `index.astro`); `twitter:site` + `twitter:creator` added to `Layout.astro`; CVE stat 19→24 in security page; `lastmod` added to all sitemap entries in `astro.config.mjs`. Phase 4 (README): invisible HTML keyword comment replaced with visible 5 Q&A mini-FAQ (GEO crawlers + humans). Phase 5 (guide section): 13 `CHAPTERS` descriptions rewritten in `scripts/prepare-guide-content.mjs` (source of truth for Starlight frontmatter) — avg 40→150 chars, now include specific agent names, hook event types, MCP server names, pattern names. diff --git a/examples/hooks/bash/governance-enforcement-hook.sh b/examples/hooks/bash/governance-enforcement-hook.sh new file mode 100755 index 0000000..1905a25 --- /dev/null +++ b/examples/hooks/bash/governance-enforcement-hook.sh @@ -0,0 +1,177 @@ +#!/bin/bash +# governance-enforcement-hook.sh +# Event: SessionStart +# +# Validates active Claude Code MCP configuration against the org's approved registry. +# Warns about unapproved MCPs and checks that security deny rules are in place. +# +# Related: guide/security/enterprise-governance.md §3.3 and §5 +# +# Installation: +# cp governance-enforcement-hook.sh ~/.claude/hooks/ +# chmod +x ~/.claude/hooks/governance-enforcement-hook.sh +# +# Then add to ~/.claude/settings.json: +# { +# "hooks": { +# "SessionStart": ["~/.claude/hooks/governance-enforcement-hook.sh"] +# } +# } +# +# Or in project .claude/settings.json: +# { +# "hooks": { +# "SessionStart": [".claude/hooks/governance-enforcement-hook.sh"] +# } +# } + +set -euo pipefail + +SETTINGS_FILE="${HOME}/.claude.json" +REGISTRY_FILE="${PWD}/.claude/mcp-registry.yaml" +PROJECT_SETTINGS="${PWD}/.claude/settings.json" + +# ───────────────────────────────────────────────────────────────── +# Helpers +# ───────────────────────────────────────────────────────────────── + +warn() { echo "GOVERNANCE WARNING: $*" >&2; } +info() { echo "GOVERNANCE: $*" >&2; } + +has_command() { command -v "$1" &>/dev/null; } + +# ───────────────────────────────────────────────────────────────── +# Check 1: Project governance config present +# ───────────────────────────────────────────────────────────────── + +check_project_config() { + if [[ ! -f "$PROJECT_SETTINGS" ]]; then + warn "No .claude/settings.json in project. Governance not applied to this repo." + warn "Set up governance: see guide/security/enterprise-governance.md" + return + fi + + # Check that deny rules exist for secrets + if has_command jq; then + local has_deny + has_deny=$(jq -e '.permissions.deny // [] | length' "$PROJECT_SETTINGS" 2>/dev/null || echo "0") + if [[ "$has_deny" == "0" ]]; then + warn "No permissions.deny rules in .claude/settings.json." + warn "Add deny rules for .env, *.key, *.pem files." + fi + + # Check for dangerous allow rules + local dangerous_allows + dangerous_allows=$(jq -r '.permissions.allow[]? // ""' "$PROJECT_SETTINGS" 2>/dev/null | \ + grep -iE '(env|secret|credential|password|token|key)' || true) + if [[ -n "$dangerous_allows" ]]; then + warn "DANGEROUS: permissions.allow contains sensitive patterns:" + echo "$dangerous_allows" | while read -r line; do + warn " Allowed: $line" + done + fi + fi +} + +# ───────────────────────────────────────────────────────────────── +# Check 2: MCP registry compliance +# ───────────────────────────────────────────────────────────────── + +check_mcp_registry() { + if [[ ! -f "$REGISTRY_FILE" ]]; then + # No registry = no enforcement (opt-in) + return + fi + + if ! has_command jq || ! has_command yq; then + warn "jq or yq not installed — cannot check MCP registry compliance." + warn "Install: brew install jq yq" + return + fi + + if [[ ! -f "$SETTINGS_FILE" ]]; then + return + fi + + # Get active MCPs + local active_mcps + active_mcps=$(jq -r '.mcpServers // {} | keys[]' "$SETTINGS_FILE" 2>/dev/null || true) + + if [[ -z "$active_mcps" ]]; then + return + fi + + # Get approved MCPs from registry + local approved_mcps + approved_mcps=$(yq e '.approved[].name' "$REGISTRY_FILE" 2>/dev/null || true) + + # Compare + local unapproved=() + while IFS= read -r mcp; do + if [[ -n "$mcp" ]] && ! echo "$approved_mcps" | grep -q "^${mcp}$"; then + unapproved+=("$mcp") + fi + done <<< "$active_mcps" + + if [[ ${#unapproved[@]} -gt 0 ]]; then + warn "Unapproved MCP servers detected:" + for mcp in "${unapproved[@]}"; do + warn " - $mcp (not in .claude/mcp-registry.yaml)" + done + warn "Submit approval request per your org's AI usage charter." + warn "Session continues — remediate within 48 hours per policy." + else + info "MCP registry check passed. All MCPs approved." + fi + + # Check for expired approvals + local today + today=$(date +%Y-%m-%d) + while IFS= read -r name; do + local expires + expires=$(yq e ".approved[] | select(.name == \"$name\") | .expires" "$REGISTRY_FILE" 2>/dev/null || true) + if [[ -n "$expires" && "$expires" < "$today" ]]; then + warn "MCP '$name' approval expired on $expires. Re-approval required." + fi + done <<< "$approved_mcps" +} + +# ───────────────────────────────────────────────────────────────── +# Check 3: Data classification context +# ───────────────────────────────────────────────────────────────── + +check_data_classification() { + # Detect sensitive files in working directory + local sensitive_patterns=(".env" "*.pem" "*.key" "secrets/" "credentials") + local found_sensitive=() + + for pattern in "${sensitive_patterns[@]}"; do + if compgen -G "${PWD}/${pattern}" &>/dev/null 2>/dev/null; then + found_sensitive+=("$pattern") + fi + done + + if [[ ${#found_sensitive[@]} -gt 0 ]]; then + info "Sensitive file patterns detected in working directory:" + for f in "${found_sensitive[@]}"; do + info " - $f" + done + info "Verify .claude/settings.json deny rules cover these files." + fi +} + +# ───────────────────────────────────────────────────────────────── +# Main +# ───────────────────────────────────────────────────────────────── + +main() { + check_project_config + check_mcp_registry + check_data_classification + + # Always exit 0 — governance hook warns but does not block session start + # Blocking at SessionStart creates too much friction; use periodic audits instead + exit 0 +} + +main diff --git a/examples/scripts/ai-usage-charter-template.md b/examples/scripts/ai-usage-charter-template.md new file mode 100644 index 0000000..1f209c0 --- /dev/null +++ b/examples/scripts/ai-usage-charter-template.md @@ -0,0 +1,200 @@ +# AI Coding Tools Usage Charter + +> **Template** — Copy to `docs/ai-usage-charter.md` in your organization's docs repo. +> Adapt sections marked with `[BRACKETS]`. +> +> Related: guide/security/enterprise-governance.md §2 + +--- + +**Organization**: [Your Organization] +**Applies to**: Claude Code and all AI coding assistants +**Effective date**: [DATE] +**Owner**: [Engineering Lead / CTO / CISO] +**Review cadence**: Quarterly +**Version**: 1.0.0 + +--- + +## 1. Purpose + +This charter defines how [Organization] employees may use AI coding assistants, which tools are approved, what data can be used with them, and who is accountable for compliance. The goal is to enable productive AI-assisted development while managing security, privacy, and regulatory risk. + +--- + +## 2. Approved Tools + +| Tool | Plan / Tier | Scope | Administered by | +|------|-------------|-------|----------------| +| Claude Code | Team/Enterprise | All engineering work | Platform Team | +| Claude Code | Personal Pro | Personal dev only (no company data above INTERNAL) | Individual | +| [Other Tool] | [Plan] | [Scope] | [Team] | + +**Using non-approved AI coding tools on company systems is prohibited.** If you believe an additional tool would benefit your work, submit an approval request to [engineering-lead@company.com]. + +--- + +## 3. Data Classification Rules + +All data at [Organization] is classified into four levels. Your use of AI tools must comply with this classification. + +| Classification | Examples | Claude Code permitted? | Notes | +|----------------|----------|----------------------|-------| +| **PUBLIC** | Open-source code, public documentation | Yes — no restrictions | | +| **INTERNAL** | Internal tools, non-sensitive business code | Yes — standard config | Use company accounts | +| **CONFIDENTIAL** | Customer data (non-PII), business secrets, proprietary algorithms | Yes — Enterprise plan only, with approved config | | +| **RESTRICTED** | PCI card data, PHI, credentials, auth tokens, encryption keys | **Never** | No exceptions | + +### Hard Rules + +- RESTRICTED data **never** enters an AI context window — not in prompts, not in files Claude reads, not as examples. +- Personal AI accounts (personal Pro subscriptions) may only be used with PUBLIC or INTERNAL data. +- Company credentials and API keys are RESTRICTED. Never paste them into prompts. + +### Technical Enforcement + +Projects handling CONFIDENTIAL or RESTRICTED data must configure `permissions.deny` in `.claude/settings.json` to block AI access to sensitive files. See the [Standard or Regulated tier config](../security/enterprise-governance.md#4-guardrail-tiers) for ready-to-use configurations. + +--- + +## 4. Approved Use Cases + +The following uses of AI coding assistants are approved without additional review: + +- Code completion and generation for approved data classifications +- Code review and quality analysis +- Test generation and mutation testing +- Documentation drafting and updating +- Debugging, root cause analysis, log analysis +- Architecture analysis of internal systems +- CLI scripting, automation, build tooling +- Refactoring and code cleanup + +--- + +## 5. Prohibited Use Cases + +The following are **not permitted** without explicit written approval: + +| Prohibited use | Reason | Exception process | +|----------------|--------|------------------| +| Processing raw PCI cardholder data | Regulatory (PCI DSS) | None — technically enforced | +| Generating code handling unencrypted PHI without security review | Regulatory (HIPAA) | Security review required | +| Autonomous deployment to production | Human oversight requirement | Approval from Eng Director | +| Using personal AI accounts for CONFIDENTIAL data | Data residency/privacy | Upgrade to company account | +| Sharing customer data as examples in prompts | Privacy, data handling | Use synthetic data | +| Bypassing governance controls (hooks, deny rules) | Policy violation | None | + +--- + +## 6. MCP Server Governance + +Model Context Protocol (MCP) servers extend Claude Code's capabilities and introduce additional risk surface. All MCP servers used on company projects must be: + +1. Listed in the approved registry (`.claude/mcp-registry.yaml` in the platform config repo) +2. Pinned to an exact version (never `@latest`) +3. Re-reviewed every 6 months or on major version bumps + +**Approval process**: Submit a request with server name, source URL, intended use case, and data scope to [platform-team@company.com] or [#claude-code-requests Slack channel]. + +Unapproved MCPs detected in project configs will be flagged at session start. Developers have 48 hours to remove or seek approval. + +--- + +## 7. Code Review and Attribution + +### AI Attribution + +All pull requests where AI assisted in writing code must include an AI disclosure section: + +```markdown +## AI Assistance +- AI tool used: Claude Code +- Scope: [e.g., "Generated tests for auth module", "Refactored payment handler"] +- Human review: Reviewer checked logic, security implications, and edge cases +``` + +The standard `Co-Authored-By: Claude ` commit trailer (added automatically by Claude Code) satisfies attribution for routine changes. Explicit PR disclosure is required for: +- Any change to authentication or authorization +- Any change to payment or financial logic +- Any database schema change +- Any new external API integration + +### Code Review Expectations + +AI-generated code is not exempt from code review. Reviewers should apply the same — or stricter — scrutiny to AI-generated sections, particularly for: +- Security-sensitive paths (auth, crypto, access control) +- Data handling (PII, financial data) +- Edge cases and error conditions that AI tools often miss + +--- + +## 8. Accountability + +### Developer Responsibilities + +By using Claude Code on company systems, you agree to: +- Follow this charter +- Report suspected data exposure to [security@company.com] within 24 hours +- Participate in quarterly access reviews +- Complete AI tools onboarding checklist when joining or switching teams +- Not circumvent governance controls (hooks, deny rules, registry) + +### Team Lead Responsibilities + +- Ensure projects are configured with the appropriate guardrail tier +- Review MCP registry quarterly +- Include AI charter in team onboarding +- Escalate charter violations per §9 + +### Platform Team Responsibilities + +- Maintain shared governance config (settings.json templates, hooks) +- Review MCP approval requests within 1 week +- Update charter when tools, tiers, or risks change +- Conduct semi-annual governance audit + +--- + +## 9. Incident Response + +### If you suspect data exposure + +1. **Stop** the current AI session immediately +2. **Document** what data may have been included in the context (which files, what prompts) +3. **Report** to [security@company.com] with "AI Data Exposure" in subject, within 24 hours +4. **Do not** attempt to investigate or remediate without security guidance + +### Charter violations + +| Severity | Examples | Response | +|----------|----------|---------| +| **Minor** | Forgot AI attribution in PR, used unapproved MCP briefly | Coaching, remediation | +| **Moderate** | Used personal account with CONFIDENTIAL data, bypassed a hook | Formal warning, re-training | +| **Severe** | Processed RESTRICTED data with AI, persistent bypass of controls | HR/legal involvement | + +--- + +## 10. Compliance Mapping + +This charter addresses the following compliance requirements: + +| Framework | Relevant Controls | This Charter Addresses | +|-----------|------------------|----------------------| +| **SOC 2** | CC6.1 (Logical access), CC7.1 (Monitoring), CC9.2 (Vendor risk) | Data classification, MCP registry, audit logging | +| **ISO 27001** | A.8.3 (Access restriction), A.8.25 (Secure dev lifecycle), A.5.23 (Cloud services) | Approved tools, governance tiers, data handling | +| **HIPAA** (if applicable) | Security Rule §164.312 (Access control, Audit controls) | RESTRICTED data prohibition, compliance-mode logging | +| **PCI DSS** (if applicable) | Req 6.3 (Security vulnerabilities), Req 12 (Policy) | PCI data prohibition, code review requirements | +| **GDPR/CCPA** | Data minimization, purpose limitation | CONFIDENTIAL/RESTRICTED classification, data scope rules | + +--- + +## 11. Revision History + +| Version | Date | Author | Changes | +|---------|------|--------|---------| +| 1.0.0 | [DATE] | [Name] | Initial version | + +--- + +*Questions or exceptions: [engineering-lead@company.com] | Slack: [#ai-tools-governance]* diff --git a/examples/scripts/mcp-registry-template.yaml b/examples/scripts/mcp-registry-template.yaml new file mode 100644 index 0000000..2a92a37 --- /dev/null +++ b/examples/scripts/mcp-registry-template.yaml @@ -0,0 +1,138 @@ +# MCP Registry Template +# Copy to: .claude/mcp-registry.yaml in your shared config repo +# +# Purpose: Track approved MCP servers, their scope, and review status. +# This is the org-level source of truth for permitted MCP usage. +# +# Related: guide/security/enterprise-governance.md §3.2 + +metadata: + organization: "[Your Organization Name]" + review_cycle: quarterly + last_reviewed: "YYYY-MM-DD" + next_review: "YYYY-MM-DD" + owner: "platform-team@company.com" + policy_doc: "https://your-wiki/ai-usage-charter" + +# ───────────────────────────────────────────────────────────────── +# APPROVED MCPs +# ───────────────────────────────────────────────────────────────── +approved: + + # Example: Read-only documentation lookup (LOW risk) + - name: context7 + version: "1.2.3" # Pin exact version — never "latest" + source: "https://github.com/context7/mcp-server" + npm_package: "@context7/mcp-server" + approved_by: "john.doe@company.com" + approved_date: "2026-01-15" + expires: "2026-07-15" # 6 months default + data_scope: PUBLIC # PUBLIC | INTERNAL | CONFIDENTIAL | RESTRICTED + risk: LOW # LOW | MEDIUM | HIGH + rationale: "Read-only documentation lookup. No data egress, no credentials." + config: + command: npx + args: ["-y", "@context7/mcp-server@1.2.3"] + env: {} + + # Example: Local reasoning (LOW risk) + - name: sequential-thinking + version: "0.6.2" + source: "https://github.com/modelcontextprotocol/servers" + npm_package: "@modelcontextprotocol/server-sequential-thinking" + approved_by: "jane.smith@company.com" + approved_date: "2026-01-15" + expires: "2026-07-15" + data_scope: INTERNAL + risk: LOW + rationale: "Local reasoning only. No network access, no file I/O beyond scratch." + config: + command: npx + args: ["-y", "@modelcontextprotocol/server-sequential-thinking@0.6.2"] + env: {} + + # Example: Read-only internal database (MEDIUM risk, shorter expiry) + - name: internal-db-readonly + version: "2.1.0" + source: "internal" # "internal" for company-built MCPs + approved_by: "security@company.com" + approved_date: "2026-02-01" + expires: "2026-05-01" # Shorter expiry for higher risk + data_scope: CONFIDENTIAL + risk: MEDIUM + rationale: "Read-only replica. Allowlisted tables exclude PII, payments, audit." + restrictions: + - "Read-only database user only (no INSERT/UPDATE/DELETE)" + - "No access to: users, payments, audit_log, sessions tables" + - "Only connect to readonly replica, never primary" + config: + command: npx + args: ["-y", "@company/db-mcp@2.1.0"] + env: + DB_HOST: "readonly-replica.internal" + DB_USER: "claude_readonly" + # DB_PASS: loaded from secrets manager at runtime + +# ───────────────────────────────────────────────────────────────── +# PENDING REVIEW +# ───────────────────────────────────────────────────────────────── +pending_review: + + - name: github-mcp + requested_by: "dev@company.com" + requested_date: "2026-03-05" + source: "https://github.com/modelcontextprotocol/servers" + use_case: "Automated PR creation, issue management" + proposed_data_scope: INTERNAL + status: under_review # under_review | sandbox_trial | awaiting_security + reviewer: "jane.smith@company.com" + expected_decision: "2026-03-20" + notes: "Check GitHub token scope — should be limited to specific repos" + +# ───────────────────────────────────────────────────────────────── +# DENIED +# ───────────────────────────────────────────────────────────────── +denied: + + - name: browser-automation-mcp + denied_date: "2026-02-10" + requested_by: "dev2@company.com" + reason: > + Full browser automation with no scope restriction. Can navigate to arbitrary URLs, + exfiltrate data via screenshots, and access internal sites via authenticated sessions. + Risk too high without a sandboxed browser environment. + alternative: "Use Playwright MCP with restricted URL allowlist if browser access required." + + - name: filesystem-mcp-unrestricted + denied_date: "2026-01-20" + requested_by: "dev3@company.com" + reason: > + Unrestricted filesystem access. CVE-2025-53109/53110 not patched in requested version. + Would allow sandbox escape via prefix bypass + symlinks. + alternative: "Use Claude Code's built-in Read/Write/Edit tools with permissions.deny rules." + +# ───────────────────────────────────────────────────────────────── +# VERSION BUMP POLICY +# ───────────────────────────────────────────────────────────────── +version_bump_policy: + patch: # e.g., 1.2.3 → 1.2.4 + requires: check_release_notes # Check for CVEs/breaking changes, then auto-approve + approver: tech_lead + turnaround: "48h" + minor: # e.g., 1.2.3 → 1.3.0 + requires: full_security_review + approver: security_team + turnaround: "1 week" + major: # e.g., 1.2.3 → 2.0.0 + requires: full_security_review + sandbox_trial + approver: security_team + engineering_director + turnaround: "2 weeks" + +# ───────────────────────────────────────────────────────────────── +# SECURITY INCIDENT CONTACTS +# ───────────────────────────────────────────────────────────────── +incident_response: + report_to: "security@company.com" + slack: "#security-incidents" + response_time_sla: "4 hours business hours" + escalation: "engineering-director@company.com" diff --git a/guide/README.md b/guide/README.md index e6d6040..a46efb0 100644 --- a/guide/README.md +++ b/guide/README.md @@ -34,6 +34,7 @@ Core documentation for mastering Claude Code, organized by topic. | [security/sandbox-native.md](./security/sandbox-native.md) | Native Claude Code sandbox: configuration and security model | 10 min | | [security/production-safety.md](./security/production-safety.md) | Production safety: guardrails, review gates, rollback strategies | 15 min | | [security/data-privacy.md](./security/data-privacy.md) | Data retention and privacy guide | 10 min | +| [security/enterprise-governance.md](./security/enterprise-governance.md) | **Org-level governance**: usage charters, MCP approval workflow, guardrail tiers (Starter/Standard/Strict/Regulated), compliance | 25 min | --- diff --git a/guide/ops/ai-traceability.md b/guide/ops/ai-traceability.md index 68f9888..1646f98 100644 --- a/guide/ops/ai-traceability.md +++ b/guide/ops/ai-traceability.md @@ -735,6 +735,23 @@ git-ai init - Mandatory human-only review for security-critical? - Approval workflow for AI-heavy PRs? +### Evidence Collection for Auditors + +When SOC2, ISO27001, or HIPAA auditors ask for evidence of AI code governance, here's what to provide and where to find it: + +| Auditor request | Evidence source | How to generate | +|-----------------|----------------|-----------------| +| "Show your AI usage policy" | `docs/ai-usage-charter.md` | See [charter template](../../examples/scripts/ai-usage-charter-template.md) | +| "Show access controls for AI tools" | `.claude/settings.json` (permissions.deny) | Committed to each project repo | +| "Show third-party AI component vetting" | `.claude/mcp-registry.yaml` | See [registry template](../../examples/scripts/mcp-registry-template.yaml) | +| "Show audit log of AI actions" | `~/.claude/projects/**/*.jsonl` | Native session logs | +| "Show code review process for AI code" | PR descriptions with AI disclosure | PR template + attribution policy | +| "Show how AI incidents are handled" | Incident response runbook | Add AI section to existing IR docs | + +**Practical tip**: Run `./scripts/claude-governance-audit.sh` (see [enterprise-governance.md §5.3](../security/enterprise-governance.md#53-compliance-checking)) before each audit to verify controls are in place and generate a baseline report. + +**For session-level audit trails** with full context (prompts, reasoning, tool calls, diffs), Entire CLI creates cryptographically-linked checkpoints in Git. This is one approach among several — evaluate based on your retention requirements and team size. See [§5.1 Entire CLI](#51-entire-cli) for setup and evaluation criteria. + --- ## Templates diff --git a/guide/ops/observability.md b/guide/ops/observability.md index 83d1fca..f12f2c4 100644 --- a/guide/ops/observability.md +++ b/guide/ops/observability.md @@ -916,11 +916,70 @@ find ~/.claude/logs -name "*.jsonl" -mtime +30 -delete --- +--- + +## Manager Audit Checklist + +For engineering managers and team leads who need to verify Claude Code is being used appropriately within their team, these are the practical audit queries. + +### Weekly Spot Check (5 minutes) + +```bash +# Did anything unusual happen this week? + +# 1. Files accessed outside project scope +find ~/.claude/projects/ -name "*.jsonl" -newer "$(date -d '7 days ago' +%Y-%m-%d 2>/dev/null || date -v-7d +%Y-%m-%d)" 2>/dev/null | \ + xargs jq -r 'select(.type == "assistant") | + .message.content[]? | + select(.type == "tool_use" and .name == "Read") | + .input.file_path' 2>/dev/null | \ + grep -v "^$(pwd)" | sort -u + +# 2. Destructive commands run +find ~/.claude/projects/ -name "*.jsonl" -newer "$(date -d '7 days ago' +%Y-%m-%d 2>/dev/null || date -v-7d +%Y-%m-%d)" 2>/dev/null | \ + xargs jq -r 'select(.type == "assistant") | + .message.content[]? | + select(.type == "tool_use" and .name == "Bash") | + .input.command' 2>/dev/null | \ + grep -iE "(drop|delete|truncate|rm -rf|git push --force)" +``` + +### Compliance Reporting + +For regulated environments, generate a summary of AI activity for auditors: + +```bash +#!/bin/bash +# Monthly compliance report for Claude Code activity + +START_DATE=${1:-$(date -d '30 days ago' +%Y-%m-%d 2>/dev/null || date -v-30d +%Y-%m-%d)} +END_DATE=${2:-$(date +%Y-%m-%d)} +REPORT_FILE="ai-activity-report-${START_DATE}-${END_DATE}.json" + +echo "Generating compliance report: $START_DATE to $END_DATE" + +# Count sessions, tool calls, and file accesses +jq -s '{ + report_period: {start: "'"$START_DATE"'", end: "'"$END_DATE"'"}, + tool_usage: (group_by(.tool) | map({tool: .[0].tool, count: length})), + unique_files_accessed: ([.[].file] | unique | length), + sessions: ([.[].session_id] | unique | length) +}' ~/.claude/logs/activity-*.jsonl 2>/dev/null > "$REPORT_FILE" || \ + echo "No activity logs found. Set up session-logger.sh hook to enable." + +echo "Report saved: $REPORT_FILE" +``` + +For a full governance setup with automatic audit trail logging, see [Enterprise AI Governance §6.2](../security/enterprise-governance.md#62-audit-trail-setup). + +--- + ## Related Resources - [Session Search Script](../examples/scripts/session-search.sh) - Fast session search & resume - [Session Logger Hook](../examples/hooks/bash/session-logger.sh) - [Stats Analysis Script](../examples/scripts/session-stats.sh) +- [Enterprise AI Governance](../security/enterprise-governance.md) - Org-level governance, audit trails, compliance - [Third-Party Tools](../ecosystem/third-party-tools.md) - Community GUIs, TUIs, and dashboards (ccusage, ccburn, claude-code-viewer) - [Data Privacy Guide](../security/data-privacy.md) - What data leaves your machine - [Cost Optimization](./ultimate-guide.md#cost-optimization) - Tips to reduce spend diff --git a/guide/roles/adoption-approaches.md b/guide/roles/adoption-approaches.md index 6430a5a..dbae95e 100644 --- a/guide/roles/adoption-approaches.md +++ b/guide/roles/adoption-approaches.md @@ -284,6 +284,41 @@ These are starting points, not rules. Team dynamics matter more than headcount. > **Emerging approach**: Some organizations explore "corporate AI marketplaces" to pool AI skills, agents, and rules at the organizational level rather than individual teams (Hugo/Writizzy 2026[^hugo2026]). Few documented production implementations yet, but the concept addresses governance at scale. +### Enterprise Rollout (50+ developers or regulated environments) + +At this scale, individual team setups are not enough. You need a shared config baseline that applies consistently across all projects. + +**Phased rollout approach:** + +**Phase 1 — Foundation (Week 1–2)**: Establish the governance baseline. +- Create org-level shared config repo (`.claude/` templates per tier) +- Publish AI Usage Charter (see [charter template](../../examples/scripts/ai-usage-charter-template.md)) +- Start MCP registry with currently-used MCPs (even if just 3 entries) +- Install global safety hooks on all developer machines via onboarding script + +**Phase 2 — Adoption (Week 3–6)**: Roll out project configs. +- Classify existing projects by tier (Starter / Standard / Strict / Regulated) +- Bootstrap each project with the appropriate tier config via setup script +- Add Claude Code onboarding to engineering onboarding checklist +- Run first governance audit to baseline the current state + +**Phase 3 — Optimization (Month 2–3)**: Refine based on friction. +- Review hook false positive rate — tune rules that block legitimate work +- Identify MCP requests and process them through registry workflow +- Add CI/CD governance gates to catch config drift +- Conduct first quarterly MCP registry review + +**Common rollout mistakes at this scale:** + +| Mistake | Effect | Fix | +|---------|--------|-----| +| Rolling out Strict tier everywhere on day 1 | Developer resistance, workarounds | Start with Standard, move critical projects to Strict | +| No central config repo | Every team diverges within weeks | Platform team owns shared templates | +| Governance checks that block work | Developers disable hooks | Warn-only hooks, fix the root cause | +| No onboarding → charter ignored | Policy exists on paper only | 30-min onboarding session per team | + +**For formal compliance programs** (SOC2, ISO27001, HIPAA), the additional requirements around audit trails, data classification, and review cycles are covered in [Enterprise AI Governance](../security/enterprise-governance.md). + [^hugo2026]: Hugo, ["AI's Impact on State of the Art in Software Engineering in 2026"](https://eventuallymaking.io/p/ai-s-impact-on-the-state-of-the-art-in-software-engineering-in-2026), Feb 6, 2026. Based on interviews with Doctolib, Malt, Alan, Google Cloud, Brevo, ManoMano, Ilek, Clever Cloud engineering teams. --- diff --git a/guide/security/enterprise-governance.md b/guide/security/enterprise-governance.md new file mode 100644 index 0000000..2391453 --- /dev/null +++ b/guide/security/enterprise-governance.md @@ -0,0 +1,1117 @@ +--- +title: "Enterprise AI Governance for Claude Code" +description: "Org-level governance for teams deploying Claude Code at scale: usage charters, MCP approval workflows, guardrail tiers, and compliance" +tags: [security, enterprise, governance, compliance] +--- + +# Enterprise AI Governance for Claude Code + +> **Audience**: Tech leads, engineering managers, security officers deploying Claude Code across teams. +> +> **Scope**: Org-level governance (policies, approval workflows, tiers, compliance). For individual dev security (injection defense, MCP vetting, CVEs), see [security-hardening.md](./security-hardening.md). For the 6 non-negotiable production rules, see [production-safety.md](./production-safety.md). + +--- + +## TL;DR + +**The governance gap**: Claude Code security docs cover what individual devs should do. They don't cover what happens when your entire organization is using it — 50 developers, different risk profiles, no shared policy. + +**What this covers**: + +| Section | What it gives you | +|---------|------------------| +| [Local vs Shared](#1-local-vs-shared-the-governance-split) | Risk matrix + decision framework | +| [Usage Charter](#2-ai-usage-charter) | Lean template, ready to adapt | +| [MCP Governance](#3-mcp-governance-workflow) | Approval workflow + YAML registry | +| [Guardrail Tiers](#4-guardrail-tiers) | 4 pre-configured tiers, copy-paste settings.json | +| [Policy at Scale](#5-policy-enforcement-at-scale) | Rollout, onboarding, CI/CD gates | +| [Audit & Compliance](#6-audit-compliance--governance-structure) | What SOC2/ISO27001 auditors actually ask | + +--- + +## 1. Local vs Shared: The Governance Split + +The biggest mistake in enterprise AI governance is applying the same rules to everything. Local usage and shared usage have fundamentally different risk profiles. + +### 1.1 Risk Matrix + +| Dimension | Local usage | Shared usage | +|-----------|-------------|--------------| +| **Data exposure** | Developer's own files | Customer data, shared codebases, secrets | +| **Blast radius** | One machine | Entire repo, CI/CD, production | +| **Accountability** | Individual | Team / org | +| **Reproducibility** | Session ends, history gone | Needs audit trail | +| **Compliance scope** | Usually none | SOC2, ISO27001, HIPAA (if applicable) | +| **Config drift** | Personal preference | Team consistency matters | + +### 1.2 What You Can and Can't Control + +**You CAN control** (via committed config): +- Which MCP servers are approved (`settings.json` in repo) +- Which tools Claude can use (`permissions.deny`) +- What CLAUDE.md says about project conventions +- Hook scripts that run pre/post tool use +- CI/CD gates that validate AI-generated code + +**You CANNOT directly control**: +- Which personal `~/.claude/settings.json` developers have +- Which models they use on personal API keys +- What they do in personal projects outside your repos +- Memory / session content between sessions + +**The practical implication**: Focus governance on what's committed to your repos and deployed in shared environments. Personal dev workflow is the developer's responsibility. + +### 1.3 Decision Framework: When to Govern + +Not everything needs heavy governance. Apply controls proportionally. + +``` +What are you governing? +│ +├─ Personal dev workflow (local, throwaway code) +│ └─ Minimal: CLAUDE.md guidelines + basic hooks +│ +├─ Team codebase (shared repo, not production) +│ └─ Standard: shared settings.json + MCP registry + PR gates +│ +├─ Production system (customer-facing, real data) +│ └─ Strict: full tier config + approval workflow + audit log +│ +└─ Regulated environment (HIPAA, SOC2, PCI, finance) + └─ Regulated: all of above + compliance audit trail +``` + +--- + +## 2. AI Usage Charter + +A usage charter answers the fundamental question: "What are we allowed to do with Claude Code at this company?" Without it, each team answers differently, creating inconsistent risk exposure. + +This is the lean version. For a full charter with legal considerations, see [Whitepaper #11: Enterprise AI Governance](../../whitepapers/en/11-enterprise-ai-governance.qmd) (when available). + +### 2.1 Lean Charter Template + +Copy this into your org's `docs/ai-usage-charter.md` and adapt: + +```markdown +# AI Coding Tools Usage Charter + +**Applies to**: Claude Code (and any AI coding assistant) +**Effective date**: [DATE] +**Owner**: Engineering Lead / CTO +**Review cadence**: Quarterly + +--- + +## Approved Tools + +| Tool | Scope | Data Classification | +|------|-------|---------------------| +| Claude Code (Pro/Team/Enterprise) | All dev work | Up to CONFIDENTIAL | +| Claude Code (personal accounts) | Personal dev only | PUBLIC/INTERNAL only | +| [Other approved tools] | [Scope] | [Classification] | + +--- + +## Data Classification Rules + +| Classification | Examples | Allowed with Claude Code? | +|----------------|----------|--------------------------| +| **PUBLIC** | Open source, public docs | Yes, no restrictions | +| **INTERNAL** | Internal tools, non-sensitive code | Yes, standard config | +| **CONFIDENTIAL** | Customer PII, business secrets | Yes, Enterprise plan only | +| **RESTRICTED** | PCI card data, PHI, credentials | No — never in AI context | + +**Hard rule**: RESTRICTED data never enters an AI context window. Not in prompts, not in files Claude reads, not as examples. Configure `permissions.deny` to block access to restricted files. + +--- + +## Approved Use Cases + +- Code completion, review, refactoring +- Test generation +- Documentation drafting +- Debugging and root cause analysis +- Architecture analysis (internal systems only) +- CLI scripting and automation + +--- + +## Prohibited Use Cases + +- Processing payment card data (PCI scope) +- Generating code that handles raw PHI without security review +- Autonomous deployment to production without human approval +- Using personal AI accounts for CONFIDENTIAL or higher data +- Sharing customer data in prompts as examples + +--- + +## Who Approves What + +| Action | Approver | +|--------|---------| +| Add new MCP server to team config | Tech Lead + Security review | +| Enable Claude Code in new project | Team Lead | +| Use Enterprise features (Zero Trust, SSO) | IT/Security team | +| Exception to any charter rule | Engineering Director | + +--- + +## Compliance Obligations + +By using Claude Code on company systems, you agree to: +1. Follow this charter +2. Report suspected data exposure to security@[company] within 24h +3. Not circumvent governance controls (hooks, permission deny rules) +4. Participate in quarterly access reviews + +--- + +**Charter violations**: Follow standard disciplinary process. First occurrence: coaching. Repeated or severe: escalation. +``` + +### 2.2 Data Classification and Claude Code Settings + +Translate data classification into actual configuration: + +```json +// .claude/settings.json — CONFIDENTIAL tier +{ + "permissions": { + "deny": [ + "Read(./**/*.pem)", + "Read(./**/*.key)", + "Read(./.env)", + "Read(./.env.*)", + "Read(./secrets/**)", + "Read(**/credentials*)", + "Bash(cat .env*)", + "Bash(printenv*)", + "Bash(env)" + ] + } +} +``` + +```markdown + +## Data Handling + +**NEVER** read, reference, or include in output: +- Files matching: .env, *.pem, *.key, credentials.*, secrets/ +- Customer PII fields (fields named: email, phone, ssn, dob, card_*) +- Credentials or API keys (even masked/redacted examples) + +If you encounter restricted data while reading a file, stop and inform the user. +Do not proceed until explicitly told to skip that content. +``` + +--- + +## 3. MCP Governance Workflow + +Individual MCP vetting (the 5-minute audit) is covered in [security-hardening.md §1.1](./security-hardening.md#11-mcp-vetting-workflow). This section covers the organizational workflow: how new MCPs get approved, deployed, and monitored across your team. + +### 3.1 Approval Workflow + +``` +Developer wants new MCP + │ + ▼ +[1] Submit MCP Request + - Name, source URL, version + - Proposed use case + - Data scope (what will it access?) + │ + ▼ +[2] Security Review (Tech Lead + optionally Security team) + - 5-min MCP audit (see security-hardening.md) + - Check: Stars >50, recent commits, no dangerous flags + - Check: No CVEs (search NVD + GitHub security advisories) + - Classify risk: LOW / MEDIUM / HIGH + │ + ┌──┴──┐ + LOW MED/HIGH + │ │ + ▼ ▼ + Approve Extended review + (2-week trial in sandbox) + + approval from Security team + │ + ▼ +[3] Add to Approved Registry + - Pin exact version + - Document approved scope + - Set expiry date (6 months) + │ + ▼ +[4] Deploy via shared settings.json + - Committed to repo + - No local overrides for approved MCPs + │ + ▼ +[5] Monitor + Periodic Re-review + - Check for security advisories every 30 days + - Re-approve at version bumps (patch: auto, minor+: manual) + - Quarterly full registry review +``` + +### 3.2 MCP Registry Format + +Maintain an approved MCP registry at `.claude/mcp-registry.yaml` in your team's shared config repo: + +```yaml +# .claude/mcp-registry.yaml +# Approved MCP servers for [Organization Name] +# Last updated: 2026-03-10 +# Reviewer: [Name, Role] + +metadata: + review_cycle: quarterly + next_review: "2026-06-10" + owner: "platform-team@company.com" + +approved: + - name: context7 + version: "1.2.3" + source: "https://github.com/context7/mcp-server" + approved_by: "john.doe@company.com" + approved_date: "2026-01-15" + expires: "2026-07-15" + data_scope: PUBLIC + risk: LOW + rationale: "Read-only documentation lookup. No data egress." + config: + command: npx + args: ["-y", "@context7/mcp-server@1.2.3"] + + - name: sequential-thinking + version: "0.6.2" + source: "https://github.com/modelcontextprotocol/servers" + approved_by: "jane.smith@company.com" + approved_date: "2026-01-15" + expires: "2026-07-15" + data_scope: INTERNAL + risk: LOW + rationale: "Local reasoning only. No network access." + config: + command: npx + args: ["-y", "@modelcontextprotocol/server-sequential-thinking@0.6.2"] + + - name: internal-db-readonly + version: "2.1.0" + source: "internal" + approved_by: "security@company.com" + approved_date: "2026-02-01" + expires: "2026-05-01" # shorter expiry for higher risk + data_scope: CONFIDENTIAL + risk: MEDIUM + rationale: "Read-only replica access. No PII tables in allowlist." + restrictions: + - "Read-only credentials only" + - "No access to users, payments, or audit tables" + config: + command: npx + args: ["-y", "@company/db-mcp@2.1.0"] + +pending_review: + - name: github-mcp + requested_by: "dev@company.com" + requested_date: "2026-03-05" + use_case: "PR automation" + status: under_review + +denied: + - name: browser-automation-mcp + denied_date: "2026-02-10" + reason: "Full browser access with no scope restriction. Risk too high." +``` + +### 3.3 Enforcing the Registry via Hook + +Use a governance hook to validate that only approved MCPs are in use: + +```bash +#!/bin/bash +# .claude/hooks/governance-check.sh +# Event: SessionStart +# Validates active MCP config against approved registry + +REGISTRY=".claude/mcp-registry.yaml" +SETTINGS="${HOME}/.claude.json" + +if [[ ! -f "$REGISTRY" ]]; then + exit 0 # No registry = no enforcement (opt-in governance) +fi + +# Check for unapproved MCPs (requires yq and jq) +if command -v jq &>/dev/null && command -v yq &>/dev/null; then + ACTIVE=$(jq -r '.mcpServers | keys[]' "$SETTINGS" 2>/dev/null) + APPROVED=$(yq e '.approved[].name' "$REGISTRY" 2>/dev/null) + + for mcp in $ACTIVE; do + if ! echo "$APPROVED" | grep -q "^${mcp}$"; then + echo "GOVERNANCE WARNING: MCP '${mcp}' is not in approved registry." + echo "Submit a request at: https://your-internal-wiki/mcp-requests" + echo "Session continues — please remediate within 48 hours." + fi + done +fi + +exit 0 +``` + +**Note**: This hook warns, it does not block. Blocking at session start creates too much friction. Use periodic compliance checks instead (see §5.3). + +--- + +## 4. Guardrail Tiers + +Pre-configured guardrail tiers for four common scenarios. Copy the relevant tier into your project's `.claude/settings.json` and `CLAUDE.md`. + +### Tier 1: Starter + +**When**: Small team (<5), internal projects, no production data, low compliance requirements. + +```json +// .claude/settings.json — Starter tier +{ + "permissions": { + "deny": [ + "Read(./.env)", + "Read(./.env.*)", + "Read(./**/*.key)", + "Read(./**/*.pem)" + ] + }, + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": ["~/.claude/hooks/dangerous-actions-blocker.sh"] + } + ] + } +} +``` + +```markdown + +## Security Basics +- Never read .env files or credential files +- Ask before running destructive commands (DROP, DELETE, rm -rf) +- Follow the codebase's existing patterns +``` + +**Investment**: 10 minutes setup. Covers basics. + +### Tier 2: Standard + +**When**: Team 5–20, production-adjacent code, some sensitive data, no hard compliance requirements. + +```json +// .claude/settings.json — Standard tier +{ + "permissions": { + "deny": [ + "Read(./.env)", + "Read(./.env.*)", + "Read(./**/*.key)", + "Read(./**/*.pem)", + "Read(./secrets/**)", + "Bash(cat .env*)", + "Bash(printenv*)", + "Edit(docker-compose.yml)", + "Edit(.github/workflows/**)", + "Edit(terraform/**)" + ] + }, + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + "~/.claude/hooks/dangerous-actions-blocker.sh", + ".claude/hooks/dependency-guard.sh" + ] + }, + { + "matcher": "Edit|Write", + "hooks": [".claude/hooks/prompt-injection-detector.sh"] + } + ], + "PostToolUse": [ + { + "matcher": "Bash", + "hooks": ["~/.claude/hooks/output-secrets-scanner.sh"] + } + ], + "SessionStart": [ + ".claude/hooks/governance-check.sh" + ] + } +} +``` + +```markdown + +## Production Safety +- Infrastructure files (docker-compose, terraform, CI/CD) are locked. + Request permission before modifying. +- New dependencies require Tech Lead approval. Do not run npm install . +- Database destructive operations (DROP, DELETE, TRUNCATE) require backup confirmation. + +## Code Review Gate +- All AI-generated code touching auth, payments, or data access must be flagged + with a "AI-generated: review required" comment in the PR description. +``` + +**Investment**: 30–45 minutes setup. Covers most teams. + +### Tier 3: Strict + +**When**: Team 20+, production-critical systems, customer data, informal compliance expectations. + +```json +// .claude/settings.json — Strict tier +{ + "permissions": { + "deny": [ + "Read(./.env)", + "Read(./.env.*)", + "Read(./.env.local)", + "Read(./**/*.key)", + "Read(./**/*.pem)", + "Read(./secrets/**)", + "Read(**/credentials*)", + "Bash(cat .env*)", + "Bash(printenv*)", + "Bash(env)", + "Bash(npm install *)", + "Bash(pnpm add *)", + "Bash(pip install *)", + "Edit(docker-compose.yml)", + "Edit(docker-compose.prod.yml)", + "Edit(.github/workflows/**)", + "Edit(terraform/**)", + "Edit(kubernetes/**)", + "Edit(prisma/schema.prisma)" + ] + }, + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + "~/.claude/hooks/dangerous-actions-blocker.sh", + ".claude/hooks/dependency-guard.sh", + ".claude/hooks/velocity-governor.sh" + ] + }, + { + "matcher": "Edit|Write", + "hooks": [ + ".claude/hooks/prompt-injection-detector.sh", + ".claude/hooks/unicode-injection-scanner.sh" + ] + } + ], + "PostToolUse": [ + { + "matcher": "Bash", + "hooks": ["~/.claude/hooks/output-secrets-scanner.sh"] + }, + { + "matcher": "Edit|Write", + "hooks": [".claude/hooks/session-logger.sh"] + } + ], + "SessionStart": [ + ".claude/hooks/governance-check.sh", + "~/.claude/hooks/mcp-config-integrity.sh" + ] + } +} +``` + +```markdown + +## Security Posture: STRICT + +You are operating in a strict security environment. Follow these rules without exception. + +### Locked Files +These files cannot be modified without explicit permission in this conversation: +- docker-compose.yml, Dockerfile, .github/workflows/**, terraform/**, kubernetes/** +- prisma/schema.prisma (database schema) +- Any file in /src/auth/, /src/payments/, /src/crypto/ + +### Dependency Protocol +Before adding any dependency: +1. State the dependency name and purpose +2. List 2+ alternatives considered +3. Wait for explicit approval before running any install command + +### Data Access Protocol +Before reading any file not in the project root: +1. State the file path and why you need it +2. Wait for approval if the path looks sensitive + +### AI Attribution +All code blocks you generate must be prefixed with `// AI-generated` in PRs. +Tests generated by AI must include `// AI-generated test` comment. +``` + +**Investment**: 1–2 hours setup. Suitable for most production teams. + +### Tier 4: Regulated + +**When**: Finance, healthcare, regulated industries. HIPAA, SOC2, PCI, ISO27001 compliance required. + +This tier adds compliance-specific controls on top of Strict. + +```json +// .claude/settings.json — Regulated tier (inherits Strict, adds) +{ + "permissions": { + "deny": [ + "Read(./.env*)", + "Read(./**/*.key)", + "Read(./**/*.pem)", + "Read(./secrets/**)", + "Read(**/credentials*)", + "Read(**/patient*)", + "Read(**/phi*)", + "Read(**/pii*)", + "Read(**/card*)", + "Read(**/ssn*)", + "Bash(cat .env*)", + "Bash(printenv*)", + "Bash(env)", + "Bash(npm install *)", + "Bash(pnpm add *)", + "Bash(pip install *)", + "Bash(curl *)", + "Bash(wget *)", + "Edit(docker-compose*.yml)", + "Edit(.github/workflows/**)", + "Edit(terraform/**)", + "Edit(kubernetes/**)", + "Edit(prisma/schema.prisma)", + "Edit(**/auth/**)", + "Edit(**/crypto/**)", + "Edit(**/encryption/**)" + ] + }, + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + "~/.claude/hooks/dangerous-actions-blocker.sh", + ".claude/hooks/dependency-guard.sh", + ".claude/hooks/velocity-governor.sh", + ".claude/hooks/compliance-pre-check.sh" + ] + }, + { + "matcher": "Edit|Write", + "hooks": [ + ".claude/hooks/prompt-injection-detector.sh", + ".claude/hooks/unicode-injection-scanner.sh", + ".claude/hooks/pii-detector.sh" + ] + } + ], + "PostToolUse": [ + { + "matcher": ".*", + "hooks": [ + "~/.claude/hooks/output-secrets-scanner.sh", + ".claude/hooks/compliance-audit-logger.sh" + ] + } + ], + "SessionStart": [ + ".claude/hooks/governance-check.sh", + "~/.claude/hooks/mcp-config-integrity.sh", + ".claude/hooks/compliance-session-init.sh" + ] + } +} +``` + +```markdown + +## Compliance Mode: [HIPAA | SOC2 | PCI] — ACTIVE + +You are operating under regulatory compliance requirements. These rules are non-negotiable. + +### Prohibited Data +NEVER include in your output, suggestions, or examples: +- PHI (patient health information), PII (names, emails, phones in customer context) +- Card numbers, CVVs, bank accounts +- SSNs, tax IDs, government IDs +- Raw authentication tokens, session cookies, API keys + +### Mandatory Review Gates +These changes require human approval BEFORE code is committed: +- Any change to authentication or authorization logic +- Any change to encryption or key management +- Any database migration +- Any new external API integration + +### Audit Trail +Every session operating on regulated data must have: +- User ID noted at session start ("This session is for: [your-email]") +- Task description at session start ("Task: [brief description]") +- Checkpoint comment at natural breakpoints + +### AI Attribution (Mandatory for Regulated) +All AI-generated code must include: +- `// AI-generated: [date] [model] [reviewer]` comment +- PR description must include AI disclosure section +``` + +**Additional tool for regulated environments**: Consider Entire CLI for full session audit trails with approval gates. See [AI Traceability §5.1](../ops/ai-traceability.md#51-entire-cli) for details and a go/no-go evaluation checklist. + +--- + +## 5. Policy Enforcement at Scale + +Having a policy is not the same as enforcing it. This section covers how to actually get governance to stick across a team of 10–100 developers. + +### 5.1 Config Distribution + +**The core principle**: Governance config lives in the repo, not on individual machines. + +``` +your-org-config/ ← separate "platform config" repo +├── .claude/ +│ ├── settings.json ← shared settings (tier-based) +│ ├── mcp-registry.yaml ← approved MCPs +│ ├── hooks/ +│ │ ├── governance-check.sh ← MCP registry check +│ │ ├── compliance-logger.sh ← audit trail +│ │ └── dependency-guard.sh ← blocks unapproved installs +│ └── agents/ +│ └── security-reviewer.md ← shared agent for code review +├── templates/ +│ ├── CLAUDE.md.starter ← per-tier CLAUDE.md templates +│ ├── CLAUDE.md.standard +│ ├── CLAUDE.md.strict +│ └── CLAUDE.md.regulated +└── scripts/ + └── setup-project.sh ← bootstraps new project with correct tier +``` + +**Bootstrapping a new project**: + +```bash +#!/bin/bash +# scripts/setup-project.sh +# Usage: ./setup-project.sh [starter|standard|strict|regulated] + +TIER=${1:-standard} +CONFIG_REPO="https://github.com/your-org/claude-code-config" + +echo "Setting up Claude Code governance: $TIER tier" + +# Create .claude directory +mkdir -p .claude/hooks + +# Copy tier config +curl -s "$CONFIG_REPO/raw/main/templates/.claude/settings.${TIER}.json" \ + -o .claude/settings.json + +# Copy CLAUDE.md template +curl -s "$CONFIG_REPO/raw/main/templates/CLAUDE.md.${TIER}" \ + -o CLAUDE.md + +# Copy governance hooks +curl -s "$CONFIG_REPO/raw/main/hooks/governance-check.sh" \ + -o .claude/hooks/governance-check.sh +chmod +x .claude/hooks/governance-check.sh + +echo "Done. Commit .claude/ and CLAUDE.md to your repo." +``` + +### 5.2 Onboarding Checklist + +New developer joining a team that uses Claude Code should complete this checklist: + +```markdown +## Claude Code Onboarding Checklist + +### Setup (30 minutes) +- [ ] Install Claude Code: `npm i -g @anthropic-ai/claude-code` +- [ ] Configure global safety hooks: `./scripts/install-global-hooks.sh` +- [ ] Verify project config loads: `claude` then ask "What tier is this project?" +- [ ] Read the AI Usage Charter (link to your doc) +- [ ] Review approved MCP list: `.claude/mcp-registry.yaml` + +### Security Basics +- [ ] Confirm `~/.claude/settings.json` has no `permissions.allow` overrides + that bypass project's deny rules +- [ ] Confirm no personal MCP servers running that access production data +- [ ] Know how to report a data exposure: security@[company] + +### First Week +- [ ] Complete one task with Claude Code (bug fix, small feature) +- [ ] Submit at least one PR with proper AI attribution section +- [ ] Flag any friction points to Tech Lead for config improvement + +### Quarterly +- [ ] Participate in MCP registry review +- [ ] Review AI Usage Charter updates +- [ ] Confirm no personal config overrides in place +``` + +### 5.3 Compliance Checking + +Automated periodic compliance check to detect configuration drift: + +```bash +#!/bin/bash +# scripts/claude-governance-audit.sh +# Run weekly via CI/CD or cron + +PASS=0 +FAIL=0 +WARN=0 + +check() { + local name="$1" + local result="$2" + local severity="${3:-FAIL}" + + if [[ "$result" == "OK" ]]; then + echo " PASS: $name" + ((PASS++)) + else + echo " $severity: $name — $result" + [[ "$severity" == "FAIL" ]] && ((FAIL++)) || ((WARN++)) + fi +} + +echo "=== Claude Code Governance Audit ===" +echo "" + +# Check: settings.json present and committed +echo "1. Repository Config" +[[ -f ".claude/settings.json" ]] \ + && check "settings.json present" "OK" \ + || check "settings.json present" "Missing — team config not enforced" "FAIL" + +git ls-files --error-unmatch .claude/settings.json &>/dev/null \ + && check "settings.json committed" "OK" \ + || check "settings.json committed" "Not tracked by git — won't apply to team" "WARN" + +# Check: deny rules for secrets +echo "" +echo "2. Secret Protection" +if [[ -f ".claude/settings.json" ]]; then + jq -e '.permissions.deny[]? | select(test("env|pem|key"))' \ + .claude/settings.json &>/dev/null \ + && check ".env protection rules" "OK" \ + || check ".env protection rules" "No deny rules for .env or key files" "FAIL" +fi + +# Check: hooks installed and executable +echo "" +echo "3. Hook Stack" +for hook in ".claude/hooks/governance-check.sh" ".claude/hooks/dependency-guard.sh"; do + if [[ -f "$hook" ]]; then + [[ -x "$hook" ]] \ + && check "$hook executable" "OK" \ + || check "$hook executable" "Not executable — run chmod +x $hook" "FAIL" + else + check "$hook present" "Missing" "WARN" + fi +done + +# Check: MCP registry present +echo "" +echo "4. MCP Governance" +[[ -f ".claude/mcp-registry.yaml" ]] \ + && check "MCP registry present" "OK" \ + || check "MCP registry present" "No registry — MCP usage ungoverned" "WARN" + +# Check: CLAUDE.md present and committed +echo "" +echo "5. Documentation" +[[ -f "CLAUDE.md" ]] || [[ -f ".claude/CLAUDE.md" ]] \ + && check "CLAUDE.md present" "OK" \ + || check "CLAUDE.md present" "Missing — no project context for AI" "WARN" + +echo "" +echo "=== Summary ===" +echo " Passed: $PASS" +echo " Failed: $FAIL (must fix)" +echo " Warnings: $WARN (should fix)" +echo "" + +[[ $FAIL -gt 0 ]] && exit 1 || exit 0 +``` + +### 5.4 Role-Based Guardrails + +Different developers have different risk profiles. Tailor Claude Code settings accordingly. + +**Approach: tier by experience/role in CLAUDE.md** + +```markdown + +## Developer Context + +This is a [JUNIOR|SENIOR|LEAD] developer project context. + +### If JUNIOR (< 1 year at company) +- Always confirm architecture decisions before implementing +- Do not modify database schemas, migrations, or auth code without pairing with a senior +- Every PR must have a human reviewer check the AI-generated sections explicitly +- Use /plan mode before implementing anything > 50 lines + +### If SENIOR (1+ years at company) +- Standard review applies +- Can modify most files, but auth/payment/crypto still require lead review +- AI attribution in PRs required + +### If LEAD/PRINCIPAL +- Full access, judgment-based restrictions +- Responsible for setting guardrail tier for their team projects +- Must conduct quarterly MCP registry review +``` + +**Approach: different settings.json per environment** + +```bash +# CI/CD pipeline — use strict tier regardless of local config +CLAUDE_SETTINGS=".claude/settings.strict.json" claude run-headless ... + +# Local dev — use standard tier +# (default settings.json is already at Standard tier) +``` + +### 5.5 CI/CD Gates + +Block non-compliant AI usage from reaching production: + +```yaml +# .github/workflows/ai-governance.yml +name: AI Governance Check + +on: [pull_request] + +jobs: + governance: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Check governance config present + run: | + if [[ ! -f ".claude/settings.json" ]]; then + echo "::error::Missing .claude/settings.json — governance config required" + exit 1 + fi + + - name: Check no credential access permissions + run: | + if jq -e '.permissions.allow[]? | select(test("env|pem|key|secret"))' \ + .claude/settings.json 2>/dev/null; then + echo "::error::Dangerous permissions.allow detected — credentials may be exposed" + exit 1 + fi + + - name: Run governance audit + run: | + chmod +x scripts/claude-governance-audit.sh + ./scripts/claude-governance-audit.sh + + - name: Check AI attribution in PR description + if: ${{ env.REQUIRE_AI_ATTRIBUTION == 'true' }} + uses: actions/github-script@v7 + with: + script: | + const body = context.payload.pull_request.body || ''; + const hasAttribution = body.includes('AI') || + body.includes('Claude') || + body.includes('AI-generated'); + if (!hasAttribution) { + core.warning('No AI attribution section found. Please disclose AI usage.'); + } +``` + +--- + +## 6. Audit, Compliance & Governance Structure + +### 6.1 What SOC2 and ISO27001 Auditors Actually Ask + +When auditors review AI coding tool usage, they typically look for evidence of these controls: + +| Auditor question | What they want to see | Claude Code implementation | +|-----------------|----------------------|---------------------------| +| "Do you have a policy for AI tool usage?" | Written charter, signed/acknowledged | `docs/ai-usage-charter.md` + onboarding checklist | +| "How do you control data sent to AI vendors?" | Data classification + technical controls | `permissions.deny` for sensitive files | +| "How do you vet third-party AI components?" | Approval workflow + registry | MCP registry + approval process | +| "Do you have an audit trail of AI actions?" | Log of tool calls, files accessed | Session JSONL logs + `compliance-audit-logger.sh` | +| "How do you review AI-generated code?" | Code review process with AI disclosure | PR template + attribution policy | +| "What happens when an incident occurs?" | Incident response procedure | Existing IR process + AI-specific additions | + +**For SOC2 specifically**: The relevant Trust Services Criteria are CC6.1 (logical access controls), CC6.3 (access removal), CC7.1 (monitoring), and CC9.2 (vendor risk). Your Claude Code governance should map to these. + +**For ISO27001 specifically**: Relevant Annex A controls include A.8.3 (information access restriction), A.8.24 (use of cryptography), A.8.25 (secure development lifecycle), and A.5.23 (information security for use of cloud services). + +### 6.2 Audit Trail Setup + +Claude Code sessions are already logged to `~/.claude/projects//*.jsonl`. The challenge is making them: +1. Accessible after the fact (not lost when developer leaves) +2. Tamper-evident (can't be retroactively edited) +3. Queryable for audit purposes + +**Minimal audit trail (no additional tools)**: + +```bash +#!/bin/bash +# .claude/hooks/compliance-audit-logger.sh +# Event: PostToolUse (all tools) +# Appends structured audit entries to a shared log + +LOG_DIR="${COMPLIANCE_LOG_DIR:-/var/log/claude-audit}" +LOG_FILE="$LOG_DIR/$(date +%Y-%m-%d).jsonl" + +mkdir -p "$LOG_DIR" + +INPUT=$(cat) +TOOL=$(echo "$INPUT" | jq -r '.tool.name // "unknown"') +USER=$(whoami) +PROJECT=$(basename "$PWD") +TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ") + +echo "{\"timestamp\":\"$TIMESTAMP\",\"user\":\"$USER\",\"project\":\"$PROJECT\",\"tool\":\"$TOOL\"}" \ + >> "$LOG_FILE" +``` + +**Shipping logs to immutable storage** (recommended for regulated environments): + +```bash +# Daily: sync session logs to immutable bucket +aws s3 sync ~/.claude/projects/ \ + s3://your-audit-bucket/claude-sessions/$(whoami)/ \ + --storage-class GLACIER_INSTANT_RETRIEVAL \ + --exclude "*.tmp" +``` + +**For full compliance audit trails with approval gates**, consider Entire CLI — it captures complete session context (prompts, reasoning, tool calls, file diffs) with cryptographic linking to git commits. See [AI Traceability §5.1](../ops/ai-traceability.md#51-entire-cli) for setup and evaluation criteria. This is one tool among several options; evaluate against your specific compliance requirements. + +### 6.3 AI Governance Committee (Compact Reference) + +For organizations managing AI risk at scale, a lightweight AI Governance Committee provides the accountability structure auditors expect. This is a coordination mechanism, not a bottleneck. + +**Minimal structure** (works for 10–100 developers): + +| Role | Person | Responsibility | +|------|--------|----------------| +| **Governance Lead** | Engineering Manager or Lead | Policy updates, quarterly review, escalations | +| **Security Rep** | SecEng or DevSecOps | MCP risk review, incident response | +| **Dev Rep** | Senior dev rotation (3-month term) | Developer feedback, usability balance | +| **Compliance Rep** | Legal/Compliance (regulated only) | Charter, regulatory mapping | + +**Meeting cadence**: Quarterly (30 min). Standing agenda: +1. MCP registry review — anything to add, remove, or flag? +2. Incident review — any AI-related security events since last meeting? +3. Policy updates — any charter changes needed? +4. Metrics — governance audit results, compliance check status + +For detailed AI governance committee structures, RACI matrices, and compliance mapping, see Whitepaper #11: Enterprise AI Governance (FR/EN). + +### 6.4 Monitoring for Compliance + +The observability layer for governance is covered in [observability.md](../ops/observability.md). For compliance specifically, these monitoring queries are most relevant: + +```bash +# Which files did Claude access in the last 30 days? +find ~/.claude/projects/ -name "*.jsonl" -newer "$(date -d '30 days ago' +%Y-%m-%d)" | \ + xargs jq -r 'select(.type == "assistant") | + .message.content[]? | + select(.type == "tool_use" and .name == "Read") | + .input.file_path' 2>/dev/null | sort -u + +# Any access to sensitive patterns? +# (Run after the above, pipe through grep) +grep -E '\.(env|pem|key)$|secrets/|credentials' + +# Bash commands run by Claude this week +find ~/.claude/projects/ -name "*.jsonl" -newer "$(date -d '7 days ago' +%Y-%m-%d)" | \ + xargs jq -r 'select(.type == "assistant") | + .message.content[]? | + select(.type == "tool_use" and .name == "Bash") | + .input.command' 2>/dev/null | sort +``` + +--- + +## Quick Reference + +### Tier Selection + +| Your situation | Tier | Setup time | +|----------------|------|------------| +| Side project, personal use | Starter | 10 min | +| Small team, internal project | Starter | 10 min | +| Team 5–20, any production code | Standard | 45 min | +| Team 20+, customer data | Strict | 2 hours | +| Regulated industry (HIPAA/SOC2/PCI) | Regulated | Half day | + +### Governance Maturity Levels + +| Maturity | What you have | What's missing | +|----------|---------------|----------------| +| **Ad hoc** | Each dev configures own setup | Consistency, accountability | +| **Basic** | Shared CLAUDE.md + settings.json | MCP governance, audit trail | +| **Managed** | + MCP registry + hooks | Compliance reporting | +| **Compliant** | + Audit logs + charter + review cycle | Nothing critical | +| **Audited** | + External validation + traceability | — | + +### Common Mistakes + +| Mistake | Fix | +|---------|-----| +| Governance only in `~/.claude` (personal) | Move to `.claude/` in repo | +| `permissions.allow` overrides team's `deny` | Review personal config quarterly | +| No MCP registry → every dev adds different MCPs | Start registry even if just 3 entries | +| CLAUDE.md too long → Claude ignores rules | Keep under 8KB, prioritize critical rules | +| Auditors ask for AI logs → nothing saved | Set up session log sync to S3 | + +--- + +## See Also + +- [Security Hardening](./security-hardening.md) — Individual dev security: MCP CVEs, injection defense, 5-min audit +- [Production Safety Rules](./production-safety.md) — 6 non-negotiable rules for prod teams (ports, DB safety, infra lock) +- [Data Privacy Guide](./data-privacy.md) — What data Claude Code sends to Anthropic, retention policies +- [AI Traceability](../ops/ai-traceability.md) — Attribution policies, Entire CLI, git-ai, compliance frameworks +- [Observability](../ops/observability.md) — Session monitoring, cost tracking, activity audit queries +- [Adoption Approaches](../roles/adoption-approaches.md) — Team rollout patterns, CLAUDE.md strategies +- [MCP Registry Template](../../examples/scripts/mcp-registry-template.yaml) — Ready-to-use registry format +- [Governance Hook](../../examples/hooks/bash/governance-enforcement-hook.sh) — Hook validating config against policy +- [AI Usage Charter Template](../../examples/scripts/ai-usage-charter-template.md) — Charter template ready to adapt + +--- + +## References + +- [Liminal AI Enterprise Governance Guide](https://www.liminal.ai/blog/enterprise-ai-governance-guide) — Practical implementation +- [Databricks AI Governance Framework](https://www.databricks.com/blog/practical-ai-governance-framework-enterprises) — Enterprise-scale framework +- [Augmentcode AI Code Governance](https://www.augmentcode.com/guides/ai-code-governance-framework-for-enterprise-dev-teams) — Dev team specific +- [Partnership on AI — Six Governance Priorities 2026](https://partnershiponai.org/resource/six-governance-priorities/) — Evaluation frameworks, accountability +- [EU AI Act](https://www.europarl.europa.eu/doceo/document/TA-9-2024-0138_EN.html) — Kill switch requirements for high-risk AI systems +- [NIST AI RMF](https://airc.nist.gov/RMF/Overview) — Risk management framework +- [SOC2 Trust Services Criteria](https://www.aicpa.org/resources/article/soc-2-trust-services-criteria) — CC6.1, CC7.1, CC9.2 + +--- + +*Version 1.0.0 | March 2026 | Part of [Claude Code Ultimate Guide](../README.md)* diff --git a/guide/security/production-safety.md b/guide/security/production-safety.md index ca68ab8..7b8caf7 100644 --- a/guide/security/production-safety.md +++ b/guide/security/production-safety.md @@ -915,7 +915,8 @@ Team settings take precedence, but individuals can opt-in to stricter rules. - [Ultimate Guide §9.12 Git Best Practices](./ultimate-guide.md#912-git-best-practices--workflows) — Commit workflow, Plan → Act pattern - [Security Hardening Guide](./security-hardening.md) — MCP security, secret protection, hook stack - [Data Privacy Guide](./data-privacy.md) — MCP database risks, retention policies -- [Adoption Approaches](../roles/adoption-approaches.md) — Team setup, shared conventions +- [Enterprise AI Governance](./enterprise-governance.md) — Org-level governance: usage charters, MCP approval workflow, guardrail tiers, compliance +- [Adoption Approaches](../roles/adoption-approaches.md) — Team setup, shared conventions, enterprise rollout - [Plan Mode](./ultimate-guide.md#25-plan-mode) — Safe exploration before execution - [Permissions System](./ultimate-guide.md#33-settings--permissions) — Allow/deny rules, hooks diff --git a/guide/security/security-hardening.md b/guide/security/security-hardening.md index dccc95b..72b3636 100644 --- a/guide/security/security-hardening.md +++ b/guide/security/security-hardening.md @@ -855,12 +855,14 @@ Beyond securing Claude Code itself, Anthropic offers a dedicated vulnerability s ## See Also +- [Enterprise AI Governance](./enterprise-governance.md) — Org-level MCP governance (approval workflow, registry, guardrail tiers). This guide covers individual MCP vetting; that guide covers org-level policy. - [Data Privacy Guide](./data-privacy.md) — Retention policies, compliance, what data leaves your machine - [AI Traceability](../ops/ai-traceability.md) — PromptPwnd vulnerability, CI/CD security, attribution policies - [Security Checklist Skill](../examples/skills/security-checklist.md) — OWASP Top 10 patterns for code review - [Security Auditor Agent](../examples/agents/security-auditor.md) — Automated vulnerability detection (read-only) - [Security Patcher Agent](../examples/agents/security-patcher.md) — Applies patches from audit findings (human approval required) - [Security Gate Hook](../examples/hooks/bash/security-gate.sh) — Blocks vulnerable code patterns at write time (7 patterns) +- [MCP Registry Template](../../examples/scripts/mcp-registry-template.yaml) — YAML format for tracking approved MCPs at org level - [Ultimate Guide §7.4](./ultimate-guide.md#74-security-hooks) — Hook system basics - [Ultimate Guide §8.6](./ultimate-guide.md#86-mcp-security) — MCP security overview diff --git a/machine-readable/reference.yaml b/machine-readable/reference.yaml index 3c003bb..f213d9c 100644 --- a/machine-readable/reference.yaml +++ b/machine-readable/reference.yaml @@ -250,6 +250,29 @@ deep_dive: sandbox_anti_patterns: "guide/security/sandbox-isolation.md:546" # Anti-Patterns sandbox_comparison_matrix: "guide/security/sandbox-isolation.md:477" # Comparison Matrix sandbox_score: "4/5" + # Enterprise AI Governance (guide/security/enterprise-governance.md) - Added 2026-03-10 + enterprise_governance_guide: "guide/security/enterprise-governance.md" + enterprise_governance_local_vs_shared: "guide/security/enterprise-governance.md#1-local-vs-shared-the-governance-split" + enterprise_governance_charter: "guide/security/enterprise-governance.md#2-ai-usage-charter" + enterprise_governance_charter_template: "examples/scripts/ai-usage-charter-template.md" + enterprise_governance_mcp_workflow: "guide/security/enterprise-governance.md#3-mcp-governance-workflow" + enterprise_governance_mcp_registry: "guide/security/enterprise-governance.md#32-mcp-registry-format" + enterprise_governance_mcp_registry_template: "examples/scripts/mcp-registry-template.yaml" + enterprise_governance_guardrail_tiers: "guide/security/enterprise-governance.md#4-guardrail-tiers" + enterprise_governance_tier_starter: "guide/security/enterprise-governance.md#tier-1-starter" + enterprise_governance_tier_standard: "guide/security/enterprise-governance.md#tier-2-standard" + enterprise_governance_tier_strict: "guide/security/enterprise-governance.md#tier-3-strict" + enterprise_governance_tier_regulated: "guide/security/enterprise-governance.md#tier-4-regulated" + enterprise_governance_policy_at_scale: "guide/security/enterprise-governance.md#5-policy-enforcement-at-scale" + enterprise_governance_onboarding_checklist: "guide/security/enterprise-governance.md#52-onboarding-checklist" + enterprise_governance_compliance_check: "guide/security/enterprise-governance.md#53-compliance-checking" + enterprise_governance_cicd_gates: "guide/security/enterprise-governance.md#55-cicd-gates" + enterprise_governance_audit: "guide/security/enterprise-governance.md#6-audit-compliance--governance-structure" + enterprise_governance_soc2_iso27001: "guide/security/enterprise-governance.md#61-what-soc2-and-iso27001-auditors-actually-ask" + enterprise_governance_audit_trail: "guide/security/enterprise-governance.md#62-audit-trail-setup" + enterprise_governance_hook: "examples/hooks/bash/governance-enforcement-hook.sh" + enterprise_governance_audience: "Tech leads, engineering managers, security officers" + enterprise_governance_scope: "Org-level policy (vs security-hardening.md = individual dev security)" # Third-Party Tools (guide/ecosystem/third-party-tools.md) - Added 2026-02-01 third_party_tools_guide: "guide/ecosystem/third-party-tools.md" third_party_tools_cost_tracking: "guide/ecosystem/third-party-tools.md:42"