Select Page

Security Guidance 是什麼？Claude Code 安全外掛安裝與用法

by | 9 月 30, 2026 | AI, 程式開發 | 0 comments

放大鏡檢查筆電上的抽象程式區塊並標出提醒，示意 Security Guidance 協助程式碼安全審查

Security Guidance 是 Anthropic 提供的 Claude Code 安全審查外掛，會在 Claude 修改程式的過程中，自動提醒可能的漏洞，並把審查結果送回同一個工作階段處理，安裝後不必每次再打一段「請檢查安全性」，也不需要記住一個專門啟動它的 Skill 指令。

它適合用在 AI 協助開發網站、API、後台與自動化腳本的日常流程，尤其程式已經能跑，卻還沒確認使用者輸入、權限檢查或資料流向是否安全時，這類即時提醒可以讓問題更早被看見。

先釐清：Security Guidance 是 Skill、Hook，還是 Plugin？

正式分類是 Plugin，也就是外掛，Skill 通常是一份描述任務做法的指引，Hook 則是在特定事件發生時自動執行的程式，Security Guidance 把安全檢查程式包成外掛，透過 Hooks 接到 Claude Code 的工作流程。

所以，它的基本用法是「安裝並保持啟用，正常讓 Claude Code 工作」，目前提供的 外掛設定檔與目錄結構以 Hooks 為核心，沒有要求你建立 SKILL.md，也沒有名為 /security-guidance 的獨立操作指令。

版本提醒：截至 2026 年 9 月 28 日，官方市集頁仍以較早的寫入前提醒介紹產品，但本文核對的 GitHub 版本為 2.0.0，實際 Hook 設定已採用寫入後檢查及背景審查。下文依這份原始碼與現行使用文件說明，安裝後也應確認自己的外掛版本。

它如何運作？三個時機，三種檢查深度

第一層：檔案修改後，快速找出危險寫法

當 Claude 透過編輯或寫入工具修改檔案，外掛會比對特定字串、正規表示式與檔案路徑，例如動態執行字串的 eval()、把輸入交給 shell 的 child_process.exec()、直接寫入 HTML，以及不安全的反序列化。

這一層不需要呼叫模型，同一個工作階段裡，同一檔案的同一條規則通常只提醒一次，避免連續修改時反覆洗版，它抓到的是「需要留意的寫法」，未必代表那一行已經構成可利用的漏洞，後續仍要看輸入來源與上下文，規則可以在 內建模式清單中查到。

第二層：一個回合結束後，檢查這回合的差異

你提出一次需求，Claude 修改程式並回覆，構成一個工作回合，外掛會用 Git 狀態整理這回合產生的差異，交給另一個以安全為目標的模型審查，這能補上單純字串比對看不出的問題，例如某個查詢是否漏掉使用者權限限制。

目前 Hook 設定使用背景審查，回覆可能先完成，稍後才把發現送回 Claude，讓它繼續處理，因此不能把「已看到完成回覆」理解成安全檢查已全部結束，依 官方回合審查說明，這一層也有檔案數與連續觸發次數限制，並不是無限檢查整個專案。

第三層：Claude 提交或推送時，追查相關程式

當 Claude 透過 Bash 工具執行符合條件的 git commit 或 git push，外掛可啟動更深入的審查，這個 reviewer 能用 Read、Grep、Glob 查看呼叫端、驗證函式與相關檔案，判斷跨檔案的資料流是否存在問題。

這裡的觸發範圍是 Claude Code 內的工具操作，不是替電腦安裝全域 Git 防線，你從自己的終端機執行 Git，或使用工作階段裡的 ! shell escape，不應假定也會受到這一層審查。

目前這三層都不會阻擋寫入或提交，發現問題後，仍要由 Claude 或開發者修正。如果團隊要求檢查未通過就不能合併，應另外使用 CI 必要檢查與分支保護，不能把背景提醒當成硬性關卡，這也是 設計 AI 工作環境與驗證流程時需要先分清楚的責任。

Security Guidance 安裝方式

本文以本機終端機版 Claude Code 為主，先準備可正常使用的 Claude Code、Git 專案，以及 Python 3.10 以上與可用的 pip。這個 第一次使用時，外掛可能在 ~/.claude/security/ 下準備專用 Python 環境並安裝 Claude Agent SDK，需要網路與套件安裝能力。企業電腦若限制下載，應先核對初始化結果。

在 Claude Code 對話輸入列執行：

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

這是 Claude Code 裡的指令，不是直接貼到一般終端機執行的 shell 指令。

安裝畫面若詢問範圍，User 適用於這台電腦上自己的各個專案，Project 用來分享專案設定，Local 則只套用到自己在目前專案的使用。

第一次體驗，可以選 User，或用 Local 限定在測試專案。

只有在系統明確回報找不到官方 marketplace 時，才先補上：

