服務定位

GitGuardian 的核心定位是 跨工具的 secret leak detection + incident workflow、不只是「pre-commit grep」。底層是一組 Detector（350+ specific detector、覆蓋 AWS / GCP / Stripe / Slack / 自家 token 等）+ Validation endpoint（call 該 service 確認 secret live 中），上層是 Incident 物件（assign / resolve / ignore / share with developer）跟 Source 抽象（GitHub / GitLab / Bitbucket / Azure DevOps / Slack / Jira / Confluence / Notion）。本機側用 ggshield CLI 做 pre-commit hook 跟 CI scan。

跟 GHAS Secret Scanning 比、GitGuardian 走 cross-tool detection + remediation workflow、GHAS 走 deep integration in GitHub：GHAS 的 push protection 在 GitHub server-side 直接攔 push、partner pattern（AWS / Stripe / Slack）廣度高；但只要組織有 GitLab self-hosted、Bitbucket、或 developer 習慣把 token 貼 Slack / Confluence，GHAS 看不到的就是 GitGuardian 的場域。跟 Gitleaks / TruffleHog OSS 比、GitGuardian 走 managed SaaS + validation + workflow、OSS 走 self-hosted + 你自己接 incident pipeline；OSS 適合預算敏感 + 已有 SOC / IR tooling、GitGuardian 適合直接買 incident workflow 不想自建。

關鍵張力：validation endpoint 是 FP 降噪核心、但也是 vendor 風險點。Detector 抓到字串後 GitGuardian call 該 service API live verify（AWS access key 試 sts:GetCallerIdentity、Stripe key 試 retrieve event）、活躍 secret 才升 Incident。意義是 noise 從 OSS gitleaks 的 70-80% FP 降到 個位數 FP；風險是 GitGuardian 本身會 call 你的 cloud account — vendor trust 跟 Failure: Credential Rotation Without Scope 的 scope map 需要在 onboarding 就釐清。

本章目標

讀完本頁、讀者能判斷：

1. GitGuardian 在 secret scanning stack 中承擔哪一段（pre-commit / SCM scan / SaaS scan / honeytoken）、哪些要外接（Vault 管 rotation、IR tool 接 incident）
2. Detector / Validation / Incident / Source 的 ownership 設計（誰 assign、誰 resolve、developer 怎麼參與）
3. 跨 SCM + SaaS coverage 該開哪些 source、historical scan 多久跑一次
4. 何時用 GitGuardian、何時走 GHAS / Gitleaks / TruffleHog 的取捨

最短判讀路徑

判斷 GitGuardian deployment 是否健康、最少看四件事：

• Source coverage 廣度：除 GitHub / GitLab 外、Slack / Jira / Confluence / Notion 是否也納入掃 — developer 把 token 貼 Slack DM 是常見 leak vector
• Validation endpoint 是否開：FP 降噪靠 live verify、未開等於回到 OSS gitleaks 的 noise 水位
• Incident remediation SLA：valid incident 從偵測到 rotation 完成的時間、是否串 Vault 自動 rotation、是否進 PagerDuty / Slack alert
• ggshield 在 CI 跟 pre-commit 的覆蓋率：是否所有 repo 走 pre-commit hook、CI step 是否阻擋 commit-with-secret merge

四件事任一缺失、就是 Secrets Management at Scale 邊界的待補項目。

日常操作與決策形狀

Detector library：350+ specific detector（AWS Access Key / Stripe Live Key / Slack Bot Token / GitHub PAT / 自家 API key pattern 等）+ generic high-entropy detector。Specific detector 走 vendor-specific pattern + validation endpoint、FP 個位數；generic detector 抓 unknown pattern、FP 較高、通常 routing 到 manual triage queue。Production tenant 應該全開 specific、generic 視 noise budget 開。

Validation endpoint：detector 抓到字串後、GitGuardian backend call 該 service API live verify。AWS key 試 sts:GetCallerIdentity、Stripe key 試 retrieve test event、GitHub PAT 試 GET /user。verify 結果 Valid / Invalid / Unknown 三態、決定 incident severity。意義是 只有 active secret 升 incident、已 revoke 的舊 commit history 不再 noise。

Incident workflow：偵測命中後會建 Incident 物件（而非直接 alert）、含 source location / detector / validation status / suggested remediation。Incident 可 assign 給 developer（developer 在 GitGuardian dashboard 自助 acknowledge / rotate / mark FP）、SecOps 只 review escalated case。對應 Security Workflow as Code 的 shift-left 模式 — developer 是 first responder、不是 SecOps 全包。

