服務定位

Keycloak 是 自管控制面 的 human identity 與 federation engine、不是 cloud resource permission engine。跟 Okta / Auth0 的本質差異在於信任邊界落點：SaaS IdP 把 signing key、tenant 隔離、support workflow 都託管出去、客戶承擔「供應商出事我也跟著被打」的風險；Keycloak 把整條控制面收回自家機房或自家 VPC、客戶承擔「signing key 過期 / DB 崩 / Java app CVE 沒跟上」的運維風險。

跟 cloud-native SSO（AWS IAM Identity Center）相比、Keycloak 的核心優勢是 不綁雲廠 + 可深度客製 authentication flow + 資料不出境。適合垂直：金融、政府、醫療某些不接受 SaaS IdP 的場景；以及預算敏感、員工數中等、SRE 量能足以接 24/7 on-call 的組織。

本章目標

讀完本頁、讀者能判斷：

1. Keycloak 該承擔哪一段 identity 控制（SSO / MFA / federation / brokering）、哪一段該交給雲端 IAM 或下游應用
2. 自管 IdP 的最低運維基線（HA、DB DR、cert / signing key rotation、CVE cadence、SIEM 接點）
3. Realm / Client / User Federation / Identity Broker / Authentication Flow / SPI 各自的決策時機與陷阱
4. 何時用 Keycloak、何時改走 SaaS（Okta / Auth0）或其他 OSS（Authentik / Zitadel）

最短判讀路徑

判斷 Keycloak 部署是否健康、最少看 SaaS IdP 的四件事加上自管特有的四個維度：

• 誰能做什麼：master realm admin 的人數、是否走 access request workflow、admin console 是否限 IP / device trust、是否強制 phishing-resistant 認證
• 憑證在哪裡：client secret 是否走 secret management、realm signing key 的 rotation 排程、admin token 的 TTL
• 入口如何暴露：哪些 realm 對外、reverse proxy / Ingress 是否做 rate limit、admin console（/auth/admin）是否限內網或 zero trust
• 證據是否可回查：Event Listener SPI 是否接 SIEM、admin event 跟 login event 是否分流、保留期是否符合稽核
• DB 健康：PostgreSQL / MySQL 是否跨 AZ、是否有 PITR、是否做過 restore 演練（不是只有備份成功訊息）
• Cert lifecycle：TLS cert 與 realm signing key 各自的 rotation 排程、是否走 Website Certificate Lifecycle 自動化
• HA topology：Keycloak cluster 是否多節點、Infinispan cache 是否跨 AZ、單節點重啟是否會踢掉所有 session
• Upgrade cadence：Keycloak 每年 major release、CVE patch 是否能在 SLA 內上、是否有 staging 跑 DB migration

八個維度任一缺失、都是自管 IdP 常見事故的入口。

日常操作與決策形狀

Realm 設計：Realm 是 Keycloak 的隔離邊界、每個 realm 有獨立的 user store、client、role、signing key。multi-tenancy 走 realm 是正確選擇、但 master realm 能管所有 realm、master realm 的 admin compromise = 全公司 IdP compromise。把 master realm 鎖在內網、operational realm 才對外、是基本姿勢。

Client 註冊與 secret：每個應用是一個 client、confidential client 有 secret、public client（SPA / mobile）走 PKCE 不存 secret。client secret 不存 source code、走 secret management 注入。client 數量爆炸時要設 naming convention 跟 ownership 標記、不然 stale client 會堆積。

User Federation：把既有 LDAP / Active Directory 接進 Keycloak、user 還是住在原 directory、Keycloak 做 protocol 翻譯（LDAP → OIDC / SAML）。這是 Keycloak 強項之一 — 不需要 user migration、漸進接入。陷阱是 LDAP 連線健康 = IdP 健康、LDAP 慢 = 全公司 login 慢。

Identity Brokering：把外部 IdP（Google、Microsoft、其他 SAML / OIDC provider）federate 進來、Keycloak 當中介。B2B 合作常見模式 — partner 用自己的 IdP、不在我的 user store 開帳號。決策點是 trust mapping：外部 claim 怎麼對應到內部 role、外部 IdP 的 MFA 狀態怎麼信任。

Authentication Flow：Keycloak 把 login / registration / reset password 做成可編輯的 flow DAG、可以插入自訂 step。這是 Keycloak 跟 SaaS IdP 最大差異點之一 — 想要 step-up MFA、device fingerprint、risk-based 判斷都可以自己接。雙面刃是 自訂 flow 容易留漏洞：跳過必要步驟、condition 寫錯讓 MFA 變可選、custom Authenticator SPI 沒處理 race condition。

Theme / 客製 UI：Keycloak 支援 theme override、可以改 login page HTML / CSS / JS。custom JS 在 login page = 自己注入 XSS 風險 — theme 寫進去之後就是 IdP 本體的攻擊面、不是普通網頁。CSP 跟 input sanitization 要當成 IdP 安全規範看待。

Event Listener / Audit：Keycloak 預設只把 event 寫進 DB、UI 上能查、但 不會自動推到外部 SIEM。生產環境必須接 Event Listener SPI（內建 jboss-logging、或自寫 Kafka / file listener）把 admin event 跟 login event 推進 SIEM。沒接的話 audit trail 只在 IdP 本機、IdP 出事就拿不到 evidence。

Exception / break-glass：master realm 留至少 2 個 break-glass admin、credential 離線存、走獨立 MFA（hardware key）。Keycloak cluster 整個失聯時、用 break-glass 直連 DB / 直連單一節點救回。

核心取捨表

選 Keycloak 的核心訴求：資料主權 + 預算控制 + 客製 flow 需求、且有 SRE 團隊能 24/7 on-call、能接受自管的運維重量。團隊小於 50 人沒 SRE 量能、應用主要在 SaaS（pre-built integration 用不上 Keycloak 強項）、需要快速接 7000+ SaaS app — 都該回頭看 Okta / Auth0。

進階主題

User Federation 跟 LDAP 整合：企業環境常見「Active Directory 是 user source of truth、Keycloak 做 protocol 層」。注意 LDAP 同步策略（read-only / writable / import）、LDAP 健康直接影響 IdP 可用性、LDAP timeout 要設嚴格避免 login 卡住整個 cluster。

Identity Brokering 跟外部 IdP：把 Google / Microsoft / 其他 SAML IdP federate 進來、外部 user 進來時 Keycloak 自動建 link。trust mapping 是關鍵 — 外部 IdP 宣稱「這個 user 已 MFA」、要不要信？外部 group claim 怎麼對應到內部 role？沒有預設答案、要用 authorization 邊界決定。

Fine-Grained Authorization（UMA / Authorization Services）：Keycloak 內建 policy engine、可以做 resource-level 授權（不只是 role-based）。適合需要中央化 policy decision 的場景、但會把應用的授權邏輯綁進 Keycloak、退場成本變高。多數場景應該把 authorization 留在應用內、Keycloak 只做 authentication + role token 發行。

Custom Authenticator SPI：用 Java 寫自訂 authenticator、插進 Authentication Flow。能做 step-up MFA、device posture、risk score 判斷。陷阱是 SPI 程式碼就是 IdP 本體的一部分、bug = IdP 漏洞、必須走完整 code review + 安全測試流程、不能當普通 feature 開發。

Realm signing key rotation：每個 realm 有自己的 RSA / EC signing key、用來簽 ID token / SAML assertion。rotation 必須跟下游 client 協調（key rollover 期間 client 要能接受新舊 key）、否則 rotation 當天全公司 login 失敗。分域分批是必做的、參考 Failure: Credential Rotation Without Scope。

排錯與失敗快速判讀

• DB 是 SPOF：Keycloak 所有 state 在 PostgreSQL / MySQL、DB 出事 = IdP 停 = 全公司 SSO 停。跨 AZ replication + PITR + 季度 restore 演練、不是 nice-to-have
• Cert / signing key 過期：自管 IdP 最常見事故、TLS cert 過期擋對外 endpoint、realm signing key 過期讓所有 token 變無效。走 Certificate Rotation 自動化、過期前 30 天 alert
• Cluster split-brain：Infinispan cache 跨節點同步、網路分區時 session 狀態不一致、user 看起來登入但下一個 request 又被踢出。HA topology 設計要考慮 cache mode（distributed vs replicated）、network 健康監控要 alert split-brain
• Major upgrade 卡 DB migration：每年 major release 帶 schema migration、staging 沒跑過就 production 升級 = 數小時 downtime。upgrade plan 包含 rollback DB snapshot + staging full rehearsal
• Custom theme / Authenticator 留漏洞：theme JS 引入 XSS、custom Authenticator 跳過 MFA、SPI 沒處理 race condition。把 IdP 客製當成 supply chain 看待、走 code review + 安全測試
• Event 沒進 SIEM：預設只在 Keycloak DB、IdP 出事就拿不到 evidence。Event Listener SPI 接 Kafka / file / SIEM、admin event 跟 login event 各自接 alert runbook
• Master realm admin 過多：日常工作不該用 master realm admin、應該在 operational realm 開有限權限 admin。master realm 是 single point of compromise

何時改走其他服務

不在本頁內的主題

