使用 Betterleaks 檢查 Git 中的 Secret

Posted on 2026-09-28

前言

AI Agent 一次修改多個檔案時，Review 時可能漏看設定檔或測試資料中的 API key、token

這篇記錄如何用 Betterleaks 檢查 Git repository，並放進 commit 前的流程，減少不小心把憑證提交到 Git 的機會

Betterleaks 是什麼？

Betterleaks 是用來找出疑似 API key、token 或密碼的 Secret Scanner，支援掃描 Git 歷史、檔案和 staged diff

本文以正式版 v1.9.0 的用法為例

安裝與掃描

macOS 可以直接用 Homebrew 安裝 V1 正式版：

1 2	brew install --cask betterleaks/tap/betterleaks@1 betterleaks-v1 version

這個套件的指令名稱是 betterleaks-v1，以下範例都使用這個名稱

先掃描 Git 歷史，盤點既有問題：

1	betterleaks-v1 git .

每次 commit 前，則只檢查 staged diff：

1	betterleaks-v1 git . --pre-commit --staged

這個指令只檢查已經 git add 的變更，尚未加入暫存區的內容不在掃描範圍內

放進 pre-commit 流程

如果每次都要手動執行，忙的時候還是容易忘記，可以用 pre-commit 自動處理

先安裝 pre-commit：

1	brew install pre-commit

在 repository 根目錄的 .pre-commit-config.yaml 加入：

repos:
  - repo: local
    hooks:
      - id: betterleaks
        name: Detect hardcoded secrets
        entry: betterleaks-v1 git --pre-commit --staged --verbose --redact
        language: system
        pass_filenames: false

Hook 會使用本機的 betterleaks-v1，使用前需先完成上述安裝

再啟用 Hook：

1	pre-commit install

之後每次 commit 就會自動掃描 staged diff，找到疑似 Secret 時會阻擋提交，先確認結果並修正，再重新 commit

遇到誤判時怎麼處理？

先確認掃描結果，再決定處理方式：

真正的憑證：先撤銷或輪替，再移除程式碼中的值，必要時清理 Git 歷史
一般測試資料：改成明確的假值，例如 YOUR_API_KEY_HERE
必須保留的測試字串：確認是誤判後，再加入忽略清單

要忽略單筆結果，可以重新掃描並顯示詳細資訊：

1	betterleaks-v1 git . --pre-commit --staged --verbose --redact

把結果中的 Fingerprint 複製到 repository 根目錄的 .betterleaksignore，每行一筆，直接複製即可

比起停用整條規則或排除整個資料夾，忽略單筆結果比較容易控制範圍，也建議留下例外原因，方便之後 Review

注意事項

本機 Hook 可以被略過，團隊專案建議在 CI 再加一道檢查，並要求檢查通過後才能合併
只刪掉憑證或新增修正 commit，不會讓已曝光的憑證失效，仍要撤銷或輪替
Secret 掃描不能限制 Agent 讀取 .env 或對外傳送資料，敏感資料仍要另外管理

對我來說，先把 staged diff 的檢查自動化，就能少一件需要靠自己記得的事，Review 時也可以更專心看程式邏輯

前言

Betterleaks 是什麼？

安裝與掃描

放進 pre-commit 流程

遇到誤判時怎麼處理？

注意事項

Reference