Metadata-Version: 2.4
Name: leakwatch-cli
Version: 0.1.0
Summary: CLI scanner for exposed secrets in Git repositories using pattern matching and Shannon entropy detection
Project-URL: Homepage, https://github.com/DavidSotoo/leakwatch
Project-URL: Repository, https://github.com/DavidSotoo/leakwatch
Author: Angel David Soto Delgado
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.9
Requires-Dist: click
Requires-Dist: gitpython
Requires-Dist: pyyaml
Requires-Dist: rich
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Description-Content-Type: text/markdown

# 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:

```bash
pip install -e .
```

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

```bash
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:

```bash
leakwatch scan /path/to/target
```

To scan the entire Git commit history across all branches:

```bash
leakwatch scan /path/to/repo --history
```

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

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

### 2. Initializing Configuration

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

```bash
leakwatch config init
```

### 3. Installing Pre-Commit Hooks

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

```bash
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