• Keycloak 完整 SAML / OIDC 規格細節、SPI Java API 文件
• Red Hat build of Keycloak 商業支援的差異與授權細節
• Keycloak Operator（Kubernetes deployment）的逐步部署教學
• LDAP / Active Directory 各種 schema 對應規格

案例回寫

Keycloak 沒有直接的廠商級公開事件（OSS 沒有 vendor incident 的對應形態）、自管 IdP 的失效模式以下分兩類整理：跨 vendor 共通的 同構失效 用既有 case 對照、自管 IdP 特有 的失效情境補敘事說明、避免案例表變成「同一個 frame 拼四個 case slug」。

對照引用（跨 vendor 同構失效）：

自管 IdP 特有的失效情境（沒有對應公開 vendor case、來自自管運維常見事故樣態）：

• Cert 過期讓全公司 SSO 卡死：Keycloak signing cert / TLS cert / 後端 DB cert 都自己管、任何一張過期 = login 全停。Okta / Auth0 客戶不會遇到這個失效面（vendor 自己 rotate）— 自管組織必須有 cert lifecycle monitoring（Prometheus exporter + alert）+ 季度 rotate rehearsal、不能等 Let’s Encrypt / 公司 PKI 發過期通知才動
• Major upgrade 卡 DB migration 變數小時 downtime：Keycloak 每年 major release 帶 schema migration、若 staging 沒 full rehearsal 就 production 升級、可能遇到 migration 比預期慢 5-10 倍、整個維護視窗炸掉。對照 Okta / Auth0：vendor 自己升、客戶感知是 minutes-level、不是 hours-level
• Realm scope 在小規模時用法跟大規模衝突：Contrast: Identity Governance by Scale 揭示不同規模治理模式差異 — 小團隊用單一 realm 順、團隊長大後該拆 realm 卻沒拆、最後 admin compromise blast radius 變整個組織。Keycloak 比 SaaS IdP 更容易踩到、因為 realm 拆分要自己決定時機、沒 vendor 推使用者升級 tier
• DB 是 SPOF、自管沒做好 = SSO 跟 DB 一起死：Keycloak 用 PostgreSQL / MySQL 存 user / session / signing key、DB 出事 = IdP 停。跨 AZ HA + 跨 region DR + 季度 failover 演練是硬性要求、不是 nice-to-have；SaaS IdP 客戶不會遇到這個層次的失效面

下一步路由

• 上游：7.2 身分與授權邊界、7.13 偵測覆蓋率與訊號治理
• 平行：Okta vendor、Auth0 vendor、AWS IAM Identity Center
• 下游：AWS IAM / Google Cloud IAM / Azure RBAC（Keycloak 之後的 cloud resource permission 層）
• 跨模組：8 事故處理 vendor 清單（自管 IdP 事件如何 routing 進 IR 流程）
• 官方：Keycloak Documentation

服務定位

Trivy 的核心定位是 把 supply chain scan 收斂成一個 CLI。同一個 binary 處理 container image、source tree、K8s cluster live state、Terraform / Dockerfile / CloudFormation 配置、secret / license / SBOM — 不需要拼裝多個工具、不需要 SaaS account、不需要 server。跟 Snyk 商業 SaaS 的差異是 資料治理權 在自己這邊（scan 結果不上 vendor cloud）、代價是 跨 repo 集中報表 需要自己拼（用 Trivy Operator 或 Aqua Platform）。

跟 Syft + Grype 的差異是 工具邊界劃法。Anchore Syft 專做 SBOM 生成、Grype 專做 vuln scan、兩個工具靠 SBOM 標準（CycloneDX / SPDX）串接；Trivy 一個 CLI 全包、SBOM 也同樣輸出標準格式。多 vendor 並存環境（例：build pipeline 用 Syft 生 SBOM、release gate 用 Grype scan、跟 SBOM repository 互通）Syft+Grype 模組化較適合；單一團隊單一 pipeline 想 一次裝完 用 Trivy 更直接。

跟 GitHub Advanced Security 的差異是 偵測類型 + 部署面。GHAS 綁 GitHub、SAST（CodeQL）覆蓋深、但容器掃跟 IaC scan 較弱；Trivy 跨 SCM、容器跟 IaC 掃強、但沒 SAST 深度。跟 Clair（RedHat / Quay 內建）或 Anchore Enterprise 比、Trivy 用戶基數大（CNCF Sandbox）、社群更新快、整合面廣（GitLab CI / GitHub Actions / Jenkins / CircleCI 都有官方 step）。

本章目標

讀完本頁、讀者能判斷：

1. Trivy 的五種 scan target（image / fs / repo / k8s / config）各承擔哪段 supply chain 責任、什麼時候用哪個
2. Trivy DB 的更新模型（OCI artifact、6 小時 cadence、air-gapped mirror）跟 CI runner 信任邊界
3. .trivyignore 跟 severity gate 在 CI 怎麼接、exception 治理要設哪些 tripwire
4. 何時用 Trivy、何時改走 Snyk / Syft + Grype / GHAS 的取捨

最短判讀路徑

判斷 Trivy 配置是否健康、最少看四件事：

• scan target 覆蓋面：是否 image / fs / config / secret 四類都跑（不是只 scan image）、CI 是否把 dev container / base image / runtime image 全納入 — 漏掉 base image 等於信任 upstream registry
• Trivy DB 更新 cadence：CI runner 是否每次都 pull 最新 DB（OCI artifact、預設 6 小時 TTL）、air-gapped 環境是否有內部 mirror（--db-repository 指到內部 registry）、trivy --skip-db-update 是否被誤用
• severity gate 是否真的 fail build：Trivy 預設 scan 完 exit 0、CI 不會 fail；需要 --exit-code 1 --severity HIGH,CRITICAL 才會把 PR build 擋下來、否則 scan 結果只在 log、沒人看
• .trivyignore 治理：ignore 的 CVE 有 reason + expiration 嗎、quarterly review 流程在嗎、.trivyignore.yaml 有用嗎 — 沒治理的 ignore list 會無限膨脹、最後等於沒 scan

四件事任一缺失、就是 supply chain integrity 邊界的待補項目。

日常操作與決策形狀

CLI 五種 scan target：trivy image <ref> 掃 container image 的 OS package + language dependency；trivy fs <dir> 掃 source tree（含 lockfile + Dockerfile + IaC manifest + secret）；trivy repo <url> 不 clone 直接掃 git repo；trivy k8s --report summary cluster 掃 K8s cluster 內所有 workload（image + manifest 配置）；trivy config <dir> 專掃 IaC 配置（Terraform / CloudFormation / K8s YAML / Dockerfile / Helm）。本地 dev 最常用 trivy fs .、CI 最常用 trivy image $IMAGE、K8s 場景用 Trivy Operator 跑 in-cluster scan。

Trivy DB（OCI artifact）：Trivy 自己維護 vulnerability DB、以 OCI artifact 形式存在 ghcr.io/aquasecurity/trivy-db、每 6 小時更新一次。CI runner 第一次 scan 自動 pull、後續用 cache。air-gapped 環境（金融 / 政府 / 工控）需要把 DB mirror 到內部 OCI registry、--db-repository internal.registry/trivy-db 指過去。DB 內容是 aggregated source — NVD、GHSA、各 Linux distro security advisory、language ecosystem advisory（npm / PyPI / Maven / RubyGems / crates.io / Go / etc.）合在一起、所以單一查詢就能跨多生態。

.trivyignore 跟 .trivyignore.yaml：scan 發現的 CVE 若已評估無風險（無 reachable code path、已有 mitigation、upstream 尚未 patch 但業務不受影響）寫進 .trivyignore（純 CVE-ID list）或 .trivyignore.yaml（含 expired_at + comment + paths、更適合治理）。後者強制每筆 ignore 有 expiration（建議 quarterly）跟 reason、過期自動失效、避免 ignore list 變成「忘了清的死帳」。CI 應該每季跑 trivy --ignorefile .trivyignore.yaml 同時 alert 即將過期的條目。

Severity gate 是 CI 必設：Trivy 預設 scan 完 print 結果但 exit 0、CI build 不會 fail。要在 CI 真正擋下高風險 PR、必須 trivy image --exit-code 1 --severity HIGH,CRITICAL $IMAGE。Severity 級別（UNKNOWN / LOW / MEDIUM / HIGH / CRITICAL）對應 CVSS score、團隊需要決定 什麼 severity 算 release blocker。常見 baseline：CRITICAL fail PR build、HIGH fail nightly build（給 24 小時修補窗口）、MEDIUM 進 backlog ticket。

SBOM 生成與 scan：trivy image --format cyclonedx --output sbom.json $IMAGE 生 CycloneDX 格式 SBOM、--format spdx-json 生 SPDX。也可以反向 — 拿別人生的 SBOM 餵給 Trivy：trivy sbom sbom.json 跑 vuln scan、不重新解析 image。這個 workflow 跟 Syft + Grype 重疊（Syft 生 SBOM + Grype scan SBOM）、差別是 Trivy 一站完成、Syft+Grype 拆兩階段更模組化。SBOM artifact 進 OCI registry（用 cosign attach）或 SBOM repository（如 Dependency-Track）做長期追蹤。

