Gitleaks：一個功能完備、停止開發的密碼掃描工具，你該怎麼用

它解決什麼問題，給誰用

Gitleaks 處理的是開發流程中一個具體的痛點：密碼、API key、token 被寫進程式碼，然後跟著 git 歷史永遠留下來。刪掉檔案不夠，因為舊 commit 還留著。Gitleaks 可以掃描整個 git 歷史，找出那些不該出現的字串。它也接受一般目錄或 stdin，所以不一定要在 git repo 裡才能用。這工具主要給兩種人：一種是負責 CI/CD 的工程師，想在每次 push 或 commit 時自動攔截；另一種是資安或 DevSecOps 人員，想對既有的 repo 做一次全面盤點。它的輸出格式包含 json、csv、sarif，可以直接餵給其他分析工具，這對後者特別有用。

偵測引擎：regex 為主，熵值為輔

Gitleaks 的偵測核心是規則，每一條規則基本上是一組 regex。作者在部落格文章標題直接說「Regex is (almost) all you need」，這透露了設計哲學。它不像某些工具用機器學習或語意分析，而是靠模式比對。例如範例中的 sidekiq-secret 規則，抓到的是類似 export BUNDLE_ENTERPRISE__CONTRIBSYS__COM=cafebabe:deadbeef 的字串，輸出會顯示 Secret、RuleID、Entropy、檔案路徑、commit hash、作者與指紋。Entropy 是輔助判斷，用來評估字串的隨機程度，但最終是否觸發還是取決於 regex 是否吻合。這表示它對已知型態的 secret 很有效，但對新型態或未定義規則的 secret，可能就漏掉。文件沒有說明它是否有內建的允許清單或例外機制，但從 flag 可以看到有 --ignore-gitleaks-allow，代表它支援在程式碼中加 gitleaks:allow 註解來忽略特定行。

安裝與基本指令：五分鐘內跑起來

安裝方式很直接，官方列出三種：macOS 用 brew install gitleaks，Docker 用 docker pull zricethezav/gitleaks:latest，或從原始碼 make build。Docker 的用法是掛載要掃描的目錄，例如 docker run -v ${path_to_host_folder_to_scan}:/path zricethezav/gitleaks:latest [COMMAND] [OPTIONS] [SOURCE_PATH]。指令分成幾個子命令：dir 掃目錄或檔案，git 掃 git repo，stdin 從標準輸入讀取。最基本的用法是 gitleaks git -v，其中 -v 代表 verbose，會印出找到的 secret 詳細資訊。若要輸出報告，可用 -f 指定格式，例如 json 或 sarif，並用 -r 指定報告路徑。配置檔的優先順序是：--config 參數、GITLEAKS_CONFIG 環境變數、GITLEAKS_CONFIG_TOML 環境變數內容、目標路徑下的 .gitleaks.toml，最後才是預設配置。這讓你可以針對不同專案放不同的 .gitleaks.toml，不用改全域設定。

整合 pre-commit 與 CI：實際配置範例

Gitleaks 可以當 pre-commit hook，這對防止新密碼進 repo 很有效。官方給的範例是在 .pre-commit-config.yaml 中加入一段設定，指向 gitleaks repo 的 rev 版本，例如 v8.24.2，然後指定 hooks 的 id 為 gitleaks。執行 pre-commit install 之後，每次 git commit 都會觸發掃描，如果找到 secret，commit 就會失敗。範例顯示輸出為 Detect hardcoded secrets.....Failed。若要跳過，可以在 commit 指令前加 SKIP=gitleaks。另外也有 gitleaks-action 可以整合 GitHub Actions，但 README 沒有提供具體 YAML 範例，只說它是獨立的專案。這種整合方式適合在 push 或 pull request 時掃整個 diff 或全歷史，比 pre-commit 更全面，因為 pre-commit 只擋新的變更。

真正的限制：功能凍結與誤判風險

最明顯的限制是作者在 README 開頭用警告標記宣告：Gitleaks is feature complete，不會再合併新功能，未來只做安全修補。這代表你不能再期待新的規則、新的命令或新的輸出格式。作者說他要轉移到 Betterleaks，這是一個未在 README 中詳細說明的專案，但暗示了未來發展方向。另一個限制是 regex 為主的偵測本質上會有誤判，例如一個測試用的假 token 可能符合規則而被標記，造成 CI 失敗。雖然可以用 .gitleaksignore 或 gitleaks:allow 註解來處理，但這需要人工介入。另外，掃描大型 git 歷史可能耗費時間，README 沒有提供效能數據，但提供了 --max-target-megabytes 來跳過過大的檔案，這暗示了作者知道大檔案是問題。最後，--max-decode-depth 預設為 0，表示它不會自動解碼 base64 或其他編碼的 secret，這意味著如果你把 token 編碼後放入程式碼，Gitleaks 可能抓不到。

替代方案：Betterleaks 與其他工具的差異

README 直接點名 Betterleaks 作為作者的下一步，這是最直接的替代方案。Betterleaks 的連結指向 GitHub，但 README 沒有說明它的具體功能或運作方式。從脈絡推測，它可能是 Gitleaks 的後繼者，會繼續開發新功能，而 Gitleaks 停在現狀。另一個常見的替代方案是 TruffleHog，但 README 完全沒有提到它，我不能聲稱有任何比較。如果你需要的是持續更新、新規則或更聰明的偵測，Betterleaks 可能是方向，但它的成熟度未知。相對地，Gitleaks 已經過多年開發，v8.30.1 是目前的版本，代表它經歷過大量修補，穩定性有保證。選擇時要考慮：你比較重視新功能還是穩定性？如果只是要一個可靠的掃描器，且願意接受不再更新，Gitleaks 仍可用。

維護與升級成本：凍結後的影響

Gitleaks 的授權是 MIT，這意味著你可以自由使用、修改、甚至複製程式碼，沒有 copyleft 的負擔。但維護成本要分兩面看。正面：作者保證安全修補，所以如果你發現漏洞，還有機會被修復。負面：不會有新功能，所以當新的 secret 型態出現（例如新的雲端服務 token），你不會從官方得到對應的規則，必須自己寫 .gitleaks.toml。升級成本低，因為它是單一 Go binary，沒有複雜的依賴，但你需要追蹤 release 頁面，至少更新到最新的安全修補版本。文件沒有提到向後相容的承諾，但版本號維持在 v8，表示 minor release 不會破壞 API。如果你的 CI 流程依賴特定輸出格式，凍結狀態反而讓格式穩定，這對長期維護是好事。

編輯結論

若你需要在 git 歷史中找出已洩漏的密碼，或想在 pre-commit 階段攔截新密碼，Gitleaks 仍是穩定且成熟的選擇，MIT 授權讓它容易整合。但作者已在 README 明確宣告 feature complete，不會合併新功能，未來只有安全修補，因此若你期待新的規則或偵測能力，應該先評估 Betterleaks 或其他仍在開發的工具。採用前，請確認你的 .gitleaks.toml 規則符合你的專案需求，並測試 --redact 與 --baseline-path 的輸出是否符合合規要求，因為這兩個功能在凍結後不會再有改善。

官方來源

1. gitleaks/gitleaks on GitHub
2. License: MIT
3. Project website
4. README
5. Releases