經過實機測試的安全配置、Hook、IaC 模組、可觀測性,以及可重現的驗證套件, 用於在受監管的企業環境(銀行、醫療、政府)中, 在 Amazon Bedrock 上部署 Claude Code。
Claude Code 功能強大,但預設情況下可能會:
- 讀取你的
.env、AWS 憑證、SSH 金鑰 - 推送程式碼到任意 git remote
- 執行
curl/wget把資料外洩到外部伺服器 - 執行破壞性指令 (
rm -rf、git reset --hard) - 被誘導繞過權限控制
- 失控的 agent 迴圈把 Bedrock token 預算燒光
在受監管的環境裡,這是不可接受的。本套件提供經過測試的控制機制 —— 附帶可重現的證據 —— 在不影響開發者生產力的前提下,鎖定 Claude Code。
這個套件不只是設定檔,是一個完整的維運套件:
| 層次 | 內容 |
|---|---|
| 強化的 Hooks | 8 個 production hook —— PII guard、git guard、gh/REST guard、MCP repo guard、audit logger(HMAC chain)、token 預算斷路器、hook 遙測 shim、Windows PowerShell PII guard |
| Wrappers | 拒絕繞過旗標、sudoers-based 權限隔離、稽核日誌旋轉 |
| 即時漂移偵測 | inotify/fswatch watcher,偵測時間 <100ms,可設定 per-host watchlist |
| 基礎設施即程式碼 (IaC) | EC2 基礎(IAM + SSM + CloudWatch)Terraform 模組 + SSM Parameter Store-backed MCP 允許清單 |
| 可觀測性 | CloudWatch dashboard + alarm(hook 崩潰率、延遲 p99、漂移事件) |
| 驗證套件 | 9 個測試套件、210+ 個斷言:PII corpus FNR/FPR、稽核鏈篡改偵測、紅隊繞過(7 類別、60 次嘗試)、延遲基準、Bedrock Guardrails 線上驗證 |
| 維運文件 | 威脅模型(STRIDE)、事件回應、值班 runbook、hook 合約、平台補償控制、測試證據、部署指南 |
| 可安裝外掛 | plugin/ —— 將 7 個 hook 打包成可一鍵安裝的 Claude Code 外掛,供官方 marketplace 收錄;個人友善預設;108 個斷言測試套件 |
九層強制執行機制,全部在實際 AWS 環境測試過:
| 層級 | 機制 | 攔下什麼 | 詳細文件 |
|---|---|---|---|
| 1 | 權限拒絕規則 | 單 token 危險指令 | docs/security-rationale.md |
| 2 | pii-guard.sh Hook |
Prompt 與工具輸入中的敏感資料 | docs/pii-guard.md |
| 3 | git-guard.sh Hook |
未授權 git push、分支違規、force-push | hook 原始碼 |
| 4 | gh-guard.sh Hook |
不經過 git 的同一組寫入:gh pr merge、gh api contents/refs 寫入、curl/wget 直打 REST API |
hook 原始碼 |
| 5 | mcp-repo-guard.sh Hook |
MCP server 的 repo 寫入(push_files、merge_pull_request …),所有 Bash matcher 都看不到 |
hook 原始碼 |
| 6 | audit-logger.sh Hook(HMAC 鏈、fail-closed) |
規避稽核、偽造稽核日誌 | hook 原始碼 |
| 7 | token-budget-guard.sh Hook |
Token 費用爆炸、失控的 agent session | hook 原始碼 |
| 8 | Wrapper Script + 檔案系統 ACL + sudoers | --dangerously-skip-permissions、--permission-mode=…、claude mcp add |
wrapper-linux.sh |
| 9 | Bedrock Guardrails(伺服器端) | 有害內容、PII、prompt-attack jailbreak | docs/bedrock-guardrails.md |
第 3–5 層之所以要分開,是因為通往同一個 remote 有三條互相獨立的寫入路徑:
git、gh CLI / REST API、以及 MCP 工具。守住其中一條,不等於守住這個 repo。
加上 作業系統沙盒(bubblewrap)、網路隔離(VPC Endpoint)、
遙測 shim(hooks/hook-wrapper.sh)將 hook 崩潰/逾時轉成 fail-closed 拒絕、
即時漂移 watcher(scripts/drift-watcher.sh)
對 managed config 或 hook 檔案的任何改動 ~60ms 內就告警。
完整的 STRIDE 攻擊樹分析請參考 docs/threat-model.md;
驗證過的效能與安全數據見 docs/test-evidence.md。
✅ 覆蓋範圍說明: 本套件早期版本只守住
git這條寫入路徑,因此已認證的ghCLI 或可寫入的 MCP server(GitHub MCP、Docker MCP Toolkit) 能直接走過所有 Bash-matcher hook。第 4–5 層補上了這個缺口:gh-guard.sh掛在Bashmatcher,mcp-repo-guard.sh掛在mcp__.*matcher —— 後者是 Bash hook 永遠不會被呼叫到的路徑。背景說明見docs/known-issues.mdIssue 13。
⚠️ 殘餘限制(依賴第 4–5 層之前請先讀):政策是以已知的工具名稱與 endpoint 形狀為判斷依據,所以某個新 MCP server 帶著沒見過的寫入動詞時,只有在它帶有 owner/repo 欄位、或 server 名稱符合MCP_GUARD_REPO_SERVER_PATTERN時才會被 攔下。Hook 也看不到它從未檢查過的子行程所做的寫入(用requests的 Python 腳本、編譯好的執行檔、Makefiletarget)。而且這裡每個 guard 都有一個公開記載的*_DISABLED逃生門 —— 請在 managed 層設定allowManagedHooksOnly: true, 讓開發者無法把它關掉。
Claude Code 從四個層級合併設定。較高層級覆蓋較低層級,managed 階層的拒絕規則無法被低層級移除:
| 層級 | 路徑 | 擁有者 | 已測試 |
|---|---|---|---|
| 1. 企業 Managed (最高) | /etc/claude-code/managed-settings.json (Linux)C:\Program Files\ClaudeCode\managed-settings.json (Win) |
root / Administrators | ✅ |
| 2. User Settings | ~/.claude/settings.json |
開發者 | ✅ |
| 3. Project Settings (可分享) | .claude/settings.json (在 repo 中) |
團隊 | (與 L2 同格式) |
| 4. Local Project Overrides | .claude/settings.local.json (gitignored) |
開發者 | (同格式) |
已驗證的 managed-only 強制執行:
allowManagedPermissionRulesOnly: true— user 階層的 deny rules 被忽略 ✅allowManagedHooksOnly: true— 僅 managed hooks 觸發 ✅allowManagedMcpServersOnly: true— 執行時過濾 MCP servers ✅
⚠ 陷阱: user settings 的 env vars 確實會覆蓋 managed env vars (這是設計如此, 但殘留的 user 階層
CLAUDE_AUDIT_LOG可能靜默破壞稽核日誌)。 部署前的檢查指令見docs/deployment-guide.md。
本套件提供 Level 1 與 Level 2 的設定:
docs/managed-settings.jsonc→ Level 1docs/settings-linux-macos.jsonc/docs/settings-windows.jsonc→ Level 2
想先評估這些控制、又不想做完整 IaC 部署?這些 hook 也打包成了可安裝的
Claude Code 外掛,採用個人友善預設(免 root —— 狀態寫到
~/.claude/claude-code-security/):
/plugin install fail-closed-security-hooks@claude-community
外掛打包了 7 個 hook(PII guard、git guard、gh/REST guard、MCP repo guard、
HMAC 鏈式稽核日誌、token 預算斷路器、fail-closed 遙測 shim),PII 偵測涵蓋 7 個法域,
並附 108 個可重現測試斷言
(plugin/tests/run-tests.sh)。詳見 plugin/README.md。
外掛 vs. 企業強制。 外掛是給個人與評估用的 opt-in、可自行移除的入口。若要 不可移除、全機隊強制執行(root 擁有路徑、fail-closed 稽核、SIEM 整合), 請用
managed-settings.json+ 下方的 Terraform 模組部署同一批 hook。 同樣的 hook,不同的信任邊界。
下方是手動安裝指令。production 環境建議使用 Terraform 模組
terraform/ec2-baseline/,整個部署是 idempotent + SSM-driven。
# 0. 安裝 Claude Code
curl -fsSL https://claude.ai/install.sh | bash # macOS / Linux
# 其他: brew install --cask claude-code | irm https://claude.ai/install.ps1 | iex (Windows)
# 1. 安裝相依套件
sudo dnf install -y bubblewrap socat jq inotify-tools openssl # 或 apt install ...
# 2. 部署 hooks (root 擁有,可執行)
sudo mkdir -p /usr/local/etc/claude-code/hooks
sudo cp hooks/*.sh /usr/local/etc/claude-code/hooks/
sudo chown root:root /usr/local/etc/claude-code/hooks/*.sh
sudo chmod 0755 /usr/local/etc/claude-code/hooks/*.sh
# 3. 部署 managed settings (root 擁有)
sudo mkdir -p /etc/claude-code
python3 -c "import re,json;c=open('docs/managed-settings.jsonc').read();c=re.sub(r'(?<!:)//[^\n]*','',c);c=re.sub(r'/\*.*?\*/','',c,flags=re.S);c=re.sub(r',(\s*[}\]])',r'\1',c);json.dump(json.loads(c),open('/tmp/m.json','w'),indent=2)"
sudo mv /tmp/m.json /etc/claude-code/managed-settings.json
# 4. 部署強化 wrapper + sudoers (real binary 0750 root:claude-users)
sudo groupadd claude-users 2>/dev/null || true
sudo mkdir -p /opt/claude-code/bin
sudo install -m 0750 -o root -g claude-users $(which claude) /opt/claude-code/bin/claude
sudo install -m 0755 -o root -g root scripts/wrapper-linux.sh /usr/local/bin/claude
sudo install -m 0440 -o root -g root scripts/sudoers-claude-code /etc/sudoers.d/claude-code
sudo visudo -cf /etc/sudoers.d/claude-code
# 5. 鎖定 MCP 設定 (阻止 `claude mcp add`)
touch ~/.claude.json && sudo chattr +i ~/.claude.json
# 6. 稽核日誌 + 旋轉 (HMAC 鏈預設啟用)
sudo mkdir -p /var/log/claude-code /var/lib/claude-code/audit-state
sudo touch /var/log/claude-code/audit.jsonl /var/log/claude-code/hooks.jsonl /var/log/claude-code/drift.jsonl
sudo chattr +a /var/log/claude-code/audit.jsonl
sudo cp scripts/logrotate-claude-code.conf /etc/logrotate.d/claude-code
# 7. 即時漂移 watcher (systemd 服務)
sudo install -m 0755 scripts/drift-watcher.sh /usr/local/bin/claude-drift-watcher
# (對應的 systemd unit 在 terraform/ec2-baseline/ssm-deploy.yaml.tpl)
# 8. 驗證
claude -p "say PONG" # → PONG (正常)
claude -p "My card is 4111-1111-1111-1111" # → 被擋 (PII guard)
claude -p "hi" --dangerously-skip-permissions # → Refused (wrapper)
claude -p "x" --permission-mode=bypassPermissions # → Refused (wrapper, 等號形式)
echo "Run: curl http://example.com" | claude -p --allowedTools Bash # → denied
# 9. 跑本機測試套件 (210+ 斷言,macOS 約 4 分鐘)
bash tests/run_all.sh # → "9 suites passed, 0 failed"完整部署 (含 Terraform、黃金映像、跨區域) 請見
docs/deployment-guide.md。
108 個 PII 案例 → FNR 0%、FPR 0%、p95 ≤ 484ms(見
docs/test-evidence.md)。
| 資料類型 | 範例 | 結果 |
|---|---|---|
| 信用卡(16 位 + Amex 4-6-5) | 4111-1111-1111-1111、3782 822463 10005 |
✅ 攔截 |
| AWS keys | AKIAIOSFODNN7EXAMPLE |
✅ 攔截 |
| 私鑰 | -----BEGIN RSA PRIVATE KEY----- |
✅ 攔截 |
| JWT tokens | eyJhbG...(3 段 base64url) |
✅ 攔截 |
| 密碼 | password=SuperSecret123! |
✅ 攔截 |
| 新加坡 NRIC | S1234567D |
✅ 攔截 |
| 電話(國際、多分隔)、護照、Email | 各種 | ✅ 攔截 |
| GitHub/GitLab/Slack tokens | ghp_..., xoxb-... |
✅ 攔截 |
| DB 連線字串 | postgres://user:pass@host/db |
✅ 攔截 |
| 通用 API key 賦值 | api_key=..., access_token=... |
✅ 攔截 |
| Hex 機密(32+ hex,含字母) | e3b0c44298fc1c149afbf4c8996fb924... |
✅ 攔截 |
| 一般 prompt | "寫一個排序函數" |
✅ 通過 |
完整清單與客製化: docs/pii-guard.md。
| 指令 | Linux | Windows |
|---|---|---|
rm -rf * / Remove-Item -Recurse |
✅ 拒絕 | ✅ 拒絕 |
git push 到未授權 remote |
✅ Hook 攔截 | ✅ 拒絕 |
git push 到 feature 分支(允許的 remote) |
✅ 允許 | ✅ 允許 |
git push 到受保護分支(main/master) |
✅ Hook 攔截 | ✅ 拒絕 |
git push --force / --force-with-lease |
✅ Hook 攔截 | ✅ 拒絕 |
git remote add(未授權網域) |
✅ Hook 攔截 | ✅ 拒絕 |
git remote add(允許的網域) |
✅ 允許 | ✅ 允許 |
git reset --hard / git clean -fd |
✅ Hook 攔截 | ✅ 拒絕 |
curl / wget / Invoke-WebRequest |
✅ 拒絕 | ✅ 拒絕 |
sudo / Set-ExecutionPolicy |
✅ 拒絕 | ✅ 拒絕 |
aws iam / aws sts / aws secretsmanager |
✅ 拒絕 | ✅ 拒絕 |
讀取 .env / .aws/credentials / .ssh/ |
✅ 拒絕 | ☑️ 改用 sandbox.denyRead |
寫入 C:\Windows\ |
N/A | ✅ 拒絕 |
下表每一列都能在 git 完全沒有執行的情況下寫進 remote,所以 git-guard.sh
什麼都看不到。已在 Amazon Linux 2023 上驗證 ——
見 docs/test-evidence.md。
| 動作 | 路徑 | 結果 |
|---|---|---|
gh pr merge 42 --squash |
gh CLI | ✅ 攔下 —— merge 是 reviewer 的決定 |
gh api -X PUT repos/O/R/contents/f(沒有 branch 欄位) |
gh CLI | ✅ 攔下 —— 沒指定 branch 就是 commit 到預設分支 |
gh api -X PUT …/contents/f -f branch=main |
gh CLI | ✅ 攔下(受保護分支) |
gh api -X PATCH …/git/refs/heads/main -F force=true |
gh CLI | ✅ 攔下 |
gh repo delete / gh repo sync / gh release delete |
gh CLI | ✅ 攔下 |
gh secret set / gh variable set / gh alias set |
gh CLI | ✅ 攔下 |
gh api -X DELETE …/branches/main/protection |
gh CLI | ✅ 攔下(竄改分支保護) |
curl -X PUT https://api.github.com/repos/O/R/contents/f |
REST,不用 gh | ✅ 攔下 |
curl -X POST …/pulls/7/merge、wget --method=PUT … |
REST,不用 gh | ✅ 攔下 |
mcp__*__push_files(沒有 branch,或 branch: main) |
MCP 工具 | ✅ 攔下 |
mcp__*__merge_pull_request、delete_branch main |
MCP 工具 | ✅ 攔下 |
mcp__*__create_repository(當成外流目的地) |
MCP 工具 | ✅ 攔下(除非明確開啟) |
gh api -X POST …/git/refs -f ref=refs/heads/feature/x |
gh CLI | ✅ 允許(合規流程第 1 步) |
gh api -X PUT …/contents/f -f branch=feature/x |
gh CLI | ✅ 允許(第 2 步) |
gh pr create --base main --head feature/x |
gh CLI | ✅ 允許(第 3 步) |
gh pr list / gh api repos/O/R / 任何 GET |
gh CLI | ✅ 允許(讀取) |
echo "gh pr merge is blocked by policy" |
Bash | ✅ 允許(提到某個動詞不等於執行它) |
允許的那幾列和攔下的一樣重要:guard 完整保留了「開分支 → commit → 開 PR」 這條路,agent 照樣能把工作做完,而 merge 的責任仍然在人身上。
| 繞過方式 | 結果 |
|---|---|
--dangerously-skip-permissions |
✅ Wrapper 拒絕 |
--allow-dangerously-skip-permissions |
✅ 拒絕 |
--permission-mode auto / bypassPermissions |
✅ 拒絕 |
--permission-mode=bypassPermissions(等號形式) |
✅ 拒絕 |
--bare(跳過 hooks) |
✅ 拒絕 |
claude mcp add --scope user |
✅ EPERM (chattr +i) |
Force-push 藏在 && 之後(複合 shell) |
✅ git-guard 抓到 |
| Hook crash → 靜默通過 | ✅ 遙測 shim 轉成 fail-closed |
CLAUDE_AUDIT_LOG=/dev/null(消音稽核) |
✅ Managed env 覆蓋;若 log 不可寫則 fail-closed |
gh pr merge 藏在 && 之後、bash -c 裡、或 $(…) 內 |
✅ gh-guard 逐段解析 |
-f message="set branch=feature"(在訊息內文偽造 branch 欄位) |
✅ 以旗標為錨點解析,不採信 |
gh api endpoint 寫成完整 https://api.github.com/… URL |
✅ 比對前先正規化 |
改用 curl 直打 REST API 而不經過 gh |
✅ 套用同一份 endpoint 政策 |
| 把被封鎖的動詞塞進 70KB 的指令裡 | ✅ 退回保守 regex 比對 |
同一個 MCP 工具換成別的 server 名稱(mcp__MCP_DOCKER__…) |
✅ 以工具名稱後綴比對 |
完整繞過測試套件:tests/bypass-attempts.sh。
token-budget-guard.sh 強制執行每 session 的 token + 工具呼叫預算。
當 session 達到 CLAUDE_TOKEN_BUDGET(預設 1M tokens)或
CLAUDE_CALL_BUDGET(預設 500 次呼叫),下一個 PreToolUse 回傳
exit 2,使用者必須開新 session。
| 政策 | 狀態 | 備註 |
|---|---|---|
| Content Filters(Hate/Insults/Sexual/Violence/Misconduct) | ✅ 可用 | Input + Output |
PROMPT_ATTACK filter |
✅ 可用(5/5 jailbreak 被攔) | 推翻了 #63637「不能用」的說法 |
| Denied Topics | ✅ 可用 | 100% recall、16.7% FPR —— 須校準定義 |
| Word Filters | ✅ 可用 | 自訂 + AWS 內建髒話清單 |
| Sensitive Information Filters | 本機 pii-guard.sh 補(NRIC、國際電話等) | |
| Contextual Grounding | 沒帶 grounding_source 的請求會直接 error —— 一般 code-gen 不要啟用 |
|
| Streaming intervention UX | 把 blockedInputMessaging(預設 BLOCKED_INPUT_BY_GUARDRAIL)當一般文字 delta 回傳 —— Claude Code 會當模型輸出顯示。請自訂為明顯非模型風格的字串(上限 500 字元,已驗證 verbatim,見 docs/bedrock-guardrails.md#streaming-ux-gotcha-read-this) |
可重現測試:tests/aws-guardrails/。
完整證據:docs/bedrock-guardrails-test-evidence.md。
| 行為 | Linux/macOS (Bash) | Windows (PowerShell) |
|---|---|---|
<tool>(git push *) deny |
☑️ 改用 :* 語法 (Bash matcher bug) |
✅ 直接可用 |
<tool>(git remote add *) deny |
☑️ 改用 git-guard.sh hook | ✅ 直接可用 |
Read(**/.env) deny |
✅ 可用 | ☑️ 改用 sandbox.denyRead |
| OS sandbox (bubblewrap) | ✅ 支援 | ❌ 原生不支援 |
| PII guard 範圍 | ✅ UserPromptSubmit + PreToolUse | ☑️ 僅 PreToolUse(UserPromptSubmit 在 Windows --print 模式不會觸發;以 Bedrock Guardrails 補 prompt 階段 PII) |
chattr +i 鎖 MCP |
✅ ext4/xfs | ☑️ 改用 icacls (Win) 或 sudo chflags schg (macOS — 注意 chflags uchg 用戶可自解,須用 schg + 非 root 用戶。見 known-issues Issue 11) |
| NFS home 目錄 | ❌ chattr 無作用 —— 見補償控制 |
❌ 同上 |
各平台補償控制:docs/platform-compensations.md。
完整平台相容性: docs/known-issues.md。
本套件附帶 9 個套件、210+ 斷言的測試框架。文件中的每一個聲明, 都有可重現的測試背書。
bash tests/run_all.sh
# === 1. PII corpus (FNR/FPR) === FNR=0.00% FPR=0.00% p95=484ms
# === 2. Hook telemetry shim === passed=12 failed=0
# === 3. Audit HMAC chain === passed=13 failed=0
# === 4. Token budget guard === passed=9 failed=0
# === 5. Drift watcher self-test === drift detected in 47ms
# === 6. Bypass red-team harness === passed=60 failed=0 (7 類別,60/60 攔截)
# === 7. Hook latency micro-bench === 所有 hook p99 ≤ 490ms (macOS 開發機)
# === 8. gh CLI guard === passed=77 failed=0
# === 9. MCP repo guard === passed=43 failed=0
# RUN-ALL: 9 suites passed, 0 failedBedrock Guardrails 線上驗證(需要 AWS 帳號,約 $0.35 美元):
bash tests/aws-guardrails/01_create_guardrail.sh # 建立測試 guardrail
python3 tests/aws-guardrails/02_streaming.py # streaming + 非 streaming
python3 tests/aws-guardrails/03_pii_detection.py # PII corpus 對 Bedrock
python3 tests/aws-guardrails/04_cross_region.py # us.* 與 global.* profiles
python3 tests/aws-guardrails/06_denied_topics.py # FPR 量測
python3 tests/aws-guardrails/08_latency.py # 30 次延遲基準
python3 tests/aws-guardrails/09_grounding.py # Contextual Grounding
python3 tests/aws-guardrails/10_prompt_attack.py # PROMPT_ATTACK 帶/不帶 tags
aws bedrock delete-guardrail --guardrail-identifier <id> # 清理測試套件揪出的 bug(然後修掉):
pii-guard.sh5 個 regex 缺陷(Amex CC、國際電話、通用 API key、hex 假陽性、護照假陽性)- 1 個 wrapper 繞過(
--permission-mode=bypassPermissions等號形式) - 1 個 silent 稽核遺失 bug(
exit 0失敗時靜默 —— 現已 fail-closed + HMAC chain)
完整數據與 value-add 稽核紀錄見 docs/test-evidence.md
與 docs/bedrock-guardrails-test-evidence.md。
文件依受眾與用途分組。
docs/deployment-guide.md— 黃金映像逐步檢查清單docs/operations-runbook.md— Onboarding、offboarding、緊急停用、憑證輪替docs/runbooks/on-call.md— 各告警對應的回應程序(對應observability/中的 CloudWatch alarms)docs/known-issues.md— Matcher bug、平台特性、已驗證 workarounddocs/platform-compensations.md— NFS / Windows--print/ macOS / Kubernetes 補償控制docs/hook-contract.md— Hook 輸入/輸出 schema、exit code 語意、遙測 schema、稽核日誌 schemadocs/hook-hardening-lessons.md— 實證強化教訓:MCP /gh寫入路徑繞過、註冊 vs 邏輯驗證、parser 繞過類型、ARG_MAX payload 陷阱、誤報控制、prefilter 效能docs/test-results.md— 原始 Linux + Windows e2e 測試證據docs/test-evidence.md— 本機測試套件結果(PII、hooks、稽核鏈、繞過、延遲)
docs/threat-model.md— STRIDE 分析與攻擊樹docs/security-rationale.md— 威脅 → 控制 對應表docs/pii-guard.md— PII guard hook 細節與客製化docs/bedrock-guardrails.md— AWS Bedrock Guardrails 整合指南(7 層防護策略、配置、已驗證行為)docs/bedrock-guardrails-test-evidence.md— 線上驗證:streaming 行為、CloudWatch metrics、PII 分類、延遲、prompt attackdocs/incident-response.md— P1-P4 處理手冊(嚴重度、SLA、升級)docs/metrics-and-kpi.md— 領先與落後指標、儀表板版型docs/disaster-recovery.md— 跨區故障切換、RTO/RPO
docs/data-classification.md— Claude Code 可能處理的資料類別docs/third-party-risk.md— Anthropic / AWS / npm 廠商風險評估docs/sbom.md— 軟體物料清單 (EO 14028、EU CRA)docs/maintenance-schedule.md— 版本升級測試、RACI 矩陣
docs/managed-settings.jsonc— 企業 managed-settings.json (Level 1)docs/settings-linux-macos.jsonc— User settings.json (Linux/macOS)docs/settings-windows.jsonc— User settings.json (Windows)
terraform/ec2-baseline/— EC2 + IAM + SSM Document + CloudWatch 基線(idempotent 部署)terraform/managed-settings-ssm/— 經 SSM Parameter Store 的核准 MCP server 清單observability/cloudwatch-dashboard.tf— Dashboard + 4 個 alarm(hook 崩潰率、p99 延遲、漂移事件、攔截率)
claude-code-on-aws-bedrock-best-practices/
├── README.md ← English version
├── README.zh-TW.md ← 本檔
├── LICENSE ← Apache 2.0
├── docs/ ← 21 個 markdown + 3 個 JSONC 設定檔
│ ├── bedrock-guardrails.md ← Bedrock Guardrails 整合指南
│ ├── bedrock-guardrails-test-evidence.md ← Guardrails 線上 AWS 驗證
│ ├── data-classification.md
│ ├── deployment-guide.md
│ ├── disaster-recovery.md
│ ├── hook-contract.md ← hook API 規格(輸入/輸出/exit code)
│ ├── incident-response.md
│ ├── known-issues.md
│ ├── maintenance-schedule.md
│ ├── managed-settings.jsonc ← Level 1 設定 (IT 部署)
│ ├── metrics-and-kpi.md
│ ├── operations-runbook.md
│ ├── pii-guard.md
│ ├── platform-compensations.md ← NFS / Windows / macOS / k8s
│ ├── runbooks/
│ │ └── on-call.md ← 各告警對應的回應程序
│ ├── sbom.md
│ ├── security-rationale.md
│ ├── settings-linux-macos.jsonc ← Level 2 設定 (使用者)
│ ├── settings-windows.jsonc ← Level 2 設定 (使用者,Windows)
│ ├── test-evidence.md ← 本機測試套件結果 + bug 稽核紀錄
│ ├── test-results.md ← 原始 Linux + Windows e2e 證據
│ ├── third-party-risk.md
│ └── threat-model.md
├── hooks/ ← 全數測試通過 ✅
│ ├── audit-logger.sh ← HMAC 鏈、fail-closed、CloudWatch dual-write
│ ├── gh-guard.sh ← gh CLI + curl/wget REST 寫入政策
│ ├── git-guard.sh ← 企業 git 政策
│ ├── hook-wrapper.sh ← 任意 hook 的遙測 + fail-closed shim
│ ├── mcp-repo-guard.sh ← MCP repo 寫入政策(mcp__.* matcher)
│ ├── pii-guard.ps1 ← PII/機密掃描器 (Windows)
│ ├── pii-guard.sh ← PII/機密掃描器 (Linux/macOS)
│ └── token-budget-guard.sh ← agent loop 斷路器
├── scripts/
│ ├── chain-verify.sh ← 驗證稽核日誌 HMAC 鏈完整性
│ ├── drift-watcher.sh ← 即時篡改偵測 (inotify/fswatch)
│ ├── logrotate-claude-code.conf ← 稽核日誌旋轉 (處理 chattr +a)
│ ├── sudoers-claude-code ← 強化 wrapper 的 sudoers 設定
│ ├── wrapper-linux.sh ← 拒絕繞過旗標 (Linux/macOS)
│ └── wrapper-windows.cmd ← 拒絕繞過旗標 (Windows)
├── terraform/
│ ├── ec2-baseline/ ← EC2 + IAM + SSM + CloudWatch (idempotent)
│ │ ├── main.tf
│ │ ├── ssm-deploy.yaml.tpl
│ │ └── user-data.sh.tpl
│ └── managed-settings-ssm/ ← MCP 允許清單的 SSM Parameter Store
│ └── main.tf
├── observability/
│ └── cloudwatch-dashboard.tf ← Dashboard + 4 個 alarm
└── tests/
├── aws-guardrails/ ← Bedrock Guardrails 驗證(10 個腳本)
│ ├── 01_create_guardrail.sh
│ ├── 02_streaming.py
│ ├── 03_pii_detection.py
│ ├── 04_cross_region.py
│ ├── 06_denied_topics.py
│ ├── 08_latency.py
│ ├── 09_grounding.py
│ ├── 10_prompt_attack.py
│ └── lib/invoke.py
├── lib/harness.sh ← 共用測試 helpers
├── pii-corpus/ ← 108 個標記的 PII 測試案例
│ ├── negative/
│ └── positive/
├── bench_hook_latency.sh ← 200 次延遲微基準
├── bypass-attempts.sh ← 60 次紅隊測試套件
├── run_all.sh ← master runner(9 個套件)
├── run_pii_corpus.sh ← 108 個 PII 案例驗證
├── test_audit_chain.sh ← HMAC 鏈篡改偵測
├── test_hook_wrapper.sh ← 遙測 + fail-closed 語意
└── test_token_budget.sh ← per-session 斷路器
| 元件 | 版本 |
|---|---|
| Claude Code | 2.1.150, 2.1.152, 2.1.156 |
| Linux | Amazon Linux 2023 (EC2 t3.medium) |
| Windows | Windows Server 2022 (EC2 t3.medium) |
| macOS | Darwin 25.5 (arm64,開發機) |
| Node.js | 20.18.0, 20.20.2 LTS |
| PowerShell | 7.4.6 (Windows) |
| AWS CLI | v2.31.23 (macOS)、v2.33.15 (Linux EC2)、v2.34.56 (Windows EC2) |
| boto3 / botocore | 1.42.79 |
| AWS Bedrock | us-east-1 透過 VPC Endpoint (private DNS) |
| Sandbox | bubblewrap 0.10.0 + socat 1.7.4.2 (Linux) |
| 模型 | us.anthropic.claude-sonnet-4-6、us.anthropic.claude-haiku-4-5-20251001-v1:0、global.* profiles |
| Inference profiles | us.* 與 global.* 跨區域 —— 兩者皆與 guardrails 一起驗證過 |
| Terraform | ≥ 1.5.0 (HCL2 parser 驗證過) |
本套件的部分功能需要特定 Claude Code 版本:
| 功能 | 最低版本 |
|---|---|
sandbox.network.deniedDomains |
v2.1.113+ |
managed-settings.d/ 目錄支援 |
v2.1.83+ |
DISABLE_AUTOUPDATER 環境變數 |
v2.1.118+ |
ANTHROPIC_BEDROCK_SERVICE_TIER |
v2.1.122+ |
本專案為獨立的個人開源作品 —— 與 Anthropic 或 AWS 無任何隸屬、背書或支援關係。 「Claude」、「Bedrock」等名稱為各自所有者的商標,此處僅作描述性使用。
本套件的安全控制以**「現狀」(AS IS)提供,不附任何形式的擔保**。它們屬盡力而為的 控制,不保證偵測所有敏感資料、也不保證符合任何法律或標準,且不構成法律、法規 或專業資安建議。你必須自行在自己的環境中驗證。詳見 DISCLAIMER.md 與 LICENSE。使用風險自負。
採用 Apache 2.0 授權 — 可自由用於企業部署。
歡迎貢獻:
- 新的 PII patterns(例如各國身分證號) —— 在
tests/pii-corpus/positive/加一筆 corpus,然後重跑bash tests/run_pii_corpus.sh證明 FNR - 平台特定測試(macOS、NFS home dirs、btrfs)
- 額外的 hook scripts(例如自訂 MCP server 驗證)
- README 翻譯
開 PR 時請附上測試證據:
- Hook/regex 變動:
bash tests/run_all.sh輸出 - Bedrock 相關變動:
tests/aws-guardrails/輸出(account ID 須遮罩) - 部署變動:來自 EC2 或本機 VM 的 shell log