Misconfig + Secret + License 一起 scan：trivy fs . 預設啟用四類 scanner — vuln（package CVE）、misconfig（IaC 配置錯誤）、secret（hardcoded credential）、license（license compliance）。Misconfig 內建 hundreds of built-in policy（Rego 寫的）涵蓋 K8s / Terraform / Docker / CloudFormation 常見錯誤（privileged container / open S3 bucket / 0.0.0.0/0 ingress）。Secret scanner 用 regex pattern 找 AWS access key / GCP service account / Stripe key 等常見格式、不是萬能、但 dev pre-commit 攔截已洩漏 secret 很實用。

Trivy Operator（K8s in-cluster scanner）：K8s 場景的標準配置。Operator 在 cluster 跑、定期 scan 所有 namespace 的 workload、產 CRD reports：VulnerabilityReport（image CVE）、ConfigAuditReport（manifest 配置）、SbomReport、ClusterComplianceReport（CIS Kubernetes Benchmark / NSA Kubernetes Hardening Guide）。Operator 可選配 ValidatingAdmissionWebhook、admission 階段拒絕高風險 image（CVE severity 超門檻）。Reports 是 CRD、可以走 kubectl get vulnerabilityreport 看、也可以 prometheus exporter 出 metric 進 Grafana。

Aqua Platform 整合：Trivy CLI / Operator 結果可以推到 Aqua Platform（商業版）做集中 dashboard、跨 cluster RBAC、policy engine、compliance report、runtime defense（runtime container 監控）。純 CLI 用戶不需要、但企業有多 cluster + 跨團隊 governance 需求時、Aqua Platform 補 server-side aggregation 那塊（對應 Snyk dashboard 的功能）。

核心取捨表

選 Trivy 的核心訴求：零 server / OSS-only 預算 / air-gapped 友善 / 一個 CLI 涵蓋 container + IaC + secret。需要跨 SCM 集中 dashboard 跟 reachability 走 Snyk；純 SBOM workflow + 多工具互通走 Syft+Grype；GitHub-only + 重 SAST 走 GHAS。

進階主題

Trivy Operator + admission control：Operator 跑 ValidatingAdmissionWebhook、admission 階段對 Pod spec 的 image 跑 vuln check、超門檻就拒絕創建。對應 supply chain integrity 的 artifact gate at deploy time。組態要小心 — webhook timeout / Trivy DB 不可用 / Operator 自己 down 都會擋住 deploy、production 通常 fail-open（DB 不可用時放行 + alert）而非 fail-close。

Custom check（Rego policy）：Trivy misconfig scanner 用 Rego 寫 policy、可以自己加 custom check（例：禁止特定 namespace 用 hostPath volume、禁止特定 IAM action）。policy 走 --policy ./custom-policies/ 載入、跟內建 policy 一起跑。比 OPA Gatekeeper 簡單（不需要部署 admission webhook、scan-time 就執行）、但 runtime enforcement 還是要靠 Gatekeeper / Kyverno。

Air-gapped DB sync：金融 / 政府 / 工控環境 CI runner 不能連外網。流程是：有對外網的 staging machine 跑 trivy --download-db-only 把 OCI artifact 拉下來、用 skopeo copy 推到內部 OCI registry、CI runner 用 --db-repository internal.registry/trivy-db --skip-db-update（或排程從內部 mirror pull）。DB 更新節奏要排程化（每天 / 每 6 小時）、否則 air-gapped DB 落後幾天會 miss 掉新公布 CVE。

Cosign + SLSA + Trivy 三件事：Trivy 看的是 known CVE、看不到 build-time backdoor。配套需要 Sigstore cosign 做 image signature verify（確認 image 真的是自家 CI 出的）+ SLSA provenance（build pipeline 不可篡改紀錄）+ Trivy scan（known CVE）三件事一起、才是完整 supply chain trust chain。對應 Cert-manager 在 TLS 的角色、Trivy 在 supply chain 的角色是 已知漏洞檢測、不是 trust establishment。

排錯與失敗快速判讀

• CI 顯示 scan 完但 build 沒 fail：忘了 --exit-code 1 --severity HIGH,CRITICAL、scan 結果只在 log、PR 一直 merge 進高風險 image — 補 severity gate flag、設 baseline
• Trivy DB 拉不下來 / 過期：CI runner 沒對外網 / GitHub Container Registry 被擋 / DB cache 太舊 — 設內部 OCI mirror、CI runner --db-repository 指過去、排程 update
• .trivyignore 無限膨脹：用純 list 沒 expiration、團隊找不到誰加的 / 為什麼加 — 改 .trivyignore.yaml 強制 reason + expiration、quarterly review 排進 sprint
• false positive 多到 alert fatigue：base image 自帶大量未修補 OS package、scan 出 50+ HIGH — 換 distroless / Chainguard / Wolfi 等 minimal base image、或 multi-stage build 只保留必要 binary、不是調高門檻當沒看到
• secret scanner 漏報：hardcoded credential 是非標準格式（內部 token、特殊 vendor key）— 加 custom secret pattern、或配合 dedicated tool（Gitleaks / GitGuardian）做第二道
• Trivy Operator 報表沒人看：reports 是 CRD、kubectl get 才看到、PR / Slack 沒通知 — 接 prometheus exporter + Grafana alert、或 webhook 推 Slack
• K8s admission webhook fail 擋住 deploy：Operator down / DB 不可用、所有 Pod 創建被拒 — webhook 配 failurePolicy: Ignore、production 通常 fail-open + alert、不是 fail-close

何時改走其他服務

不在本頁內的主題

• Trivy CLI 所有 flag 跟 output format 完整 reference
• Rego policy language 完整語法（OPA / Rego 自有體系）
• Aqua Platform 商業版完整功能矩陣（dashboard / RBAC / runtime defense）
• 各 PCI DSS / SOC 2 / FedRAMP 合規 mapping
• 跟其他 scanner（Clair / Anchore Enterprise / Twistlock）的逐項比較

案例回寫

Trivy 在 07 案例庫沒有 直接 vendor-level 事件（Trivy 本身 OSS、無 vendor-side 控制面風險）、但 supply chain 案例都對應 Trivy 的能力與邊界：

下一步路由

• 上游：7.12 供應鏈完整性與 Artifact 信任
• 平行：Snyk、Syft + Grype、GitHub Advanced Security、Dependabot
• 下游：7.3 入口治理與伺服器防護（image 漏洞最終影響的是 origin server 風險面）
• 跨類：cert-manager（TLS lifecycle）、HashiCorp Vault（secret rotation 對應 Trivy secret scan 找到的 hardcoded credential）
• 跨模組：8 事故處理 vendor 清單（CVE 緊急 response 流程 / 高風險 image rollback）
• 官方：Trivy Documentation、Trivy Operator

服務定位

Syft + Grype 的核心定位是 SBOM-first 的 OSS supply chain scan tool chain。SBOM 不是中間產物、是 正式可簽章 artifact：Syft 產 SBOM 後通常用 Sigstore cosign attest --predicate sbom.cdx.json 把 SBOM 簽進 image OCI metadata、跟 image 一起發布；下游團隊 / 客戶 / scan pipeline 拿 trusted SBOM 跑 Grype、不需要重新 scan image。對 air-gapped 環境、multi-team handoff、合規場景（EO 14028 / FedRAMP 要求交付 CycloneDX 或 SPDX）特別合適。

跟 Trivy 的差異是 分工 vs 全包：Trivy 一個 binary 把 SBOM 生成 + vuln scan + IaC + secret + license 都做了；Syft + Grype 拆兩個工具、SBOM 互通流程適合、團隊偏好 Unix philosophy 選這條。功能覆蓋面 Trivy 略廣（含 IaC / secret scan）、Syft 的 SBOM 格式互通性是 OSS reference implementation。跟 Snyk 的差異更直接：Snyk 商業 SaaS、覆蓋廣（SAST / IaC / CSPM / Reachability）、有 dashboard 跟 fix PR；Syft + Grype 純 CLI、OSS 免費、聚焦 SBOM + vuln 兩件事、沒 server / 沒 dashboard、要 dashboard 走商業 Anchore Enterprise 或自接 JSON 到 Elasticsearch / Grafana。

關鍵 first-class concept：Source（OCI image / OCI archive / Docker daemon / dir / file / 既有 SBOM）、Catalog（Syft 內部 package inventory 結構）、Package、Vulnerability、Match（Grype 的 package ↔ CVE 配對）、Match Configuration（grype.yaml 設 severity gate / 比對策略）、Vulnerability DB（Grype-DB、Anchore 聚合 NVD + GHSA + 各 distro secdb）、Ignore Rule（CVE 例外、強制帶 expiration）。

本章目標

讀完本頁、讀者能判斷：

1. Syft 跟 Grype 各自的責任邊界、為什麼拆兩個工具比合一個工具好（SBOM 互通、attestation、air-gapped）
2. SBOM 格式（CycloneDX / SPDX / SyftJSON）的選擇、跟合規要求對應
3. Grype Match Configuration 跟 Ignore Rule 怎麼設、CI fail 條件怎麼定
4. 何時改走 Trivy 全包式、何時走 Snyk 商業 SaaS

