Skip to content

PyBetterleaks

Python-native Betterleaks. No CLI wrapper, no Go toolchain in production images, and 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, agent tools, notebooks, and Docker images that should stay simple.

Why It Exists

Betterleaks is fast and serious. Python is everywhere. The awkward bit is the boundary between them.

Shelling out works until process output becomes your SDK contract. PyBetterleaks keeps the engine native and gives Python a clean importable API.

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

What v0.2 Adds

  • typed config dataclasses
  • async scan wrappers with cooperative native cancellation
  • validation env var bridging
  • self-contained platform wheels
  • bundled Betterleaks v1.6.1
  • release artifact checksums
  • Docker packaging E2E
  • no runtime binary downloads
  • no runtime Betterleaks CLI dependency

Musllinux/Alpine remains a documented loader blocker for the current Go shared library design.

Start Here