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

transform provides explicit share-safe transformations:

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

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. Privacy-first Rust engine for detecting secrets and sensitive data.

Cribrais a deterministic, local-first scanning core. It accepts UTF-8 text and returns structured findings without filesystem, network, terminal, browser or cloud responsibilities.

§Example

use cribra::{Rule, Scanner, Severity};

let scanner = Scanner::builder()
    .rule(Rule::prefix(
        "example-token",
        "example_live_",
        Severity::Critical,
    ))
    .build()?;

let results = scanner.scan([
    ("memory", "TOKEN=example_live_123456"),
]);

let report = results.single_report().expect("one source was scanned");
assert_eq!(report.len(), 1);

With the optional parallel feature, native callers can use Scanner::parallel_scan while preserving input order.

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.
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.

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.
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.