D3：設定與使用供應鏈安全
D3-O1 理解與管理相依性及供應鏈風險
Dependency graph 是其他功能的資料基礎
Dependency graph 是 repository 中 manifest 與 lock 檔的摘要，再加上用 dependency submission API 提交的相依性。它列出兩個方向：dependencies（你依賴的生態系與套件）與 dependents（依賴你的 repository 與套件）。每個相依性可以看到版本、授權、來自哪個 manifest，以及是否有已知弱點；對支援間接相依性的生態系，還能展開「Show paths」，看是哪條路徑把它帶進來。有弱點的套件會排在最上面。
- 公開 repository 預設啟用；私有 repository 與 fork 也能使用，由 repository 管理員啟用或停用。
- Dependents 只在公開 repository 列出，私有 repository 不回報這項資料。
- Dependency review 與 Dependabot security updates 都以它為前提：dependency review 要先啟用 dependency graph；security updates 要先啟用 dependency graph 與 Dependabot alerts。
除了分析 manifest 與 lock 檔，也可以用 dependency submission API 自行提交相依性資料；dependency review API 的結果會包含這些提交的相依性。
弱點資料來源
Dependabot 警示的弱點資料來自 GitHub Advisory Database，只有經 GitHub 審查的 advisory 會觸發警示。
SBOM（軟體物料清單）
SBOM 是專案相依性的正式、機器可讀清單。GitHub 可以把 dependency graph 的目前狀態匯出為業界標準的 SPDX 格式。內容包含相依性、版本、套件識別碼、授權、間接相依性路徑與著作權資訊，不包含 dependents。
| 匯出方式 | 做法 |
|---|---|
| 介面 | Insights → Dependency graph → 右上角 Export SBOM |
| REST API | 先請求產生；在回應為 202 時輪詢 sbom_url，回應為 302 時依重新導向下載完成的 SBOM |
| GitHub Actions | SPDX Dependency Submission Action、Anchore SBOM Action（均產生 SPDX 2.2 相容的 SBOM）；SBOM Dependency Submission Action 則是把 CycloneDX SBOM 上傳到 dependency submission API |
判斷練習
情境： 稽核要求你提交一份包含「依賴本專案的其他專案」的清單，團隊打算直接匯出 SBOM 交差。
解析： SBOM 描述的是你專案依賴的東西，不含 dependents。要看誰依賴你，要用 dependency graph 的 Dependents 檢視（且只在公開 repository 可用）。
來源：Dependency graph（GH500-DOC-16）、Exporting a software bill of materials for your repository（GH500-DOC-17）；2026-11-02 已逐句對照抓下的頁面原文，整理性的敘述以頁面內容為限；備考前請讀來源原文。
D3-O2 偵測、排定優先順序並回應供應鏈警示
警示何時產生
Dependabot 掃描 repository 的預設分支，在兩種情況下發出警示：GitHub Advisory Database 新增了一則弱點；或 repository 的 dependency graph 改變（例如推送了更新套件版本的 commit）。警示顯示在 Security and quality 頁籤與 dependency graph，內容包含受影響檔案的連結、弱點細節與嚴重度，以及已修復的版本（若有）。
官方列出的限制：警示不能抓到所有安全問題；新弱點需要時間才會進入資料庫；只有經 GitHub 審查的 advisory 會觸發警示；Dependabot 不掃描封存的 repository；GitHub Actions 只對使用 semantic versioning 的 action 產生警示，使用 SHA 的不會。
排定優先順序
官方文件建議合併參考：嚴重度、EPSS（Exploit Prediction Scoring System）分數、相依性的範圍（scope）、相依性的關係（直接或間接）。另有選用的 reachability analysis（公開預覽，目前支援使用 npm、pnpm 或 Yarn 的 JavaScript repository 與 TypeScript repository），判斷你的應用程式能否到達有弱點的相依性程式碼。
回應：security updates
啟用 Dependabot security updates 後，只要依賴 dependency graph 的警示出現，Dependabot 就會嘗試修復：確認能否在不破壞 dependency graph 的前提下升級，再開 pull request 把相依性更新到包含修補的最低版本，並連結到警示；做不到則在警示上回報錯誤。合併這個 pull request 會關閉對應的警示。
- 啟用後，Dependabot 會嘗試為每個有可用修補的開啟警示開 pull request。
- 想自行挑選要開 pull request 的警示，官方建議：保持 security updates 停用，改建 auto-triage 規則。
dependabot.yml與警示之間沒有互動，唯一的關聯是合併 Dependabot 開的 security update pull request 會關閉警示。- 只有 manifest 或 lock 檔明確指定的相依性才會觸發 security updates。
實測註記（單次觀察，2026-11-02）： 在練習用公開 repository 啟用 security updates 後，lodash 4.17.15 的警示中最高的修復版本是 4.18.0，但 Dependabot 開的 pull request 把它升到 4.18.1（當時 npm 的最新版）。官方文字寫的是「包含修補的最低版本」，這次實測與該字面不一致，原因沒有查明；不要把「一定是最低的修補版本」當成可預測的行為，考試仍以官方文字為準。詳見實測紀錄。
- Grouped security updates 在同一個生態系內把多個相依性合成一個 pull request；不會跨生態系，也不會把 security updates 與 version updates 合併。
通知與自動分流
預設下，GitHub 以電子郵件通知「有 write、maintain 或 admin 權限，並且關注此 repository」的人。首次啟用 Dependabot 時，不會為已存在的弱點寄通知，只通知啟用後新發現的。可改用每週摘要，或關閉通知但保留警示；web 與電子郵件通知會在啟用、新增 manifest 以及發現嚴重度為 critical 或 high 的新弱點時送出，但弱點更新時不會再通知。
Auto-triage 規則在通知寄出之前套用，所以能減少雜訊：
| 類型 | 內容 |
|---|---|
| GitHub 預設規則 | Dismiss low impact issues for development-scoped dependencies：公開 repository 預設啟用，私有 repository 可自行選用；Dismiss package malware alerts：預設停用 |
| 自訂規則 | 依嚴重度、套件名稱、CWE 等中繼資料自動關閉、延後（snooze）或重新開啟警示，並可指定要開 pull request 的警示；限公開 repository，或有 Code Security 的 GitHub Team 組織 repository |
被自動關閉的警示，其關閉原因為 resolution:auto-dismiss，仍可查詢與重新開啟。若中繼資料改變（例如把相依性範圍從 development 改成 production，或 GitHub 修改了 advisory 的某些中繼資料），警示可以被自動重新開啟。要在警示頁面看到它們，需先清除預設的 is:open 篩選，再選 Closed as → Auto-dismissed。自動關閉的活動會出現在 webhook、REST 與 GraphQL API 以及稽核日誌。
本節沒有涵蓋學習指南提到的「透過 campaigns 修復供應鏈警示」：我讀到的 security campaigns 官方頁面只描述 code scanning 與 secret scanning 警示，沒有提到 Dependabot，所以不補寫。
判斷練習
情境： 團隊啟用 Dependabot security updates，卻抱怨「每個警示都開 pull request，噪音太多」，打算在 dependabot.yml 設定只處理 high 嚴重度。
解析： dependabot.yml 與警示沒有互動，這個設定無法篩選要處理的警示。官方建議的做法是停用 security updates，改建 auto-triage 規則來指定要開 pull request 的警示。
來源：Dependabot alerts（GH500-DOC-13）、Dependabot auto-triage rules（GH500-DOC-14）、Dependabot security updates（GH500-DOC-20）、Configuring notifications for Dependabot alerts（GH500-DOC-21）、Managing alerts that have been automatically dismissed（GH500-DOC-22）；2026-11-02 已逐句對照抓下的頁面原文，整理性的敘述以頁面內容為限；備考前請讀來源原文。
D3-O3 在開發過程中保護相依性
Dependency review
Dependency review 在 pull request 的 Files changed 頁籤以 rich diff 顯示相依性的變動：新增、移除或更新了哪些相依性及其發布日期、有多少專案使用這些元件，以及弱點資料。它也包含 lock 檔中間接相依性的變動。可用條件：公開 repository，或有 Code Security 的 GitHub Team 組織 repository；而且要先啟用 dependency graph。與 Dependabot alerts 的差別在於：alerts 找出已經在相依性中的弱點，dependency review 則是在引入之前就攔下。
Dependency review action
這個 action 在 pull request 比較基底與 head 的相依性差異，預設只要發現有弱點的套件，檢查就會失敗；若 repository 要求此檢查必須通過，pull request 就無法合併。它適用所有公開 repository，以及啟用 Code Security 或 Advanced Security 的私有 repository。常用設定（可內嵌在 workflow，或用 config-file 引用設定檔）：
| 選項 | 作用 |
|---|---|
fail-on-severity |
達到哪個嚴重度（critical、high、moderate、low）就失敗 |
allow-licenses／deny-licenses |
只允許或封鎖指定授權（SPDX 識別碼）；兩者只能擇一 |
allow-ghsas |
偵測時略過指定的 GitHub Advisory Database ID |
fail-on-scopes |
在哪些範圍（development、runtime、unknown）引入弱點就失敗 |
可設定的人：repository 擁有者、組織擁有者、security manager 與具 admin 角色的使用者。
在組織內強制： 先在某個 repository 設定好 action，再建立 branch ruleset，啟用「Require workflows to pass before merging」並把 dependency review workflow 設為必要，pull request 通過才能合併。
競態條件： 若相依性是在建置時用 dependency submission API 提交，應把提交與 dependency review 放在同一個 workflow；若分開執行，需設定 retry-on-snapshot-warnings: true，並把 retry-on-snapshot-warnings-timeout 設成略長於最慢提交動作的時間。
授權合規（企業層級）： 在 GitHub Enterprise Cloud 且啟用 Code Security 時，可用企業政策與 ruleset 定義允許的授權（可匯入 SPDX 識別碼）。含不合規相依性的 pull request 會被擋下，直到更新相依性、核准套件例外，或調整政策。可把 Enterprise Open-Source License Manager 角色指派給使用者或團隊，讓他們收到並回應關閉請求。
Dependabot version updates 與進階更新規則
Version updates 靠 repository 中的 dependabot.yml 啟用，依 semantic versioning 判斷新版本，依你設定的排程開 pull request 更新到符合設定的最新版本。重點：
- Cooldown： 預設有 3 天的 cooldown，新版本發布後 3 天才會被考慮；此預設不適用於 security updates。可用
cooldown選項自訂。 - 可更新 GitHub Actions 的參照與 reusable workflows，也支援 vendored 相依性（部分套件管理員）。
- 分組： security updates 的分組可在 Advanced Security 設定（repository 或組織的 Global settings）啟用，或在
dependabot.yml以更細的方式分組：依套件名稱、development 或 production、SemVer 等級、或跨多個目錄。 - 維護者長時間不理會 Dependabot 的 pull request 時，Dependabot 會暫時暫停更新並通知。
判斷練習
情境： 團隊在 pull request 上加了 dependency review action，設定 allow-licenses 與 deny-licenses 兩個選項想雙重把關。
解析： 這兩個選項只能擇一，不能同時使用。要限定可接受的授權就用 allow，要封鎖特定授權就用 deny。
來源：Dependency review（GH500-DOC-15）、Configuring the dependency review action（GH500-DOC-18）、Configuring open source license policies（GH500-DOC-19）、Enforcing dependency review across an organization（GH500-DOC-24）、Dependabot version updates（GH500-DOC-23）、Dependabot security updates（GH500-DOC-20）；2026-11-02 已逐句對照抓下的頁面原文，整理性的敘述以頁面內容為限；備考前請讀來源原文。
D3-O4 設定原則、權限與整合
誰能啟用與管理
- Dependabot alerts： repository 管理員與組織擁有者可以啟用；啟用時 GitHub 立即建立 dependency graph 並為偵測到的弱點建立警示。管理員可以再授權其他人或團隊。
- Dependency graph： repository 管理員啟用或停用。
- Security updates： 需要先啟用 dependency graph 與 Dependabot alerts。
- Auto-triage 規則： 組織擁有者、security manager 與具 admin 權限的使用者可以啟用、停用與檢視；自訂規則可由 admin 建立。
警示指派（ownership）
有 write 或更高權限的使用者可以把 Dependabot 警示指派給協作者、團隊，或 AI agent（Copilot，或在 repository 設定中啟用的第三方 agent，例如 Codex 或 Claude）。被指派者會收到通知，警示清單顯示其名稱，並可依指派者篩選。指派給 agent 時，agent 會自動建立 session 並開啟含建議修復的 draft pull request；若無法產生修復，仍保留為指派者，可在警示時間軸點 View Session 檢視日誌。注意事項：
- 指派 Dependabot 警示需要 Code Security 或 Advanced Security 授權，即使是公開 repository。
- 指派只顯示在 repository 層級的警示檢視，組織層級的 security overview 不顯示。
整合與自動化
- 警示的指派者變動時，GitHub 送出
assignees_changedwebhook 事件，可用來觸發 workflow 或與外部系統同步；也可用 REST API 以程式管理指派。 - 自動關閉的活動出現在 webhook、REST 與 GraphQL API，以及稽核日誌的
repository_vulnerability_alert項目。 - 通知電子郵件包含
X-GitHub-Severity標頭，可據以過濾；電子郵件摘要最多涵蓋 10 個 repository。
判斷練習
情境： 資安主管想把一批 Dependabot 警示指派給 Copilot 產生修復，團隊使用 GitHub Team，沒有購買 Code Security 或 Advanced Security，但這批警示都在公開 repository。
解析： 指派 Dependabot 警示需要授權，官方明說連公開 repository 也一樣。沒有授權就不能指派，不能因為 repository 是公開的就繞過。
來源：Dependabot alerts（GH500-DOC-13）、Dependabot auto-triage rules（GH500-DOC-14）、Managing alerts that have been automatically dismissed（GH500-DOC-22）、Configuring notifications for Dependabot alerts（GH500-DOC-21）；2026-11-02 已逐句對照抓下的頁面原文，整理性的敘述以頁面內容為限；備考前請讀來源原文。