D4：設定與使用 Code Security

D4-O1 理解程式碼掃描的做法與工具

Code scanning 是什麼

Code scanning 分析 repository 中的程式碼，找出安全弱點與程式錯誤，結果以警示顯示在 repository 中；修復觸發警示的程式碼後，GitHub 會關閉該警示。可以排程在特定日期與時間掃描，也可以在 push 等事件發生時觸發。它使用 GitHub Actions，每次 workflow 執行都會消耗 Actions 分鐘數。

可用條件：公開 repository；或是啟用 GitHub Code Security 的組織私有 repository（GitHub Team、Enterprise Cloud 或 Enterprise Server）。要在私有 repository 使用 code scanning，需要 Code Security 授權。購買前可執行免費的 code security risk assessment 評估暴露程度。

可以設定使用 GitHub 維護的 CodeQL，或使用第三方掃描工具。

CodeQL

CodeQL 是 GitHub 開發的程式碼分析引擎，把程式碼當作資料處理。流程是：先為程式碼建立 CodeQL database，再對資料庫執行 CodeQL queries，結果在 GitHub 上顯示為 code scanning 警示。

支援語言： C/C++、C#、Go、Java/Kotlin、JavaScript/TypeScript、Python、Ruby、Rust、Swift，以及 GitHub Actions workflows。分析 Java 或 Kotlin 用 java-kotlin，分析 JavaScript 或 TypeScript 用 javascript-typescript。不支援清單以外的語言（例如 PHP、Scala），嘗試使用可能不會產生警示，分析也不完整。

使用 CodeQL 有三種主要方式：

編譯式語言的建置模式

編譯式語言（C/C++、C#、Go、Java、Kotlin、Rust、Swift）建立資料庫常需要建置。CodeQL action 支援三種 build mode：

• none：不建置，直接從程式碼建立資料庫；支援所有直譯式語言，另外支援 C/C++、C#、Java 與 Rust。
• autobuild：偵測最可能的建置方式並嘗試建置；支援 C/C++、C#、Go、Java、Kotlin 與 Swift。
• manual：由你在 workflow 中定義建置步驟；支援 C/C++、C#、Go、Java、Kotlin 與 Swift。

啟用 code scanning 時，default 與 advanced setup 都用最簡單可行的方法：C/C++、C#、Java 與 Rust 用 none，其他編譯式語言用 autobuild。Dependency caching 可把相依性存成 GitHub Actions 快取，支援 Java、Go 與 C#，適用所有 build mode。

Query suite

Query suite 讓你不必逐一指定查詢檔，就能一次傳入多個查詢。內建三個：

自訂 query suite 需要 advanced setup；定義存在副檔名為 .qls 的 YAML 檔，指令依出現順序執行。組織擁有者與 security manager 可以為整個組織推薦 default setup 使用的 query suite。

實測註記（單次觀察，2026-11-02）： 在練習用公開 repository 啟用 default setup（default query suite）後，首次掃描在 eval(req.query.expr) 上標出一則 js/code-injection（error，security severity 為 critical）；同一檔案中把使用者輸入直接寫進 res.send 的 XSS 沒有警示。這說明 default suite 不會標出所有弱點；改用 security-and-quality 是否會多出警示，我尚未實測。詳見實測紀錄。

自訂查詢

自訂查詢用來偵測專屬於你應用程式架構或框架的弱點，或強制組織自訂的程式碼規範。查詢存成 .ql 檔，內含中繼資料；必要屬性包含查詢識別碼 @id（小寫字母或數字，以 / 或 - 分隔）與查詢類型 @kind（problem、path-problem、diagnostic、metric）。要額外執行查詢，必須使用 advanced setup 或外部 CI，而且查詢要屬於已發布的 CodeQL query pack 或 repository 中的 CodeQL pack。

第三方工具與 SARIF

第三方工具只要輸出 SARIF（Static Analysis Results Interchange Format，開放、以 JSON 為基礎的標準）就能整合。Code scanning 支援 SARIF 2.1.0 結構描述的子集。用 default setup 或以 GitHub Actions 執行 CodeQL action 時，不必自行處理 SARIF；結果會自動上傳並解析。

判斷練習

情境： 團隊的專案主要用 PHP 撰寫，打算啟用 CodeQL default setup 取得完整覆蓋。

解析： CodeQL 不支援 PHP；嘗試使用可能不產生警示或分析不完整。若要掃描 PHP，需要改用能輸出 SARIF 的第三方工具，並透過 Actions 或 API 上傳。

