credhunter 0.1.0__py3-none-any.whl

credhunter-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,20 @@
+secretguard/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+secretguard/cli.py,sha256=ludv2zZWtFpf69B1pknUKqgh7c19SgUR6sNhzUHQbRM,10851
+secretguard/masking.py,sha256=v6UcEOc1JAknbtceaNS6N62qT9n8BocQYbJJjbhJe5c,1307
+secretguard/models.py,sha256=zHKskI_nnzXmg30i2seQNg9Wy50f0PJqfxhGYISjiT4,1404
+secretguard/scanner.py,sha256=-o42QKNe_1LknmfMdiLPU-xqhoV85rHwp_WhnYorChs,8456
+secretguard/scoring.py,sha256=hhkkZRjvKhDCVxj9zr5-noeYsEzBRlz_KT_YmvoDEac,2041
+secretguard/detectors/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+secretguard/detectors/context.py,sha256=h86EqMfrwn1Pc7oZhQapjF9WSjroKySvoAyUjkI_9oY,1184
+secretguard/detectors/entropy.py,sha256=kjRcrJ6lXKi8_2_22P04inRF0YW9pQVv57g8eKzvFvM,1866
+secretguard/detectors/regex_detector.py,sha256=e62ga7jmYAxwmOX0YPoWQjBci90vj9zKgh1tYdtMOKQ,2986
+secretguard/reporters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+secretguard/reporters/html_reporter.py,sha256=1ycZmVOceCschZAE6PkZNDTGwAU8tHQQltGd0_wO128,9094
+secretguard/reporters/json_reporter.py,sha256=hry9Owd2rNWgQmMIgqX-Ghx-WURYKCiCfEhug1zPyYc,667
+secretguard/reporters/pdf_reporter.py,sha256=VJSve-yrHbTDt0i1nffE97oZMy7hS7nAmiB4OAL5Wa4,3041
+secretguard/rules/secrets.yaml,sha256=oQ7LudxqTDYD5voujz1lq8mPAxC7eM3IJyRV-8IOptQ,2371
+credhunter-0.1.0.dist-info/METADATA,sha256=VH3EtCPUYDAo1bPiDku0_btP5xni_ldMuaxqJyhaidU,8708
+credhunter-0.1.0.dist-info/WHEEL,sha256=a-udL2m4V_6Yn8b-uKzWb12RjRxwwMo6ohYFM24tpaY,91
+credhunter-0.1.0.dist-info/entry_points.txt,sha256=HI2PH0quT4turllh8XUMVkN4K9XGOED-_MW7TivDAgU,51
+credhunter-0.1.0.dist-info/top_level.txt,sha256=VC8CbOxTsPOaEMygTmdSjebxOVGHe0aim9KmuJGFLik,12
+credhunter-0.1.0.dist-info/RECORD,,

credhunter-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

credhunter-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+credhunter = secretguard.cli:app

credhunter-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+secretguard

secretguard/cli.py

