Crate keyhog_core 

Core types shared across all KeyHog crates.

Re-exports

pub use crate::ascii_ci::contains_bytes_ignore_ascii_case;

pub use crate::ascii_ci::contains_ignore_ascii_case;

pub use crate::ascii_ci::ends_with_ignore_ascii_case;

pub use crate::ascii_ci::starts_with_ignore_ascii_case;

Modules

ascii_ci

Shared ASCII case-insensitive primitives: starts_with / ends_with_ignore_ascii_case and the ci_find byte-substring search. Single owner (ONE PLACE) for allocation-free case-folded comparisons on the scanner and verifier hot paths, callers use these instead of allocating a lowercased copy of each candidate.

git_lfs

Git-LFS pointer recognition, shared by the scanner (oid suppression) and sources (unscanned-blob coverage gap). Git-LFS pointer recognition.

json_selector

Detector verification response selector grammar and evaluator. Bounded rooted selectors for detector-owned verification responses.

timing

Shared paired performance statistics used by release gates and routing evidence. Shared statistical evidence for paired performance comparisons.

verification_domain

Verification-domain policy shared by detector validation and the network verifier. Shared verification-domain policy.

winpath

Canonical Windows-path classification predicates.

Structs

Allowlist

User-defined suppressions loaded from .keyhogignore: credential hashes, detector IDs, and path globs.

BetaCounters

A detector’s running Beta posterior counters. Always ≥1 each (Beta(1,1) uniform prior baseline) to avoid posterior_mean undefined when a detector has had no observations yet.

Calibration

Process-wide calibration store. Concurrent updates are serialized via a single RwLock because update events are rare (one per keyhog calibrate invocation or per verifier outcome) and the locked region is constant-time. We deliberately don’t shard via DashMap - the persisted artifact is small enough that contention is a non-issue.

CanonicalHexKeyMaterialSpec

One detector-local pure-hex key-material policy.

Chunk

A scannable chunk of text with metadata about where it came from.

ChunkMetadata

Metadata that tracks the source location for a scanned chunk.

CompanionSpec

Secondary pattern used to confirm a primary match or provide extra context.

Credential

Opaque credential bytes. The inner Arc<Zeroizing<Box<[u8]>>> clones are cheap (refcount bump) but every owning Credential zeroizes on drop. Arc lets the engine intern identical credentials without copying; when the last ref drops, Zeroizing<Box<[u8]>> overwrites the heap allocation before Box::drop returns it to the allocator.

CredentialHash

SHA-256 digest of a credential.

CredentialShape

Per-detector credential SHAPE constraint ([detector.credential_shape]), OWNED HERE per the architecture law (was a centralized rules/detector-credential-shapes.toml [[shape]] list keyed by detector id, a per-detector property in a second file). A candidate whose byte length / prefix / post-prefix body length does not fit the declared shape is suppressed by the scanner’s shape gate (CredentialShapeRule::allows). Only a couple of fixed-format vendor detectors declare it: aws-access-key is exactly 20 bytes; anthropic-api-key is sk-ant-api03- + an 80..=120 body.

DedupedMatch

A group of related raw matches representing a single distinct secret finding.

DetectorDecodeTransformSpec

Literal admission prefixes for detector-owned evasion recovery.

DetectorFile

Wrapping struct for a detector TOML file.

DetectorIntrospection

Redaction-safe serialized view of one detector declaration.

DetectorMatchConfidenceSpec

Complete detector-local confidence policy for regex candidates.

DetectorMlPolicySpec

Complete detector-local configuration for the shared ML scoring engine.

DetectorPlausibilityPolicySpec

Strict candidate-plausibility policy owned by one detector TOML.

DetectorPostMatchConfidenceSpec

Detector-local confidence penalties applied after optional model scoring.

DetectorSpec

A complete detector definition loaded from a TOML file.

DetectorTestSpec

One inline detector self-test fixture ([[detector.tests]]).

EntropyFallbackConfidenceSpec

Confidence mapping for one detector’s synthetic entropy findings.

EntropyFallbackMetadata

Detector-owned identity for a finding emitted by the entropy fallback path.

EntropyFloorBucket

