credhunter

credhunter is a Python command-line tool for scanning files and directories for potential hardcoded secrets. It combines pattern-based detection with context and entropy signals, assigns confidence and severity, masks detected values in output, and can generate JSON and HTML reports.

credhunter is a detection aid, not a guarantee that every secret will be found. Review findings before taking action, and never use real production credentials in test fixtures.

Features

• Scan a single file or directory.
• Detect configured secret patterns using rules packaged with credhunter.
• Use context analysis and Shannon entropy as detection signals.
• Assign confidence scores and severity levels.
• Filter configured placeholder values to reduce some false positives.
• Mask detected values in console output and reports.
• Generate JSON and HTML reports.
• Configure CI failure behavior with --fail-on.
• Display the installed package version with --version.

Requirements

• Python 3.10 or newer.
• Windows, Linux, or macOS with a compatible Python installation.

Installation

Install from PyPI

Once credhunter has been published to PyPI, install it with:

python -m pip install credhunter

Verify the installation:

credhunter --version
credhunter --help

Install from source for development

If you have cloned or downloaded the source repository, open a terminal in the project directory.

Windows PowerShell

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .

Linux/macOS

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

To install development and test dependencies:

python -m pip install -e ".[dev]"

The editable installation is intended for development. It allows changes to the source code to be used without rebuilding and reinstalling the package.

Usage

The command accepts a file or directory path as its positional argument.

Show the installed version

credhunter --version

Show help

credhunter --help

Scan the current directory

credhunter .

Scan a directory

Windows PowerShell

credhunter .\examples\vulnerable_project

Scan a single file

credhunter .\path\to\file.py

Generate JSON and HTML reports

credhunter .\examples\vulnerable_project --json report.json --html report.html

Choose report destinations that are writable. Review generated reports before sharing them, as they can contain sensitive repository details even when detected secret values are masked.

Configure the CI/CD failure threshold

credhunter .\examples\vulnerable_project --fail-on high

Supported thresholds:

• critical
• high
• medium
• low
• none

The command returns exit code 1 when at least one finding meets or exceeds the selected threshold; otherwise, it returns 0. Use --fail-on none to complete a scan without failing based on findings:

credhunter .\examples\vulnerable_project --fail-on none

How Detection Works

credhunter uses several signals to evaluate potential secrets:

1. Pattern matching: configured regular expressions identify values that match known secret formats.
2. Context analysis: nearby names or text, such as password, token, and api_key, can help assess whether a value is a credential.
3. Entropy analysis: Shannon entropy helps assess how random-looking a string is.
4. Confidence and severity: findings include a confidence score and severity classification.
5. Placeholder filtering: configured placeholder markers can suppress common test or example values.
6. Masking: console output and reports use masked snippets rather than intentionally displaying the complete detected value.
7. Fingerprinting: SHA-256 fingerprints can help identify repeated values without storing the raw secret as the fingerprint.

These signals do not guarantee that every secret will be detected or that every finding is correct. False positives and false negatives are possible.

Detection Rules

Detection rules are stored in the package at:

credhunter/rules/secrets.yaml

The rule file defines patterns and related metadata used by the scanner. Configured rules may cover credential types such as cloud access keys, tokens, private-key blocks, database connection strings, passwords, and generic API keys. Actual detection depends on the rules and the scanner's filtering and scoring logic.

When adding a rule, use a unique ID, a descriptive name, a severity, a detection pattern, and any context keywords required by the rule format. Add or update tests to verify the expected detection and check for false positives.

Reports

Console output

The CLI displays findings with details such as severity, confidence, location, and a masked snippet.

JSON report

Generate a machine-readable report with:

credhunter .\examples\vulnerable_project --json report.json --fail-on none

HTML report

Generate a human-readable report with:

credhunter .\examples\vulnerable_project --html report.html --fail-on none

To generate both formats in one scan:

credhunter .\examples\vulnerable_project --json report.json --html report.html --fail-on none

Testing

Install the development dependencies:

python -m pip install -e ".[dev]"

Run the test suite:

python -m pytest

Before releasing a version, confirm that all tests pass. Also perform manual checks in a clean virtual environment:

1. Run credhunter --version and credhunter --help.
2. Scan a test project containing synthetic secrets.
3. Scan a clean test project and review unexpected findings.
4. Generate JSON and HTML reports.
5. Confirm the original synthetic secret is not exposed in console output or either report.
6. Check exit codes for --fail-on none and severity thresholds that should and should not be triggered.
7. Confirm an installed package can locate its bundled YAML rules.

Use only fake, nonfunctional test values in examples and tests.

Security Response Guidance

If credhunter identifies a real credential:

1. Revoke or rotate the credential promptly.
2. Remove it from the source code and use an appropriate secrets-management solution.
3. Review repository history and access logs where appropriate.
4. Assess whether the credential may have been accessed by an unauthorized party.
5. Update tests or detection rules if the finding reveals a coverage gap.

Removing a secret from the latest version of a file does not necessarily remove it from version-control history.

Known Limitations

• Detection depends on configured rules and may miss custom or proprietary credential formats.
• False positives and false negatives are possible.
• Placeholder filtering may suppress a value if it contains a configured placeholder marker.
• Masking should be verified for each output format.
• A successful scan does not prove that a repository contains no secrets.

Project Structure

The core package follows this general layout:

credhunter/
├── credhunter/
│   ├── cli.py
│   ├── scanner.py
│   ├── masking.py
│   ├── models.py
│   ├── scoring.py
│   ├── detectors/
│   │   ├── regex_detector.py
│   │   ├── entropy.py
│   │   └── context.py
│   ├── reporters/
│   │   ├── json_reporter.py
│   │   ├── html_reporter.py
│   │   └── pdf_reporter.py
│   └── rules/
│       └── secrets.yaml
├── tests/
├── examples/
├── pyproject.toml
└── README.md

The exact structure may change as development continues.

License

Add a license file and the corresponding package metadata before publishing if you intend others to use, modify, or redistribute credhunter.