leakwatch-cli 0.1.0

CLI scanner for exposed secrets in Git repositories using pattern matching and Shannon entropy detection

LeakWatch

A simplified credentials and exposed secrets scanner for Git repositories.

Why

This tool exists because I accidentally committed a MongoDB connection string with production credentials to a public repo. That incident showed me how easily a secret can slip through a code review, so I built LeakWatch to catch these before they ever reach GitHub.

Installation

To install LeakWatch in editable mode for development, clone the repository and run:

pip install -e .

To install dev dependencies (such as pytest) as well, run:

pip install -e .[dev]

Usage

LeakWatch provides a command-line interface with three main command groups:

1. Scanning files and Git history

To scan a directory or a specific file:

leakwatch scan /path/to/target

To scan the entire Git commit history across all branches:

leakwatch scan /path/to/repo --history

To format the output (options: console, json, sarif):

leakwatch scan /path/to/target --format json

2. Initializing Configuration

To generate a sample configuration file .leakwatch.yml in the current working directory:

leakwatch config init

3. Installing Pre-Commit Hooks

To configure a Git pre-commit hook (runs automatically before commits):

leakwatch install-hook

Note: This command is currently a placeholder and will be completed in a future release.

How it works

LeakWatch implements a two-pronged scanning strategy:

1. Pattern Matching: Scans file contents line-by-line using regular expressions configured for specific known services (such as AWS Access Keys, MongoDB, Postgres, MySQL connection strings, Stripe keys, JWT tokens, and PEM private keys).
2. Entropy Analysis: Evaluates Shannon entropy for long alphanumeric strings (length greater than 20 characters). Candidates that exceed a configurable threshold (default: 4.5) are flagged as potential high-entropy secrets (e.g. random API keys or database passwords).

Paths can be ignored and specific false positives can be allowed by editing .leakwatch.yml.

Roadmap

• Full Git commit history scanning (Complete)
• Basic and configurable Shannon entropy analysis (Complete)
• Extensible SARIF output format support (Stub implemented)
• Automated pre-commit hook installation
• Publishing the package to PyPI