LeakLens is a production-focused credential and secret detection tool for Git repositories.
It is designed to be stronger than regex-only scanners by combining:
- regex detection for known secret formats
- entropy detection for unknown/random secrets
- contextual code analysis for suspicious hardcoded values
- developer-friendly remediation guidance
- safe autofix suggestions (advisory only, no automatic file mutation)
Most leaked credentials are introduced during normal development and code review misses. LeakLens helps developers catch those leaks early:
- locally via CLI
- before commit via pre-commit hook
- in CI/CD via GitHub Actions
leaklens scan .leaklens scan --stagedleaklens scan --commit <hash>leaklens scan --diff <base> <head>leaklens rules listleaklens report --format jsonleaklens report --format sarifleaklens scan --verify(optional provider/syntax verification)
Deterministic CI behavior:
- stable sort order for findings and JSON/SARIF output
- non-zero exit code when findings meet
--fail-on(or configured threshold) - redacted previews only (never full secret output)
Detection pipeline:
- Regex detectors (AWS/GitHub/GitLab/Slack/Stripe/OpenAI/Google/JWT/private keys/.env/db URLs)
- Entropy detector using Shannon entropy over candidate literals
- Context detector for suspicious assignments and auth-adjacent literals
Output includes:
- finding type
- file path and line number
- redacted preview
- detector source(s)
- confidence score
- severity (
low|medium|high|critical) - risk explanation
- safer alternative
- remediation guidance
- autofix suggestion
pip install -e .Development setup:
pip install -e '.[dev]'Command quick reference:
| Command | Purpose |
|---|---|
leaklens scan . |
Full repository scan |
leaklens scan --staged |
Staged changes scan |
leaklens scan --commit <hash> |
Single commit scan |
leaklens scan --diff <base> <head> |
Commit-range diff scan |
leaklens scan --verify |
Scan and attempt verification of supported secret types |
leaklens rules list |
List active rules |
leaklens report --format json |
CI JSON report |
leaklens report --format sarif |
SARIF report for code scanning |
Scan repository:
leaklens scan .Scan staged changes:
leaklens scan --stagedScan specific commit:
leaklens scan --commit <hash>Scan diff range:
leaklens scan --diff main HEADList rules:
leaklens rules listCI JSON report:
leaklens report --format jsonSARIF report:
leaklens report --format sarif --output leaklens.sarifVersion:
leaklens --versionFail threshold override:
leaklens scan . --fail-on highScan with verification:
leaklens scan . --verifyRun as module:
python -m leaklens scan .Exit code semantics:
0: no findings at/above fail threshold1: findings at/above fail threshold2: CLI usage/configuration errors
LeakLens supports optional verification with --verify for selected finding types.
- GitHub tokens: checked via GitHub API
- Stripe keys: checked via Stripe API
- Slack tokens: checked via Slack API
- JWTs: syntax/expiry checks (signature not validated)
Verification status is included in JSON/SARIF output and shown in terminal output when enabled.
Notes:
- Verification makes outbound network requests.
- Secrets are never printed in full.
- Unsupported types are marked as
unverifiableinstead of assumed valid.
Default config file: leaklens.yml
Example:
entropy_threshold: 4.2
severity_threshold: medium
enabled_detectors: [regex, entropy, context]
ignored_paths:
- "node_modules/**"
allowlist:
values: ["example-secret"]
patterns: ["^dummy_"]
rules:
- name: custom_internal_token
regex: "inttok_[A-Za-z0-9]{24}"
secret_type: "Internal API Token"
severity: high
confidence: 0.9
baseline_file: .leaklens-baseline.json.leaklensignorefor path patterns- inline ignore markers:
leaklens:ignore - allowlist values and patterns in config
- baseline suppression via fingerprints
- legacy compatibility:
.aicredleakignoreandaicredleak:ignoreare also accepted .gitignoreis respected automatically- dotenv variants are scanned:
.env,.env.local,.env.example,.env.*
Generate baseline from current findings:
leaklens scan . --write-baseline .leaklens-baseline.jsonLeakLens never prints full secret values. Example previews:
ghp_****ABCDsk-****XYZ
Use the included .pre-commit-config.yaml hook:
repos:
- repo: local
hooks:
- id: leaklens
entry: leaklens scan --stagedUse .github/workflows/leaklens.yml.
The workflow:
- installs dependencies
- runs tests
- generates SARIF via
leaklens report --format sarif - uploads SARIF to GitHub Code Scanning
src/leaklens/
cli.py
config.py
engine.py
rules.py
models.py
detectors/
reporters/
tests/
examples/
.github/workflows/
- Verification is optional (
--verify) and currently limited to supported providers - Context detection is heuristic and may produce false positives in edge cases
- Binary and generated minified assets are intentionally skipped
- LeakLens does not rewrite source files automatically; autofix output is advisory guidance
- Optional AI review stage for borderline findings
- PR comment bot integration for developer feedback loops
- Secret validity verification integrations (cloud/vendor APIs)
- Exposure timeline analysis across commit history and branches
pytest
ruff check src tests
ruff format src tests