omerta icon

omerta

Omerta is an offline CLI and Git hook that detects environment-value leaks in staged, tracked, or repository-history files without exposing secrets.

omerta

Offline detection for environment-file values

Omerta is an offline Git secret-detection CLI and hook for finding the actual values loaded from environment files in source control. Instead of matching generic key patterns, it reads values from untracked `.env` and `.env.*` files and checks whether those values have been staged, tracked, or committed in repository history.

It is designed to catch leaks before commits and to investigate existing repositories. Results identify the variable name and the env-file source without printing the value; scans return distinct exit codes for no findings, findings, and errors. The project documents use with pre-commit, other Git-hook managers, and CI.

Key features

Value-based secret detection

Reads values from untracked root `.env` and `.env.*` files and checks whether those exact values appear in staged changes, tracked files, or repository history.

Encoded and non-text coverage

Searches values as written and in URL percent-encoded, JSON-escaped, and base64-encoded forms, including text, binary files, and file names.

Working-tree and history scans

Provides separate commands for staged changes, a path, all tracked files, or every reachable file version and commit or tag message.

Offline, redacted findings

Runs locally without network access and reports variable names and source env files rather than the matched secret values.

Automation-friendly workflow

Supports pre-commit and examples for Husky, Lefthook, plain Git hooks, and CI workflows. Its exit codes distinguish clean results, findings, and errors.

Configurable scanning

Supports `.omerta.toml` or `pyproject.toml` configuration for env-file patterns, ignored variables, minimum value length, encoded searching, JSON Lines output, quiet mode, and repository paths.

Use cases

  • Blocking leaks before commit

    Add the documented Omerta hook to a repository's pre-commit configuration so staged changes are checked before a commit is created. Husky, Lefthook, plain Git hooks, and Python-local hook setups are also documented.

  • Auditing a working repository

    Run `omerta check --all` against a checkout to identify environment values already present in tracked files, including values embedded in paths or encoded content.

  • Investigating repository history

    Run `omerta history` after a full checkout to locate the commit where an environment value enters a file, tag, or commit message. This supports investigation of past exposure.

  • Continuous integration checks

    Add the CLI to a CI job on pushes or pull requests. The documented workflow uses a full Git history checkout, checks tracked files, and then scans history without requiring the developer's local untracked `.env` files.

Pros and Cons

Pros

  • Checks real environment-file values rather than relying only on secret-looking patterns.
  • Can inspect staged changes, tracked content, encoded representations, binary files, file names, and reachable Git history.
  • Keeps findings redacted by naming the variable instead of printing the matched value.
  • Works offline and provides documented Git-hook and CI integration paths.

Cons

  • The tool is focused on values available from local or committed environment files; a rotated value is no longer searched unless it is supplied through another env file.
  • Python 3.11 or later and Git 2.31 or later are required, and Windows on ARM requires x64 Python because of the documented hyperscan wheel limitation.
  • Values shorter than eight characters are skipped by default and may require changing `min-chars`, which can increase ordinary-text matches.

FAQ

How do you install and run Omerta?

Install it with `uvx omerta check --all` for tracked files or `uvx omerta history` for reachable commits, tags, and messages. It can also be installed with `pip install omerta`.

Can Omerta run as a Git hook?

Yes. The documented pre-commit configuration uses Omerta as a hook. The project also shows examples for Husky, Lefthook, plain Git hooks, and a local hook in a Python project.

How does Omerta fit into CI?

In CI, Omerta scans committed environment files because the untracked local `.env` files are not available. The documented GitHub Actions example checks all tracked files and scans history after a full checkout.

What does Omerta search for, and does it expose secret values?

Omerta reads values from root-level `.env` and `.env.*` files that Git does not track, then searches for those values as written and in percent-encoded, JSON-escaped, or base64-encoded forms. It reports the variable name and source file without printing the value.

What are Omerta's documented requirements?

The documented requirements are Git 2.31 or later and Python 3.11 or later. On Windows on ARM, the project specifies using an x64 Python because its hyperscan dependency has no Windows ARM wheels.

Quick Facts

Category
Developer Tool
Product type
Open-source CLI and Git hook
Primary workflow
Environment-secret leak detection
Execution model
Offline
Configuration
`.omerta.toml` or `pyproject.toml`
Source
github.com/shcherbak-ai/omerta