/plugin marketplace add anthropics/claude-plugins-official

接著重試安裝。若安裝摘要提示需要啟用更新，依畫面執行 /reload-plugins，再透過 /plugin 檢查已安裝與啟用狀態。安裝範圍及重新載入方式可對照 官方外掛安裝文件。

若你使用 Claude 桌面版或 VS Code 擴充套件，外掛管理入口可能不同。

安裝後怎麼用？照常開發，再處理提醒

不必先提出安全審查要求才能觸發。你可以像平常一樣請 Claude 新增功能、修改測試或整理程式，

外掛會依事件自動工作。比較有用的工作要求，是同時讓 Claude 回報做了什麼驗證，以及安全提醒最後如何處理，例如：

請替客服後台新增留言預覽功能。
使用者輸入只需顯示純文字，不需要 HTML 格式。
完成後執行相關測試，並說明 Security Guidance 若提出提醒，你如何修正或確認。

這段提示不是外掛的專用語法，而是本文的工作要求示例。它讓功能需求與驗收方式更清楚，無須故意要求 Claude 寫出危險程式來測試外掛。

範例一：顯示留言時，避開不必要的 HTML 注入

假設功能只是顯示訪客留下的文字，卻把內容直接指定給 innerHTML，外掛的模式規則可能提出 XSS 提醒。問題不在「有 HTML 就一定錯」，而是未受信任的內容會被瀏覽器當作標記處理。

若只需要純文字，較直接的實作是：

previewElement.textContent = commentText

React 中也可以直接把文字放進 JSX 的文字位置，不必為了顯示普通留言使用 dangerouslySetInnerHTML。若功能確實需要富文字，才另外定義允許的標記與清理流程。這是在 使用 Claude Code 製作網站時，很常遇到的需求界線。

範例二：呼叫外部工具時，把參數與 shell 字串分開

假設系統要呼叫一個已知的檔案分析工具，把檔名拼進 shell 指令字串，可能讓特殊字元被當成指令語法。Security Guidance 會對 child_process.exec 這類寫法提醒檢查輸入。

可以考慮用 execFile() 直接呼叫固定程式，將檔名放進參數陣列。例如以下概念片段，前提是程式路徑固定，且已先驗證檔案確實位於允許的目錄：

import { execFile } from 'node:child_process'

execFile('/opt/myapp/bin/file-inspector', [validatedFilePath], callback)

這裡的工具路徑與變數都是示意，不能直接照貼就當成完整程式。參數陣列能避開 shell 字串解析，但目標工具本身怎麼解讀參數、檔案存取範圍與權限，仍然要檢查。外掛的提醒應該促使你看完整條資料流。

範例三：修改 GitHub Actions，先看資料如何進入腳本

編輯 .github/workflows/ 裡的 YAML 檔案時，外掛可依路徑給出提醒。這不表示整份 workflow 已被判定有漏洞，而是這類檔案可能使用儲存庫權限、執行 shell 或接觸機密，值得額外檢查。

例如只想印出 Issue 標題，可以先把事件資料放到環境變數，再於 shell 使用帶引號的變數，而不是把外部文字直接插進腳本原始碼：

env:
  ISSUE_TITLE: ${{ github.event.issue.title }}
run: printf '%s\n' "$ISSUE_TITLE"

這只是 workflow 中的一個步驟片段，用來示範安全處理文字，不代表整份流程已經安全。

還要看 job 權限、第三方 action、事件來源與 secrets 是否使用得當。若尚不熟悉分支與提交，可以先讀 AI 開發時的 GitHub 版本管理，把修改留在可檢查、可回復的範圍。

加入自己的專案規則，讓提醒更貼近實際需求

用 Markdown 說明團隊規範

在專案建立 .claude/claude-security-guidance.md，寫下模型不會自行知道的要求，以下是本文設計的多租戶後台示例，可依自己的函式名稱與資料表調整：

# 本專案安全規則

- 所有 /admin 路由必須先通過 requireAdmin，再讀取業務資料。
- 查詢租戶資料時，tenant_id 必須來自已驗證的工作階段，不可信任請求直接提供的值。
- 日誌不得包含存取權杖、密碼或完整的付款資料。
- 訪客留言預設以純文字顯示，富文字必須使用專案核准的清理函式。

規則應寫出「哪裡需要什麼條件」，比單純要求「遵守最佳安全實務」更容易被檢查，不要把 API key、真實權杖或正式客戶資料放進檔案，因為內容可能被加入模型審查的提示。

也可以把個人通用規則放在 ~/.claude/claude-security-guidance.md，或用 .claude/claude-security-guidance.local.md 保存不打算共用的專案設定，官方目前對不同審查路徑載入規則的說明仍有版本差異，因此至少要確認回合差異審查有載入，不能只因為檔案存在就推定所有路徑都生效。