來源：About code scanning（GH500-DOC-25）、Code scanning with CodeQL（GH500-DOC-27）、CodeQL query suites（GH500-DOC-28）、Custom CodeQL queries（GH500-DOC-29）、SARIF files for code scanning（GH500-DOC-30）、CodeQL code scanning for compiled languages（GH500-DOC-40）；2026-11-02 已對照抓下的頁面段落（未讀完的頁面後半不在內）；其餘為整理，備考前請讀來源原文。

D4-O2 設定 Code Security

Default setup

Default setup 是最快、最省維護的方式。它依 repository 中的程式碼自動建立設定，不需要建立或維護 workflow 檔，CodeQL 支援語言的程式碼會在下列時機掃描：

• 啟用時。
• 每次 push 到預設分支或任何受保護分支。
• 建立或提交到以預設分支或受保護分支為目標的 pull request 時，不含來自 fork 的 pull request。
• 每週排程，前提是過去 180 天內有 push 或 pull request 觸發過掃描。
• 由組織擁有者啟用時，對不活躍的 repository 每 30 天掃描一次。

每週排程只在有 push 或 pull request 觸發掃描之後才開始；首次掃描以及因設定或語言變更觸發的掃描，不會啟動或延長每週排程；啟用 default setup 之前的 push 與 pull request 也不算。若 repository 沒有 CodeQL 支援的語言，default setup 不會執行掃描或消耗 Actions 分鐘數；之後語言加入預設分支時，會自動開始。

可自訂項目： 要分析的語言、query suite、threat model（公開預覽，目前只支援 Java/Kotlin 與 C#；決定哪些污染資料來源被視為風險）、以 CodeQL model pack 擴充涵蓋範圍，以及用 github-codeql-config-file repository property 套用自訂設定檔。Runner： 可使用 GitHub 代管或自管 runner；自管 runner 加上預設標籤 code-scanning，或使用自訂標籤讓不同 repository 使用不同 runner。

Advanced setup

當 default setup 的自訂選項（含自訂設定檔）不夠用，改用 advanced setup。適合需要自訂 GitHub Actions workflow 的情況，例如建置編譯式語言、使用 matrix build，或變更分析排程。可透過 GitHub Actions，或透過外部 CI/CD 系統分析後上傳結果。

• 前提：repository 使用 CodeQL 支援的語言，或打算用第三方工具；已啟用 GitHub Actions；公開，或已啟用 Code Security。
• 設定位置：Settings → Security and quality → Advanced Security → CodeQL analysis → Set up → Advanced。建議的 workflow 預設在 push 到預設分支或受保護分支，或對預設分支開 pull request 時分析。
• 從 default 改成 advanced：選 Switch to advanced，並在彈出視窗按 Disable CodeQL。
• 有權設定的人：repository 擁有者、組織擁有者、security manager，以及具 admin 角色的使用者。

Repository properties

可用 repository properties 調整 code scanning，並可套用到整個組織或單一 repository，且套用到所有 setup 類型。這些屬性必須由組織自行手動建立。支援的屬性：

設定檔可放在公開、內部或私有 repository；要用 default setup 讀取其他 internal 或 private repository 的設定檔，需設定 Git Source private registry。若 advanced workflow 明確指定 config-file 輸入，它優先於 repository property。與 default setup 合併時，在介面上選擇的 threat model 與 model pack 會保留。先測再推： 第一次設定屬性時，先在組織建立但不設值，改在一個測試 repository 設值並驗證後，再推廣。

Code scanning 授權與位置

私有與內部 repository 需要啟用 Code Security 才能使用 code scanning；若看到「GitHub Code Security or GitHub Advanced Security must be enabled for this repository to use code scanning」錯誤，檢查 Code Security 是否已啟用。

判斷練習

情境： 團隊需要為 Java 專案指定自己的建置步驟，並把掃描排程改成每天一次。

解析： 變更排程與自訂建置步驟超出 default setup 的自訂範圍，應改用 advanced setup 並編輯 workflow 檔。

來源：About setup types for code scanning（GH500-DOC-26）、Configuring advanced setup for code scanning（GH500-DOC-37）、Repository properties for code scanning（GH500-DOC-36）、Uploading a SARIF file to GitHub（GH500-DOC-38）；2026-11-02 已對照抓下的頁面段落（未讀完的頁面後半不在內）；其餘為整理，備考前請讀來源原文。

D4-O3 分析、分流並修復程式碼掃描結果

警示頁面

