Security Model

重要性：⭐⭐⭐ 目标读者：安全工程师 / 企业 IT / 高级用户 关联：analysis/security-audit.md

---

1. 安全概览

Claude Code 采用纵深防御（Defense in Depth）：

┌─────────────────────────────────────┐
│  Layer 0: OS 层（反调试 / PATH）    │
├─────────────────────────────────────┤
│  Layer 1: 用户层（信任对话框）    │
├─────────────────────────────────────┤
│  Layer 2: 配置层（白/黑名单）     │
├─────────────────────────────────────┤
│  Layer 3: 工具层（25+ validator）  │
├─────────────────────────────────────┤
│  Layer 4: AI 层（LLM classifier）   │
├─────────────────────────────────────┤
│  Layer 5: 监控层（audit / telemetry）│
└─────────────────────────────────────┘

6 层防御。

---

2. 6 大安全面

2.1 Bash 命令

风险：命令执行 防御： - 25+ validator（tools/BashTool/bashSecurity.ts） - 6 层决策（exact → wildcard → sandbox → early deny → semantic → classifier） - 50 subcommands 上限 - speculative LLM classifier - 完整审计见 analysis/security-audit.md

2.2 MCP

风险：外部 server 任意工具 防御： - OAuth 2.0 + PKCE 强制 - 2 步动态 client registration - 12 项敏感参数脱敏 - 30s timeout - Step-up auth - 完整审计见 deep-dive-mcp-auth.md

2.3 Path

风险：rm -rf / 等 防御： - 680 行 CmdletPathConfig - 50+ cmdlet 配置 - isDangerousRemovalRawPath - 保守 deny（未明确路径 = deny） - glob 不展开 - 完整审计见 deep-dive-powershell-path.md

2.4 Auth

风险：API key 泄露 防御： - 5 种方式（API key / helper / OAuth / AWS / GCP） - macOS keychain 隔离 - pending401Handlers 去重 - 5min / 15min / 1h TTL - 完整审计见 deep-dive-auth.md

2.5 Settings

风险：配置篡改 防御： - 4 级 settings 源（policy > local > project > user） - Enterprise policy limits - Remote managed settings（失败 open） - Settings 同步（feature gate）

2.6 Telemetry

风险：敏感信息泄露 防御： - 命名约定 _I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS - URL 凭证脱敏 - 12 项 OAuth 敏感参数脱敏 - 用户可控 isAnalyticsDisabled - 完整审计见 logging-telemetry.md

---

3. 6 层防御详解

3.1 Layer 0: OS 层

// Windows PATH 防御
process.env.NoDefaultCurrentDirectoryInExePath = '1'

// 反调试（商业版）
if ("external" !== 'ant' && isBeingDebugged()) {
  process.exit(1)
}

2 措施。

3.2 Layer 1: 用户层

// 信任对话框
if (!checkHasTrustDialogAccepted()) {
  // 警告 + 退出
}

// Sandbox 模式
function checkSandboxAutoAllow(command): boolean { ... }

2 措施。

3.3 Layer 2: 配置层

// settings.json
{
  "permissions": {
    "allow": ["Bash(git:*)"],
    "deny": ["Bash(rm -rf:*)"]
  }
}

白/黑名单。

3.4 Layer 3: 工具层

// bashSecurity.ts
function validateXxx(context): PermissionResult { ... }
// 25+ validator

25+ 规则。

3.5 Layer 4: AI 层

// LLM classifier
async function bashClassifier(command): Promise<{ allow, reason }> { ... }

// speculative
const speculativeChecks = new Map()

LLM 兜底。

3.6 Layer 5: 监控层

// logError
logError(err)

// logEvent
logEvent('tengu_security_xxx', { ... })

审计。

---

4. 信任模型

4.1 完全信任

• ✅ 用户的 settings.json
• ✅ 项目级 .claude/settings.json
• ⚠️ Plugin（需审查）
• ❌ MCP server（需审查）

4.2 零信任

• ❌ 用户输入
• ❌ Hook 输出
• ❌ Tool result 内容
• ❌ Bash 命令
• ❌ 网络响应

零信任外部输入。

4.3 部分信任

• ⚠️ Skill 内容
• ⚠️ Command 描述
• ⚠️ Agent 描述

部分信任——需校验。

---

5. 攻击面

5.1 攻击者能做什么

恶意 plugin    → 任意代码执行
恶意 MCP server → 任意工具注册 + 任意 IO
恶意 hook      → shell 命令
恶意 skill     → prompt 注入

4 攻击面。

5.2 攻击者不能做什么

- 修改其他 plugin 路径（路径校验）
- 隐藏 stderr 信息（脱敏）
- 无限次重试 refresh（pending401Handlers）
- 跨 token 关联（隔离）

4 不能。

---

6. Prompt 注入防御

6.1 攻击向量