用 JSON 加入可重現的文字提醒

如果某個舊函式不應再出現在新程式裡，可以建立 .claude/security-patterns.json。以下示例看到 legacyUnsafeRenderer( 就提醒改用專案的新介面：

{
  "patterns": [
    {
      "rule_name": "legacy_renderer",
      "substrings": [
        "legacyUnsafeRenderer("
      ],
      "paths": [
        "**/src/**"
      ],
      "reminder": "這個舊介面不應用於新程式，請改用專案的安全文字顯示函式，並確認輸入來源。"
    }
  ]
}

這裡的函式名稱是示例，不是內建 API。paths 用來限制檔案範圍，比對的是完整路徑，因此專案相對位置前面使用 **/。JSON 不需要額外的 YAML 解析套件，比第一次就加入正規表示式更容易確認設定是否正確。

這類自訂規則是補充提醒，並不會刪除內建規則，也不是程式碼執行權限設定。其格式與載入行為可對照 自訂規則實作。

怎麼確認真的有啟用？用無害的測試標記

最容易誤會的是「沒有出現警告，所以一切正常」。沒有警告，也可能是沒有符合模式、這個工作階段已提醒過、背景審查還沒結束，或環境缺少必要元件。

想確認自訂模式有載入，可以在可丟棄的測試分支中，讓 Claude 用編輯工具新增 src/security-guidance-demo.js，內容只放下面這行註解，然後觀察是否收到 legacy_renderer 的提醒：

// 示範字串 legacyUnsafeRenderer(，僅供規則比對，不執行任何函式

字串規則可能連註解也會匹配，正好可以用來測試，不必真的執行危險程式。

需要排查時，先看 ~/.claude/security/log.txt 的活動與錯誤，再確認專案有 Git、Python 與 SDK 初始化成功，以及所選模型與服務供應商可用。若沒有 Git 儲存庫，仍可能有逐次編輯提醒，但以 Git 差異為基礎的審查無法照常工作。

費用與資料流向：不要把它當成完全離線檢查

模式比對本身不呼叫模型，回合差異與提交審查則會額外使用模型額度，深入審查可能讀取更多檔案、進行多輪判斷，因此不能把外掛安裝後的使用成本視為零。

核對版本的預設審查模型為 Claude Opus 4.7。SECURITY_REVIEW_MODEL 用於差異審查，SG_AGENTIC_MODEL 用於 agentic 審查。若改用 Bedrock、Vertex 或其他端點，模型識別名稱應依供應商設定，不宜直接複製別人的環境變數。

執行模型審查時，變更路徑、差異與相關程式內容會傳到設定的模型端點，深入審查還可能讀取其他相關檔案

。使用公司程式碼時，應沿用組織允許的端點與資料政策。這是此工具的運作條件，不能把「Hook 在本機執行」解讀成程式碼永遠不會離開本機。

它和 /security-review、Claude Security 有什麼不同？

  • Security Guidance：跟著 Claude Code 的開發過程自動提醒與審查，適合日常修改。
  • /security-review：由使用者主動提出的一次性安全檢查，與自動 Hook 的觸發方式不同。
  • Claude Security 外掛：提供更深入的程式庫或差異掃描與修補工作流，是另一個工具，不能只因名稱都有 Security 就視為同一套功能。

如果需求是檢查既有的整個網站，或確認某個版本能否上線，還要搭配人工審查、依賴套件掃描、測試與 CI。Security Guidance 能把部分問題提前到開發當下，但「沒提醒」不是安全認證。

Security Guidance 常見問題

只要把 SKILL.md 放進專案就能用嗎？

不能等同。Security Guidance 是包含 Hook 設定與程式的外掛，應透過官方外掛流程安裝，單獨放一份 Skill 指引不會啟動它的檢查。

它會阻止有漏洞的程式被提交嗎？

目前三層都是提醒或背景審查，不會阻擋寫入與提交。需要強制把關時，應另外設定 CI 必要檢查與分支保護。

所有安全提醒都必須照單全收嗎？

先核對輸入是否可被外部控制、既有驗證是否有效，以及實際影響。若確定是誤報，應保留具體理由，不能只用一句「這是安全的」取代證據。

從小型專案開始，把提醒接到修正與驗證

第一次使用，先選一個可回復修改的 Git 專案，確認外掛啟用，再讓 Claude 完成小功能。看到提醒後檢查原因、修正程式並跑相關測試，最後再決定是否提交。習慣這個流程後，再加入團隊規則，效果會比一開始塞進大量抽象要求更容易評估。

Security Guidance 的實際價值，在於把安全問題放回寫程式的當下，讓你更早知道哪裡需要檢查。它能協助縮短發現問題到修正的距離，最後的驗收仍要回到程式行為與測試結果。

Submit a Comment