omerta icon

omerta

omerta 是一款离线 CLI 和 Git 钩子工具,可检测未跟踪 .env 文件中的实际值是否出现在暂存更改、已跟踪文件或仓库历史中,并在不打印匹配密钥的情况下帮助团队发现环境值泄漏。

omerta

离线检测环境文件值

Omerta 是一款离线 Git 密钥检测 CLI 和钩子工具,用于查找从环境文件加载的实际值是否出现在源代码管理中。它不匹配通用的密钥模式,而是从未跟踪的 `.env` 和 `.env.*` 文件中读取值,并检查这些值是否已被暂存、跟踪或提交到仓库历史中。

它旨在在提交前捕获泄漏,也可用于调查现有仓库。结果会标识变量名和环境文件来源,但不会打印值;扫描会针对无发现、有发现和错误返回不同的退出代码。项目文档介绍了与 pre-commit、其他 Git 钩子管理器及 CI 的配合使用。

主要功能

基于值的密钥检测

从未跟踪的根目录 `.env` 和 `.env.*` 文件中读取值,并检查这些确切值是否出现在暂存更改、已跟踪文件或仓库历史中。

编码内容和非文本内容覆盖

以原始形式以及 URL 百分号编码、JSON 转义和 base64 编码形式搜索值,涵盖文本文件、二进制文件和文件名。

工作区和历史扫描

为暂存更改、指定路径、所有已跟踪文件,或每个可访问的文件版本以及提交或标签消息提供独立命令。

离线运行,脱敏报告

无需网络访问即可在本地运行,并报告变量名和源环境文件,而不是匹配到的密钥值。

便于自动化的工作流

支持 pre-commit,并提供 Husky、Lefthook、普通 Git 钩子和 CI 工作流示例。其退出代码可区分无发现、有发现和错误。

可配置扫描

支持使用 `.omerta.toml` 或 `pyproject.toml` 配置环境文件模式、忽略变量、最小值长度、编码搜索、JSON Lines 输出、静默模式和仓库路径。

使用场景

  • 在提交前阻止泄漏

    将文档中的 Omerta 钩子添加到仓库的 pre-commit 配置中,以便在创建提交前检查暂存更改。文档还介绍了 Husky、Lefthook、普通 Git 钩子和 Python 本地钩子的设置。

  • 审计工作仓库

    对检出内容运行 `omerta check --all`,以识别已存在于已跟踪文件中的环境值,包括嵌入路径或编码内容中的值。

  • 调查仓库历史

    完成完整检出后运行 `omerta history`,以定位环境值进入文件、标签或提交消息的提交。这有助于调查过去的暴露情况。

  • 持续集成检查

    在推送或拉取请求时将 CLI 添加到 CI 作业中。文档化的工作流会完整检出 Git 历史,检查已跟踪文件,然后扫描历史,无需开发者本地未跟踪的 `.env` 文件。

Pros and Cons

Pros

  • 检查实际的环境文件值,而不只是依赖看起来像密钥的模式。
  • 可以检查暂存更改、已跟踪内容、编码表示、二进制文件、文件名以及可访问的 Git 历史。
  • 通过报告变量名而不是打印匹配值,保持发现结果脱敏。
  • 支持离线运行,并提供文档化的 Git 钩子和 CI 集成路径。

Cons

  • 该工具专注于从本地或已提交的环境文件中获取的值;除非通过其他环境文件提供,否则轮换后的值不会再被搜索。
  • 需要 Python 3.11 或更高版本以及 Git 2.31 或更高版本;由于文档所述 hyperscan wheel 的限制,ARM 架构的 Windows 需要使用 x64 Python。
  • 默认会跳过长度少于 8 个字符的值,可能需要更改 `min-chars`;这可能会增加普通文本匹配。

FAQ

如何安装和运行 Omerta?

使用 `uvx omerta check --all` 检查已跟踪文件,或使用 `uvx omerta history` 检查可访问的提交、标签和消息。也可以使用 `pip install omerta` 安装。

Omerta 可以作为 Git 钩子运行吗?

可以。文档中的 pre-commit 配置将 Omerta 用作钩子。项目还提供了 Husky、Lefthook、普通 Git 钩子以及 Python 项目本地钩子的示例。

Omerta 如何用于 CI?

在 CI 中,Omerta 会扫描已提交的环境文件,因为本地未跟踪的 `.env` 文件不可用。文档中的 GitHub Actions 示例会检查所有已跟踪文件,并在完整检出后扫描历史。

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 钩子
主要工作流
环境密钥泄漏检测
执行模式
离线
配置
`.omerta.toml` 或 `pyproject.toml`
来源
github.com/shcherbak-ai/omerta