leakhound 0.1.0__tar.gz

leakhound-0.1.0/.github/workflows/pypi.yml

@@ -0,0 +1,73 @@
+name: PyPI
+
+# Build native wheels on every OS (leakhound is a compiled C++ binary, so there
+# is no pure-Python wheel) plus an sdist, then publish to PyPI via Trusted
+# Publishing on a version tag. No API token needed.
+#
+# One-time setup on PyPI: add a Trusted Publisher for project `leakhound` ->
+# owner `Makeph`, repo `leakhound`, workflow `pypi.yml`, environment `pypi`.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  wheels:
+    name: wheel (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # macos-14 -> arm64, windows -> amd64. Linux and Intel-mac binary wheels
+        # are intentionally omitted: `python -m build` on a plain ubuntu runner
+        # emits a raw `linux_x86_64` tag that PyPI rejects (it requires
+        # manylinux, which needs cibuildwheel), and the macos-13 runner queue
+        # stalls for hours. Linux/Intel-mac users install from the sdist.
+        os: [macos-14, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build --wheel
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheel-${{ matrix.os }}
+          path: dist/*.whl
+
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: |
+          python -m pip install --upgrade build
+          python -m build --sdist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  publish:
+    name: publish to PyPI
+    needs: [wheels, sdist]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

leakhound-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+build/
+out/
+*.exe
+*.obj
+*.pdb
+*.ilk
+*.user
+*.suo
+*.ninja
+CMakeCache.txt
+CMakeFiles/
+Testing/
+_deps/

leakhound-0.1.0/CMakeLists.txt

@@ -0,0 +1,26 @@
+cmake_minimum_required(VERSION 3.15)
+project(leakhound LANGUAGES CXX)
+
+add_executable(leakhound src/leakhound.cpp)
+target_compile_features(leakhound PRIVATE cxx_std_17)
+set_target_properties(leakhound PROPERTIES
+    CXX_STANDARD 17
+    CXX_STANDARD_REQUIRED YES
+    CXX_EXTENSIONS NO
+)
+
+if(MSVC)
+    target_compile_options(leakhound PRIVATE /W4)
+else()
+    target_compile_options(leakhound PRIVATE -Wall -Wextra)
+endif()
+
+# Install rule -- used by scikit-build-core to place the binary as a pip
+# console script (SKBUILD_SCRIPTS_DIR), and by a normal `cmake --install`
+# otherwise. Harmless to a plain `cmake --build`.
+include(GNUInstallDirs)
+if(DEFINED SKBUILD_SCRIPTS_DIR)
+    install(TARGETS leakhound RUNTIME DESTINATION "${SKBUILD_SCRIPTS_DIR}")
+else()
+    install(TARGETS leakhound RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}")
+endif()

leakhound-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Makeph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

leakhound-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.1
+Name: leakhound
+Version: 0.1.0
+Summary: Zero-dependency C++17 secret scanner - AWS/GitHub/Slack/Stripe keys, PEM, JWTs, entropy heuristics. Single binary, CI-friendly exit codes.
+Keywords: secrets,scanner,security,secret-detection,credentials,cli
+Author: Makeph
+License: MIT
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: C++
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Project-URL: Homepage, https://github.com/Makeph/leakhound
+Project-URL: Repository, https://github.com/Makeph/leakhound
+Project-URL: Issues, https://github.com/Makeph/leakhound/issues
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# leakhound
+
+`leakhound` is a fast local credential and secret scanner. It is a single C++17
+binary with no external dependencies.
+
+## Build
+
+With CMake:
+
+```sh
+cmake -S . -B build
+cmake --build build --config Release
+```
+
+On Windows with the MSVC command prompt:
+
+```bat
+build.bat
+```
+
+The batch file runs:
+
+```bat
+cl /std:c++17 /O2 /W4 /EHsc src\leakhound.cpp /Fe:leakhound.exe
+```
+
+## Usage
+
+```text
+leakhound [options] <path>...
+  --json           machine-readable output (one JSON object, findings array)
+  --no-entropy     disable entropy heuristics (pattern rules only)
+  --max-size N     skip files larger than N bytes (default 2 MiB)
+  --quiet          suppress per-finding lines, print summary only
+  -h, --help       usage
+```
+
+Paths may be files or directories. Directories are scanned recursively, while
+common generated or dependency directories such as `.git`, `node_modules`,
+`vendor`, `dist`, `build`, `target`, `__pycache__`, `.venv`, and `venv` are
+skipped.
+
+Default output:
+
+```text
+HIGH aws-access-key path/to/file.txt:12  AKIA12...CDEF
+Summary: files scanned=4, files skipped=1, HIGH=1, MEDIUM=0, LOW=0, wall time=3ms
+```
+
+JSON output:
+
+```sh
+leakhound --json .
+```
+
+## Rules
+
+| Rule ID | Severity | Pattern |
+| --- | --- | --- |
+| `aws-access-key` | HIGH | `AKIA[0-9A-Z]{16}` |
+| `github-token` | HIGH | `gh[pousr]_[A-Za-z0-9]{36,}` |
+| `slack-token` | HIGH | `xox[baprs]-[A-Za-z0-9-]{10,}` |
+| `stripe-live-key` | HIGH | `sk_live_[A-Za-z0-9]{16,}` |
+| `private-key-pem` | HIGH | PEM private key header lines |
+| `google-api-key` | HIGH | `AIza[0-9A-Za-z_-]{35}` |
+| `npm-token` | HIGH | `npm_[A-Za-z0-9]{36}` |
+| `jwt` | MEDIUM | JWT-shaped three-part token |
+| `generic-assignment` | MEDIUM | Secret-like key assigned to a quoted non-placeholder value |
+| `high-entropy-token` | LOW | High-entropy mixed-case token heuristic |
+
+The entropy heuristic tokenizes each line into runs of
+`[A-Za-z0-9+/=_-]` from 24 to 128 characters, then flags tokens with Shannon
+entropy greater than 4.5 bits per character that contain at least one digit and
+mixed case. Use `--no-entropy` to disable this tier.
+
+## Exit Codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Scan completed with no findings |
+| 1 | Scan completed with findings |
+| 2 | Usage or IO error |
+
+## Tests
+
+```sh
+python tests/run_tests.py
+```
+
+The test runner builds temporary fixtures, runs the scanner, checks exit codes,
+validates JSON output, verifies redaction and placeholder rejection, and checks
+binary, directory, and max-size skipping. If no compiler is available, set
+`LEAKHOUND_BIN` to an existing scanner binary.

leakhound-0.1.0/README.md

@@ -0,0 +1,93 @@
+# leakhound
+
+`leakhound` is a fast local credential and secret scanner. It is a single C++17
+binary with no external dependencies.
+
+## Build
+
+With CMake:
+
+```sh
+cmake -S . -B build
+cmake --build build --config Release
+```
+
+On Windows with the MSVC command prompt:
+
+```bat
+build.bat
+```
+
+The batch file runs:
+
+```bat
+cl /std:c++17 /O2 /W4 /EHsc src\leakhound.cpp /Fe:leakhound.exe
+```
+
+## Usage
+
+```text
+leakhound [options] <path>...
+  --json           machine-readable output (one JSON object, findings array)
+  --no-entropy     disable entropy heuristics (pattern rules only)
+  --max-size N     skip files larger than N bytes (default 2 MiB)
+  --quiet          suppress per-finding lines, print summary only
+  -h, --help       usage
+```
+
+Paths may be files or directories. Directories are scanned recursively, while
+common generated or dependency directories such as `.git`, `node_modules`,
+`vendor`, `dist`, `build`, `target`, `__pycache__`, `.venv`, and `venv` are
+skipped.
+
+Default output:
+
+```text
+HIGH aws-access-key path/to/file.txt:12  AKIA12...CDEF
+Summary: files scanned=4, files skipped=1, HIGH=1, MEDIUM=0, LOW=0, wall time=3ms
+```
+
+JSON output:
+
+```sh
+leakhound --json .
+```
+
+## Rules
+
+| Rule ID | Severity | Pattern |
+| --- | --- | --- |
+| `aws-access-key` | HIGH | `AKIA[0-9A-Z]{16}` |
+| `github-token` | HIGH | `gh[pousr]_[A-Za-z0-9]{36,}` |
+| `slack-token` | HIGH | `xox[baprs]-[A-Za-z0-9-]{10,}` |
+| `stripe-live-key` | HIGH | `sk_live_[A-Za-z0-9]{16,}` |
+| `private-key-pem` | HIGH | PEM private key header lines |
+| `google-api-key` | HIGH | `AIza[0-9A-Za-z_-]{35}` |
+| `npm-token` | HIGH | `npm_[A-Za-z0-9]{36}` |
+| `jwt` | MEDIUM | JWT-shaped three-part token |
+| `generic-assignment` | MEDIUM | Secret-like key assigned to a quoted non-placeholder value |
+| `high-entropy-token` | LOW | High-entropy mixed-case token heuristic |
+
+The entropy heuristic tokenizes each line into runs of
+`[A-Za-z0-9+/=_-]` from 24 to 128 characters, then flags tokens with Shannon
+entropy greater than 4.5 bits per character that contain at least one digit and
+mixed case. Use `--no-entropy` to disable this tier.
+
+## Exit Codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Scan completed with no findings |
+| 1 | Scan completed with findings |
+| 2 | Usage or IO error |
+
+## Tests
+
+```sh
+python tests/run_tests.py
+```
+
+The test runner builds temporary fixtures, runs the scanner, checks exit codes,
+validates JSON output, verifies redaction and placeholder rejection, and checks
+binary, directory, and max-size skipping. If no compiler is available, set
+`LEAKHOUND_BIN` to an existing scanner binary.

leakhound-0.1.0/SPEC.md

@@ -0,0 +1,82 @@
+# leakhound — spec
+
+Fast credential/secret scanner. Single static binary, C++17, **zero external
+dependencies** (standard library only). Target compilers: MSVC 2022 (`cl`) and
+g++/clang. Must compile warning-clean at `/W4` / `-Wall -Wextra`.
+
+## CLI
+
+```
+leakhound [options] <path>...
+  --json           machine-readable output (one JSON object, findings array)
+  --no-entropy     disable entropy heuristics (pattern rules only)
+  --max-size N     skip files larger than N bytes (default 2 MiB)
+  --quiet          suppress per-finding lines, print summary only
+  -h, --help       usage
+```
+
+- Paths may be files or directories (recursed).
+- Exit code: 0 = no findings, 1 = findings, 2 = usage/IO error.
+
+## Scanning behavior
+
+- Skip directories named: `.git`, `node_modules`, `vendor`, `dist`, `build`,
+  `target`, `__pycache__`, `.venv`, `venv`.
+- Skip binary files: if the first 4096 bytes contain a NUL byte.
+- Read files in one shot (they are capped by --max-size).
+- Track line numbers for findings.
+
+## Detection rules (pattern tier — high confidence)
+
+Implement with hand-rolled matchers or std::regex, whichever is cleaner, but
+each rule gets an id, a human name, and a severity (HIGH/MEDIUM):
+
+1. `aws-access-key`   — `AKIA[0-9A-Z]{16}` (HIGH)
+2. `github-token`     — `gh[pousr]_[A-Za-z0-9]{36,}` (HIGH)
+3. `slack-token`      — `xox[baprs]-[A-Za-z0-9-]{10,}` (HIGH)
+4. `stripe-live-key`  — `sk_live_[A-Za-z0-9]{16,}` (HIGH)
+5. `private-key-pem`  — line containing `-----BEGIN` + (`RSA`|`EC`|`OPENSSH`|`DSA`|`PGP`)? + `PRIVATE KEY` (HIGH)
+6. `google-api-key`   — `AIza[0-9A-Za-z_-]{35}` (HIGH)
+7. `npm-token`        — `npm_[A-Za-z0-9]{36}` (HIGH)
+8. `jwt`              — `eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{5,}` (MEDIUM)
+9. `generic-assignment` — key names (`api_key`, `apikey`, `secret`, `token`,
+   `passwd`, `password`, `auth`) followed by `=` or `:` and a quoted literal
+   of 12+ chars that is not an obvious placeholder (reject values containing
+   `example`, `changeme`, `placeholder`, `xxxx`, `your_`, `<`, `>`, `${`, `%s`) (MEDIUM)
+
+## Entropy tier (heuristic — LOW severity)
+
+- Tokenize each line into runs of `[A-Za-z0-9+/=_-]` of length 24–128.
+- Shannon entropy over the token's bytes; flag when > 4.5 bits/char and the
+  token contains at least one digit and mixed case (cuts English-word noise).
+- Skip tokens already covered by a pattern finding on the same line.
+- Skip lines that look like lockfile/hash noise: filename ends in
+  `.lock`, `-lock.json`, `.sum`, or line contains `integrity` or `sha512-`.
+
+## Output
+
+Console (default): `SEVERITY rule-id path:line  <match, redacted>`.
+Redaction: show first 6 and last 4 chars of the match, `…` between.
+Summary line: files scanned, files skipped, findings by severity, wall time.
+JSON mode: `{"version":1,"findings":[{"rule","severity","path","line","redacted"}...],"stats":{...}}`.
+No color codes in --json mode. Console colors via ANSI only when stdout is a
+TTY (use `_isatty(_fileno(stdout))` on Windows, `isatty(1)` elsewhere; enable
+VT processing on Windows with SetConsoleMode).
+
+## Layout
+
+```
+src/leakhound.cpp     (single translation unit is fine; keep functions small)
+tests/run_tests.py    (python3: builds fixtures in a temp dir, runs the binary,
+                       asserts exit codes, finding counts, JSON validity,
+                       redaction, placeholder rejection, binary/dir skipping)
+CMakeLists.txt        (minimal, C++17, /W4 or -Wall -Wextra)
+build.bat             (MSVC one-liner fallback: cl /std:c++17 /O2 /W4 /EHsc src\leakhound.cpp /Fe:leakhound.exe)
+README.md             (usage, rules table, exit codes, build instructions)
+.gitignore            (build artifacts)
+```
+
+## Non-goals
+
+Do not add: config files, network calls, git history scanning, multithreading
+(keep it simple; it is IO-bound at typical repo sizes).

leakhound-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["scikit-build-core>=0.8"]
+build-backend = "scikit_build_core.build"
+
+[project]
+name = "leakhound"
+version = "0.1.0"
+description = "Zero-dependency C++17 secret scanner - AWS/GitHub/Slack/Stripe keys, PEM, JWTs, entropy heuristics. Single binary, CI-friendly exit codes."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Makeph" }]
+keywords = ["secrets", "scanner", "security", "secret-detection", "credentials", "cli"]
+classifiers = [
+    "Environment :: Console",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: C++",
+    "Topic :: Security",
+    "Topic :: Software Development :: Quality Assurance",
+]
+
+[project.urls]
+Homepage = "https://github.com/Makeph/leakhound"
+Repository = "https://github.com/Makeph/leakhound"
+Issues = "https://github.com/Makeph/leakhound/issues"
+
+[tool.scikit-build]
+# This wheel ships a compiled binary, not a Python module, so it is
+# Python-version independent (one wheel per platform).
+wheel.py-api = "py3"
+wheel.packages = []
+cmake.version = ">=3.15"
+minimum-version = "0.8"
+
+[tool.scikit-build.sdist]
+# Only the sources needed to build; keep prebuilt junk out of the sdist.
+include = ["src/**", "tests/**", "CMakeLists.txt", "README.md", "SPEC.md", "LICENSE"]
+exclude = ["*.exe", "*.obj", "build/**", "build.bat"]

leakhound-0.1.0/src/leakhound.cpp

@@ -0,0 +1,683 @@
+#include <chrono>
+#include <cmath>
+#include <cstddef>
+#include <cstdio>
+#include <cstdint>
+#include <filesystem>
+#include <fstream>
+#include <iostream>
+#include <limits>
+#include <regex>
+#include <sstream>
+#include <string>
+#include <vector>
+
+#ifdef _WIN32
+#define NOMINMAX
+#include <io.h>
+#include <windows.h>
+#else
+#include <unistd.h>
+#endif
+
+namespace fs = std::filesystem;
+
+namespace {
+
+enum class Severity {
+    High,
+    Medium,
+    Low
+};
+
+struct Options {
+    bool json = false;
+    bool entropy = true;
+    bool quiet = false;
+    std::uintmax_t max_size = 2U * 1024U * 1024U;
+    std::vector<fs::path> paths;
+};
+
+struct Rule {
+    std::string id;
+    std::string name;
+    Severity severity;
+    std::regex pattern;
+};
+
+struct Finding {
+    std::string rule;
+    Severity severity;
+    std::string path;
+    std::size_t line = 0;
+    std::string redacted;
+};
+
+struct Span {
+    std::size_t begin = 0;
+    std::size_t end = 0;
+};
+
+struct Stats {
+    std::size_t files_scanned = 0;
+    std::size_t files_skipped = 0;
+    std::size_t high = 0;
+    std::size_t medium = 0;
+    std::size_t low = 0;
+    long long duration_ms = 0;
+};
+
+struct ScanResult {
+    std::vector<Finding> findings;
+    Stats stats;
+    bool io_error = false;
+};
+
+std::string severity_to_string(Severity severity) {
+    switch (severity) {
+    case Severity::High:
+        return "HIGH";
+    case Severity::Medium:
+        return "MEDIUM";
+    case Severity::Low:
+        return "LOW";
+    }
+    return "LOW";
+}
+
+const char *severity_color(Severity severity) {
+    switch (severity) {
+    case Severity::High:
+        return "\033[31m";
+    case Severity::Medium:
+        return "\033[33m";
+    case Severity::Low:
+        return "\033[36m";
+    }
+    return "";
+}
+
+bool stdout_is_tty() {
+#ifdef _WIN32
+    return _isatty(_fileno(stdout)) != 0;
+#else
+    return isatty(1) != 0;
+#endif
+}
+
+void enable_ansi_if_possible() {
+#ifdef _WIN32
+    HANDLE handle = GetStdHandle(STD_OUTPUT_HANDLE);
+    if (handle == INVALID_HANDLE_VALUE) {
+        return;
+    }
+    DWORD mode = 0;
+    if (GetConsoleMode(handle, &mode) == 0) {
+        return;
+    }
+    mode |= ENABLE_VIRTUAL_TERMINAL_PROCESSING;
+    static_cast<void>(SetConsoleMode(handle, mode));
+#endif
+}
+
+std::string usage() {
+    return "leakhound [options] <path>...\n"
+           "  --json           machine-readable output (one JSON object, findings array)\n"
+           "  --no-entropy     disable entropy heuristics (pattern rules only)\n"
+           "  --max-size N     skip files larger than N bytes (default 2 MiB)\n"
+           "  --quiet          suppress per-finding lines, print summary only\n"
+           "  -h, --help       usage\n";
+}
+
+bool parse_uintmax(const std::string &text, std::uintmax_t &value) {
+    if (text.empty()) {
+        return false;
+    }
+    std::uintmax_t result = 0;
+    for (char ch : text) {
+        if (ch < '0' || ch > '9') {
+            return false;
+        }
+        const std::uintmax_t digit = static_cast<std::uintmax_t>(ch - '0');
+        if (result > (std::numeric_limits<std::uintmax_t>::max() - digit) / 10U) {
+            return false;
+        }
+        result = result * 10U + digit;
+    }
+    value = result;
+    return true;
+}
+
+bool parse_args(int argc, char **argv, Options &options, bool &help, std::string &error) {
+    help = false;
+    for (int i = 1; i < argc; ++i) {
+        const std::string arg(argv[i]);
+        if (arg == "--json") {
+            options.json = true;
+        } else if (arg == "--no-entropy") {
+            options.entropy = false;
+        } else if (arg == "--quiet") {
+            options.quiet = true;
+        } else if (arg == "-h" || arg == "--help") {
+            help = true;
+            return true;
+        } else if (arg == "--max-size") {
+            if (i + 1 >= argc) {
+                error = "--max-size requires a value";
+                return false;
+            }
+            ++i;
+            if (!parse_uintmax(argv[i], options.max_size)) {
+                error = "--max-size must be a non-negative integer";
+                return false;
+            }
+        } else if (!arg.empty() && arg[0] == '-') {
+            error = "unknown option: " + arg;
+            return false;
+        } else {
+            options.paths.push_back(fs::path(arg));
+        }
+    }
+    if (options.paths.empty()) {
+        error = "at least one path is required";
+        return false;
+    }
+    return true;
+}
+
+std::vector<Rule> build_rules() {
+    const std::regex::flag_type flags = std::regex::ECMAScript;
+    std::vector<Rule> rules;
+    rules.push_back({"aws-access-key", "AWS access key", Severity::High,
+                     std::regex("AKIA[0-9A-Z]{16}", flags)});
+    rules.push_back({"github-token", "GitHub token", Severity::High,
+                     std::regex("gh[pousr]_[A-Za-z0-9]{36,}", flags)});
+    rules.push_back({"slack-token", "Slack token", Severity::High,
+                     std::regex("xox[baprs]-[A-Za-z0-9-]{10,}", flags)});
+    rules.push_back({"stripe-live-key", "Stripe live key", Severity::High,
+                     std::regex("sk_live_[A-Za-z0-9]{16,}", flags)});
+    rules.push_back({"private-key-pem", "Private key PEM", Severity::High,
+                     std::regex("-----BEGIN (RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY", flags)});
+    rules.push_back({"google-api-key", "Google API key", Severity::High,
+                     std::regex("AIza[0-9A-Za-z_-]{35}", flags)});
+    rules.push_back({"npm-token", "npm token", Severity::High,
+                     std::regex("npm_[A-Za-z0-9]{36}", flags)});
+    rules.push_back({"jwt", "JWT", Severity::Medium,
+                     std::regex("eyJ[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{5,}", flags)});
+    return rules;
+}
+
+bool is_skipped_directory_name(const fs::path &path) {
+    const std::string name = path.filename().string();
+    static const char *const skipped[] = {
+        ".git", "node_modules", "vendor", "dist", "build",
+        "target", "__pycache__", ".venv", "venv"};
+    for (const char *entry : skipped) {
+        if (name == entry) {
+            return true;
+        }
+    }
+    return false;
+}
+
+std::string to_lower_ascii(std::string text) {
+    for (char &ch : text) {
+        if (ch >= 'A' && ch <= 'Z') {
+            ch = static_cast<char>(ch - 'A' + 'a');
+        }
+    }
+    return text;
+}
+
+bool contains_placeholder(const std::string &value) {
+    const std::string lower = to_lower_ascii(value);
+    static const char *const placeholders[] = {
+        "example", "changeme", "placeholder", "xxxx", "your_", "<", ">", "${", "%s"};
+    for (const char *placeholder : placeholders) {
+        if (lower.find(placeholder) != std::string::npos) {
+            return true;
+        }
+    }
+    return false;
+}
+
+std::string redact(const std::string &text) {
+    if (text.size() <= 10U) {
+        return text;
+    }
+    return text.substr(0U, 6U) + "\xE2\x80\xA6" + text.substr(text.size() - 4U);
+}
+
+std::string json_escape(const std::string &text) {
+    std::ostringstream out;
+    for (unsigned char ch : text) {
+        switch (ch) {
+        case '"':
+            out << "\\\"";
+            break;
+        case '\\':
+            out << "\\\\";
+            break;
+        case '\b':
+            out << "\\b";
+            break;
+        case '\f':
+            out << "\\f";
+            break;
+        case '\n':
+            out << "\\n";
+            break;
+        case '\r':
+            out << "\\r";
+            break;
+        case '\t':
+            out << "\\t";
+            break;
+        default:
+            if (ch < 0x20U) {
+                static const char digits[] = "0123456789abcdef";
+                out << "\\u00" << digits[(ch >> 4U) & 0x0FU] << digits[ch & 0x0FU];
+            } else {
+                out << static_cast<char>(ch);
+            }
+            break;
+        }
+    }
+    return out.str();
+}
+
+void add_finding(ScanResult &result,
+                 const std::string &rule,
+                 Severity severity,
+                 const std::string &path,
+                 std::size_t line,
+                 const std::string &match) {
+    Finding finding;
+    finding.rule = rule;
+    finding.severity = severity;
+    finding.path = path;
+    finding.line = line;
+    finding.redacted = redact(match);
+    result.findings.push_back(finding);
+    if (severity == Severity::High) {
+        ++result.stats.high;
+    } else if (severity == Severity::Medium) {
+        ++result.stats.medium;
+    } else {
+        ++result.stats.low;
+    }
+}
+
+bool spans_overlap(std::size_t begin, std::size_t end, const std::vector<Span> &spans) {
+    for (const Span &span : spans) {
+        if (begin < span.end && end > span.begin) {
+            return true;
+        }
+    }
+    return false;
+}
+
+bool is_binary_file(const fs::path &path, bool &io_error) {
+    std::ifstream input(path, std::ios::binary);
+    if (!input) {
+        io_error = true;
+        return false;
+    }
+    char buffer[4096];
+    input.read(buffer, sizeof(buffer));
+    const std::streamsize read_count = input.gcount();
+    for (std::streamsize i = 0; i < read_count; ++i) {
+        if (buffer[static_cast<std::size_t>(i)] == '\0') {
+            return true;
+        }
+    }
+    return false;
+}
+
+bool read_file(const fs::path &path, std::uintmax_t size, std::string &content) {
+    if (size > static_cast<std::uintmax_t>(std::numeric_limits<std::size_t>::max()) ||
+        size > static_cast<std::uintmax_t>(std::numeric_limits<std::streamsize>::max())) {
+        return false;
+    }
+    std::ifstream input(path, std::ios::binary);
+    if (!input) {
+        return false;
+    }
+    content.resize(static_cast<std::size_t>(size));
+    if (!content.empty()) {
+        input.read(&content[0], static_cast<std::streamsize>(content.size()));
+        if (input.gcount() != static_cast<std::streamsize>(content.size())) {
+            return false;
+        }
+    }
+    return true;
+}
+
+bool should_skip_entropy_line(const std::string &path, const std::string &line) {
+    const std::string lower_path = to_lower_ascii(path);
+    const std::string lower_line = to_lower_ascii(line);
+    if (lower_path.size() >= 5U && lower_path.compare(lower_path.size() - 5U, 5U, ".lock") == 0) {
+        return true;
+    }
+    if (lower_path.size() >= 10U && lower_path.compare(lower_path.size() - 10U, 10U, "-lock.json") == 0) {
+        return true;
+    }
+    if (lower_path.size() >= 4U && lower_path.compare(lower_path.size() - 4U, 4U, ".sum") == 0) {
+        return true;
+    }
+    return lower_line.find("integrity") != std::string::npos ||
+           lower_line.find("sha512-") != std::string::npos;
+}
+
+bool is_token_char(char ch) {
+    return (ch >= 'A' && ch <= 'Z') ||
+           (ch >= 'a' && ch <= 'z') ||
+           (ch >= '0' && ch <= '9') ||
+           ch == '+' || ch == '/' || ch == '=' || ch == '_' || ch == '-';
+}
+
+double shannon_entropy(const std::string &token) {
+    int counts[256] = {};
+    for (unsigned char ch : token) {
+        ++counts[ch];
+    }
+    double entropy = 0.0;
+    const double length = static_cast<double>(token.size());
+    for (int count : counts) {
+        if (count > 0) {
+            const double probability = static_cast<double>(count) / length;
+            entropy -= probability * std::log2(probability);
+        }
+    }
+    return entropy;
+}
+
+bool has_digit_and_mixed_case(const std::string &token) {
+    bool digit = false;
+    bool lower = false;
+    bool upper = false;
+    for (char ch : token) {
+        if (ch >= '0' && ch <= '9') {
+            digit = true;
+        } else if (ch >= 'a' && ch <= 'z') {
+            lower = true;
+        } else if (ch >= 'A' && ch <= 'Z') {
+            upper = true;
+        }
+    }
+    return digit && lower && upper;
+}
+
+void scan_entropy_line(ScanResult &result,
+                       const std::string &path,
+                       const std::string &line,
+                       std::size_t line_number,
+                       const std::vector<Span> &covered_spans) {
+    if (should_skip_entropy_line(path, line)) {
+        return;
+    }
+
+    std::size_t index = 0;
+    while (index < line.size()) {
+        while (index < line.size() && !is_token_char(line[index])) {
+            ++index;
+        }
+        const std::size_t begin = index;
+        while (index < line.size() && is_token_char(line[index])) {
+            ++index;
+        }
+        const std::size_t end = index;
+        const std::size_t length = end - begin;
+        if (length >= 24U && length <= 128U && !spans_overlap(begin, end, covered_spans)) {
+            const std::string token = line.substr(begin, length);
+            if (has_digit_and_mixed_case(token) && shannon_entropy(token) > 4.5) {
+                add_finding(result, "high-entropy-token", Severity::Low, path, line_number, token);
+            }
+        }
+    }
+}
+
+void scan_line(ScanResult &result,
+               const std::vector<Rule> &rules,
+               const Options &options,
+               const std::string &path,
+               const std::string &line,
+               std::size_t line_number) {
+    std::vector<Span> covered_spans;
+    for (const Rule &rule : rules) {
+        std::sregex_iterator it(line.begin(), line.end(), rule.pattern);
+        const std::sregex_iterator end;
+        for (; it != end; ++it) {
+            const std::smatch match = *it;
+            const std::size_t begin = static_cast<std::size_t>(match.position(0));
+            const std::size_t length = static_cast<std::size_t>(match.length(0));
+            covered_spans.push_back({begin, begin + length});
+            add_finding(result, rule.id, rule.severity, path, line_number, match.str(0));
+        }
+    }
+
+    static const std::regex assignment_pattern(
+        "\\b(api_key|apikey|secret|token|passwd|password|auth)\\b[ \\t]*[=:][ \\t]*([\"'])([^\"']{12,})\\2",
+        std::regex::ECMAScript | std::regex::icase);
+    std::sregex_iterator assignment_it(line.begin(), line.end(), assignment_pattern);
+    const std::sregex_iterator assignment_end;
+    for (; assignment_it != assignment_end; ++assignment_it) {
+        const std::smatch match = *assignment_it;
+        const std::string value = match.str(3);
+        const std::size_t begin = static_cast<std::size_t>(match.position(3));
+        const std::size_t length = static_cast<std::size_t>(match.length(3));
+        // a value already matched by a specific pattern rule is reported once,
+        // under the more precise rule
+        if (!contains_placeholder(value) && !spans_overlap(begin, begin + length, covered_spans)) {
+            covered_spans.push_back({begin, begin + length});
+            add_finding(result, "generic-assignment", Severity::Medium, path, line_number, value);
+        }
+    }
+
+    if (options.entropy) {
+        scan_entropy_line(result, path, line, line_number, covered_spans);
+    }
+}
+
+void scan_content(ScanResult &result,
+                  const std::vector<Rule> &rules,
+                  const Options &options,
+                  const std::string &path,
+                  const std::string &content) {
+    std::size_t line_number = 1;
+    std::size_t begin = 0;
+    while (begin <= content.size()) {
+        std::size_t end = content.find('\n', begin);
+        if (end == std::string::npos) {
+            end = content.size();
+        }
+        std::string line = content.substr(begin, end - begin);
+        if (!line.empty() && line[line.size() - 1U] == '\r') {
+            line.erase(line.size() - 1U);
+        }
+        scan_line(result, rules, options, path, line, line_number);
+        if (end == content.size()) {
+            break;
+        }
+        begin = end + 1U;
+        ++line_number;
+    }
+}
+
+void scan_file(ScanResult &result,
+               const std::vector<Rule> &rules,
+               const Options &options,
+               const fs::path &path) {
+    std::error_code ec;
+    const std::uintmax_t size = fs::file_size(path, ec);
+    if (ec) {
+        result.io_error = true;
+        return;
+    }
+    if (size > options.max_size) {
+        ++result.stats.files_skipped;
+        return;
+    }
+
+    bool binary_io_error = false;
+    if (is_binary_file(path, binary_io_error)) {
+        ++result.stats.files_skipped;
+        return;
+    }
+    if (binary_io_error) {
+        result.io_error = true;
+        return;
+    }
+
+    std::string content;
+    if (!read_file(path, size, content)) {
+        result.io_error = true;
+        return;
+    }
+    ++result.stats.files_scanned;
+    scan_content(result, rules, options, path.string(), content);
+}
+
+void scan_path(ScanResult &result,
+               const std::vector<Rule> &rules,
+               const Options &options,
+               const fs::path &path) {
+    std::error_code ec;
+    const fs::file_status status = fs::status(path, ec);
+    if (ec || !fs::exists(status)) {
+        result.io_error = true;
+        return;
+    }
+
+    if (fs::is_regular_file(status)) {
+        scan_file(result, rules, options, path);
+        return;
+    }
+
+    if (!fs::is_directory(status)) {
+        ++result.stats.files_skipped;
+        return;
+    }
+
+    fs::recursive_directory_iterator it(path, fs::directory_options::skip_permission_denied, ec);
+    if (ec) {
+        result.io_error = true;
+        return;
+    }
+    const fs::recursive_directory_iterator end;
+    for (; it != end; it.increment(ec)) {
+        if (ec) {
+            result.io_error = true;
+            ec.clear();
+            continue;
+        }
+
+        const fs::path current = it->path();
+        std::error_code status_ec;
+        const fs::file_status current_status = it->symlink_status(status_ec);
+        if (status_ec) {
+            result.io_error = true;
+            continue;
+        }
+
+        if (fs::is_directory(current_status)) {
+            if (is_skipped_directory_name(current)) {
+                it.disable_recursion_pending();
+            }
+            continue;
+        }
+        if (fs::is_regular_file(current_status)) {
+            scan_file(result, rules, options, current);
+        } else {
+            ++result.stats.files_skipped;
+        }
+    }
+}
+
+void print_json(const ScanResult &result) {
+    std::cout << "{\"version\":1,\"findings\":[";
+    for (std::size_t i = 0; i < result.findings.size(); ++i) {
+        const Finding &finding = result.findings[i];
+        if (i != 0U) {
+            std::cout << ",";
+        }
+        std::cout << "{\"rule\":\"" << json_escape(finding.rule)
+                  << "\",\"severity\":\"" << severity_to_string(finding.severity)
+                  << "\",\"path\":\"" << json_escape(finding.path)
+                  << "\",\"line\":" << finding.line
+                  << ",\"redacted\":\"" << json_escape(finding.redacted) << "\"}";
+    }
+    std::cout << "],\"stats\":{"
+              << "\"files_scanned\":" << result.stats.files_scanned
+              << ",\"files_skipped\":" << result.stats.files_skipped
+              << ",\"findings_high\":" << result.stats.high
+              << ",\"findings_medium\":" << result.stats.medium
+              << ",\"findings_low\":" << result.stats.low
+              << ",\"duration_ms\":" << result.stats.duration_ms
+              << "}}\n";
+}
+
+void print_console(const ScanResult &result, bool quiet) {
+    const bool color = stdout_is_tty();
+    if (color) {
+        enable_ansi_if_possible();
+    }
+
+    if (!quiet) {
+        for (const Finding &finding : result.findings) {
+            if (color) {
+                std::cout << severity_color(finding.severity);
+            }
+            std::cout << severity_to_string(finding.severity);
+            if (color) {
+                std::cout << "\033[0m";
+            }
+            std::cout << " " << finding.rule << " " << finding.path << ":"
+                      << finding.line << "  " << finding.redacted << "\n";
+        }
+    }
+
+    std::cout << "Summary: files scanned=" << result.stats.files_scanned
+              << ", files skipped=" << result.stats.files_skipped
+              << ", HIGH=" << result.stats.high
+              << ", MEDIUM=" << result.stats.medium
+              << ", LOW=" << result.stats.low
+              << ", wall time=" << result.stats.duration_ms << "ms\n";
+}
+
+} // namespace
+
+int main(int argc, char **argv) {
+    Options options;
+    bool help = false;
+    std::string error;
+    if (!parse_args(argc, argv, options, help, error)) {
+        std::cerr << "error: " << error << "\n" << usage();
+        return 2;
+    }
+    if (help) {
+        std::cout << usage();
+        return 0;
+    }
+
+    const std::vector<Rule> rules = build_rules();
+    ScanResult result;
+    const auto start = std::chrono::steady_clock::now();
+    for (const fs::path &path : options.paths) {
+        scan_path(result, rules, options, path);
+    }
+    const auto finish = std::chrono::steady_clock::now();
+    result.stats.duration_ms =
+        std::chrono::duration_cast<std::chrono::milliseconds>(finish - start).count();
+
+    if (options.json) {
+        print_json(result);
+    } else {
+        print_console(result, options.quiet);
+    }
+
+    if (result.io_error) {
+        return 2;
+    }
+    return result.findings.empty() ? 0 : 1;
+}

leakhound-0.1.0/tests/run_tests.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def run(cmd, **kwargs):
+    return subprocess.run(
+        cmd, text=True, encoding="utf-8", stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs
+    )
+
+
+def compiler_available(name):
+    return shutil.which(name) is not None
+
+
+def build_binary():
+    env_bin = os.environ.get("LEAKHOUND_BIN")
+    if env_bin:
+        path = Path(env_bin)
+        if not path.exists():
+            raise AssertionError(f"LEAKHOUND_BIN does not exist: {path}")
+        return path
+
+    exe_name = "leakhound.exe" if os.name == "nt" else "leakhound"
+    direct_exe = ROOT / exe_name
+    if direct_exe.exists():
+        return direct_exe
+
+    build_dir = ROOT / "build" / "tests"
+    build_dir.mkdir(parents=True, exist_ok=True)
+
+    if compiler_available("cmake"):
+        cfg = run(["cmake", "-S", str(ROOT), "-B", str(build_dir)])
+        if cfg.returncode == 0:
+            bld = run(["cmake", "--build", str(build_dir), "--config", "Release"])
+            if bld.returncode == 0:
+                candidates = [
+                    build_dir / exe_name,
+                    build_dir / "Release" / exe_name,
+                    build_dir / "Debug" / exe_name,
+                ]
+                for candidate in candidates:
+                    if candidate.exists():
+                        return candidate
+            else:
+                raise AssertionError(bld.stderr or bld.stdout)
+        else:
+            raise AssertionError(cfg.stderr or cfg.stdout)
+
+    if os.name == "nt" and compiler_available("cl"):
+        out = build_dir / "leakhound.exe"
+        cmd = [
+            "cl",
+            "/std:c++17",
+            "/O2",
+            "/W4",
+            "/EHsc",
+            str(ROOT / "src" / "leakhound.cpp"),
+            f"/Fe:{out}",
+        ]
+        result = run(cmd, cwd=ROOT)
+        if result.returncode != 0:
+            raise AssertionError(result.stderr or result.stdout)
+        return out
+
+    for compiler in ("c++", "g++", "clang++"):
+        if compiler_available(compiler):
+            out = build_dir / "leakhound"
+            cmd = [
+                compiler,
+                "-std=c++17",
+                "-O2",
+                "-Wall",
+                "-Wextra",
+                str(ROOT / "src" / "leakhound.cpp"),
+                "-o",
+                str(out),
+            ]
+            result = run(cmd, cwd=ROOT)
+            if result.returncode != 0:
+                raise AssertionError(result.stderr or result.stdout)
+            return out
+
+    raise AssertionError("no leakhound binary or C++17 compiler found; set LEAKHOUND_BIN")
+
+
+def write_text(path, text):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+
+
+def make_fixture(root):
+    scan = root / "scan"
+    scan.mkdir()
+    write_text(
+        scan / "secrets.txt",
+        "\n".join(
+            [
+                "const aws = 'AKIA1234567890ABCDEF';",
+                "password = \"CorrectHorseBattery99\"",
+                "api_key = 'sk_live_4eC39HqLyjWDarjtT1zd'",
+                "token = \"example_placeholder_value\"",
+                "random = aB3dE5fG7hI9jK1lM2nO4pQ6rS8tU0vW",
+                "",
+            ]
+        ),
+    )
+    write_text(
+        scan / "package-lock.json",
+        "integrity sha512-aB3dE5fG7hI9jK1lM2nO4pQ6rS8tU0vW\n",
+    )
+    write_text(scan / "node_modules" / "ignored.js", "AKIAABCDEFGHIJKLMNOP\n")
+    (scan / "binary.bin").write_bytes(b"\x00AKIA1234567890ABCDEF\n")
+    return scan
+
+
+def assert_equal(actual, expected, label):
+    if actual != expected:
+        raise AssertionError(f"{label}: expected {expected!r}, got {actual!r}")
+
+
+def test_json_scan(binary):
+    with tempfile.TemporaryDirectory() as tmp:
+        scan = make_fixture(Path(tmp))
+        result = run([str(binary), "--json", str(scan)])
+        assert_equal(result.returncode, 1, "json scan exit")
+        payload = json.loads(result.stdout)
+        findings = payload["findings"]
+        rules = [item["rule"] for item in findings]
+        assert_equal(rules.count("aws-access-key"), 1, "aws finding count")
+        assert_equal(rules.count("stripe-live-key"), 1, "stripe finding count")
+        # the stripe value sits in an api_key assignment: reported once, under
+        # the specific rule, not duplicated by generic-assignment
+        assert_equal(rules.count("generic-assignment"), 1, "generic finding count")
+        assert_equal(rules.count("high-entropy-token"), 1, "entropy finding count")
+        assert "example_placeholder_value" not in result.stdout
+        assert "AKIA12\u2026CDEF" in result.stdout
+        assert payload["stats"]["files_skipped"] >= 1
+        assert payload["stats"]["findings_high"] == 2
+        assert payload["stats"]["findings_medium"] == 1
+        assert payload["stats"]["findings_low"] == 1
+
+
+def test_no_entropy_and_quiet(binary):
+    with tempfile.TemporaryDirectory() as tmp:
+        scan = make_fixture(Path(tmp))
+        result = run([str(binary), "--no-entropy", "--quiet", str(scan)])
+        assert_equal(result.returncode, 1, "no entropy exit")
+        assert "high-entropy-token" not in result.stdout
+        assert "aws-access-key" not in result.stdout
+        assert "Summary:" in result.stdout
+        assert "LOW=0" in result.stdout
+
+
+def test_clean_and_usage_exit_codes(binary):
+    with tempfile.TemporaryDirectory() as tmp:
+        clean = Path(tmp) / "clean.txt"
+        write_text(clean, "hello world\n")
+        ok = run([str(binary), str(clean)])
+        assert_equal(ok.returncode, 0, "clean exit")
+
+        missing = run([str(binary), str(Path(tmp) / "missing.txt")])
+        assert_equal(missing.returncode, 2, "missing path exit")
+
+        usage = run([str(binary)])
+        assert_equal(usage.returncode, 2, "usage exit")
+
+
+def test_max_size_skip(binary):
+    with tempfile.TemporaryDirectory() as tmp:
+        large = Path(tmp) / "large.txt"
+        write_text(large, "AKIA1234567890ABCDEF\n")
+        result = run([str(binary), "--json", "--max-size", "3", str(large)])
+        assert_equal(result.returncode, 0, "max size skip exit")
+        payload = json.loads(result.stdout)
+        assert_equal(len(payload["findings"]), 0, "max size findings")
+        assert_equal(payload["stats"]["files_skipped"], 1, "max size skipped")
+
+
+def main():
+    binary = build_binary()
+    test_json_scan(binary)
+    test_no_entropy_and_quiet(binary)
+    test_clean_and_usage_exit_codes(binary)
+    test_max_size_skip(binary)
+    print("all tests passed")
+
+
+if __name__ == "__main__":
+    main()