Source coverage：GitGuardian 預設掃 SCM（GitHub / GitLab / Bitbucket / Azure DevOps / 自管 Git），但 差異化價值在 SaaS scan — Slack workspace（message / DM / file upload）、Jira issue / comment、Confluence page、Notion workspace、Microsoft Teams 都可接 source connector。Developer 在 Slack 貼 prod DB password 是真實常見 case、SCM-only 工具看不到。

ggshield CLI：本地 / CI 端的 detection engine。pre-commit hook 攔住 push 前 leak（developer 機器、可被 bypass 但成本提高）、CI step 在 PR 跑 historical scan（不可 bypass、阻擋 merge）。跟 GHAS Push Protection 同類、但跨 SCM、且 detector pool 來自同一個 GitGuardian backend、跟 dashboard incident 走同一條 lineage。

Historical scan：onboarding 第一次跑 full git history scan、回填過去所有 commit 的 leak。意義是 已 leaked 多年的 secret 被找出來、強制 rotation。對應 CircleCI 2023 Secrets Rotation 的場景：CI 環境 compromise 後、historical scan 在數小時內找出 CI 環境曾接觸過的所有 secret、配合 secret store API 自動 rotation。

Honeytokens：散佈假 AWS / Stripe / GitHub token 到 repo 角落 / Confluence page / internal doc、attacker 拿到後試用會觸發 alert。是 早期偵測 unauthorized access 的工程化做法、不依賴 detection model 抓 attacker behavior、而是讓 attacker 自己 trigger 自己。對應 GitHub OAuth 2022 Token Supply Chain — attacker 拿到 OAuth token 後試 GitHub API、honeytoken 在 attacker map 環境時就 trigger。

Rotation 整合：detect 完不是工作結束、要 rotate the secret。GitGuardian 自身不存 secret，rotation 走 webhook / API 拉 Vault / AWS Secrets Manager / Azure Key Vault 觸發 rotation workflow。意義是 偵測跟 remediation 解耦、但需要組織側先把 secret store 接好、否則 incident 只能 manual rotation。

核心取捨表

選 GitGuardian 的核心訴求：跨 SCM + SaaS coverage + 內建 incident workflow + honeytoken、且能投入 per-developer 訂閱（大型公司 contributor 數會放大成本）+ 有 SecOps 跟 developer 分工承接 incident。GitHub-only 環境且已買 GHAS、重疊不必要、直接用 GHAS；預算敏感且自家有 IR pipeline、走 Gitleaks 或 TruffleHog OSS。

進階主題

Honeytokens 散佈策略：honeytoken 的效果取決於 放在哪裡 + 看起來多真。放 repo README、Confluence runbook、Slack #engineering 過期附件、舊 backup script — attacker reconnaissance 會優先看的地方。token 的命名要跟組織 naming convention 一致（prod-db-readonly-2024）、避免一看就是假的。每個 honeytoken 配 unique ID、trigger 時能定位 attacker 從哪個位置拿到、反推 leak surface。

Validation endpoint 的 trade-off：validation 是 FP 降噪核心、但代價是 GitGuardian 會 call 你的 cloud account。AWS key 命中時 GitGuardian 從自家 IP call sts:GetCallerIdentity、log 留在你的 CloudTrail。Onboarding 要 把 GitGuardian IP range allowlist 進 SIEM whitelist、避免被自家 detection 誤判為 unauthorized access；同時要評估 vendor trust — 2020 年 GitGuardian 自家 source code 透過第三方 SaaS leak、提醒 vendor 不是 detection-only 的零信任邊界。

IR workflow 整合：Incident 不應該停在 GitGuardian dashboard、要 routing 到組織既有 IR tooling — PagerDuty for on-call、Slack channel for SecOps、Jira ticket for tracking。Webhook 是標準做法、payload 含 incident metadata + validation status、由組織側決定升級邏輯（valid + prod scope → PagerDuty page；invalid + dev scope → Slack info）。

Historical scan + scope map：偵測到 leaked secret 後、要回答 這個 secret 還在哪裡用。GitGuardian 的 historical scan 找出 所有 commit 提到該 pattern 的位置、配合組織側 secret store 的 who uses this secret metadata、形成 scope map。對應 Failure: Credential Rotation Without Scope — rotation 不能只換一個地方、要全 scope 一起換、否則舊 secret 還在某個 service 用、rotation 沒生效。

排錯與失敗快速判讀

