GitHub Code Scanning 的 Mitigated 怎麼用？把已緩解與 Won’t fix 分開

Mitigated 不是「漏洞已修好」#

可以用下面的判斷表選擇關閉方式：

Mitigated 的核心不是「我們覺得應該沒事」，而是能指出哪一個外部控制在什麼範圍內阻擋或限制了利用路徑。若只是計畫未來加 WAF、只在某個環境手動擋過一次，或控制沒有 owner 與監控，就不應把它當成已緩解。

關閉前先留下可重查的證據#

至少記錄以下資料，讓半年後接手的人仍能重新驗證：

• 控制名稱與規則 ID，例如 WAF rule、API gateway policy 或網路 ACL。
• 控制套用的環境、網域、route、服務和流量範圍。
• 它如何阻擋這個 alert 對應的輸入或利用路徑，以及哪些路徑沒有被涵蓋。
• 啟用時間、最近一次測試或 log 觀察結果，以及控制的 owner。
• review date 或 expiry date；外部控制變更、移除或失效時要重新開啟評估。

描述不必把整段 incident 貼進 comment，但要能從 comment 連到變更單、規則文件或監控查詢。也不要把 WAF 當成修正程式碼的替代品：只要 route、來源、內部呼叫或新部署繞過控制，原本的 CodeQL alert 仍然是有價值的警告。

在 GitHub UI 關閉 Mitigated alert#

先打開 repository 的 Security → Code scanning，進入 alert 詳細頁，閱讀受影響的檔案、資料流和觸發條件。確認問題確實仍存在，再選擇關閉 alert 的動作，將 reason 設為 Mitigated，並在 comment 寫入外部控制與 review 資訊。

操作順序建議是：

1. 先確認不是可以直接修正的程式碼問題，也不是 CodeQL 誤判。
2. 對照 production 與 staging 的 route 和政策，確認外部控制真的在目標範圍生效。
3. 寫入規則 ID、涵蓋範圍、owner、驗證日期和下一次 review date。
4. 關閉後到 Closed alerts 檢查 reason 與 comment，避免只看 open count 減少。
5. 把控制失效或部署路徑變更加入重新開啟 alert 的維運條件。

GitHub 文件指出，dismiss alert 會把它移到 Closed 清單，而且關閉動作適用所有 branches；因此 comment 不應只寫「production 已擋」，而要說清楚掃描結果與外部控制的邊界。若控制只覆蓋 production，測試環境的差異也應明確記錄。

用 REST API 一致化批次處理#

需要把既有審查結果接到治理流程時，可以用 GitHub CLI 呼叫 Code Scanning alert API：

1
gh api --method PATCH \
2
  -H "Accept: application/vnd.github+json" \
3
  -H "X-GitHub-Api-Version: 2022-11-28" \
4
  "/repos/OWNER/REPO/code-scanning/alerts/ALERT_NUMBER" \
5
  -f state=dismissed \
6
  -f dismissed_reason=mitigated \
7
  -f dismissed_comment='WAF rule WAF-123 blocks the affected route; owner=platform-security; review=2026-10-31'

OWNER、REPO、ALERT_NUMBER 和 comment 都是示例值。API 可以把 reason 與 comment 寫入 GitHub，但不會替你驗證 WAF rule 是否真的存在或仍然啟用；批次腳本應先從內部控制目錄或變更系統取得證據，再更新 alert。若外部控制已移除或 scope 改變，也應把 alert 重新開啟並回到修正流程。

如果你正在調整 CodeQL 的掃描範圍，可以先看 GitHub Code Scanning default setup 共用設定檔；那是設定掃描規則與排除路徑的問題，不能用來取代對單一 alert 的風險判斷。

什麼時候不該選 Mitigated？#

有三種常見誤用：第一，漏洞其實已經修好，卻沒有更新程式碼或測試紀錄；第二，只有人工操作或口頭規範，沒有強制執行的 policy；第三，控制只在某一條入口生效，卻把整個 alert 當成已緩解。這些情況應分別回到 Fix、其他合適的 dismissal reason，或先補上控制與驗證。

把 Mitigated 當成帶期限的風險狀態會比較安全：控制有 owner、證據、review date，且控制一旦失效就重新評估。這樣關閉 alert 是降低重複噪音，而不是把未修正的程式碼藏起來。

常見問題#