credhunter 0.1.0__tar.gz

credhunter-0.1.0/PKG-INFO

@@ -0,0 +1,279 @@
+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.

credhunter-0.1.0/README.md

@@ -0,0 +1,267 @@
+# 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.