Imported Rule Capabilities¶
imported-rules-capabilities.yml is Kingfisher's operational overlay for Betterleaks and Veles rules. Detection patterns and upstream validation remain owned by their source projects; this file adds Kingfisher-specific behavior without creating another detector catalog.
Generic API-key confidence¶
The built-in generic-api-key overlay sets static low confidence; generic-credential-uri stays medium. Generic rules are not all low confidence. generic-password and generic-username remain excluded from the catalog. The importer removes pinned upstream confidence-only computations from built-in filters, preserving every rejection predicate. Unknown setter layouts fail import for review. Default CLI/Python/Node minimum medium confidence excludes generic-api-key before native compilation; opt in with CLI --confidence low, Python Rules(confidence="low"), or Node Rules.load({ confidence: 'low' }).
All rules use their configured confidence; filters cannot upgrade or downgrade findings, and there are no runtime confidence variants. Custom Betterleaks TOML and Kingfisher YAML files remain loadable without edits. Legacy one-string setConfidence(...) and filter.setConfidence(...) calls are inert value passthroughs. Rejection expressions and credential-association helpers remain active.
Provider revocation¶
Provider contracts, required inputs, limits, and first-party provenance cover the explicitly invoked revocation bindings. Owner-ID actions require an exact full-token mapping and independently supplied management credentials; masked list entries are not enough. Expression bindings use the existing Betterleaks revocation engine and supplied env.get variables. Existing YAML/TOML and existing primary actions are unchanged. Unsupported credential families do not gain account-wide deletion or mutation failover.
Format¶
version: 1
betterleaks:
upstream-rule-id:
verify_candidates: [AWS_SECRET_ACCESS_KEY] # dependency variable names, Betterleaks only
bare: true | false
confidence: low | medium | high
authoritative: true | false
validation: Assumed | JWT | MongoDB | CredentialUri | { type: Ethereum, content: private_key | public_key | mnemonic }
validation_override: 'Betterleaks validation expression'
filter_override: 'Betterleaks filter expression'
tls_mode: strict | lax | off
access_map:
handler: provider
inputs:
input_name: finding.secret | components.component-rule-id
reachable_2xx: true | false
revocation:
# Kingfisher revocation definition
revocation_bindings:
secret: finding.secret | components.component-rule-id
variables:
NAME: finding.secret | components.component-rule-id
veles:
secrets/upstream-plugin-id:
revocation:
# Kingfisher revocation definition
Fields¶
barederives a context-free token pattern from the upstream Betterleaks capture. It defaults tofalseand is accepted only for supported single-capture layouts; unsupported upstream changes fail the build.confidenceoverrides the upstream rule confidence. Valid values arelow,medium, andhigh.authoritativecontrols whether successful validation may classify a finding as an active credential. It defaults totrue. Set it tofalsefor broad detection rules whose matches must never be reported as active or valid credentials.validationattaches a Kingfisher validator. It supportsAssumed,JWT,MongoDB,CredentialUri, and configuredEthereumvalidation forprivate_key,public_key, ormnemonicmaterial.CredentialUriuses a namedURIcapture, validates HTTPS URIs with Basic Auth, dispatches supported database schemes to their typed validators, and leaves other unsupported URI schemes unvalidated.validation_overridereplaces an upstream Betterleaks validation expression.filter_overrideadds a filter to the upstream Betterleaks filter expression. A filter returning true discards the finding.tls_modedeclares how strictly the rule's validator should verify TLS certificates. Valid values arestrict(default),lax, andoff. Betterleaks has no equivalent concept, so this is a Kingfisher operational capability. It is opt-in on both sides: a rule declaringlaxstill gets full WebPKI verification unless the operator also runs with--tls-mode lax(--tls-mode offrelaxes every rule regardless). Use it for validators that legitimately reach self-managed endpoints presenting private-CA or self-signed certificates — databases, JWKS endpoints on self-hosted IdPs — and not to paper over a broken certificate chain on a public SaaS API. The build rejects atls_modeon a rule that has no validator, since it would have no effect.access_mapselects a provider mapper and optionally supplies component values.reachable_2xxpermits access mapping on a reachable 2xx response when the validator is otherwise inconclusive.revocationdefines a Kingfisher revocation action.revocation_bindingsmaps the finding secret and validator variables to the detected secret or component captures. Bindings require a Betterleaks validation expression and a revocation action.
Betterleaks keys are unqualified upstream IDs such as mongodb-connection-string, not generated betterleaks.mongodb-connection-string IDs. Veles keys, when present, are upstream plugin IDs rather than generated veles.* IDs. Every entry must match a pinned, selected source rule; the build rejects stale and unselected IDs. Each source rule ID may appear only once; combine its filter, revocation, and other capabilities in that entry. Duplicate IDs are rejected rather than silently replacing an earlier capability.
Veles source-precedence filters suppress only matching credential formats. Git credential suppression also requires a Veles-covered path and complete HTTPS URL; unrelated host suffixes, HTTP URLs, explicit ports, and empty usernames keep their Betterleaks coverage. OpenRouter's uppercase prefix remains with Betterleaks because Veles covers only the lowercase prefix. Heroku tokens ending in - also remain with Betterleaks because Veles requires a trailing word boundary.
Bare token detection (Betterleaks only)¶
bare: true derives a pattern from the pinned upstream regex during bundle generation; it does not accept a replacement regex. It removes provider/assignment context before the reported secret while retaining the secret format, effective scoped flags, and trailing delimiters. The default is false. DeepSeek, Kimi/Moonshot, ZAI/GLM, and Voyage AI enable it in the bundled overlay. These rules use medium confidence; MiniMax is already context-free upstream.
The importer uses regex-syntax HIR and requires exactly one nonempty, mandatory top-level capture (implicit group 1 or explicit secretGroup = 1). Alternation/repetition inside that capture is supported. Multiple captures, captures beneath alternation/repetition, missing captures, and path-only rules fail import with the rule ID. Unsupported upstream changes therefore fail the build instead of silently retaining contextual detection.
An assertion-only prefix on an already-bare pattern is preserved. Otherwise the prefix is replaced by start-of-input or a consumed byte outside [A-Za-z0-9_-]. The reported secret excludes that delimiter. Trailing constraints are retained exactly in meaning; no lookbehind is introduced. Token lengths and alphabets are not widened, so this does not repair format variants such as different Anthropic key lengths or missing AWS components.
Upstream filters, components, and validation remain in place. Enabling bare changes the full match and removes evidence of provider identity: review any expressions using the full match and the validator destination before opting in another rule. Bare matches are candidates; medium confidence does not disable live validation. Detection-only scans also use the bare pattern. This is a source-controlled build overlay, not a runtime custom-rule option.
Placeholder exclusions¶
The private-key overlay explicitly opts into Kingfisher's offline malformedPrivateKey(secret) finding-filter helper. It checks matching PEM labels, Base64, and decoded container structure rather than a minimum text length. Empty containers, explicit PRIVATE_KEY placeholders, and cleanly decoded malformed containers are rejected. Known ASN.1 containers whose intact first Base64 quartet cannot begin a SEQUENCE are also rejected when the remaining encoding is malformed, excluding repeated foo/bar fixtures. Unrecognized source syntax and plausibly encoded undecodable armor remain findings. The helper is an additive Kingfisher extension, not an upstream Betterleaks function; existing custom YAML/TOML rules are unchanged unless they explicitly use it.
For the built-in private-key rule with this filter, the importer derives an explicit END marker from the pinned upstream BEGIN pattern and removes its minimum body length. Short placeholder containers then end at their own footer, allowing a following real key to be scanned independently. Custom detector patterns and unknown upstream pattern forms are unchanged.
- PKCS#1 RSA (including multi-prime), SEC1 EC (including explicit parameters), and traditional DSA containers are checked for their required fields, tags, versions and complete DER consumption.
- PKCS#8 checks the outer container and known inner encodings: RSA/RSA-PSS/RSA-OAEP, EC, DSA, Ed25519/Ed448 and X25519/X448. RFC5958 public-key fields and attributes remain supported.
- Encrypted PKCS#8 checks the algorithm identifier, PBES2/PBKDF2/scrypt parameter structure when recognized, and nonempty ciphertext. Traditional PEM checks
Proc-Type/DEK-Infoheaders and encoding without trying to decrypt the payload. - OpenSSH checks magic, length-prefixed fields, key count and public records. Known unencrypted records also check field sizes, checkints, comments and padding. Encrypted records remain opaque; bcrypt options and AEAD tag framing are checked without running a KDF.
- OpenPGP checks old/new/partial packet framing and requires a secret-key or secret-subkey packet; known v2–v4 algorithms check public fields and unencrypted secret MPIs/checksum. Optional armor CRC24 is checked. Newer versions, unknown algorithms, and encrypted secret fields stay opaque.
CRLF, source-escaped newlines, adjacent/concatenated string literals, and shared per-line comment/diff/quote prefixes are supported without evaluating source or removing arbitrary punctuation. DER-family labels are hints: a valid key under another DER label is retained. Unknown formats/algorithms with valid armor, incomplete/nonstandard envelopes, candidates over 1 MiB, and DER nesting beyond 24 levels are retained conservatively. All checks run during detection, including --no-validate and Rust/Python SDK scans. No network, decryption, signing, key derivation or expensive mathematical key-consistency tests are performed. Retained candidates still use Assumed, not proof of active access; compact Ed25519 PKCS#8 keys remain detectable.
The mongodb-connection-string filter excludes passwords consisting entirely of a variable reference: $(NAME), ${NAME}, $NAME, or {{ NAME }} (including dotted template names). This additional filter does not exclude literal passwords merely because usernames or hosts are templated, or passwords that mix literal text with variable-like syntax. Existing upstream filters remain in effect. Filtering occurs before live validation and also applies to detection-only scans.
Candidate verification (Betterleaks only)¶
verify_candidates names component variables allowed to participate in bounded credential-pair verification. The importer rejects names absent from the source rule's components. Opt-ins cover AWS access tokens, BrowserStack, ClickHouse Cloud, MongoDB Atlas service accounts, PlanetScale, Razorpay, and Wiz. Their detection patterns and upstream validation expressions remain unchanged. The generated AWS session-token compatibility rule also opts in for its access-key ID and secret.
This capability permits ranked attempts against supported fixed-destination validators, never choosing a discovered endpoint by proximity. Unsupported validators retain strict ambiguity handling. See opt-in candidate verification for limits, ranking, supported validators, and unresolved-result semantics.