Kingfisher Secret Scanner for Python

Fast secret detection, credential validation and revocation for Python, powered by Kingfisher's Rust libraries. Native, in-process execution; no CLI subprocess required. Requires CPython 3.10+.

Install

uv add kingfisher-secret-scanner

The PyPI distribution is kingfisher-secret-scanner; the Python import is kingfisher_sdk. It coexists with the separately distributed kingfisher-bin CLI.

Scan offline

from kingfisher_sdk import Scanner

scanner = Scanner()  # Compile the bundled rules once and reuse the scanner.
for finding in scanner.scan_file("application.conf"):
    if finding.visible:
        print(finding.to_dict())  # Secrets and captures are redacted by default.

Validate explicitly

from kingfisher_sdk import Scanner, Validator

findings = Scanner().scan_file("application.conf")
for result in Validator(timeout=10, concurrency=4).validate(findings):
    if result.finding.visible:
        print(result.to_dict())

Scanning is offline. Validation may contact providers using detected credentials. Keep the complete scan result, including invisible supporting findings, until validation finishes. Report redacted results; do not log finding.secret.

Revocation is available through Revoker.revoke() and requires confirm=True. It can disable or delete real credentials. The local lifecycle example demonstrates detection, validation and revocation against a loopback mock with a synthetic credential. Blocking SDK operations release the GIL; use asyncio.to_thread in async applications.

Documentation and examples

• Python guide on GitHub: API reference, custom YAML/TOML rules, validation outcomes, revocation, local uv builds and tests, supported platforms, and publishing.
• Runnable Python examples: offline scans, live validation, explicit revocation and a safe local lifecycle.
• Kingfisher repository: source, project documentation, CLI features and contributions.
• Report an issue.

For a source checkout, build and run the local example from the repository root:

uv sync --locked --no-install-project
uv run --no-sync maturin develop --locked --profile dev
uv run --no-sync python python/examples/local_workflow.py

For a downloaded example and a published package, use:

uv run --no-project --with kingfisher-secret-scanner python local_workflow.py

Download demo.yml beside local_workflow.py; the example loads that synthetic rule by its location. Source archives include the examples and fixture together.