Metadata-Version: 2.4
Name: credhunter
Version: 0.1.0
Summary: Automated secrets detection and reporting tool
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.9.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: fpdf2>=2.7.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

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

```bash
python -m pip install credhunter
```

Verify the installation:

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

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

**Linux/macOS**

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

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

```bash
credhunter --version
```

### Show help

```bash
credhunter --help
```

### Scan the current directory

```bash
credhunter .
```

### Scan a directory

**Windows PowerShell**

```powershell
credhunter .\examples\vulnerable_project
```

### Scan a single file

```powershell
credhunter .\path\to\file.py
```

### Generate JSON and HTML reports

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

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

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

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

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

### HTML report

Generate a human-readable report with:

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

To generate both formats in one scan:

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

## Testing

Install the development dependencies:

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

Run the test suite:

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

```text
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.