預設情況下，警示頁面只顯示預設分支的警示；需要 write 權限才能檢視 Security and quality 頁籤中的摘要。警示頁面的狀態與細節只反映警示在預設分支上的狀態，其他分支的狀態看右側的 Affected branches；若警示不在預設分支，狀態顯示灰色的「in pull request」或「in branch」。每則警示顯示觸發的程式碼行、工具名稱、嚴重度與安全嚴重度、問題性質與首次引入時間；CodeQL 警示還含修復建議。

• Severity： 所有警示都有 Error、Warning 或 Note。
• Security severity： CodeQL 找到的安全警示另有 Critical、High、Medium 或 Low；若有，會優先使用它。它遵循 CVSS。計算方式：找出與查詢相關 CWE 的所有 CVE，取 CVSS 分數的第 75 百分位。
• Data-flow 警示： 點 Show paths 可看資料從來源（source）到使用處（sink）的每一步；同一弱點的多條路徑會歸在同一則警示下。
• 非應用程式碼的標籤： Generated、Test、Library、Documentation；依檔案路徑分類，不能手動分類。
• 多重設定： 每個設定產生自己的一組警示；同一查詢的結果可能來自多個設定，狀態也可能不一致。要更新狀態，重新執行過期的設定；也可刪除分支上的過期設定以移除過期警示。

Pull request 中的分流

Code scanning 結果以名為 Code scanning results 的檢查和註解出現在 pull request（所有設定都是這個名稱）；每個工具的結果分開顯示。有讀取權限的人就能看到註解。只有當警示標出的所有程式碼行都在 pull request 的 diff 中，才會在 pull request 顯示警示。若發現 error、critical 或 high 嚴重度的問題，檢查失敗；較低嚴重度視為警告或附註，檢查成功。可在 repository 設定中覆寫哪些嚴重度與安全嚴重度會讓檢查失敗。依分支保護規則，此檢查可以設為必要檢查。

Merge protection（ruleset）

在 ruleset 加入 code scanning 規則，下列任一條件成立時阻擋合併：必要工具發現 ruleset 所定義嚴重度的警示；必要工具的分析仍在進行；必要工具未在 repository 設定。通常用在長期存在的功能分支。可在 repository 層級設定，或在組織層級（僅限 GitHub Enterprise 方案）。例外： 不適用於 merge queue groups，也不適用於 default setup 分析的 Dependabot pull request。設定這條規則不會自動啟用 code scanning。它與 status checks 無關。

修復

• Agentic autofix： 把一則或多則警示指派給 Copilot，由 agent 探索程式碼庫、產生並驗證修復，再開啟 draft pull request。一次可從 backlog 或 security campaign 選最多 25 則警示；一次指派產生一個 agent session 與一個 pull request。只適用預設分支的 backlog 警示。不需要 Copilot 授權，但會消耗 Code Security AI Credits 與 GitHub Actions 分鐘數。也可用 REST API 把指派者設為 copilot-swe-agent[bot]。
• Copilot Autofix： 為單一警示產生一個建議修復，由你審查後自行建立 pull request（Generate fix → Create PR with fix）。使用 CodeQL 時預設啟用，不需另外步驟；default 與 advanced setup 運作相同；不消耗 AI credits；公開 repository 都可用，組織與企業的私有或內部 repository 需 Code Security 授權；也適用於 Enterprise Managed Users 擁有的 repository。管理員可在企業、組織、repository 層級停用，設定向下層層生效：上層停用後，下層無法重新啟用。
• Agentic autofix 的啟用： 組織擁有的 repository 由組織擁有者或 security manager 啟用；若組織屬於企業，企業擁有者或 security manager 也必須允許。組織啟用會預設開啟符合資格的 repository，但 repository 管理員可選擇退出。不適用於 Enterprise Managed Users 擁有的 repository。
• 兩者都是盡力而為（best-effort），不保證成功；agentic autofix 以 CodeQL 重跑驗證，無法確認自訂 CodeQL 查詢、security-extended query suite 或第三方工具警示的修復。合併前一律要審查與測試。
• 手動修復： 有 write 權限的人可提交修正。若已設定在 pull request 掃描，最好開 pull request，才能觸發分析驗證修正沒有引入新問題。

關閉（dismiss）警示

關閉警示用於你認為不需要修復的情況，例如只用於測試的程式碼，或修復成本高於效益。關閉時：在所有分支關閉；從目前警示數移除；移到 Closed 清單（可重新開啟）；記錄原因，可另加註解；下次掃描相同程式碼不會再產生警示。關閉原因要選對，因為可能影響查詢是否繼續納入未來的分析。可以依篩選條件批次關閉。若把 CodeQL 警示關閉為誤報（false positive），官方建議考慮回饋到 CodeQL repository 改善分析。

