D2：設定與使用 Secret Protection
D2-O1 啟用與設定 Secret Protection
Secret scanning 掃描的不只是最新的程式碼。它會檢查所有分支的完整 Git 歷史，也會檢查 issue 與 pull request 的文字、Discussions、wiki 與 secret gist，找出寫死在其中的 API 金鑰、密碼與權杖。警示出現在 repository 的 Security and quality 頁籤。
誰需要啟用、誰不用
| 範圍 | 條件 |
|---|---|
| 公開 repository | 自動掃描，不另外收費 |
| 組織擁有的私有與 internal repository | 需要 GitHub Secret Protection（GitHub Team 或 Enterprise Cloud） |
| 使用者擁有的私有與 internal repository | 限於 Enterprise Cloud 的 Enterprise Managed Users，或已啟用 Secret Protection 的 GitHub Enterprise Server |
實測註記（單次觀察，2026-11-02）： 新建一個公開 repository 後，沒有做任何設定，secret scanning 與 push protection 都已是啟用狀態；non-provider patterns 與 validity checks 則是停用。上表只寫 secret scanning 對公開 repository 自動啟用，沒有提到 push protection；這個預設是 repository 的預設、帳號層級的設定，還是公開 repository 的規則，我沒有查證。詳見實測紀錄。
組織也可以在 Assessments 頁面隨時執行免費的程式碼掃描評估。
樣式類型與有效性檢查
- Partner patterns（合作夥伴樣式）：偵測服務供應商發行的憑證，屬於預設的偵測（官方稱 default detection）。這類 secret 會直接回報給供應商，由供應商採取行動（例如撤銷），不會出現在你的 repository 警示中。
- Non-provider patterns（非供應商樣式）：偵測不屬於特定供應商的 secret，例如私密金鑰、連線字串與一般 API 金鑰。
- Validity checks（有效性檢查）：確認偵測到的 secret 是否仍然有效，讓你依風險排定處理順序。檢查時可能需要連到發行該 secret 的服務。
操作示例：為單一 repository 啟用
- 開啟 repository 的 Settings；看不到時，從 More 下拉選單進入。
- 在側邊欄的 Security and quality 區塊選 Advanced Security。
- 在 Secret Protection 右側按 Enable，檢視影響後按 Enable Secret Protection。
啟用 Secret Protection 時，secret scanning 的使用者警示會一併啟用。要一次對多個 repository 啟用，組織擁有者使用 security configurations；步驟見官方的「Enabling security features at scale」，本節不展開。
判斷練習
情境： 你的組織有一批私有 repository，團隊以為「secret scanning 預設就會跑」，所以沒有做任何設定。
解析： 自動掃描只保證公開 repository。組織擁有的私有 repository 需要 GitHub Secret Protection，並在 Advanced Security 設定中啟用；沒有啟用就沒有警示，這不代表沒有外洩。
來源：About secret scanning（GH500-DOC-01）、Enabling secret scanning for your repository（GH500-DOC-06）；2026-11-02 以頁面原文比對本節的數字與名稱；其餘敘述為整理，備考前請讀來源原文。
D2-O2 預防機密外洩
Push protection 在 secret 進入 repository 之前就攔截。偵測到疑似 secret 時，推送會被阻擋並說明原因；貢獻者必須檢視被標記的內容、移除敏感資訊後重新推送。這是「預防」，與事後才出現警示的 secret scanning 不同。
涵蓋的途徑與樣式
Push protection 支援四類樣式：partner patterns、generic patterns（私密金鑰、資料庫連線字串等結構化 secret）、custom patterns，以及 AI 偵測的 secret（公開預覽，針對密碼這類沒有固定格式的 secret）。
| 途徑 | 支援的樣式 |
|---|---|
| 命令列推送 | 全部四類 |
| GitHub 網頁介面提交 | 全部四類 |
| 上傳檔案到 GitHub | 全部四類 |
| REST API 請求 | partner、generic、custom；不含 AI 偵測 |
繞過與其後果
預設下，有寫入權限的人可以選擇繞過，並須從三個理由擇一：
| 理由 | 建立的警示 |
|---|---|
| It's used in tests | 已關閉，原因為 used in tests |
| It's a false positive | 已關閉，原因為 false positive |
| I'll fix it later | 開啟中（open） |
繞過後，警示會出現在 repository、組織與企業的 Security and quality 頁籤，事件寫入稽核日誌，並以電子郵件通知有關注該 repository 的擁有者、security manager 與 repository 管理員，信中附上 secret 連結與繞過理由。
另有「使用者層級的 push protection」：只在 GitHub.com、綁定個人帳號、預設啟用，用來阻止你把 secret 推到公開 repository。除非 repository 層級也啟用了 push protection，否則你繞過它時不會產生警示。
判斷練習
情境： 開發者用 REST API 提交一個密碼，該密碼沒有固定格式，只能靠 AI 偵測辨識。團隊認為「所有途徑都有同樣保護」。
解析： AI 偵測的 secret 在命令列、網頁介面與檔案上傳受保護，但 REST API 不含這一類。評估防護範圍時要按途徑逐項核對，不能用「有啟用 push protection」概括。
來源：About push protection（GH500-DOC-02）；2026-11-02 以頁面原文比對本節的數字與名稱；其餘敘述為整理，備考前請讀來源原文。
D2-O3 管理與回應 Secret Protection 警示
審查警示後的流程是：評估、修復，再關閉。關閉時在 Close as 下拉選單選一個原因，可附註解，再按 Close alert。你可以設定警示通知，也可以稽核團隊如何回應；管理員還能控制誰有權限關閉警示（delegated alert dismissal）。
修復的優先順序
- 把已提交的 secret 視為已外洩。
- 更新所有使用舊憑證的服務；若是 GitHub personal access token，刪除舊的並建立新的。
- 依 secret 供應商的不同，檢查安全日誌，確認有無未經授權的活動。
- 私有 repository 中外洩的 GitHub personal access token（仍有效或尚未確認者），可通報 GitHub 請其撤銷；此功能目前為公開預覽。通報前宜先輪替憑證，以免撤銷後讓依賴它的工作流程中斷。
官方強調：憑證一旦撤銷，改寫 Git 歷史通常不必要，而且耗時。優先順序是讓憑證失效，不是清除歷史。
判斷練習
情境： 團隊發現某個 API 金鑰留在三個月前的 commit 裡，決定先花兩天用 rebase 把歷史清乾淨，再處理金鑰。
解析： 順序反了。金鑰在被發現的那一刻就應視為已外洩；先撤銷或輪替，才能終止風險。歷史改寫可以之後再評估，且往往不需要。
本節沒有列出「Close as」的完整原因清單：官方該頁面只說明要從下拉選單選一個原因，未列出全部標籤。需要精確標籤時請在實際的警示畫面核對。
來源：Resolving alerts from secret scanning（GH500-DOC-03）、About secret scanning（GH500-DOC-01）；2026-11-02 以頁面原文比對本節的數字與名稱；其餘敘述為整理，備考前請讀來源原文。
D2-O4 控制存取、原則與自訂
委派繞過（delegated bypass）
預設下有寫入權限的人都能繞過 push protection。委派繞過把這項權限收斂給指定對象，其他貢獻者的繞過要送審。它提供兩種授權：
- Bypass privileges（繞過權限）：被授權者在被阻擋時可自行繞過，並能審查、核准他人的繞過請求。
- Exemption（豁免）：被授權者的推送完全不觸發 push protection。官方建議留給需要頻繁推送的可信自動化，例如遷移機器人或服務帳號。
永遠可以繞過的對象包括：組織擁有者、security manager、被加入繞過名單的團隊、預設角色或自訂角色，以及擁有細部權限「review and manage secret scanning bypass requests」的自訂角色。不在名單上的貢獻者提出的請求進入審查流程，請求在 7 天後過期。
自訂樣式（custom patterns）
自訂樣式可定義在 repository、組織或企業三個層級。表單包含必填的 Pattern name 與 Secret format（規則運算式），以及 More options（周圍內容與額外比對條件）和 Sample test string（確認樣式符合預期）。
流程是：先 Save and dry run，找出符合項但不建立警示；結果最多顯示 1,000 筆，檢視誤判、調整後再跑。確認後按 Publish pattern。
| 層級 | dry run 範圍 |
|---|---|
| Repository | 目前的 repository |
| 組織 | 全部 repository，或最多 10 個選定的 |
| 企業 | 最多 10 個選定且你擁有管理權限的 |
發佈後，才能按 Enable 對該樣式啟用 push protection。在組織層級，它只對已啟用 push protection 的 repository 生效；官方提醒，對常見樣式啟用 push protection 可能干擾貢獻者。企業層級的樣式，只有建立者能編輯或執行 dry run。
判斷練習
情境： 你剛寫好一個公司內部權杖的自訂樣式，想立刻讓 push protection 擋住它。
解析： 先 dry run 檢視誤判，確認後 Publish，之後才有 Enable push protection 的選項。跳過 dry run 就發佈，等於讓貢獻者承擔誤判的代價。
本節沒有涵蓋學習指南中的「alert recipients 與 exclusions」：我尚未找到可核對的官方頁面，寫入前不補寫。
來源：About delegated bypass for push protection（GH500-DOC-04）、Defining custom patterns for secret scanning（GH500-DOC-05）；2026-11-02 以頁面原文比對本節的數字與名稱；其餘敘述為整理，備考前請讀來源原文。