@@ -0,0 +1,349 @@
+"""Command-line interface for CredHunter.
+
+Usage:
+    credhunter scan .
+    credhunter scan . --format json
+    credhunter scan . --format html
+    credhunter scan . --format both
+    credhunter scan . --format json --output my-report.json
+    credhunter scan . --format html --output security-report.html
+    credhunter scan . --fail-on high
+    credhunter --version
+"""
+
+import os
+import sys
+import webbrowser
+from pathlib import Path
+from importlib.metadata import PackageNotFoundError, version as package_version
+
+import typer
+
+from .models import Severity
+from .reporters.html_reporter import generate_html_report
+from .reporters.json_reporter import generate_json_report
+from .scanner import scan_path
+
+app = typer.Typer(
+    help="CredHunter: scan source code for hardcoded secrets.",
+    no_args_is_help=True,
+)
+
+# Environment variables commonly set by CI/CD systems.
+CI_ENV_VARS = (
+    "CI",
+    "GITHUB_ACTIONS",
+    "GITLAB_CI",
+    "JENKINS_URL",
+    "TF_BUILD",
+)
+
+
+def version_callback(value: bool) -> None:
+    """Display the installed CredHunter version."""
+    if not value:
+        return
+
+    try:
+        current_version = package_version("credhunter")
+    except PackageNotFoundError:
+        current_version = "unknown"
+
+    typer.echo(f"credhunter version {current_version}")
+    raise typer.Exit()
+
+
+def _is_interactive_session() -> bool:
+    """Return True for an interactive terminal outside CI/CD."""
+    running_in_ci = any(os.environ.get(name) for name in CI_ENV_VARS)
+    return sys.stdout.isatty() and not running_in_ci
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=version_callback,
+        is_eager=True,
+        help="Show the installed CredHunter version and exit.",
+    ),
+) -> None:
+    """CredHunter command-line interface."""
+
+
+@app.command()
+def scan(
+    path: str = typer.Argument(
+        ".",
+        help="File or directory to scan. Defaults to the current directory.",
+    ),
+    report_format: str = typer.Option(
+        "none",
+        "--format",
+        help="Report format: none, json, html, or both.",
+        case_sensitive=False,
+    ),
+    output: str | None = typer.Option(
+        None,
+        "--output",
+        help="Custom report filename. Used with --format json or --format html.",
+    ),
+    fail_on: str = typer.Option(
+        "high",
+        "--fail-on",
+        help=(
+            "Minimum severity that causes a non-zero exit code: "
+            "critical, high, medium, low, none."
+        ),
+        case_sensitive=False,
+    ),
+) -> None:
+    """Scan PATH for hardcoded secrets and optionally generate reports."""
+
+    # Validate options before scanning.
+    report_format = report_format.lower()
+    fail_on = fail_on.lower()
+
+    allowed_formats = {"none", "json", "html", "both"}
+    if report_format not in allowed_formats:
+        typer.secho(
+            "Invalid --format value. Choose: none, json, html, or both.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=2)
+
+    allowed_severities = {"critical", "high", "medium", "low", "none"}
+    if fail_on not in allowed_severities:
+        typer.secho(
+            "Invalid --fail-on value. Choose: critical, high, medium, low, or none.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=2)
+
+    if output and report_format not in {"json", "html"}:
+        typer.secho(
+            "--output can only be used with --format json or --format html. "
+            "Use --format both to generate both default report files.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=2)
+
+    # Run the existing scanner.
+    findings = scan_path(path)
+
+    # Preserve the existing terminal output, including context snippets.
+    if not findings:
+        typer.secho("✔ No secrets found.", fg=typer.colors.GREEN)
+    else:
+        typer.secho(
+            f"⚠ {len(findings)} finding(s) detected:\n",
+            fg=typer.colors.YELLOW,
+            bold=True,
+        )
+
+        for finding in sorted(
+            findings,
+            key=lambda item: item.severity.rank,
+            reverse=True,
+        ):
+            typer.echo(
+                f"[{finding.severity.value.upper():8}] "
+                f"{finding.rule_name} "
+                f"({finding.confidence}% confidence) - "
+                f"{finding.file_path}:{finding.line_number}"
+            )
+            # Retains the existing context display and masking behavior.
+            typer.echo(f"          {finding.context_line}")
+
+    # Generate the requested report(s).
+    json_out: str | None = None
+    html_out: str | None = None
+
+    if report_format == "json":
+        json_out = output or "credhunter-report.json"
+    elif report_format == "html":
+        html_out = output or "credhunter-report.html"
+    elif report_format == "both":
+        json_out = "credhunter-report.json"
+        html_out = "credhunter-report.html"
+
+    if json_out:
+        generate_json_report(findings, json_out)
+        typer.echo(f"\nJSON report written to {json_out}")
+
+    if html_out:
+        generate_html_report(findings, html_out)
+        typer.echo(f"HTML report written to {html_out}")
+
+    # Preserve severity-based exit behavior for local use and CI/CD.
+    should_fail = False
+
+    if fail_on != "none":
+        threshold = Severity(fail_on)
+        should_fail = any(
+            finding.severity.rank >= threshold.rank
+            for finding in findings
+        )
+
+        if should_fail:
+            typer.secho(
+                f"\n✘ Failing: findings at or above '{fail_on}' "
+                "severity were detected.",
+                fg=typer.colors.RED,
+                bold=True,
+            )
+
+    # Open the generated HTML report only in an interactive local session.
+    # CI/CD runs and redirected/piped output will not trigger a browser.
+    if html_out and _is_interactive_session():
+        try:
+            report_path = Path(html_out).resolve()
+            webbrowser.open_new_tab(report_path.as_uri())
+        except Exception as exc:
+            typer.secho(
+                f"Warning: could not open the HTML report automatically: {exc}",
+                fg=typer.colors.YELLOW,
+                err=True,
+            )
+            typer.echo(f"You can open it manually: {Path(html_out).resolve()}")
+
+    # Keep CI/CD integration: return a non-zero status when the configured
+    # severity threshold is met or exceeded.
+    raise typer.Exit(code=1 if should_fail else 0)
+
+
+if __name__ == "__main__":
+    app()
+
+
+
+
+
+
+
+
+
+# """
+# Command-line interface.
+
+# Usage:
+#     python -m credhunter.cli scan <path>
+#     python -m credhunter.cli scan <path> --json report.json --html report.html
+#     python -m credhunter.cli scan <path> --fail-on high
+# """
+
+# import os
+# import sys
+# import webbrowser
+# from pathlib import Path
+
+# import typer
+
+# from importlib.metadata import PackageNotFoundError, version as package_version
+
+# from .models import Severity
+# from .reporters.html_reporter import generate_html_report
+# from .reporters.json_reporter import generate_json_report
+# from .scanner import scan_path
+
+# app = typer.Typer(help="credhunter: scan source code for hardcoded secrets.")
+
+# # Environment variables that CI/CD systems set automatically.
+# CI_ENV_VARS = ("CI", "GITHUB_ACTIONS", "GITLAB_CI", "JENKINS_URL", "TF_BUILD")
+
+# def version_callback(value: bool) -> None:
+#     if not value:
+#         return
+
+#     try:
+#         current_version = package_version("credhunter")
+#     except PackageNotFoundError:
+#         current_version = "unknown"
+
+#     typer.echo(f"credhunter version {current_version}")
+#     raise typer.Exit()
+
+# def _is_interactive_session() -> bool:
+#     """
+#     True only when a person is sitting at a terminal. False in CI/CD, and
+#     false when the output is piped or redirected, so a pipeline never tries
+#     to open a browser.
+#     """
+#     running_in_ci = any(os.environ.get(name) for name in CI_ENV_VARS)
+#     return sys.stdout.isatty() and not running_in_ci
+
+
+# @app.command()
+# def scan(
+#     path: str = typer.Argument(..., help="File or directory to scan."),
+#     json_out: str = typer.Option(None, "--json", help="Write a JSON report to this path."),
+#     html_out: str = typer.Option(None, "--html", help="Write an HTML report to this path."),
+#     fail_on: str = typer.Option(
+#         "high", "--fail-on",
+#         help="Minimum severity that causes a non-zero exit code: critical, high, medium, low, none.",
+#     ),
+#     version: bool = typer.Option(
+#         False,
+#         "--version",
+#         callback=version_callback,
+#         is_eager=True,
+#         help="Show the installed credhunter version and exit.",
+#     ),
+# ):
+#     """Scan PATH for hardcoded secrets and print/report the findings."""
+#     findings = scan_path(path)
+
+#     if not findings:
+#         typer.secho("✔ No secrets found.", fg=typer.colors.GREEN)
+#     else:
+#         typer.secho(f"⚠ {len(findings)} finding(s) detected:\n", fg=typer.colors.YELLOW, bold=True)
+#         for f in sorted(findings, key=lambda x: x.severity.rank, reverse=True):
+#             typer.echo(
+#                 f"[{f.severity.value.upper():8}] {f.rule_name} "
+#                 f"({f.confidence}% confidence) - {f.file_path}:{f.line_number}"
+#             )
+#             typer.echo(f"          {f.context_line}")
+
+#     if json_out:
+#         generate_json_report(findings, json_out)
+#         typer.echo(f"\nJSON report written to {json_out}")
+
+#     if html_out:
+#         generate_html_report(findings, html_out)
+#         typer.echo(f"HTML report written to {html_out}")
+
+#     should_fail = False
+#     if fail_on.lower() != "none":
+#         threshold = Severity(fail_on.lower())
+#         should_fail = any(f.severity.rank >= threshold.rank for f in findings)
+#         if should_fail:
+#             typer.secho(
+#                 f"\n✘ Failing: findings at or above '{fail_on}' severity were detected.",
+#                 fg=typer.colors.RED, bold=True,
+#             )
+
+#     # Show the HTML report in the default web browser. Only when a person ran
+#     # this at a terminal - never in CI/CD, so pipelines are not affected.
+#     if html_out and _is_interactive_session():
+#         webbrowser.open_new_tab(Path(html_out).resolve().as_uri())
+
+#     sys.exit(1 if should_fail else 0)
+
+
+# if __name__ == "__main__":
+#     app()
+
+
+
+
+
+
+
+
+
+
+

secretguard/detectors/context.py

@@ -0,0 +1,29 @@
+"""
+Context analysis: a regex match on its own is weak evidence. A line that
+also contains a relevant keyword (password, api_key, token, secret, ...)
+is much more likely to be a real credential than coincidental text.
+"""
+
+GENERIC_SECRET_KEYWORDS = [
+    "password", "passwd", "pwd",
+    "secret", "token", "api_key", "apikey",
+    "access_key", "access_token", "credential",
+    "authorization", "auth_token", "private_key",
+    "client_secret", "session_key",
+]
+
+
+def has_context_keywords(line: str, keywords: list[str] | None = None) -> bool:
+    """Case-insensitive check for whether any relevant keyword appears on the line."""
+    line_lower = line.lower()
+    keyword_list = keywords if keywords else GENERIC_SECRET_KEYWORDS
+    return any(keyword.lower() in line_lower for keyword in keyword_list)
+
+
+def is_placeholder(value: str, placeholder_markers: list[str]) -> bool:
+    """
+    Check whether a matched value looks like a placeholder/example rather
+    than a real secret (e.g. 'your_api_key_here', 'AKIAFAKEEXAMPLE...').
+    """
+    value_lower = value.lower()
+    return any(marker.lower() in value_lower for marker in placeholder_markers)