scannerctl
scannerctl is a provider-neutral DLP scanning and egress-enforcement runtime. It inspects an outbound request body before it leaves your infrastructure and returns one of four exhaustive verdicts — clean, block, error, disabled — over a versioned contract. It runs two ways from the same binary: as a CLI that scans one payload, and as a forward proxy that scans every request it relays. The scanning backend is replaceable; the initial one is gitleaks.
Why it exists
Egress scanning tends to be re-implemented per consumer: a copied proxy script here, an ad-hoc gitleaks install there, each drifting from the others and each with its own idea of what happens when the scanner is missing, times out, or returns something unexpected. That variation is the failure mode — the states nobody implemented consistently are exactly the ones that let unscanned traffic through.
scannerctl exists so there is one runtime with one contract, and so the answer to "what happens when scanning cannot complete?" is the same everywhere: egress is denied. block, error, disabled, malformed output, and any unknown state all deny. A caller cannot accidentally treat "the scanner is broken" as "the payload is fine".
Security properties
- Four exhaustive verdicts: clean, block, error, disabled. Anything else
is a schema error, and a schema error denies.
- Benign and must-detect canaries run before the proxy accepts any work. Wrong
polarity in either direction means the runtime does not start.
- No runtime downloads. Release bundles and OCI images contain the pinned
backend and baseline config; nothing is fetched while serving a request.
- Findings are redacted: a block result carries rule IDs, never secret text.
- Every release publishes checksums, Sigstore signatures, SLSA provenance, and
an SPDX SBOM, for darwin/linux on amd64/arm64 plus a linux/amd64 + linux/arm64 OCI index.
- Metrics expose all four verdict counters, canary state, last-scan timestamps,
and runtime/config identity. A zero last-scan timestamp means no data, and is never rendered as healthy.
How to run it
Prerequisites: Python 3.11+, and a gitleaks binary plus a config — both are included in a release bundle; from a source checkout, point at your own with --backend / --config or SCANNERCTLGITLEAKS / SCANNERCTLCONFIG.