• Incident volume 爆炸 / developer 看不完：generic high-entropy detector 全開 + 沒 assign 到 developer — 縮 generic detector scope、incident 走 assign-to-author、SecOps 只 review escalated
• Valid incident rotation 慢 / SLA 跑掉：沒接 secret store rotation API、停在 manual rotation — 接 Vault / Secrets Manager webhook、自動觸發 rotation workflow
• Slack / Confluence 沒掃進來：以為 SCM-only 就夠 — 接 SaaS source connector、developer 貼 token 在 Slack DM 是常見 leak vector
• ggshield 被 bypass：pre-commit 在 developer 機器、可 --no-verify — 同步在 CI step 跑 ggshield、CI 不可 bypass、阻擋 merge
• Validation FP 不降：validation endpoint 沒開、或被 firewall 擋 — 確認 GitGuardian IP range 在 cloud account allowlist、validation status 是 Valid 不是 Unknown
• Honeytoken 沒 trigger / 假警報：token 放錯位置（attacker 不會看的 deep nested folder）或命名一看就假 — 散佈到 reconnaissance hot spot、命名跟組織 convention 一致
• Per-developer 計費暴衝：contractor / bot account 也算 developer — review billing report、排除 service account / read-only viewer、跟 vendor 談 contributor 定義

何時改走其他服務

不在本頁內的主題

• ggshield 完整 CLI flag reference 跟 custom detector YAML schema
• GitGuardian Internal Monitoring (self-hosted enterprise) 的部署架構細節
• Honeytoken 在 active deception / canary token 廣義生態的位置（屬 deception engineering、不在本頁）
• Detector pattern 的 regex / entropy 細節（屬 detection engineering）

案例回寫

GitGuardian 在 07 案例庫沒有直接 vendor-level 事件、但所有 secret leak / supply chain case 都是它的偵測對照：

下一步路由

• 上游：7.x Secrets Management at Scale、Security Workflow as Code
• 平行：GHAS Secret Scanning、Gitleaks、TruffleHog
• 下游：HashiCorp Vault（rotation 接點）、AWS Secrets Manager / Azure Key Vault
• 跨類：Splunk（Incident webhook → SIEM）、Sigstore（build provenance 覆蓋 secret scanning 抓不到的段）
• 跨模組：8 事故處理 vendor 清單（Incident → IR routing）
• 官方：GitGuardian Documentation

服務定位

Gitleaks 的核心定位是 git-aware secret scan 的 CLI 原語、不是 secret 治理平台。Rule 寫在 .gitleaks.toml、輸出走標準格式（SARIF / JSON / CSV）、跟下游 pipeline（CI、SIEM、GHAS Code Scanning）解耦。

跟 GitGuardian 比、GitGuardian 是 SaaS + dashboard + remediation workflow + validation endpoint（呼叫真實 API 驗證 secret 是否有效降 FP）+ honeytoken decoy、Gitleaks 沒有任一項 — 它只回答「這個 string 看起來像不像 secret」。GitGuardian 適合大型組織 + 預算允許 + 要跨 Slack / Jira / Notion 等 SaaS scan；Gitleaks 適合預算敏感 + 只需要 git scope + 內部已有 CI / SIEM 接 SARIF 的場景。

跟 GHAS Secret Scanning 比、GHAS 限 GitHub 平台、提供 push protection（partner pattern 在 push 前直接擋）跟 partner 自動 revoke 等深度整合、但只覆蓋 GitHub repo；Gitleaks 跨 GitHub / GitLab / Bitbucket / 自架 Gitea、CLI 跑哪都行、缺點是沒有 partner revoke 跟 push protection 要自己用 hook 接。

跟 TruffleHog OSS 比、兩者都是 OSS CLI secret scanner、TruffleHog 強在 verifier（對 200+ secret type 呼叫對應 API 驗證真偽）、Gitleaks 強在 rule TOML 表達力跟 SARIF output 成熟度。實務上很多組織兩個一起跑、用不同的 rule 覆蓋面互補。

關鍵張力：Allowlist 治理 ↔ FP 噪音 是 Gitleaks 客戶最大的長期問題。OSS 沒有 validation endpoint、entropy + path filter 一定會誤判 test fixture / mock token / sample config、allowlist 不持續 review 會膨脹成「全部都白名單」最後 rule 失效。

本章目標

讀完本頁、讀者能判斷：

1. Gitleaks 在 secret scan stack 中承擔哪一段（pre-commit / CI scan / historical audit）、哪些要外接（Vault rotate、GHAS Code Scanning 收 SARIF dashboard）
2. Custom rule 跟 allowlist 的 ownership 設計（誰寫 rule、誰核准 allowlist、定期 review 週期）
3. detect vs protect 兩個子命令的職責切分、跟 pre-commit framework / CI 整合的位置
4. 何時用 Gitleaks、何時升級到 GitGuardian / GHAS Secret Scanning 的取捨