@ 提及文件内容 → 进入 prompt
bash 输出 → 引用
plugin 描述 → tool description
hook 输出 → 注入

4 攻击向量。

6.2 防御

// 1. @ 提及隔离为独立 message
// 2. bash 输出引用（非内联）
// 3. tool 描述截断 2KB
const MAX_MCP_DESCRIPTION_LENGTH = 2048

// 4. system prompt 显式声明

4 防御。

---

7. 数据流

用户输入
  ↓
@ 提及（隔离）
  ↓
attachments（无恶意）
  ↓
system prompt
  ↓
Claude API
  ↓
tool 决策
  ↓
hook 检查
  ↓
实际执行
  ↓
tool result
  ↓
引用（而非内联）
  ↓
下轮 prompt

11 步。

---

8. 凭据保护

8.1 5 种凭据

凭据	存储	加密
API key (env)	env var	OS env 隔离
API key (keychain)	macOS keychain	OS 加密
OAuth token	local file	filesystem perms
AWS STS	内存	OS mem
GCP creds	内存	OS mem

5 种。

8.2 防御

• ❌ 不存 plaintext 到 log
• ❌ 不上报 API key
• ❌ 不进 telemetry
• ✅ 内存隔离
• ✅ OS 加密（keychain）

5 措施。

---

9. 5 个反模式（项目避免的）

9.1 静默失败

// ❌
try { } catch (e) {}
// ✅
try { } catch (e) { logError(e); throw }

避免静默。

9.2 错误信息含敏感

// ❌
throw new Error(`API call failed: ${apiKey}`)
// ✅
throw new Error('API call failed')

避免泄露。

9.3 sudo

// ❌
"command": "sudo my-hook.sh"
// ✅
"command": "my-hook.sh"  // 不要 sudo

避免 sudo。

9.4 路径跳出

// ❌
"command": "../../../etc/passwd"
// ✅
"command": "./scripts/validate.sh"

避免跳出。

9.5 不验证输入

// ❌
process.argv[2]  // 不验证
// ✅
const validated = zodSchema.parse(process.argv[2])

验证输入。

---

10. 合规考虑

10.1 SOC 2

• 审计日志
• 访问控制
• 数据加密

3 项。

10.2 GDPR

• 数据最小化
• 用户控制
• 透明度

3 项。

10.3 HIPAA

• 不存 PHI
• 加密传输
• 审计

3 项。

---

11. 5 个企业部署建议

11.1 Policy Settings

// /etc/claude-code/policy.json
{
  "permissions": {
    "deny": ["Bash(rm -rf:*)", "WebFetch", "Bash(curl:*)"]
  }
}

强制。

11.2 远程管理

loadRemoteManagedSettings()  // 异步拉取

集中管理。

11.3 审计日志

logEvent('tengu_audit', { ... })

审计。

11.4 关闭 telemetry

CLAUDE_CODE_DISABLE_TELEMETRY=1

关闭。

11.5 Sandbox

# 启用 sandbox
--sandbox

沙箱。

---

12. 5 个安全更新检查

12.1 bash validator

# 检查 25+ validator 是否齐全
grep "function validate" tools/BashTool/bashSecurity.ts | wc -l

检查。

12.2 凭证脱敏

# 检查 log 中无 API key
grep -i "sk-ant-" logs/*.jsonl

检查。

12.3 路径校验

# 检查 plugin hooks 路径
grep "hooks" plugins/*/hooks/hooks.json

检查。

12.4 信任模型

# 检查未签字的 plugin
claude plugin validate --strict

检查（推测）。

12.5 feature flag

# 确认商业版 vs 内部版
echo $BUILD_TYPE

检查。

---

13. 5 个常见误解

1. "plugin 沙箱" —— ❌ 没有
2. "MCP server 隔离" —— ❌ 没有
3. "hook 沙箱" —— ❌ 没有
4. "自动审核" —— ❌ 没有
5. "100% sandbox" —— ❌ 没有

5 误解——用户自己负责。

---

14. 5 个推荐工作流

14.1 启动前

# 看 settings
cat .claude/settings.json

# 看 plugins
claude plugin list

# 看 MCP
claude mcp list

审计。

14.2 启动时

# 检查 trust dialog
# 接受 / 拒绝

信任。

14.3 运行时

# 看 log
claude --debug api

观察。

14.4 完成后

# 关闭 session
exit

清理。

14.5 团队

• 共享 .claude/settings.json 模板
• 共享 plugin 集合
• 共享 hook 脚本
• 共享 marketplace

共享。

---

15. 总结

Claude Code 的安全模型 = 纵深防御 + 用户责任。

核心： - 6 层防御 - 6 大安全面 - 25+ bash validator - 5 种凭据保护 - 4 种 credential 存储 - 用户负责审查

下一步： - 审计 security-audit.md - 配 policy - 监控