omerta icon

omerta

omerta 是離線 CLI 與 Git hook 工具,可檢查未追蹤 .env 檔案中的實際值是否出現在暫存變更、已追蹤檔案或儲存庫歷史中,協助團隊偵測環境值外洩且不顯示秘密內容。

omerta

離線偵測環境檔案值

Omerta 是離線 Git 秘密偵測 CLI 與 hook,用於在原始碼管理中尋找從環境檔案載入的實際值。它不比對通用的鍵名稱模式,而是從未追蹤的 `.env` 與 `.env.*` 檔案讀取值,並檢查這些值是否已暫存、受追蹤或提交至儲存庫歷史中。

它旨在於提交前捕捉外洩,也可用於調查現有儲存庫。結果會識別變數名稱與環境檔案來源,但不會顯示值;掃描會針對沒有發現、發現結果與錯誤回傳不同的結束碼。專案文件說明了與 pre-commit、其他 Git hook 管理工具及 CI 的使用方式。

主要功能

以值為基礎的秘密偵測

從未追蹤的根目錄 `.env` 與 `.env.*` 檔案讀取值,並檢查這些確切值是否出現在暫存變更、已追蹤檔案或儲存庫歷史中。

編碼與非文字內容涵蓋

以原始形式,以及 URL 百分比編碼、JSON 跳脫和 base64 編碼形式搜尋值,涵蓋文字檔、二進位檔與檔名。

工作樹與歷史掃描

提供分別針對暫存變更、指定路徑、所有已追蹤檔案,或每個可到達的檔案版本與提交或標籤訊息進行掃描的指令。

離線且已遮蔽的發現結果

在本機執行且不需要網路存取,回報變數名稱與來源環境檔案,而不是相符的秘密值。

適合自動化的工作流程

支援 pre-commit,並提供 Husky、Lefthook、一般 Git hook 與 CI 工作流程的範例。其結束碼可區分無發現、發現結果與錯誤。

可設定的掃描

支援使用 `.omerta.toml` 或 `pyproject.toml` 設定環境檔案模式、忽略的變數、值的最小長度、編碼搜尋、JSON Lines 輸出、靜默模式與儲存庫路徑。

使用情境

  • 在提交前阻擋外洩

    將文件中的 Omerta hook 加入儲存庫的 pre-commit 設定,讓系統在建立提交前檢查暫存變更。文件也說明了 Husky、Lefthook、一般 Git hook 與 Python 本機 hook 設定。

  • 稽核工作中的儲存庫

    對 checkout 執行 `omerta check --all`,以找出已存在於已追蹤檔案中的環境值,包括嵌入路徑或編碼內容中的值。

  • 調查儲存庫歷史

    完成完整 checkout 後執行 `omerta history`,找出環境值進入檔案、標籤或提交訊息的提交。這有助於調查過去的暴露情況。

  • 持續整合檢查

    在推送或 pull request 時將 CLI 加入 CI 工作。文件中的工作流程會使用完整 Git 歷史 checkout、檢查已追蹤檔案,接著掃描歷史,無須開發者本機未追蹤的 `.env` 檔案。

Pros and Cons

Pros

  • 檢查實際的環境檔案值,而不只依賴看似秘密的模式。
  • 可檢查暫存變更、已追蹤內容、編碼表示、二進位檔、檔名與可到達的 Git 歷史。
  • 透過列出變數名稱而不顯示相符值,讓發現結果維持遮蔽狀態。
  • 可離線運作,並提供文件化的 Git hook 與 CI 整合方式。

Cons

  • 此工具專注於可從本機或已提交環境檔案取得的值;若值已輪替,除非透過其他環境檔案提供,否則不會再搜尋該值。
  • 需要 Python 3.11 或更新版本及 Git 2.31 或更新版本;在 ARM 架構的 Windows 上,因文件所述的 hyperscan wheel 限制,需要使用 x64 Python。
  • 預設會略過短於八個字元的值,可能需要變更 `min-chars`;這可能增加一般文字的相符結果。

FAQ

如何安裝並執行 Omerta?

使用 `uvx omerta check --all` 掃描已追蹤檔案,或使用 `uvx omerta history` 掃描可到達的提交、標籤與訊息。也可以使用 `pip install omerta` 安裝。

Omerta 可以作為 Git hook 執行嗎?

可以。文件中的 pre-commit 設定會將 Omerta 用作 hook。專案也提供 Husky、Lefthook、一般 Git hook,以及 Python 專案本機 hook 的範例。

Omerta 如何整合至 CI?

在 CI 中,Omerta 會掃描已提交的環境檔案,因為本機未追蹤的 `.env` 檔案無法取得。文件中的 GitHub Actions 範例會在完整 checkout 後檢查所有已追蹤檔案並掃描歷史。

Omerta 會搜尋什麼?會暴露秘密值嗎?

Omerta 會讀取 Git 未追蹤的根目錄 `.env` 與 `.env.*` 檔案中的值,接著以原始形式,以及 URL 百分比編碼、JSON 跳脫或 base64 編碼形式搜尋這些值。它會回報變數名稱與來源檔案,但不會顯示值。

Omerta 的文件所列需求為何?

文件所列的需求為 Git 2.31 或更新版本,以及 Python 3.11 或更新版本。在 ARM 架構的 Windows 上,專案指定使用 x64 Python,因為其 hyperscan 相依套件沒有 Windows ARM wheel。

Quick Facts

類別
開發者工具
產品類型
開源 CLI 與 Git hook
主要工作流程
環境秘密外洩偵測
執行模式
離線
設定
`.omerta.toml` 或 `pyproject.toml`
來源
github.com/shcherbak-ai/omerta