最短判讀路徑

判斷 Gitleaks 部署是否健康、最少看四件事：

• 誰能改 .gitleaks.toml：rule 跟 allowlist 是否走 Git PR review、commit message 是否帶 allowlist 原因、是否有 owner 簽核
• detect vs protect 是否都接：CI 跑 gitleaks detect（掃 history + working tree）、pre-commit hook 跑 gitleaks protect（只掃 staged changes）— 缺 protect 等於 leak 進 history 才知道、缺 detect 等於既有 leak 永遠不發現
• SARIF 是否上傳 dashboard：CI output 是否 upload 到 GHAS Code Scanning 或內部 SIEM、不然 finding 散在 CI log 沒人看
• Allowlist 是否定期 review：allowlist entry 是否帶 expire date / reason / owner、每季是否 revisit 把過期項目刪掉、不然 allowlist 會膨脹到掩蓋真實 leak

四件事任一缺失、就是 Detection Coverage and Signal Governance 邊界的待補項目。

日常操作與決策形狀

Rule TOML / JSON：rule 結構是 id + regex pattern + 可選 entropy threshold（高熵字串通常是 secret、避開 lorem ipsum FP）+ 可選 path filter（限定 / 排除路徑）。預設 rule library 涵蓋 AWS / GCP / Azure / Stripe / Slack token 等 100+ pattern；organization 通常 先 import 預設、再加自家 token format custom rule。Custom rule 必須給 valid + invalid sample 跑 unit test、不然 regex 寫錯會大量 FP。

gitleaks detect（historical scan）：掃整個 git history + working tree、CI 跑、適合 發現既有 leak。預設掃 HEAD 到根、可用 --log-opts 限定 commit range 加速。實務上 PR scan 限定 --log-opts="--since=...$(git merge-base origin/main HEAD)" 只看本 PR 新增 commit、避免每次跑整個 history 慢死。

gitleaks protect（pre-commit）：只掃 staged changes、pre-commit hook 跑、適合 攔住未來 leak。它不掃 history、意義是 commit 前的最後一道閘；配合 pre-commit framework（pre-commit-hooks 或 pre-commit.com）的 repos: gitleaks 配置直接接入。

Report 格式（JSON / SARIF / CSV）：JSON 是 raw 結構、適合 script 處理；SARIF 是 OASIS 標準、跟 GHAS Code Scanning / 商業 SAST dashboard 共用；CSV 適合人讀 / Excel 二次處理。Production 通常 CI 輸出 SARIF + 上傳 GHAS Code Scanning、把 OSS scanner 的 finding 跟商業 SAST 同 dashboard、SOC 不用切多工具。

跟 CI 整合：GitHub Actions 用 gitleaks/gitleaks-action、GitLab CI 用 official Docker image、Jenkins 用 binary download + shell step。CI 失敗策略要決定 — block PR 還是 warn only：嚴格組織 block PR、寬鬆組織 warn + 上 SARIF 讓 SOC 自行 triage、避免初期高 FP 阻塞所有 merge。

跟 pre-commit framework 整合：.pre-commit-config.yaml 加 - repo: https://github.com/gitleaks/gitleaks 條目、pre-commit install 後每次 commit 自動跑。注意 pre-commit 只在開發者 machine 跑、繞過很簡單（git commit --no-verify）、所以一定要配 CI scan 兜底、不能只信 pre-commit。

Allowlist 治理：.gitleaks.toml 裡 [allowlist] section 寫 paths / regexes / commits / stopwords。每個 entry 應該帶 reason（# allowlist reason: test fixture for OAuth flow, expire 2026-Q4）、PR review 時要問「為什麼這個是 FP、什麼時候會過期」。Quarterly 跑 audit 把過期項目刪掉、避免 allowlist 變成「全部都白名單」。

核心取捨表

選 Gitleaks 的核心訴求：OSS + 預算敏感 + 只需要 git scope + 內部 CI / SIEM 已能消化 SARIF、且願意自己投入 rule / allowlist 治理。要跨 SaaS scan + incident workflow 升 GitGuardian、要 push protection + partner revoke 走 GHAS Secret Scanning。

進階主題

Custom rule 寫法（regex + entropy + path）：自家 internal token 通常有特定 prefix（xy_live_ / int_token_）、寫 custom rule 就是 regex = '''xy_live_[A-Za-z0-9]{32}''' + entropy = 4.0 + path = '''.*\.go$'''。Entropy threshold 越高 FP 越少但 FN 越多、實務值 3.5–4.5 之間 tune。每個 rule 一定要在 repo 加 unit test fixture（valid + invalid sample）、CI 跑 rule 自我驗證、避免 regex 寫錯後 silent break。

