在 Claude 編寫程式碼時捕捉安全問題

security-guidance 外掛程式讓 Claude 在工作時檢查自己的程式碼變更是否存在常見漏洞，並在同一個工作階段中修復發現的問題。該外掛程式可以捕捉注入、不安全的反序列化和不安全的 DOM API 等問題，防止程式碼進入拉取請求，減少人工審查人員的安全審查負擔。安裝後，外掛程式會自動執行。無需調用任何內容，也無需記住任何單獨的命令。該外掛程式是 Code Review 的工作階段內伴侶，Code Review 在拉取請求上執行。此外掛程式減少了進入 PR 的內容。Code Review 捕捉遺漏的內容。有關外掛程式如何與按需審查和 CI 掃描分層的信息，請參閱此功能如何與其他安全工具配合。

先決條件

Claude Code CLI 版本 2.1.144 或更高版本
Python 3.8 或更高版本在您的 PATH 上。該外掛程式會依次嘗試 python3、python 和 py -3

安裝外掛程式

在 Claude Code 工作階段中，從官方 Anthropic 市場安裝：

/plugin install security-guidance@claude-plugins-official

然後在當前工作階段中啟用它：

/reload-plugins

安裝會寫入您的使用者設定，因此外掛程式會在您在此機器上啟動的每個新本地工作階段中載入。已經執行的工作階段需要 /reload-plugins 才能載入它。

在雲端工作階段和共享儲存庫中啟用

使用者範圍的外掛程式不會進入網路上的 Claude Code，因為這些工作階段在 Anthropic 基礎設施上執行，而不是在您的機器上。要在那裡啟用外掛程式，或為克隆儲存庫的所有人開啟它，請在專案的簽入設定中聲明它：

.claude/settings.json

{
  "enabledPlugins": {
    "security-guidance@claude-plugins-official": true
  }
}

管理員可以通過在受管設定中設定 enabledPlugins 來組織範圍內啟用外掛程式。

外掛程式檢查的內容

外掛程式在三個點檢查 Claude 的工作，每個點的深度不同：

在每個檔案編輯上：快速模式匹配危險呼叫，無需模型呼叫
在每個回合結束時：對該回合更改的所有內容進行背景模型審查
在 Claude 進行的每次提交或推送上：讀取周圍程式碼的更深層代理審查

您可以通過添加自己的規則擴展每一層。內置檢查無法單獨移除，但您可以獨立禁用每一層。

在每個檔案編輯上

當 Claude 寫入檔案時，外掛程式會掃描新內容中的已知危險模式。這是一個沒有模型呼叫的模式匹配，因此不會增加使用成本。示例模式類別：