最短判讀路徑

判斷 Syft + Grype 配置是否健康、最少看四件事：

• SBOM 格式跟保存：產出格式是否符合合規（多數 EO 14028 / FedRAMP 場景要 CycloneDX 或 SPDX、不是 SyftJSON）、SBOM 是否簽章（cosign attest）、是否集中保存（OCI registry 旁邊 / artifact store）、是否有 baseline diff（image 升級前後依賴變化）
• Grype DB 更新：DB 是否每日同步、air-gapped 場景是否 mirror 到內部 registry（Grype DB 是 OCI artifact、可 oras pull 鏡像）、DB version 是否進 SBOM scan record（重現性）
• Match Configuration：grype.yaml 的 severity gate（CI fail 條件、通常 high / critical fail）、only-fixed: true 是否開（只報有 patch 的 CVE）、add-cpes-if-none: true 對 binary-only package 行為
• Ignore Rule 治理：例外清單是否帶 expiration、reason 欄位是否填 ticket / decision 連結、quarterly review 機制、過期自動回到 fail 狀態

四件事任一缺失、就是 Supply Chain Integrity 邊界的待補項目。

日常操作與決策形狀

Syft 用法跟 Source 種類：syft <source> -o <format> 是核心 — source 可以是 OCI image（registry/image:tag）、OCI archive（oci-archive:image.tar）、Docker daemon（docker:image:tag）、目錄（dir:./）、單一檔案、甚至既有 SBOM（sbom:./prev.cdx.json、用來 轉格式）。format 包括 cyclonedx-json / cyclonedx-xml / spdx-json / spdx-tag-value / syft-json / table。production 通常產 cyclonedx-json（合規要求最常見）+ 保留 syft-json（Syft 自家最完整、未來 round-trip 用）。

Package detector 廣度：Syft 自動偵測 OS package（apk / dpkg / rpm）+ 語言 dependency（npm / pip / gem / go module / cargo / maven / gradle / nuget / composer / hex / conan / swift / dart 等）+ binary analysis（Go binary 內 embedded module、Rust binary metadata、Java jar / war / ear nested）。對 static binary / FAT image 的支援是 Syft 的強項、比多數 SBOM tool 廣。但 runtime-only dependency（dlopen / dynamic load）SBOM 看不到、要靠 runtime workload protection（Falco / Cilium Tetragon 類工具、見 7 後續候選 vendor 清單）補。

Grype 用法：grype <source> 或 grype sbom:./image.cdx.json。輸出 table / json / cyclonedx-json（CycloneDX VEX 格式）/ sarif（GitHub code scanning）/ template（Go template 自訂）。production CI 通常 --output sarif 上傳 GitHub code scanning + --output json 進內部 SIEM。grype sbom:./prev.cdx.json 模式是 SBOM-only scan、不碰 image — 適合 下游團隊拿 SBOM 持續 monitor、原始 image 已經 frozen 或不可達。

Match Configuration（grype.yaml）：核心欄位包括 fail-on-severity: high（CI gate）、only-fixed: true（只回報有 fix 可用的 CVE、避免 noise）、ignore list（個別 CVE 例外）、match strategy（如何把 package CPE / PURL 對應到 CVE、預設策略對 90% 場景夠用、特殊 binary 場景才調）。所有設定走版控、grype.yaml 跟程式碼一起 review、避免 console 改。

Ignore Rule 治理：grype.yaml 的 ignore entry 結構：vulnerability + reason + expiration（YYYY-MM-DD）+ optional package.name / fix-state。Anchore 設計 沒有「永久 ignore」、必須帶 expiration — 強制 quarterly review、避免「五年前 ignore 的 CVE 早被 fix 了還在清單裡」。reason 欄位填 ticket 編號或 ADR link、給未來的人 context。

Cosign attest SBOM：syft image:tag -o cyclonedx-json > sbom.cdx.json && cosign attest --predicate sbom.cdx.json --type cyclonedx --key cosign.key image:tag — SBOM 被簽進 image 的 OCI signature manifest、下游 cosign verify-attestation --type cyclonedx ... 拿到 cryptographically signed SBOM。這把 SBOM 從「可被竄改的 JSON 檔」升級到 trusted artifact、是 SLSA L3+ provenance 的基礎。

SLSA / SPDX 流程整合：Syft SBOM 是 build 階段產物、跟 SLSA provenance（誰 build 的、用什麼 builder、source commit 是什麼）併存、不互斥 — SBOM 答「裡面有什麼」、provenance 答「怎麼 build 的」。完整 supply chain trust 需要兩者 + cosign signature。

核心取捨表

選 Syft + Grype 的核心訴求：要正式 SBOM 作為交付 artifact（合規 / 多 team handoff）+ 偏好 OSS Unix philosophy（兩個工具各做一件事、容易整合自家 pipeline）+ 不需要 SaaS dashboard（自家 SIEM / Grafana 已經有）。需要 IaC scan 一起做、看一下 Trivy 是不是更省整合成本；需要 fix workflow 跟 reachability、商業預算足、走 Snyk。

進階主題

SBOM attestation 完整鏈：build pipeline 順序通常是 — build image → syft image -o cyclonedx-json > sbom.cdx.json → cosign sign image → cosign attest --predicate sbom.cdx.json --type cyclonedx image → push。下游 admission controller（Kyverno / Gatekeeper / Sigstore policy-controller）verify-attestation 拿 trusted SBOM、再 Grype scan、policy 決定是否允許 deploy。這條鏈把 SBOM 從 文件 升級成 deploy gate。

Grype DB air-gapped sync：Grype DB 是 OCI artifact（ghcr.io/anchore/grype/listing.json + db.tar.gz）、oras pull 或 grype db update 取得。air-gapped 場景：DMZ 跑 grype db update --skip-listing-content-check、把 ~/.cache/grype/db/ 整個 sync 到內部 mirror registry、內部 grype 透過 GRYPE_DB_UPDATE_URL 指到內部 listing。DB 版本進 scan record、確保 相同 SBOM + 相同 DB = 相同結果（可重現）。

Custom matcher / Ignore Rule 細部：Grype 預設 matcher 對 90% 場景夠、但 Go binary、static-linked binary、custom C++ build 可能需要 add-cpes-if-none: true 強制配對 CPE。Ignore Rule 支援 vex-status 欄位（accepted / under-investigation / fixed / not-affected）對齊 CycloneDX VEX 標準、輸出 VEX-enriched SBOM 給下游 / 客戶。

Anchore Enterprise 商業整合：OSS Syft + Grype 不夠時、Anchore Enterprise 加：policy engine（GraphQL 寫複雜 policy）、dashboard、RBAC、SLA-backed support、跟 Kubernetes admission integration、跟 Jira / ServiceNow ticket 自動建單。OSS 是 90% 場景的起點、Enterprise 解的是 policy + workflow 而非 scan ability。

SBOM diff（baseline 比對）：syft 自己沒內建 diff、但 cyclonedx-cli diff 或自家 script 可以比對 image v1 SBOM vs image v2 SBOM、找出新增 / 移除 / 升級的 package。用途：XZ backdoor 之類「相同 version 但被植入後門」事件、單靠 SBOM 看不出來、但 baseline + behavior anomaly 雙軌可以提早警示。

排錯與失敗快速判讀

• Syft scan 找不到 package：image 是 FROM scratch 或 distroless、Syft 偵測不到 OS package metadata — 改 scan source 為 build 階段的 dir:./ 或保留 builder image 的 SBOM
• Grype 報一堆 unfixed CVE：base image 老、有 CVE 但 upstream 還沒 patch — 設 only-fixed: true 過濾 noise、focus 在 actionable item；同時排程 base image 升級
• CI 突然 fail 變多：Grype DB 更新後新 CVE 揭露 — 看 DB version diff、評估是 真新風險 還是 舊 package 被重新分類、必要時用 Ignore Rule + expiration 過渡
• SBOM 格式下游不認：合規要求 SPDX、產的是 SyftJSON — 用 syft convert syft-json:./sbom.json -o spdx-json 轉格式（Syft 本身就是 SBOM 互轉工具）
• Air-gapped 環境 Grype 跑不動：DB 沒同步、scan 直接報 0 vulnerability（假陰性）— grype db status 看 DB age、mirror sync 機制檢查、加 staleness alarm
• Ignore Rule 過期回到 fail：CI 突然 fail、查 expiration 已過 — 預期行為、強制 quarterly review；補 rotation 機制（cronjob 提前一週 alert owner）
• Binary 偵測不到 module：Go binary stripped、-trimpath 後 module path 沒了 — build 改加 -buildvcs=true 保留 VCS info、或 build 階段 SBOM scan source code、不是 binary
• cosign verify-attestation 失敗：image 被 re-tag / re-push 後 attestation manifest 不對 — 用 image digest（@sha256:...）而非 tag 做 attest、tag 不可信
• Grype 不抓某個 ecosystem：例如新冒出的 package manager — Syft 沒實作 detector、Grype 也看不到；submit issue 或自己寫 catalogger 貢獻

何時改走其他服務

