marketing-shibata50/claude-code-ultimate-guide
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(security): add enterprise AI governance guide + templates

Browse source 
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>
This commit is contained in:
Florian BRUNIAUX 2026-03-10 11:05:21 +01:00
parent b65630641b
commit 77b48db01b
12 changed files with 1797 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

200
examples/scripts/ai-usage-charter-template.md Normal file
View file

@ -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 <noreply@anthropic.com>` 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]*

138
examples/scripts/mcp-registry-template.yaml Normal file
View file

@ -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"