One length bucket of a detector’s DetectorSpec::entropy_floor. Owned in the detector’s TOML (entropy_floor = [{ max_len = 24, floor = 3.0 }, { floor = 3.5 }]).

EntropyShapeSpec

A declarative structural shape that may cross a detector’s broad isolated entropy floor. Every field is detector TOML data and the scanner keeps one general matcher, so a new shape family (base64, hex block) is added by a detector TOML rather than a scanner enum variant.

GenericAssignmentConfidenceSpec

Confidence mapping for a detector-owned generic assignment candidate.

HardeningReport

Outcome of a hardening attempt - collected so callers can log which protections actually took.

HeaderSpec

Custom HTTP header specification.

JsonReportCoverageGap

One scan-wide coverage gap preserved in a versioned JSON report.

JsonReportEnvelope

Versioned machine-readable JSON report.

JsonReportSchemaVersion

Version marker carried by every versioned JSON report.

JsonlStream

One validated segment of a JSONL input. Concatenated streams produce one segment per header, so boundaries remain explicit instead of being inferred from finding content.

JsonlStreamHeader

Header written as the first record of a versioned JSONL stream.

JsonlStreamSummary

Terminal record written when a versioned JSONL stream completes.

MatchLocation

Where a credential was found: file path, line number, commit, and author.

MerkleIndex

In-memory file-hash index loaded from / saved to a JSON cache file.

MerkleLoadReport

Result of loading a persisted MerkleIndex cache.

MetadataSpec

Metadata field specification for verification results.

ObservedPaths

A Vec-compatible path list that records direct mutable access.

OobSpec

Out-of-band callback verification configuration.

PatternSpec

A regex pattern with optional capture group and description.

RawMatch

A raw pattern match before verification or deduplication.

RawMatchDedupKey

Borrowed raw-match identity used before report-scope deduplication.

RedactedFinding

Redacted, disk-safe view of a RawMatch. Carries only the SHA-256 hash and a “first4…last4” preview, never the plaintext credential. This is the only finding shape that should ever leave keyhog’s process boundary.

ReportError

Common error type used by all reporters. The Error type, a wrapper around a dynamic error type.

ResolvedScanManifest

Stable, machine-diffable description of the resolved detection mode.

RuleSuppressor

Parsed .keyhogignore.toml - a list of [[suppress]] rules, each compiled into a RuleFormula.

ScanBackendRecoverySummary

Bounded, non-secret summary of one completed automatic backend recovery.

ScanConfig

Configuration for a scan run.

ScanReport

The format-neutral input shared by every report renderer.

ScanReportMetadata

Format-neutral operator-visible metadata for a scan report.

SensitiveString

A heap-allocated string that is zeroized on drop.

ShapeGrouping

Fixed-width separator grouping, e.g. a Bluesky app password’s four dash-separated groups of four. Absent means an ungrouped run.

StateFileWriteLock

Exclusive advisory lock held across a state file’s read/merge/write cycle.

StepSpec

A single step in a multi-step verification flow.

SuccessSpec

Criteria for a successful verification response.

VerifiedFinding

A finding after verification - the final output.

VerifySpec

Live verification configuration for a detector.

Enums

AuthSpec

Authentication scheme for verification requests.

CalibrationLoadError

Error returned when an existing calibration cache cannot be trusted.

ConfigError

Errors returned while validating a scan configuration.

DedupScope

Deduplication scope for grouping findings.

DetectorBase64Alphabet

Exact base64 dialect accepted by a detector-owned offline validator.

DetectorKind

Which scan phase produces a detector’s findings (see DetectorSpec::kind).

DetectorMlMode

How the shared ML model participates in one detector path.

DetectorValidatorSpec

An offline validator declared by one detector.

EntropyDetectionRole

Detector-owned entry roles for the shared entropy engine.

EntropyFallbackClass

Semantic role of a detector-owned synthetic entropy finding.

HttpMethod

HTTP method for verification requests.

MerkleLoadStatus

Operator-relevant status for a Merkle cache load.

OobPolicy

How OOB observation combines with HTTP success criteria.

OobProtocol

Out-of-band callback protocol expected from a successful exfil.

ProviderEvidenceRole

Stable semantic role of provider evidence exposed in findings.

