Expand description
Privacy-first scanning core for secrets and sensitive data.
cribra provides deterministic detection, reporting, querying and
share-safe transformation of UTF-8 text. Applications own I/O and storage;
the crate operates on caller-provided text and does not retain matched
secret values inside public Finding values.
§Quick start
use cribra::Scanner;
let scanner = Scanner::default();
let results = scanner.scan([
("config.env", "TOKEN=example"),
("settings.toml", "mode = \"production\""),
]);
assert_eq!(results.len(), 2);
println!("{}", results.summary());§Result model
A scan returns ScanResults<K>, preserving the caller’s source key K.
Each source owns an immutable ScanReport, whose Finding values expose
rule metadata, severity, confidence, optional Remediation and a
Location.
Source coordinates use:
- zero-based, half-open UTF-8 byte offsets;
- one-based lines;
- one-based Unicode scalar columns.
Findings intentionally do not contain the matched source value.
§Ambiguous candidates and explainability
ScanReport keeps classified Finding values separate from
SensitiveCandidate values that are structurally review-worthy but do not
have enough evidence for classification.
Explainability projects those existing authorities into Explanation:
Explanation::Classified(DetectionMode)describes how a rule-backed finding was validated;Explanation::Ambiguous(CandidateEvidence)describes the evidence behind a review-only candidate.
Findings do not duplicate rule metadata. Their explanation is resolved
against the Scanner that owns the compiled metadata and fails closed when
it cannot be resolved unambiguously. Candidate explanation is projected
directly from its existing evidence.
Explanation is presentation-agnostic and contains no source snippets or matched sensitive values. Applications remain responsible for human-facing copy.
§Querying
ScanResults::query builds a lazy ScanQuery over borrowed findings.
Filters can be composed before optionally materializing an explicitly sorted
SortedScanQuery.
use cribra::{ScanSort, Scanner, Severity};
let scanner = Scanner::default();
let results = scanner.scan([("config.env", "TOKEN=example")]);
let findings = results
.query()
.minimum_severity(Severity::High)
.sort(ScanSort::Location);
for (source, finding) in findings.iter() {
println!("{source}: {}", finding.rule_id());
}§Transformations
The default-enabled transform feature provides explicit share-safe transformations:
transform::redactfor conservative replacement;transform::templatefor semantic placeholders;transform::pseudonymizefor deterministic keyed pseudonyms;transform::synthesizefor deterministic keyed synthetic values;transform::ShareBundlefor transformed keyed batches plus manifest metadata.
use cribra::{Rule, Scanner, Severity, transform::redact};
let scanner = Scanner::builder()
.rule(Rule::literal("credential", "SECRET", Severity::High))
.build()?;
let source = "TOKEN=SECRET";
let results = scanner.scan([("memory", source)]);
let report = results.single_report().expect("one report");
assert_eq!(redact(source, report)?, "TOKEN=[REDACTED]");
§Optional features
Minimal (default-features = false) includes scanning, built-ins, reporting,
streaming and incremental sessions, with the standalone Redaction type.
Standard (the default) adds transform, including keyed transformations backed
by BLAKE3. Full adds parallel and serde to Standard.
serde enables serialization support for public data contracts.
parallel enables Scanner::parallel_scan, which distributes independent
inputs through Rayon while preserving input order and the same per-source
semantics as serial scanning.
§Application boundary
File loading, network access, repository integration, authentication, persistence and UI are intentionally outside this crate. This keeps the scanner reusable in local-first native, WASM/PWA, desktop and service applications.
§Execution models
Scanner::scan is the whole-source semantic reference. Published v0.5.0
supports Scanner::stream for explicitly admitted configurations, with
bounded retained source history and successful-EOF-only complete reports.
Complete built-in portfolios remain unsupported for streaming.
Available since v0.6.0, IncrementalSession owns a revisioned
UTF-8 document and maintains exact complete reports after replacement edits.
Literal and structural matching use local invalidation; Prefix, Suffix and
regex rules use authoritative whole-rule fallback. This is mutable-document
rescanning, distinct from append-only streaming.
Optional limits account for controlled logical payload and result ownership, not total heap memory. Incremental resource/execution failures preserve the last complete snapshot and prevent further edits. Input errors are recoverable. Session APIs are Rust-core surfaces; current adapters do not expose them.
Re-exports§
pub use transform::redact;
Modules§
Structs§
- Finding
- A single detection produced by a scanner.
- Incremental
Limits - Optional per-operation limits for an owned mutable document.
- Incremental
Session - A revisioned UTF-8 document with immutable scanner configuration. No report or cache borrow can outlive a mutable edit of this session. Every successful edit publishes a complete report equivalent to whole-source scanning. Literal/structural matching is localized; other matchers replay. Recoverable input errors preserve activity. Resource/internal failures make edits terminal while the previous complete source/report remain readable. Allocation failure and panic recovery are outside this contract.
- Location
- Exact location of a detected span in a UTF-8 source string.
- Redaction
- Replacement text used when presenting or exporting a detected span.
- Rule
- Owned declarative detection rule.
- RuleId
- Stable identifier assigned to a detection rule.
- Rule
Metadata - Presentation-safe metadata describing a scan rule.
- Rule
Spec - Allocation-free definition of a built-in rule.
- Scan
Entry - Result produced for one identified UTF-8 source.
- Scan
Query - Borrowed query over findings produced by a batch scan.
- Scan
Report - Findings produced by scanning one UTF-8 source.
- Scan
Results - Ordered results for a batch of identified UTF-8 sources.
- Scan
Summary - Aggregate statistics derived from
ScanResults. - Scanner
- Immutable scanner that executes a precompiled set of detection rules.
- Scanner
Builder - Builder used to configure and compile an immutable
Scanner. - Sensitive
Candidate - A structurally plausible sensitive value that requires manual review.
- Sorted
Scan Query - Materialized, sorted view of findings selected by a
ScanQuery. - Stream
Limits - Optional limits for one source; the default leaves all three unlimited.
- Stream
Session - Opaque execution for one byte-partitioned UTF-8 source.
Enums§
- Candidate
Evidence - Describes the evidence that caused a value to be surfaced as a candidate.
- Confidence
- Indicates how reliable a detection is.
- Detection
Mode - Describes how a rule decides whether a matched candidate should become a finding.
- Explanation
- Explains which existing authority caused a scan result to exist.
- Incremental
Error - Recoverable edit errors or terminal resource/execution failures. Errors never contain source text; terminal failures preserve the old snapshot.
- Remediation
- Recommended response to a detected sensitive value.
- Rule
Error - Error produced while constructing an individual
Rule. - Rule
Kind - Declarative matching strategy used by a static
RuleSpec. - Scan
Sort - Ordering applied when a scan query is materialized.
- Scanner
Build Error - Error returned when a
Scannercannot be compiled from its configured rules. - Sensitive
Candidate Kind - Describes the kind of sensitive value a candidate resembles.
- Severity
- Indicates the impact of a detected finding.
- Stream
Error - Admission or terminal execution failure. Errors contain no source text.