不在本頁內的主題

• CycloneDX / SPDX 完整 schema 規格逐欄位解讀
• Sigstore cosign / Rekor / Fulcio 完整架構（attest 鏈的 OIDC / transparency log）
• SLSA framework 各 level 對應的 builder 要求
• Anchore Enterprise policy DSL 完整語法
• VEX（Vulnerability Exploitability eXchange）跟 CSAF 標準對照細節

案例回寫

07 案例庫沒有直接 Syft / Grype-level 事件、但供應鏈案例都是 SBOM-first 思維的對照：

下一步路由

• 上游：7.12 供應鏈完整性與 Artifact 信任
• 平行：Trivy（一站式替代）、Snyk（商業 SaaS）、GitHub Advanced Security（GitHub 內建）
• 下游：Sigstore cosign（SBOM attestation）、admission policy（Kyverno / OPA Gatekeeper、見 7 後續候選 vendor 清單）
• 跨類：runtime workload protection（Falco / Cilium Tetragon、見 7 後續候選 vendor 清單）、HashiCorp Vault（cosign signing key 保存）
• 跨模組：8 事故處理 vendor 清單（新 CVE 揭露時的 SBOM-based fan-out 查詢）
• 官方：Syft Documentation / Grype Documentation

服務定位

OPA 的核心抽象是 decoupled decision + enforcement — OPA 只負責 decide（input 進來、allow / deny + decision metadata 出去）、application 負責 enforce（拿到 decision 後實際 reject request / block deploy / mask data）。這個解耦讓同一份 policy 跨 K8s admission（透過 Gatekeeper 或 kube-mgmt sidecar）、Envoy authz filter、API gateway、Terraform pre-plan、SQL row-level filter、Kafka topic ACL 都能重用。

OPA 的查詢語言是 Rego、Datalog-like declarative language、設計上適合表達「給定一組 fact，這個動作合法嗎」。Rego 跟一般 imperative programming（Python / Go / YAML rules）差距大、team 要投入 1-2 週才能寫出 production-grade policy；換回的是 表達力 + 跨情境一致性 — Kyverno 的 YAML policy 易上手、但跨 K8s 邊界後沒辦法用。

關鍵張力：Rego 學習曲線 ↔ unified policy 的長期價值。只跑 K8s 的團隊用 Kyverno YAML 更直覺；只跑 CI policy 的用 Conftest 更輕；要在 K8s + API + Terraform + DB 跨層統一 policy、或要 audit-grade decision log、或預期 policy 會長期累積成資產的、才值得投資 OPA + Rego。

商業模型：核心 OPA 是 Apache 2.0 OSS、免費。Styra DAS（OPA 創辦人公司）是 enterprise SKU、提供 policy library + impact analysis + multi-cluster management + audit dashboard、適合大型團隊。OPAL（Permit.io 維護的 OSS）是 GitOps-style policy distribution layer、補 OSS OPA 缺的 bundle server。

本章目標

讀完本頁、讀者能判斷：

1. OPA 在 policy stack 中承擔哪一段（decision engine） vs enforcement point 各自的 ownership
2. Rego 投資門檻是否值得（K8s-only vs 跨 enforcement point）
3. Policy bundle / Decision log / Partial evaluation 三個 first-class concept 在 production 的設計形狀
4. 何時用 OPA、何時走 Kyverno / Gatekeeper / Conftest 的取捨

最短判讀路徑

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

• Policy ownership：誰能寫 / 改 Rego policy（platform team / security team / SRE）、policy 是否進 Git、change 是否經 PR review + staging tenant 跑 24-48hr 觀察
• Bundle distribution：policy 是否 build 成 bundle（tar.gz）、是否簽章、OPA agent 是否定期 pull、bundle server 在哪（自管 nginx / S3 / OPAL / Styra DAS）
• Decision log governance：每個 decision 是否進 audit log（input + output + policy version + timestamp）、log 是否進 SIEM（Splunk / Elastic）、retention 多久
• Enforcement coverage：哪些 enforcement point 接 OPA（K8s admission / API / Envoy / Terraform）、policy 是否 share 還是各 point 各寫一份、跨 point 的一致性怎麼驗

四件事任一缺失、就是 Policy as Code Foundations 的待補項目。

日常操作與決策形狀

Rego policy 形狀：Rego 是 Datalog-like declarative language、policy 寫成 allow { ... } rule、所有條件成立才 evaluate 為 true。實務 idiom：底層寫 base policy（如 policies/k8s/required_labels.rego）、上層寫 policy library（共用 helper 如 policies/lib/registry.rego）、application 端傳 input（K8s admission request / API request / Terraform plan JSON）查詢。Rego 鼓勵 small composable rule、不寫長 imperative function。

Policy bundle：OPA 不從 Git 直接讀 policy、而是讀 bundle（tar.gz、含 .rego + data JSON、optional 簽章）。Bundle 從 bundle server pull（自管 nginx / S3 / OPAL / Styra DAS）、OPA agent 定期 polling（預設 60s）。Bundle 的核心價值是 versioned + signed + atomically swap — policy 更新不會 partial apply、簽章確保中間沒被改、版本 metadata 讓 decision log 可追到當時用哪版 policy。

Decision log：每個 OPA query 都可開 decision logging、log entry 含 input + result + policy_version + timestamp + decision_id。意義是 audit-grade reconstruction — 事後可以重跑 opa eval --bundle <version> --input <log_input> 驗證當時 decision 是否正確。Decision log 進 SIEM 後可做 over-permission analysis（哪些 user 拿到 allow 但實際從不該被 allow）跟 policy coverage check（哪些 rule 從沒被觸發過、可能是 dead code）。

Integration pattern：production OPA 主要四種 enforcement integration — K8s admission（走 Gatekeeper 是 OPA 官方 K8s integration、或 kube-mgmt 把 OPA 當 sidecar 跑、admission webhook 把 request 送進 OPA decide）；API authz（application 在 request handler 開頭 query OPA、拿 allow/deny 後 enforce）；Envoy / service mesh（Envoy 的 ext_authz filter 接 OPA、L7 authz decision）；Infrastructure as Code（CI 跑 Conftest 對 Terraform plan / K8s YAML 做 OPA 評估）。

Partial evaluation：OPA 進階 feature、把一份 policy 對某個 partial input（如 user="alice"）pre-evaluate、產出 殘餘 query（如 SQL WHERE tenant_id IN (...) 或 regex），下發給 enforcement point 直接用。意義是 把 policy decision 推到 enforcement point 內部、減少每次 query 都要過 OPA 的 latency；常用於 row-level data filter（policy 寫一次、partial eval 出 SQL WHERE clause、application 直接拼進 query）。

OPAL（GitOps for OPA）：OSS、Permit.io 維護、解決「policy 從 Git push 到所有 OPA agent」的 distribution 問題。Git → OPAL Server → OPA Agent 的 push model、policy commit 到 main branch 後幾秒內所有 OPA 更新。對應 OSS-only 的 production setup；Styra DAS 提供同等功能 + 管理 UI。

Styra DAS（商業 management）：Styra 是 OPA 創辦人公司、DAS 是 enterprise SKU。核心價值：policy library（pre-built policy for K8s / Terraform / Kafka）、impact analysis（policy 上 production 前 dry-run 看會 deny 多少現有 resource）、multi-cluster policy distribution、audit dashboard。OSS-only 自己拼 OPAL + decision log + SIEM 也能做、但團隊 > 50 個 cluster / 多 BU 時 DAS 划算。

Constraint Framework：Gatekeeper 在 OPA 之上加的 K8s-specific 抽象、用 ConstraintTemplate（Rego policy 模板）+ Constraint（K8s CRD instance、實際 enforce）。對純 K8s 場景比直接寫 Rego 更 K8s-native；但這個抽象只在 K8s 領域有意義、不會跨到 API / Terraform。

核心取捨表

選 OPA 的核心訴求：跨 enforcement point 的 unified policy + long-term policy 資產化 + audit-grade decision log + 團隊願意投資 Rego。純 K8s + 想快速上手用 Kyverno；K8s + 已決定走 OPA 生態用 Gatekeeper；只跑 CI 不跑 runtime 用 Conftest。

進階主題

Rego idioms（policy library + base policy）：production Rego 走分層結構 — lib/（utility function、registry whitelist、CIDR check）、base/（concrete policy、引用 lib）、tests/（用 opa test 跑 unit test）。Policy 也是 code、走 PR review + CI test + staging tenant、不是 console 直改。

Partial evaluation for SQL row-level filter：把 policy 寫成「user 能看哪些 row」、用 opa eval --partial 把 user="alice" 部分 pre-evaluate、output 殘餘 query 變 SQL WHERE tenant_id IN ('a', 'b', 'c')、application 拼進 query。意義是 policy 不在 query path latency 上、policy 規則仍是 SSoT。對應 RLS（row-level security）的工程化作法。

跟 SPIRE workload identity 整合 authz：service-to-service authz 場景、SPIRE 簽 SVID（SPIFFE ID + mTLS cert）證明 caller 身份、OPA 拿到 SPIFFE ID 後 decide「這個 service 能呼叫這個 API 嗎」。SPIRE 解 who、OPA 解 can they do this、職責清楚分離。

