pybetterleaks 0.5.0

Native Python bindings for Betterleaks

PyBetterleaks

Python-native Betterleaks. No CLI wrapper. No Go toolchain in your runtime image. No runtime subprocess.

pip install pybetterleaks

from pybetterleaks import BetterleaksConfig, Rule, scan_text

config = BetterleaksConfig(
    rules=[
        Rule(
            id="internal-token",
            description="Internal service token",
            regex=r"INTERNAL_[A-Z0-9]{16}",
            keywords=["INTERNAL_"],
        )
    ]
)

result = scan_text("INTERNAL_0123456789ABCDEF", config=config)
for finding in result.findings:
    print(f"{finding.rule_id}: {finding.secret}")

PyBetterleaks wraps the Betterleaks Go engine through a tiny ctypes JSON ABI and returns typed Python dataclasses. It is built for CI jobs, Python services, notebooks, agent tools, and Docker images that should stay simple.

Status: alpha. PyPI wheels are published for CPython 3.9-3.15 on supported glibc Linux, macOS, and Windows targets. Musllinux/Alpine remains unsupported for the current Go c-shared design; see Platforms.

Getting Started

From a checkout:

uv sync --all-extras --dev
uv run python scripts/build_native.py
uv run coverage run -m pytest
uv run coverage report

Run a scan with the bundled Betterleaks defaults:

uv run python - <<'PY'
from pybetterleaks import betterleaks_version, scan_text

print("Betterleaks:", betterleaks_version())

result = scan_text(
    "AGE-SECRET-KEY-"
    + "1QPZRY9X8GF2TVDW0S3JN54KHCE6MUA7LQPZRY9X8GF2TVDW0S3JN54KHCE"
)

for finding in result.findings:
    print(f"{finding.rule_id}: {finding.secret}")
PY

Expected output:

Betterleaks: v1.6.1
age-secret-key: REDACTED

The example secrets are synthetic fixtures.

Why Not Subprocess?

Shelling out is fine for one script. It becomes awkward as an SDK boundary:

• process output becomes the API contract
• quoting and path behavior leak into user code
• Docker images need extra binaries
• errors are process-shaped instead of Python-shaped
• async and agent workflows pay process startup overhead

PyBetterleaks keeps the Betterleaks engine native and gives Python an importable API:

Python app
  -> pybetterleaks
    -> ctypes JSON ABI
      -> bundled Go shared library
        -> Betterleaks

API

from pybetterleaks import SUPPORTED_GIT_SCOPES, betterleaks_version, scan_dir, scan_git, scan_text

print(betterleaks_version())
print(SUPPORTED_GIT_SCOPES)

text_result = scan_text("token goes here", validation=False, redact=True)
dir_result = scan_dir(".", config_path=".betterleaks.toml")
git_result = scan_git(".", scope="worktree", config_path=".betterleaks.toml")

scan_git currently supports local worktree scans. It validates that the target is inside a Git worktree, skips .git metadata, and does not invoke the Git executable.

Programmatic config uses Betterleaks' TOML concepts directly, with helpers for filters, validation results, common rule shapes, and relative extend.path handling:

from pybetterleaks import BetterleaksConfig, Expr, Rule, Validation, scan_dir

config = BetterleaksConfig.with_defaults(
    rules=[
        Rule.regex_rule(
            id="internal-token",
            description="Internal service token",
            regex=r"INTERNAL_[A-Z0-9]{16}",
            keywords=["INTERNAL_"],
            filter=Expr.min_entropy(3.5),
            validate=Validation.needs_validation(provider="internal"),
        )
    ],
    disabled_rules=["generic-api-key"],
)

result = scan_dir("src", config=config, validation=True)

Async wrappers run the blocking native scan in an executor and request cooperative cancellation from the Go bridge when the task is cancelled:

import asyncio
from pybetterleaks import scan_text_async

async def main() -> None:
    result = await scan_text_async("INTERNAL_0123456789ABCDEF", timeout_seconds=5)
    print(result.ok, len(result.findings))

asyncio.run(main())

Docker

FROM python:3.12-slim

RUN pip install --only-binary=:all: pybetterleaks

COPY . /app
WORKDIR /app

CMD ["python", "scan.py"]

No go install. No Betterleaks CLI. No install-time binary downloads.

Platforms

Target wheel matrix:

Platform	Status
Linux x86_64	manylinux wheels published
macOS arm64	macOS 11+ wheels published
macOS x86_64	macOS 11+ wheels published
Windows amd64	win_amd64 wheels published
Linux arm64	future CI capacity
Alpine/musllinux	unsupported; no wheels published

Previous Alpine experiments failed while loading the Go shared library through Python ctypes on musl:

initial-exec TLS resolves to dynamic definition

This is a Go + musl shared-library loader limitation, not a missing Docker package. The same failure reproduces with Go c-shared and a Go c-archive linked into a musl shared object, so the project will not publish musllinux wheels until that loader path is fixed. Use Debian/Ubuntu-style glibc Python images, such as python:3.12-slim, for supported Linux runtime images. Track musllinux work in issue #1.

Local Development

uv sync --all-extras --dev
uv run python scripts/build_native.py
uv run coverage run -m pytest
uv run coverage report
uv run ruff check .
uv run mypy python
uv run --group docs mkdocs build --strict

Build a local wheel after the native library exists:

uv build --wheel

Run the Docker packaging E2E:

bash e2e/run.sh

Verify the published PyPI wheel in a temporary virtual environment:

uv run python scripts/pypi_smoke.py

Benchmarks

Synthetic benchmarks live in benchmarks/:

uv run python benchmarks/bench.py --rounds 10 --files 50 --secrets-per-file 2

To compare against a local Betterleaks CLI:

uv run python benchmarks/bench.py --cli --cli-path /path/to/betterleaks

README numbers will stay blank until they are measured on release hardware. No fake charts.

Security And Supply Chain

• Betterleaks is pinned in bridge/go.mod
• the bundled Betterleaks pin is documented in docs/betterleaks-pin.md
• CI checks that go.mod, go.sum, and the bridge version constant agree
• wheels are built in GitHub Actions
• release artifacts get SHA256 checksums and checksum verification
• GitHub releases attach SHA256SUMS
• GitHub artifact attestations tie wheels back to the release workflow
• PyPI publication uses trusted publishing
• runtime installs never download native binaries
• wheel smoke tests import the package, run betterleaks_version(), scan text, and exercise typed config plus async wrappers
• Docker E2E installs a locally built wheel into a no-Go runtime image
• post-publish smoke tests install from PyPI in a temporary virtual environment