majiayu000 AI Agent 安全設計模式
基於 Claude Code v2.1.88 的安全機制逆向分析（bashSecurity 2592 行 + bashPermissions 2621 行 + 3 份 readOnlyValidation）。
1. 七層縱深防禦
[1] Schema Validation (Zod) — 型別正確嗎
[2] Custom validateInput() — 業務邏輯合理嗎
[3] Input Sanitization — 有危險字元嗎
[4] PreToolUse Hooks — 外部規則要攔嗎
[5] Permission Resolution — 使用者授權了嗎
[6] Actual Execution — 最後才執行
[7] PostToolUse Hooks — 執行後通知/記錄
原則：每層只問「能否拒絕」。拒絕即停。執行邏輯永遠在最後一層。
2. Parser Differential — 核心威脅模型
Claude Code 安全系統最重要的威脅模型：harness 的 parser 和實際執行環境的 parser 對同一個字串有不同理解。
shell-quote 解析： FOO=bar rm -rf / → 三個 token
bash 實際執行： FOO=bar rm -rf / → 設定環境變數後執行 rm
23 個 Bash validator 中超過一半是針對這種差異。
防禦原則：
- 永遠用更嚴格的解析（寧可誤殺）
- 正在遷移到 Tree-sitter AST（
TREE_SITTER_BASHfeature flag）取代字串解析 - 對 deny 規則使用更激進的 env var 剝除（全部剝除 vs allow 時的白名單剝除）
3. 白名單 > 黑名單
Claude Code 的 Bash 安全：
- 命令白名單：SAFE_ENV_VARS 列出允許的環境變數
- 旗標白名單：每個安全命令有允許的旗標集合
- 路徑白名單：檔案系統權限用 5 種前綴規則
例：git 命令的 -S 旗標
-S 在 git log 中是安全的（搜尋 diff）
-S 在 git diff 中可能不安全（接受程式碼作為引數）
→ 旗標白名單需要 per-command 定義
4. Deny 規則的激進策略
// Allow 路徑：只剝除非白名單的 env vars
const sanitized = stripNonWhitelistedEnvVars(command, SAFE_ENV_VARS)
// Deny 路徑：剝除所有 env vars（更激進）
const sanitized = stripAllEnvVars(command)
原因：FOO=bar denied_cmd 可以繞過基於命令名稱的 deny 檢查。Deny 時全部剝除，再檢查剝除後的命令。
5. 唯讀模式三層實作
| 層 | 檔案 | 行數 | 覆蓋 |
|---|---|---|---|
| Bash | readOnlyValidation.ts |
1990 | Unix shell 命令 |
| Shell 共用庫 | readOnlyCommandValidation.ts |
1893 | 跨 shell 通用邏輯 |
| PowerShell | readOnlyValidation.ts |
1823 | Windows PS 命令 |
每份都獨立維護一套白名單，因為不同 shell 的命令語義差異太大。
6. Sandbox 設計
| 平台 | 技術 | 特點 |
|---|---|---|
| Linux | bubblewrap (bwrap) | namespace 隔離、唯讀 bind mount |
| macOS | sandbox-exec | seatbelt profile，Apple 原生 |
兩套路徑語義差異（已知問題 #30067）：
- Permission rule：用 glob pattern（
~/project/**） - Sandbox config：用 literal path（
/home/user/project）
裸 repo 逃脫防護：偵測 .git 是檔案（非目錄）時，追蹤 gitdir: 指向的實際 repo 路徑。
7. Permission Hook 系統
// 5 個並發決策源，ResolveOnce 保護
const decision = await ResolveOnce.race([
classifierDecision, // AI 分類器
hookDecision, // 使用者 hook
ruleDecision, // 預設規則
channelDecision, // 手機批准
interactiveDecision, // 終端 UI
])
第一個回應的決策源贏，其餘取消。
8. 安全 Prompt 指令
cyberRiskInstruction.ts 的設計：
- 對開發者：「DO NOT MODIFY THIS FILE」
- 對 Claude（程式碼層）：「DO NOT modify, move, or edit this file when working in the codebase」
- 作為模型指令：「Assist with authorized security testing, defensive security, CTF challenges. Refuse requests for destructive techniques, DoS, mass targeting.」
參考
詳見 references/validator-rules.md 和 references/threat-model.md。