77b48db01b
New section for org-level Claude Code governance — fills the gap between individual dev security (security-hardening.md) and what engineering managers actually need when deploying at scale. New files: - guide/security/enterprise-governance.md (1117 lines) 6 sections: local/shared split, usage charter, MCP approval workflow, 4 guardrail tiers (Starter/Standard/Strict/Regulated), policy enforcement at scale, SOC2/ISO27001 compliance guide - examples/scripts/mcp-registry-template.yaml Org-level MCP registry with approved/pending/denied tracking - examples/hooks/bash/governance-enforcement-hook.sh SessionStart hook validating MCPs against approved registry - examples/scripts/ai-usage-charter-template.md Full charter template with data classification, use case rules, compliance mapping (SOC2/ISO27001/HIPAA/PCI DSS/GDPR) Enriched sections: - adoption-approaches.md: enterprise rollout (50+ devs) with 3-phase approach and common mistakes - observability.md: manager audit checklist, compliance reporting - ai-traceability.md: evidence collection table for auditors - production-safety.md + security-hardening.md: cross-references with explicit scope boundaries Integration: guide/README.md, reference.yaml (22 new entries), CHANGELOG.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
138 lines
6.7 KiB
YAML
138 lines
6.7 KiB
YAML
# 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"
|