判斷練習

情境： 開發者在功能分支修好一個警示，但預設分支還沒合併，他發現警示頁面仍顯示「開啟」。

解析： 警示頁面的狀態只反映預設分支；其他分支的狀態看 Affected branches。要等修復合併進預設分支，警示才會在預設分支關閉。

來源：Code scanning alerts（GH500-DOC-31）、Triaging code scanning alerts in pull requests（GH500-DOC-32）、Code scanning merge protection（GH500-DOC-33）、About autofix for code scanning（GH500-DOC-34）、Resolving code scanning alerts（GH500-DOC-39）；2026-11-02 已對照抓下的頁面段落（未讀完的頁面後半不在內）；其餘為整理，備考前請讀來源原文。

D4-O4 最佳化並自動化 Code Security 營運

Tool status page

顯示 repository 層級、僅預設分支的所有 code scanning 工具狀態（不在組織層級），是 code scanning 不如預期時除錯的起點。三種狀態：All configurations are working、Some configurations need attention、Some configurations are not working。所有工具都可看到設定狀態、掃描排程、首次與最近掃描時間、使用的規則；整合工具（如 CodeQL）另有各語言的檔案涵蓋率、各 setup 類型的設定細節、具體錯誤訊息，以及可下載的 CSV 報告與規則清單。涵蓋率：高 → 運作正常；低 → 檢查診斷輸出；零 → 可能有未分析的語言，更新設定納入。若同時設定 advanced 與 default setup，頁面只顯示 default setup。

以 security overview 衡量成效

「Code scanning on pull requests」報告顯示 code scanning 在組織 pull request 中預防了多少弱點，分為 CodeQL 與 AI Scan 兩個分頁。CodeQL 的指標只追蹤已合併到預設分支的 pull request，包含：有無 Copilot Autofix 建議而修復的警示數、未修復即合併的警示數、被關閉為誤報或接受風險的數量、造成最多警示的規則、修復率與平均修復時間。Copilot Autofix 的指標只在啟用的 repository 顯示。組織檢視需要對組織中 repository 有 write 權限；企業檢視需要組織擁有者或 security manager。

追蹤與整合

• 連結 issue： 有 write 權限的人可在警示頁面右側點 Tracking，選擇建立新 issue 或 Add existing GitHub issue。這項功能目前是公開預覽，可能變動。新 issue 會預先填入弱點細節並自動連結。
• Webhook 與 API： 可用 code scanning webhook 建立整合（例如有新警示時建立 issue 或發 Slack 通知），並用 REST API 監控整個組織或 repository 的結果。
• 外部掃描： 可在別處用 CodeQL CLI 或其他靜態分析工具分析，再上傳結果；外部產生的警示與 GitHub 內產生的顯示方式相同。

上傳 SARIF

依產生方式選擇上傳方法：用 Actions 執行 CodeQL action，會自動上傳；用 Actions 執行其他相容工具，在 workflow 最後加上傳步驟；用 CodeQL CLI 在 CI 中執行，由 CLI 上傳；工具把結果放在 repository 外的 artifact，則用 code scanning API 上傳。預設每次分析預期一個 SARIF 檔；同一 commit 上傳多組結果時，必須為每組指定唯一的 category。用 CodeQL CLI 時傳入 --sarif-category；codeql-action/analyze 會依 workflow 名稱與 matrix 變數（通常是語言）自動設定，可用 category 輸入覆寫；用 Actions 上傳其他工具的結果，同一 workflow 上傳超過一個檔案時必須指定 category。

判斷練習

情境： 團隊每次 workflow 執行都用 upload-sarif 動作，對同一個 commit 上傳兩個不同工具的 SARIF 檔，但都沒有指定 category。

解析： 同一 commit 上傳多組結果時，必須為每組指定唯一的 category；沒有 category，後上傳的結果無法與前一組區分。

來源：About the tool status page（GH500-DOC-35）、Code scanning on pull requests（GH500-DOC-42）、Linking code scanning alerts to GitHub issues（GH500-DOC-41）、Integration with code scanning（GH500-DOC-43）、Uploading a SARIF file to GitHub（GH500-DOC-38）；2026-11-02 已對照抓下的頁面段落（未讀完的頁面後半不在內）；其餘為整理，備考前請讀來源原文。