跟 Vault 整合 dynamic credential policy：Vault 簽 dynamic credential（DB password / cloud STS token）的 issue 決定可以走 OPA — Vault 收到 issue request、轉 OPA decide「這個 caller 在這個 context 能不能拿這個 scope 的 token」。對應 Failure: Credential Rotation Without Scope 的 lesson：scope 判斷不分散在應用層、集中到 policy engine。

Decision log 進 SIEM：OPA decision log 設成 push 到 Splunk HEC / Elastic / Datadog、進 SIEM 後可做三件事 — over-permission analysis（哪些 allow 從沒被合法理由觸發）、dead policy detection（哪些 rule 從沒被 evaluate）、anomalous decision pattern（某 service 突然大量 allow 不在 baseline）。

跟 K8s admission 的兩條路：純 K8s admission 場景、走 Gatekeeper（OPA 官方 K8s integration、有 Constraint Framework 抽象、社群活躍）比直接跑 OPA + kube-mgmt sidecar 更 production-ready。kube-mgmt 路線適合 already-running OPA 想加 K8s admission 而不引入 Gatekeeper 抽象。

排錯與失敗快速判讀

• Rego policy review 卡 SRE：policy 都得 SRE 寫、security team 看不懂 — 拆 lib/ 給 SRE 維護、base/ 給 security review、用 opa test unit test 保持迭代速度
• Bundle distribution 慢 / policy 不一致：自管 nginx bundle server 沒高可用、agent pull 失敗 fallback 用舊版 — 換 OPAL push model 或 S3 + CloudFront、bundle pull 失敗時 OPA --set status.console=true 直接 alert
• Decision log 沒進 SIEM：OPA 開了 decision log 但只進本地 file、沒人看 — 設 decision log plugin push 到 Splunk HEC / Kafka、不是寫本地 disk
• Policy 改完 production 大量 deny：新 policy 沒在 staging dry-run、上 production 後合法 traffic 被擋 — Styra DAS 的 impact analysis 或自己跑 opa eval --partial 對歷史 decision log replay、看 deny 數量再 promote
• OPA latency 高 / API 卡：每個 request 都 round-trip OPA、policy 複雜 evaluation 慢 — embed OPA as library（Go SDK / WASM）跑 in-process、或用 partial evaluation 把 policy compile 進 SQL / regex
• Rego policy bug 線上才發現：沒 unit test、staging 沒 cover edge case — 強制 PR 要含 opa test case、staging 跑 shadow mode（log only 不 enforce）24hr 再切 enforce
• 跨 cluster policy drift：多 cluster 各自 apply、版本不同步 — OPAL 或 Styra DAS multi-cluster sync、不靠 kubectl apply 人工同步

何時改走其他服務

不在本頁內的主題

• Rego 完整語法 reference（rule / function / built-in / with / some）
• Gatekeeper Constraint Framework 的 ConstraintTemplate / Constraint CRD 設計細節（屬 Gatekeeper 頁）
• Conftest CLI 用法跟 conftest test / conftest verify 流程（屬 Conftest 頁）
• Kyverno YAML policy 語法跟 mutate / generate / verifyImages（屬 Kyverno 頁）
• Styra DAS 商業 license / SKU 對照、Nirmata Enterprise 對照
• WASM-compiled Rego policy 的 edge deployment 細節

案例回寫

下一步路由

• 上游：7 章 policy-as-code foundations、7.12 供應鏈完整性
• 平行（Policy-as-Code 批次）：Conftest（CI static check）、Kyverno（K8s YAML-native）、Gatekeeper（OPA K8s integration）
• 跨類：SPIRE（workload identity → OPA authz）、Vault（dynamic credential policy）、Trivy（scan → OPA gate）、Splunk（decision log → SIEM）
• 跨模組：6 reliability（CI pre-deploy gate 接 Conftest）、8 incident response（policy violation alert → IR routing）
• 官方：Open Policy Agent、Rego Policy Language、Styra DAS、OPAL

服務定位

Conftest 是 OPA 生態中 最輕量的 CI-time tool — 拿一份 Rego policy + 一份 config file、跑 conftest test 就出 violation report。它不需要 cluster、不需要 daemon、不接 admission webhook、只是個 binary。跟 OPA 比、OPA 是 runtime decision engine（HTTP server / library / sidecar 提供 policy decision）、Conftest 只是 CLI 跑 once、結束即關。跟 Gatekeeper 比、Gatekeeper 是 K8s admission controller runtime、會在 kubectl apply 時攔下違規；Conftest 是在 PR 階段就攔下、deploy 前就 fail CI。跟 Kyverno 比、Kyverno 是 K8s-only 的 admission policy（YAML 語法）、Conftest 跨多 config format（不只 K8s）且用 Rego。跟 Trivy Config 比、Trivy Config 是 built-in misconfig rule（開箱即用、預定義常見 anti-pattern）、Conftest 是 自己寫 Rego policy（客製化彈性大但要寫 rule）。

關鍵張力：CI-time static check ↔ runtime admission enforcement 是兩種互補機制、不是替代。CI 抓在 deploy 之前、但 manifest 不一定都走 PR（kubectl apply 直接打 cluster 就漏接）；admission 抓 runtime 寫入、但 deploy 後才 fail 已經慢。production 通常 CI（Conftest / Trivy Config）+ admission（Gatekeeper / Kyverno）雙層覆蓋。

本章目標

讀完本頁、讀者能判斷：

1. Conftest 在 policy-as-code stack 中承擔哪一段（CI gate）、跟 admission runtime 怎麼分工
2. Rego policy directory / conftest test / conftest verify / Bundle / Combine flag 的 ownership 跟工程化做法
3. Conftest vs Trivy Config vs Checkov vs OPA + custom CI wrapper 的取捨
4. 何時用 Conftest、何時走 Trivy Config（不想學 Rego）或 Gatekeeper（runtime enforcement）

最短判讀路徑

判斷 Conftest 導入是否健康、最少看四件事：

• Policy directory 走版控：Rego files（policy/*.rego）跟 application code 同 repo、或抽到中央 policy repo + Bundle 拉取、PR review 才能改 policy
• conftest verify 是否跑：Rego policy 本身有單元測試（*_test.rego）、policy 改動有 test coverage、不是寫完就上 production CI
• CI integration 點：跑在 PR check / merge gate、fail 阻斷 merge、不是只跑 warning 沒人看
• 跟 admission 是否雙層：CI fail 之外、cluster 也裝 Gatekeeper / Kyverno 接 runtime；否則 kubectl apply 繞過 CI 就破口

四件事任一缺失、就是 Supply Chain Integrity 邊界的待補項目。

日常操作與決策形狀

Policy directory（Rego files）：Conftest 預設讀 ./policy/ 目錄下所有 *.rego 檔。Policy 用 deny[msg] / warn[msg] / violation[msg] rule 表達 — deny 失敗整個 test、warn 只 print 不 fail、violation 給結構化輸出（含 metadata 給後續 SOAR 處理）。慣例是一個 policy 檔對一個 anti-pattern（policy/k8s_privileged.rego / policy/terraform_public_s3.rego）、不混寫。

conftest test command：conftest test deployment.yaml / conftest test --policy ./custom-policy terraform.plan.json 是日常入口。支援 --all-namespaces（K8s 多 manifest）、--input（強制 parser 類型）、--combine（跨檔 check）、--output json|tap|table（CI 報表格式）。CI integration 通常 conftest test infra/**/*.yaml --output github 直接 emit GitHub Actions annotation。

Parser（多 format 支援）：Conftest 原生支援 HCL（Terraform）/ YAML / JSON / TOML / INI / Dockerfile / CUE / Jsonnet / EDN / XML / VCL（Fastly）/ Cyclonedx SBOM 等。同一份 Rego 可跑多 format — parser 把不同 format normalize 成 Rego input JSON、policy 寫 input.spec.containers[_].securityContext.privileged == true 不管原本是 YAML 還是 JSON。這是 Conftest 比 Checkov / Trivy Config 客製化彈性更大的關鍵：同一個 policy 引擎處理跨 format misconfig。

Combine flag（跨檔 check）：conftest test --combine *.yaml 把多檔合併成單一 input array、policy 可跨檔 reference。實務場景：K8s deployment 必須有對應 service + configmap + networkpolicy、缺一就 fail；Terraform module 跨檔 reference（VPC + subnet + security group）必須一致。沒有 Combine 就只能單檔檢查、跨檔 invariant 抓不到。

conftest verify（policy unit test）：Policy 本身要有測試 — policy/k8s_privileged_test.rego 寫 test_privileged_denied / test_non_privileged_allowed、conftest verify 跑這些測試。Policy 改動先跑 verify、再 merge policy 到 production CI。沒做 verify 的 policy 是「policy 自己 broken 沒人發現」的常見破口。

Bundle（OPA bundle 拉 policy）：conftest pull 從 OCI registry / HTTP / git / S3 拉 policy bundle、policy 集中在 central repo、各 service repo 不重複維護。Bundle 包含 Rego files + data files + manifest、可簽章驗證（配 Sigstore cosign）。大組織通常 platform team 維護 policy bundle、application team 在 CI 拉最新版本跑。

