Skip to main content

Crate cribra

Crate cribra 

Source
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::redact for conservative replacement;
  • transform::template for semantic placeholders;
  • transform::pseudonymize for deterministic keyed pseudonyms;
  • transform::synthesize for deterministic keyed synthetic values;
  • transform::ShareBundle for 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§

builtins
Built-in detection contracts.
transform
Safe source transformations driven by scan findings.

Structs§

Finding
A single detection produced by a scanner.
IncrementalLimits
Optional per-operation limits for an owned mutable document.
IncrementalSession
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.
RuleMetadata
Presentation-safe metadata describing a scan rule.
RuleSpec
Allocation-free definition of a built-in rule.
ScanEntry
Result produced for one identified UTF-8 source.
ScanQuery
Borrowed query over findings produced by a batch scan.
ScanReport
Findings produced by scanning one UTF-8 source.
ScanResults
Ordered results for a batch of identified UTF-8 sources.
ScanSummary
Aggregate statistics derived from ScanResults.
Scanner
Immutable scanner that executes a precompiled set of detection rules.
ScannerBuilder
Builder used to configure and compile an immutable Scanner.
SensitiveCandidate
A structurally plausible sensitive value that requires manual review.
SortedScanQuery
Materialized, sorted view of findings selected by a ScanQuery.
StreamLimits
Optional limits for one source; the default leaves all three unlimited.
StreamSession
Opaque execution for one byte-partitioned UTF-8 source.

Enums§

CandidateEvidence
Describes the evidence that caused a value to be surfaced as a candidate.
Confidence
Indicates how reliable a detection is.
DetectionMode
Describes how a rule decides whether a matched candidate should become a finding.
Explanation
Explains which existing authority caused a scan result to exist.
IncrementalError
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.
RuleError
Error produced while constructing an individual Rule.
RuleKind
Declarative matching strategy used by a static RuleSpec.
ScanSort
Ordering applied when a scan query is materialized.
ScannerBuildError
Error returned when a Scanner cannot be compiled from its configured rules.
SensitiveCandidateKind
Describes the kind of sensitive value a candidate resembles.
Severity
Indicates the impact of a detected finding.
StreamError
Admission or terminal execution failure. Errors contain no source text.