ProviderEvidenceSensitivity

Confidentiality policy for detector-owned provider evidence.

QualityIssue

Quality issue found in a detector spec.

ReportFormat

Output format and formatter options for write_report.

RuleSuppressorError

Errors from loading or parsing .keyhogignore.toml.

ScanCompletionStatus

Terminal state carried by detached scan artifacts.

ScriptEngine

Script interpreter names accepted by the detector TOML schema.

Severity

Severity level for a finding.

ShapeCharset

Character class an isolated entropy shape admits. Replaces the former per-shape enum variant so a new shape family is TOML data, not scanner code.

SourceCoverageGapKind

Machine-readable reason a requested source surface was not fully scanned.

SourceError

Errors returned by input sources while enumerating or reading content.

SpecError

Errors returned while loading or validating detector specifications.

VerificationResult

Result of live verification: whether the credential is active, revoked, or untested.

Constants

DEFAULT_ENTROPY_BPE_MAX_BYTES_PER_TOKEN

Single owner of the BPE “rare-not-random” gate default (the ScanConfig::default().entropy_bpe_max_bytes_per_token knob). An entropy / generic candidate whose cl100k_base bytes-per-token is STRICTLY GREATER than this compresses into few common subword tokens, word-like (a probable false positive: dotted API paths, prose, XML) rather than a random secret and is suppressed. 2.2 is the empirical CredData F1 peak (see keyhog_scanner::entropy::bpe; the offline A/B lifted F1 0.368→0.424).

DEFAULT_ENTROPY_THRESHOLD

Single owner of the Tier-A generic-entropy gate default (the ScanConfig::default().entropy_threshold knob). The scanner’s adjudicate fallback (generic_entropy_floor) resolves an absent per-scan value to this SAME number, so it references this const rather than re-spelling 4.5: the two must stay equal by construction, not by two hand-kept literals.

DEFAULT_MAX_FILE_SIZE_BYTES

Shipped filesystem per-file scan cap.

DETECTOR_TOML_FILE_BYTES

Maximum accepted size for one on-disk detector TOML file.

HYPERSCAN_CACHE_FILE_BYTES

Hard cap for one serialized Hyperscan shard cache file, including the KeyHog header.

HYPERSCAN_CACHE_HEADER_LEN

Byte length of the KeyHog Hyperscan cache header: magic plus little-endian version.

HYPERSCAN_CACHE_MAGIC

Magic bytes at the front of every KeyHog Hyperscan shard cache file.

HYPERSCAN_CACHE_VERSION

KeyHog-owned cache header version for serialized Hyperscan shard files.

JSONL_REPORT_SCHEMA_MINOR

Current minor version for the versioned JSONL stream contract.

JSON_REPORT_SCHEMA_MAJOR

Current major version for the versioned JSON report envelope.

JSON_REPORT_SCHEMA_MINOR

Current minor version for the versioned JSON report envelope.

Traits

Source

Produces chunks of text for the scanner to process. Each implementation handles a different input source.

Functions

apply_protections

Apply the process protections for the requested security mode.

apply_protections_with_persistence_paths

Apply process protections and, in lockdown mode, fail closed on known persistence artifacts outside the default keyhog cache root.

calibration_default_cache_path

Default calibration cache location: $XDG_CACHE_HOME/keyhog/calibration.json (or the macOS/Windows equivalents via the dirs crate).

compute_spec_hash

Compute a stable BLAKE3 digest over the canonical detector set so a later scan can detect that detectors changed.

decode_standard_base64

Decode standard-alphabet base64 (with optional = padding).

dedup_cross_detector

Cross-detector dedup at emit time.

dedup_matches

Deduplicate raw matches according to the given DedupScope.

detector_digest

Digest identifying the EXACT embedded detector set compiled into this binary (<count>-<fnv1a_hex>). Stamped by build.rs via cargo:rustc-env=KEYHOG_DETECTOR_DIGEST. Lets the benchmark and --version assert the running binary’s detectors match the on-disk detectors/ tree the authoritative answer to “what got compiled in” when cargo’s rerun-if-changed can’t be trusted across in-place TOML edits.

detector_spec_by_id