跟 SARIF + GHAS Code Scanning 整合補位：Gitleaks CI 跑完輸出 SARIF、用 github/codeql-action/upload-sarif 上傳到 GHAS Code Scanning。GHAS Code Scanning 不限 CodeQL 來源、任何 SARIF tool 都收。意義是 OSS scanner + GHAS dashboard 是預算友善組合 — 不買 GHAS Secret Scanning license、但 finding 集中在 Security tab 跟 SAST 共看。對應 GHAS Advanced Security 的 Code Scanning section。

跟 Vault 自動 rotation pipeline：Gitleaks 找到 leak 不是終點、是 rotation trigger。CI 把 finding 推 SOAR（或自家 webhook）、SOAR 呼叫 Vault API 對該 credential type rotate（dynamic credential 直接 revoke、static secret 換新版本）、再 broadcast 給依賴該 secret 的 service rolling restart。沒這條 pipeline、Gitleaks 只是 finding 列表沒實際治理價值。

Allowlist 治理（FP 不能無限）：OSS 沒 validation endpoint、test fixture / mock token / sample config 一定觸發 FP。allowlist 治理三原則 — 每個 entry 帶 reason + owner + expire date、PR review 必問「為什麼 FP」、quarterly audit 刪過期項目。沒這個治理 allowlist 會在 6–12 個月內膨脹到「半個 repo 都在白名單」、那時候 rule 已經沒用、refactor 成本比一開始嚴格更高。

跟 Trivy secret scan 重疊：Trivy 內建 secret scanner（用同樣的 regex pattern）、container image / filesystem 都掃。Gitleaks 跟 Trivy secret scan 在 container build pipeline 階段會重疊 — 實務分工：Gitleaks 掃 source repo（git history + working tree）、Trivy 掃 built artifact（image layer + filesystem）。兩者覆蓋不同階段、不衝突。

排錯與失敗快速判讀

• FP 太多、開發者開始忽略 Gitleaks finding：rule 沒 tune entropy threshold 或 path filter — 對 high-FP rule 加 entropy = 4.0 跟 paths = ['''!test/.*''']、staging branch 跑 1 週統計 FP 再 promote
• Pre-commit 被繞過（--no-verify）：開發者本機跑不過直接 bypass — pre-commit 不能當唯一防線、CI gitleaks detect block PR 才是真實 gate
• Historical scan 太慢、CI timeout：每次掃整個 git history — PR scan 限定 --log-opts="$(git merge-base origin/main HEAD)..HEAD" 只看本 PR commit、nightly job 才跑 full history
• SARIF 上傳失敗 / GHAS dashboard 沒 finding：github/codeql-action/upload-sarif 權限不足或 security-events: write permission 沒給 — 補 GitHub Actions permission、或改 upload 內部 SIEM
• Allowlist 膨脹、規則失效：FP 全部塞 allowlist、沒 reason 沒 expire — quarterly audit、刪過期項目、把高 FP rule 改寫成更窄的 regex 而不是 allowlist 蓋過
• 既有 leak 沒被發現、新 commit 攔得很乾淨：只接 protect 沒接 detect — CI 加 detect job、找出 history 中已 leak 的 secret 一次性 rotate（Vault 自動化）
• Custom rule 寫錯、silent skip 真 leak：rule regex 沒 unit test fixture、production 才發現 — 強制 custom rule 加 valid + invalid sample、CI 跑 rule 自驗

何時改走其他服務

不在本頁內的主題

• Gitleaks v8 跟 v7 的 rule 格式遷移細節
• Gitleaks 內部 git odb 解析跟性能 tuning（large monorepo 加速）
• Pre-commit framework 本身的安裝跟治理（屬開發者工作流、不在資安範圍）
• Rotation playbook 完整實作（屬 Vault / AWS Secrets Manager 章節）
• Secret 治理整體政策（屬 Secrets Management section 上層原則）

案例回寫

Gitleaks 在 07 案例庫沒有直接 vendor-level 事件、所有 secret leak case 都是 git history scan + rotation pipeline 的對照：

下一步路由

• 上游：7 章 Secrets Management section、Detection Coverage and Signal Governance
• 平行：GitGuardian、GHAS Secret Scanning、Trivy
• 下游：HashiCorp Vault（找到 leak 後 rotate）、AWS Secrets Manager / Google Secret Manager / Azure Key Vault
• 跨類：GHAS Code Scanning（收 SARIF dashboard）、Splunk / Elastic Security（finding 進 SIEM）
• 官方：Gitleaks GitHub、Gitleaks Documentation