CI integration：GitHub Actions（open-policy-agent/conftest-action）/ GitLab CI / Jenkins / CircleCI 都有現成 step。跑點通常在 PR check 階段（review 前 fail fast）+ merge gate（防止繞過）。失敗訊息含 file / line / policy name、SOC / SRE 看 annotation 就知道哪行違規。

核心取捨表

選 Conftest 的核心訴求：組織有 custom policy 需求 + 已用 OPA / Rego（admission 走 Gatekeeper、CI 走 Conftest 統一語言） + 跨多 config format 需要同一個 policy 引擎。如果只是要 K8s privileged container / Terraform public S3 這類常見 anti-pattern 攔截、直接 Trivy Config 開箱即用更划算。

進階主題

conftest verify（policy unit test lifecycle）：Policy 是 code、code 要有測試。policy/k8s_privileged_test.rego 寫 test_privileged_denied { count(deny) > 0 with input as {...} }、CI 跑 conftest verify ./policy 把 policy test 當 unit test。Policy change 走 PR → verify pass → 部署到 central bundle → application CI 拉新版本。沒 verify 的 policy 是「沒人知道 policy 自己壞掉、所有 application CI 都 silently pass」的 systemic 風險。

Bundle 從 OCI registry pull + 簽章驗證：conftest pull oci://registry.example.com/policy-bundle:v1.2.3 從 OCI registry 拉 policy bundle、policy distribution 走 container image 同一套 supply chain。配 Sigstore cosign 簽章驗證、policy bundle 也走 7.12 供應鏈完整性 的 release gate 邏輯 — policy 本身就是 artifact、需要 signing + verification。

跟 Trivy Config 混用：實務上 Trivy Config 跑預設 rule（CIS / NSA / OWASP baseline、開箱即用）+ Conftest 跑客製 rule（organization-specific：必須有特定 label、必須走特定 namespace、必須引用特定 ConfigMap）。兩者 CI 階段都跑、報表合併。不是二選一、是 baseline + custom 的分工。

跟 admission 雙層：CI 階段 Conftest fail 之外、cluster 也裝 Gatekeeper 接 admission。Gatekeeper 用 ConstraintTemplate（也是 Rego）、同一份 Rego policy 理論上 CI / runtime 共用 — 但實務上 admission 場景跟 static check 場景的 input shape 不同（admission 拿 AdmissionReview object、static 拿 raw manifest）、policy 通常分兩份維護或寫 abstraction layer 共用。

排錯與失敗快速判讀

• Policy pass 但 production 還是 misconfig：CI 沒卡在 merge gate、或有 kubectl apply 繞過 PR — 加 admission controller（Gatekeeper / Kyverno）做 runtime 雙層
• Rego policy 自己 broken / silently pass：沒寫 *_test.rego + conftest verify — 補 policy unit test、CI 跑 verify 才 promote
• conftest test 跑出 0 violations 但 manifest 有問題：policy directory 沒讀對、或 parser 自動偵測選錯 — 顯式 --policy ./policy --input yaml
• 跨檔 invariant 抓不到（deployment 沒對應 service）：忘記用 --combine flag — 改 conftest test --combine *.yaml
• Bundle 拉到舊版本 / policy drift：沒固定 bundle tag、用 latest 漂移 — bundle reference 用 digest（sha256:...）或 immutable tag
• False positive 多 / team 開始 ignore CI：policy 寫得太寬、沒考慮合理例外 — Rego 加 exception list（data.exceptions）、走 Exception Workflow lifecycle
• Policy 散落各 application repo / 維護不一致：沒走 central bundle — 抽 policy 到中央 repo、各 application 拉 bundle

何時改走其他服務

不在本頁內的主題

• Rego 完整語法 reference、every / walk / built-in function 進階用法
• OPA Bundle 的 server-side 實作（policy publish pipeline）
• Conftest 跟 Open Policy Agent runtime 的內部架構差異
• Sigstore cosign 的 keyless signing flow 細節

案例回寫

Conftest 在 07 案例庫沒有直接 vendor-level 事件、但所有 supply chain case 都是 CI-time policy gate 的對照：

下一步路由

• 上游：7.12 供應鏈完整性與 artifact 信任
• 平行：OPA、Gatekeeper、Kyverno、Trivy
• 跨類：GitHub Advanced Security（CI security check pipeline 共用）
• 官方：Conftest Documentation

服務定位

Falco 的核心定位是 K8s container runtime detection engine 的 OSS 基準、不是 full CNAPP、也不是 inline enforcement。底層 Driver 分三層：modern eBPF（Linux 5.8+、預設）、legacy kernel module (kmod)（舊 kernel fallback）、pdig userspace probe（沒 root 或非 Linux）；Driver 抓 syscall 跟 K8s audit / cloud audit event、送進 Falco engine；engine 用 Sysdig filter syntax 比對 YAML rule、命中後吐 alert。Plugin 系統讓 Falco 看到非 syscall event（K8s audit log、Okta event、GitHub audit、AWS CloudTrail）— 變成 general detection engine、不只 host runtime。

跟 Cilium Tetragon 比、Falco 走 rule engine + alert-only、Tetragon 走 eBPF + 可 enforce kill action；Falco 偵測為主、Tetragon 偵測 + 防護。跟 Datadog Security（CWS）比、Datadog 是 SaaS observability 上加 runtime security view、ML-based behavioral baseline 內建、但 vendor lock + per-host 計費；Falco 是 OSS 自管、rule 完全可寫、但 ML baseline / threat intel / cross-source correlation 要自己接 SIEM。跟 Lacework Polygraph 比、Lacework 走 behavior graph 自動建 baseline、Falco 走 rule-explicit、邊界看得到也好 audit。

關鍵張力：偵測 vs 防護 跟 rule-explicit vs ML-baseline 是兩條取捨軸。Falco 預設只發 alert、要 inline kill / cordon 要靠 Falco Talon 或外接 SOAR；rule 完全可寫是優點也是負擔 — 自家 anti-pattern 要自己寫成 condition、不像 SaaS CNAPP 預設有 ML baseline。

本章目標

讀完本頁、讀者能判斷：

1. Falco 在 K8s runtime security stack 中承擔哪一段（syscall detection / audit log detection / alert forwarding）、哪些要外接（Talon / SIEM / SOAR）
2. Driver 選擇（modern eBPF / kmod / pdig）跟 kernel 環境 / 部署模型 的對應、選錯會 silent miss event
3. Rule 寫作的 ownership 設計（誰寫、誰 review、staging 怎麼觀察 false positive）
4. 何時用 Falco、何時改走 Tetragon（要 enforcement）或商業 CNAPP（要 ML baseline + 跨雲 posture）

最短判讀路徑

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

• Driver 是否符合 kernel 環境：modern eBPF on 5.8+ / kmod on legacy / pdig on serverless 或 non-root container；driver 跟 kernel 不對等於 silent miss，要看 falco --version 跟啟動 log 確認 driver 載入成功
• Rule ownership 跟 lifecycle：Falco 內建 rule（falco_rules.yaml / k8s_audit_rules.yaml）+ 自家 custom rule 是否走 Git PR review、staging tenant 跑幾小時觀察 false positive、再 promote production
• Alert sink + downstream routing：Falco 預設輸出 stdout / file / syslog、production 幾乎都接 Falcosidekick 做 fan-out（Slack / SIEM / S3 / Webhook），跟 Splunk / Elastic Security / Datadog Security 的接點明確
• Response 是 alert-only 還是有 enforcement：純 alert 走 8 事故處理 routing；要自動 kill pod / cordon node 需 Falco Talon 或 SOAR、且 high-impact action 走 approval gate

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

日常操作與決策形狀

Driver layer：Falco 三種 driver — modern eBPF（CO-RE、Linux 5.8+、預設、不需 kernel header）、legacy kernel module（kmod、舊 kernel 唯一選、要 DKMS build）、pdig（userspace、ptrace-based、非 root container 或 macOS dev 環境用、效能差）。production K8s deployment 幾乎都走 modern eBPF、DaemonSet 部署到每個 node、kernel 版本不夠才走 kmod；不要混用 driver、否則 alert source 難對齊。

Rule YAML 結構：Falco rule 由 condition（Sysdig filter syntax、類 SQL where）、output（alert template、含 field interpolation）、priority（emergency / alert / critical / error / warning / notice / informational / debug）、tags（mitre / cis / NIST 對應）組成。condition 寫法跟 Linux syscall 緊耦合（evt.type=execve、fd.name=/etc/passwd、proc.name=nc）— rule engineer 要對 syscall 跟 process tree 熟悉。macro 跟 list 讓 rule 可重用（macro: container_started / list: shell_binaries）、production rule 庫應該 macro-first、不是每條 rule 重寫 condition。

Plugin ecosystem：Plugin 把 Falco 從 host syscall 擴張到任意 event source — k8saudit plugin 接 K8s API server audit log（看 RBAC change / Secret access）、cloudtrail plugin 接 AWS CloudTrail、okta plugin 接 Okta system log、github plugin 接 GitHub audit log。Plugin 讓 Falco 成為 general detection engine、不只 container runtime；但 plugin event source 跟 SIEM 重疊、要清楚 ownership — Falco 做近 host 即時偵測、SIEM 做跨來源歷史 correlation、別兩邊都跑同一條 rule。