動態程式碼執行：eval(、new Function、os.system、child_process.exec
不安全的反序列化：pickle
DOM 注入：dangerouslySetInnerHTML、.innerHTML =、document.write
工作流檔案：.github/workflows/ 下的編輯，可以授予儲存庫級別的權限

檢查在編輯完成後執行，並將警告附加到 Claude 的下一步上下文中。每個警告在每個工作階段中每個檔案每個模式觸發一次，因此同一檔案中的重複匹配不會淹沒對話。您可以使用 security-patterns.yaml 檔案添加自己的模式到此層。

在每個回合結束時

一個回合是 Claude 響應的一輪：您發送一條消息，Claude 工作並回覆，回合結束。在每個回合之後，外掛程式計算工作樹中在回合期間更改的所有內容的 git diff，包括來自 Claude 的編輯工具、Bash 命令和子代理的更改，並將其發送到專注於安全的單獨 Claude 審查。審查在背景中執行，因此 Claude 的回覆不會延遲。如果審查發現問題，Claude 會被重新提示發現的內容，並作為後續行動解決它們。這捕捉了字符串匹配無法捕捉的問題，例如：

授權繞過
不安全的直接物件參考
注入
伺服器端請求偽造
弱密碼學

您可以直接在您的工作階段中看到發現和 Claude 的解決方案。審查涵蓋每個回合最多 30 個更改的檔案，並在最多連續三次後才讓位給您。

在 Claude 進行的每次提交或推送上

當 Claude 通過其 Bash 工具執行 git commit 或 git push 時，外掛程式在背景中執行對變更的更深層代理審查。此審查讀取周圍程式碼，包括呼叫者、清理程式和相關檔案，以決定發現是否真實，然後再報告它。額外的上下文使假陽性在看起來危險但在您的程式碼庫中安全的模式上保持低位。此層僅在 Claude 通過其 Bash 工具進行的提交和推送上觸發。您從自己的 shell 執行的提交，包括工作階段內的 ! shell 逃逸，不會被審查。提交和推送審查限制為每滾動小時 20 次。

審查獨立性和限制

外掛程式不會要求編寫程式碼的同一 Claude 實例對自己進行評分。每個編輯檢查是一個確定性的字符串匹配，不涉及模型。端回合和提交審查作為單獨的 Claude 呼叫執行，具有新鮮的上下文和安全聚焦的提示：審查者從 diff 開始，對原始方法沒有投資，並且僅被指示查找問題。沒有任何層阻止寫入或提交。發現作為指令到達編寫 Claude，Claude 在對話中解決它們，審查模型可能會遺漏問題。將外掛程式視為深度防禦的一層，而不是完整的安全解決方案。請參閱此功能如何與其他安全工具配合。

添加自己的規則

外掛程式有兩個擴展點：用於模型支持的審查的 Markdown 指導檔案，以及用於每個編輯字符串匹配的 YAML 或 JSON 模式檔案。兩者都是附加的。您可以添加檢查，但無法從這些檔案中禁用內置檢查。

為模型支持的審查添加指導

在您的專案中建立 .claude/claude-security-guidance.md，並用純文字描述您的威脅模型和審查清單。模型支持的審查將其作為附加上下文與內置漏洞清單一起載入。以下示例適用於具有角色門控管理員路由和客戶資料日誌記錄政策的網路服務：

.claude/claude-security-guidance.md

# 此儲存庫的安全指導

- 不要在 INFO 級別或更高級別記錄 `customer_id` 或 `account_number`。
- `/admin` 下的所有路由必須在任何資料庫讀取之前呼叫 `require_role("admin")`。
- 使用 `crypto.timingSafeEqual` 進行令牌比較，而不是 `===`。

這些規則是審查者的指導，而不是確定性的護欄。外掛程式將違規作為發現呈現給 Claude 修復，但它不會阻止寫入或保證捕捉每個違規。指導是附加的：說要忽略漏洞類別的規則不會抑制這些發現。對於硬執行，將外掛程式與阻止編輯受保護檔案的鉤子或 CI 檢查配對。

添加自訂的每個編輯模式

建立 .claude/security-patterns.yaml 以將 regex 或子字符串規則添加到每個編輯模式檢查。這些作為確定性字符串匹配與內置模式一起執行：

.claude/security-patterns.yaml

patterns:
  - rule_name: internal_api_key
    substrings: ["sk_live_", "AKIA"]
    reminder: "硬編碼的 API 金鑰前綴。從秘密管理器載入認證。"
  - rule_name: tenant_unfiltered_query
    regex: "\\.objects\\.all\\(\\)"
    paths: ["src/tenants/**"]
    reminder: "多租戶程式碼必須按 org_id 篩選。"

欄位	類型	描述
`rule_name`	string	警告中顯示的識別碼
`reminder`	string	附加到 Claude 上下文的警告文本，上限為 1 KB
`regex`	string	針對編輯內容匹配的 Python regex
`substrings`	list	文字子字符串；提供此或 `regex`
`paths`	list	可選的 glob 模式；規則僅適用於匹配的檔案
`exclude_paths`	list	可選的 glob 模式以跳過

外掛程式還讀取 .claude/security-patterns.yml 和 .claude/security-patterns.json，具有相同的架構。JSON 適用於任何 Python 安裝。YAML 形式需要 PyYAML 可導入，外掛程式不會為您安裝。外掛程式載入最多 50 個自訂規則，並跳過看起來容易發生災難性回溯的 regex。

規則檔案查找位置

外掛程式在相同位置查找 claude-security-guidance.md 和 security-patterns.yaml，與外掛程式的啟用方式無關：

範圍	路徑	備註
使用者	`~/.claude/claude-security-guidance.md`	適用於您機器上的每個專案
專案	`.claude/claude-security-guidance.md`	與儲存庫一起簽入
專案本地	`.claude/claude-security-guidance.local.md`	Gitignored，用於個人覆蓋

外掛程式載入所有存在的位置並連接它們，指導檔案的組合上限為 8 KB。管理員可以通過設備管理將使用者範圍檔案推送到 ~/.claude/ 來分發組織範圍的規則。相同的路徑適用於 security-patterns.yaml。

使用成本

每個編輯模式檢查不進行模型呼叫，不增加成本。端回合和提交審查各自花費額外的模型使用，計入您的使用，就像任何其他 Claude 請求一樣。提交審查是代理性的，每次提交可能需要多個模型回合。增加量隨著 Claude 在工作階段中編輯檔案和提交的頻率而變化。兩個模型支持的審查預設使用 Claude Opus 4.7。設定 SECURITY_REVIEW_MODEL 為端回合審查選擇不同的模型，設定 SG_AGENTIC_MODEL 為提交審查選擇不同的模型。外掛程式在所有計畫上可用。

禁用或卸載

要關閉各個層同時保持其餘層，請設定匹配的環境變數：

變數	效果
`ENABLE_PATTERN_RULES=0`	禁用每個編輯模式檢查
`ENABLE_STOP_REVIEW=0`	禁用端回合 diff 審查
`ENABLE_COMMIT_REVIEW=0`	禁用提交和推送審查
`ENABLE_CODE_SECURITY_REVIEW=0`	一次禁用所有模型支持的審查
`SECURITY_GUIDANCE_DISABLE=1`	禁用外掛程式而不卸載

要在您的使用者範圍中暫停外掛程式：

/plugin disable security-guidance@claude-plugins-official

要從您的使用者範圍中移除它：

/plugin uninstall security-guidance@claude-plugins-official

如果外掛程式通過專案的 .claude/settings.json 啟用，從 /plugin 禁用它會將覆蓋寫入您的 .claude/settings.local.json，而不是編輯簽入的檔案，因此外掛程式對您保持關閉，而不影響隊友。如果它通過受管設定啟用，只有管理員可以禁用它。

外掛程式如何與 Claude Code 整合

外掛程式完全建立在 hooks 上，這是在 Claude 迴圈中的特定點執行您自己的程式碼的機制。它註冊：

Hook 事件	目的
`SessionStart`	啟動外掛程式的 Python 環境
`UserPromptSubmit`	捕捉端回合審查 diff 的工作樹基線
`PostToolUse` 在 `Edit`、`Write` 和 `NotebookEdit` 上	每個編輯模式匹配
`Stop`	端回合 diff 審查，在背景中執行
`PostToolUse` 在 `Bash` 上，篩選為 `git commit` 和 `git push`	提交和推送審查，在背景中執行

如果您構建自己的 hooks，外掛程式的源代碼是從 hook 執行單獨模型呼叫並將結果反饋到工作階段的工作示例。

此功能如何與其他安全工具配合

外掛程式是深度防禦方法中的一層。它最早捕捉問題，當程式碼仍在編輯器中時，但它不是保證，也不能替代後來的檢查。典型的堆棧：

階段	工具	涵蓋的內容
在工作階段中	Security guidance 外掛程式	Claude 編寫的程式碼中的常見漏洞，在同一工作階段中修復
按需	`/security-review`	對當前分支的一次性安全檢查，在您要求時執行
在拉取請求上	Code Review，Team 和 Enterprise 計畫	具有完整程式碼庫上下文的多代理正確性和安全審查
在 CI 中	您現有的靜態分析和依賴掃描器	語言特定的規則、供應鏈檢查和外掛程式不嘗試的政策執行

每個後期階段捕捉早期階段遺漏的內容。外掛程式的價值是減少到達它們的數量，而不是消除對它們的需求。

Documentation Index

​先決條件

​安裝外掛程式

​在雲端工作階段和共享儲存庫中啟用

​外掛程式檢查的內容

​在每個檔案編輯上

​在每個回合結束時

​在 Claude 進行的每次提交或推送上

​審查獨立性和限制

​添加自己的規則

​為模型支持的審查添加指導

​添加自訂的每個編輯模式

​規則檔案查找位置

​使用成本

​禁用或卸載

​外掛程式如何與 Claude Code 整合

​此功能如何與其他安全工具配合

​相關資源