Canonical id → DetectorSpec lookup over the embedded corpus, built EXACTLY ONCE.

embedded_detector_count

Number of embedded detector specs (authoritative for banners and tests).

embedded_detector_specs

Every embedded detector spec, parsed EXACTLY ONCE for the whole process.

finding_metadata

Build the offline metadata for an AWS-access-key finding: always { "account_id": "<12 digits>" } for a decodable AKIA…/ASIA… key, plus { "is_canary": "true", "canary_message": <note> } when the decoded account belongs to a known canary issuer. None when credential is not a well-formed AWS access-key ID.

git_hash

Git commit SHA the binary was built from, or "unknown" for a build with no reachable .git tree (e.g. a cargo package / crates.io build). Stamped by build.rs via cargo:rustc-env=GIT_HASH; env! resolves here because the rustc-env applies to THIS crate’s compilation. Surfaced in keyhog --version and meant to be embedded in every result so a scan traces back to an exact commit (MC-06: the false “F1 regression” was a stale binary benched against HEAD, undetectable while every build reported the same empty version).

hex_encode

Lower-case hex of digest bytes. The only place the hex string is materialized for CredentialHash values (reporters, Debug).

hyperscan_cache_filename

Build the on-disk filename of a KeyHog Hyperscan shard cache file from its content shard_key: hs-<shard_key>.db. Single owner of the name FORMAT, shared by the scanner shard writer (which persists the file) and the hardening lockdown gate (which recognises/strips it via [HYPERSCAN_CACHE_PREFIX]/[HYPERSCAN_CACHE_SUFFIX]), so writer and reader can never disagree on the shard filename. Previously the writer re-inlined the hs-/.db affixes in a format!, a latent drift from this owner.

hyperscan_cache_header_is_valid

Return true when header is exactly the current KeyHog Hyperscan cache header.

key_id_canary_status

Checked canary classifier used by live-verification paths.

load_detectors

Load all detector specs from a directory of TOML files. Runs the quality gate on each detector and fails closed if any detector cannot be read, parsed, or accepted by the gate.

load_embedded_detectors_or_fail

Parse the embedded detector corpus, FAILING CLOSED on any malformed TOML.

max_decode_depth_limit

Maximum recursive decode passes accepted from CLI and TOML config.

merkle_default_cache_path

Default Merkle index location: $XDG_CACHE_HOME/keyhog/merkle.idx or ~/.cache/keyhog/merkle.idx on Linux, ~/Library/Caches/keyhog/... on macOS.

parse_canary_account_ids

Parse and validate raw 12-digit account IDs from .keyhog.toml config.

parse_jsonl_stream

Parse one or more concatenated, versioned JSONL streams.

read_detector_toml_file

Read one detector TOML without allowing metadata races to bypass the cap.

redact

Redact a sensitive credential string for safe display.

redact_companions

Redact every companion value at the process boundary.

resolve_safe_bin

Resolve name to an absolute path inside one of the trusted system binary directories. Returns None if not found in any trusted dir (do NOT fall back to Command::new(name) - that’s exactly the bug).

set_extra_canary_accounts

Replace the process-local extra canary account set supplied by .keyhog.toml.

set_extra_trusted_dirs

Replace the caller-configured trusted binary directories.

sha256_hash

SHA-256 of a string as the CredentialHash domain type. This is the single source for credential hashing across the workspace (scanner, dedup, telemetry); hex encoding is a separate step at the serde/reporter boundary via hex_encode, keeping the pre-dedup hot path zero-heap.

state_file_lock_path

Canonical sibling lock filename for a KeyHog state artifact.

strip_windows_verbatim_prefix

Strip the Windows verbatim path prefix (\\?\) from a display string.

validate_canary_accounts

Validate the compiled Tier-B canary account baseline.

validate_detector

Validate a detector spec against the quality gate.

write_csv_coverage_report

Write a CSV scan artifact with a self-describing scan-status preamble.

write_hyperscan_cache_header

Append the current KeyHog Hyperscan cache header to a serialized-cache buffer.

write_report

Write a complete findings report in the requested format.

write_scan_report

Write a complete report from the shared scan model.

Type Aliases

HtmlScanMetadata

Compatibility name for callers that used the original HTML-only type.