Falcosidekick + alert fan-out：Falco engine 預設輸出 stdout / file / gRPC、production 接 Falcosidekick（DaemonSet 旁邊或單獨 Deployment）做 fan-out — 同一個 alert 同時 forward 到 Slack（SOC chat）、Splunk HEC / Elastic / Loki（SIEM 持久化）、S3（合規 archive）、Webhook（自家 dashboard）、Prometheus（metrics）。Sidekick 是 stateless forwarder、不做 dedup / aggregation、那層要在 SIEM 處理。

Falco Talon + 自動 response：Talon 是 response orchestrator、訂閱 Falcosidekick 的 webhook output、依照 rule action 自動執行 — kill pod、cordon node、加 NetworkPolicy、call webhook 通知 SOAR。Talon 把 偵測 → 處置 從手動 SOC playbook 變 declarative YAML、但 high-impact action（kill prod pod、cordon node）必須走 approval gate 或限制在 staging namespace、不能黑箱 fire-and-forget。對應 Detection to Response Routing 的章節原則。

Helm chart 部署 + GitOps：Falco 官方 Helm chart 把 DaemonSet（Falco engine + driver）、Deployment（Falcosidekick）、ConfigMap（rule YAML）、ServiceAccount + RBAC 包成一組。生產 deployment 走 Argo CD / Flux 同步 Helm value、rule YAML 進 Git PR review、merge 觸發 staging tenant deploy、人工觀察 24-48hr false positive、再 promote production。Rule 直接改 ConfigMap、不走版控等於 detection drift、後續審計接不上。

跟 SIEM / 8 事故處理整合：Falco alert 經 Falcosidekick 進 Splunk / Elastic Security / Datadog Security 後、走跟其他 detection signal 同一條 correlation + triage 管線、不獨立 channel。Notable / high-priority alert 進 8 事故處理 的 IR queue、走 incident commander handoff。

核心取捨表

選 Falco 的核心訴求：K8s container runtime detection、OSS + rule-customizable、SIEM 已部署、SOC 有 detection engineer 寫得了 Sysdig filter rule。要 inline enforcement 直接走 Tetragon；要 ML baseline + 跨雲 posture + 不想自管 rule lifecycle 直接走 Datadog CWS / Lacework / Wiz + CrowdStrike Falcon CS。

進階主題

Custom rule 設計：production rule 庫應該 macro-first、把可重用條件抽成 macro（container_started / sensitive_mount / shell_in_container）跟 list（shell_binaries / sensitive_files）；rule 引用 macro 而非重寫 condition、修改 macro 等於同時更新所有引用 rule。Rule 反例是 single-event noisy rule（看到一個 shell exec 就 alert）— production rule 應該 context-bounded（shell exec in container + parent 不在 allowlist + image 非 trusted registry）+ priority 階梯（生產 Notice、staging Warning、新規則先 Informational 觀察）。

eBPF driver vs kmod 取捨：modern eBPF 用 CO-RE（Compile Once, Run Everywhere）、不需 per-kernel build、運行時動態 attach；kmod 需要 DKMS 在 host build、跟 kernel version 強耦合、升級 kernel 要重 build。所有現代 Linux distro 預設都該走 modern eBPF；只有 RHEL 7 / 老 Ubuntu LTS（kernel < 5.8）才有理由用 kmod。pdig 給沒 root / 沒 eBPF 的環境（某些 serverless container、macOS dev）、效能差不適合 production。

Falco Talon 自動 response 設計：Talon 把「Falco alert → 自動處置」變 declarative — rule action 可以是 kubernetes:terminate-pod、kubernetes:label-pod、kubernetes:cordon-node、aws:disable-iam-user、calico:add-networkpolicy。production 用 Talon 的關鍵原則：high-impact action 走 approval gate（PagerDuty incident → human approve → execute）、containment-first not deletion（先 cordon + label、再人工決定是否 terminate）、blast radius 限制（只能影響特定 namespace / label selector）、audit trail（每個 action 進 Splunk + IR queue）。

Plugin ecosystem 邊界：Plugin 把 Falco 變 general detection engine、但要明確 plugin event 跟 SIEM 重疊處的 ownership。建議：host syscall + container runtime → Falco rule（即時 + low latency）、K8s audit + cloud audit + IdP audit → 同時跑 Falco plugin（近即時 alert） + SIEM（歷史 correlation）、純跨來源 correlation（多 user 多 source 多時段）→ SIEM 為主。別讓 Falco plugin 跟 SIEM rule 跑重複條件、會 double-alert 也 double-cost。

Sigstore + SBOM 整合的位置：Falco 不做 image scan / SBOM 驗證（那是 Trivy / Syft & Grype 的位置）、但 runtime detection 是 Supply Chain Integrity 縱深防禦的最後一層 — image scan 過、簽章驗證過、但 runtime 出現異常 syscall（log4shell 觸發 outbound LDAP、SolarWinds 合法簽章但行為異常）、Falco rule 是最後抓的點。

排錯與失敗快速判讀

• Falco 啟動成功但完全沒 event：driver 沒載入（modern eBPF 在舊 kernel fallback 失敗）— 看啟動 log 確認 driver loaded successfully、falco --version 對 driver 版本、舊 kernel 改 kmod
• 大量 false positive 淹沒 SOC：rule 寫太寬（shell in container 但合法 debug shell 也 trigger）— staging tenant 跑 48hr 統計 FP、加 exception list 或改 macro 排除已知合法 source、新 rule 先 Informational priority 觀察
• Alert 沒進 SIEM：Falcosidekick 沒接、或 output channel 設錯 — 確認 Falcosidekick Deployment up、output webhook 對、SIEM HEC token 沒過期；Falco engine 本身的 stdout / file output 仍會留、不會 silent miss
• Rule update 後 detection drift：直接改 ConfigMap、沒走 Git PR + staging 觀察 — 強制 GitOps（Argo CD / Flux）、ConfigMap immutable、rule change 必須走 PR review + staging promote
• Plugin event lag / 漏抓：plugin polling cloud audit log（CloudTrail / Okta）的 latency 跟 API rate limit、不是即時 — 純即時偵測別靠 plugin、改靠 SIEM streaming ingest；plugin 適合補 syscall 看不到的層
• Talon 自動 response 誤殺 prod：rule action 直接 kill pod、沒 approval gate — 高影響 action 拆成兩步（先 label + cordon、再人工 approve terminate）、blast radius 限 namespace / label selector、audit trail 全進 SIEM
• eBPF driver 跟 kernel 升級不對齊：node kernel 升級後 modern eBPF 仍 CO-RE 自動適配、但 Falco 版本太舊不支援新 syscall — Falco engine 跟著定期升級、別 pin 在兩年前的 version

何時改走其他服務

不在本頁內的主題

• Sysdig filter syntax 完整 reference、syscall field 細目
• Falco source code 內部架構（libsinsp / libscap）
• Sysdig Secure（Falco 的商業版、Sysdig Inc. 維護、含 ML baseline + cloud posture）的功能對照細節
• Container image scan / SBOM 驗證（屬 Trivy / Syft & Grype 的位置）
• Kubernetes RBAC / Pod Security Standards / NetworkPolicy 的設計（屬 K8s 平台層、不在 runtime detection 範圍）

案例回寫

Falco 在 07 案例庫沒有直接 vendor-level 事件、但多個 runtime / supply chain case 都是 Falco rule 第一線該抓的場景：

下一步路由

• 上游：7.13 偵測覆蓋率與訊號治理、Detection Engineering Lifecycle、Detection to Response Routing
• 平行：Cilium Tetragon、Datadog Security、Lacework、Prisma Cloud
• 下游：Splunk / Elastic Security / Google Security Operations（Falco alert 進 SIEM 做 cross-source correlation）
• 跨類：Trivy / Syft & Grype（image scan + SBOM、跟 runtime detection 構成 supply chain 縱深）、Wiz / CrowdStrike Falcon CS（商業 CNAPP runtime 對照）
• 跨模組：8 事故處理 vendor 清單（Falco notable alert → IR routing）、Supply Chain Integrity（artifact trust 跟 runtime detection 的縱深關係）
• 官方：Falco Documentation、Falco Rules Repository

服務定位

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

來源

Defender Pressure

Control Gap

控制缺口的核心是開源元件信任只看版本與簽章,缺少對維護者活動與 build artifact 行為的監控。XZ Utils 的 backdoor 只在特定 release 路徑啟用,單純依賴上游版本號與 license 檢查會漏掉這類風險。

Detection Route

Exercise Hook

本案例可支撐 Supply chain artifact drill 的開源變體。演練重點是確認團隊能在上游 advisory 出現時,快速比對 SBOM、降版受影響元件並驗證 sshd 行為。

Write-back Target

• 7.12 供應鏈完整性與 Artifact 信任
• 7.22 資安風險如何進入 Release Gate
• Detection lifecycle pattern
• Vulnerability response pattern