silens_scan/lib.rs
1//! Privacy-first scanning core for secrets and sensitive data.
2//!
3//! `silens-scan` provides deterministic detection, reporting, querying and
4//! share-safe transformation of UTF-8 text. Applications own I/O and storage;
5//! the crate operates on caller-provided text and does not retain matched
6//! secret values inside public [`Finding`] values.
7//!
8//! # Quick start
9//!
10//! ```
11//! use silens_scan::Scanner;
12//!
13//! let scanner = Scanner::default();
14//! let results = scanner.scan([
15//! ("config.env", "TOKEN=example"),
16//! ("settings.toml", "mode = \"production\""),
17//! ]);
18//!
19//! assert_eq!(results.len(), 2);
20//! println!("{}", results.summary());
21//! ```
22//!
23//! # Result model
24//!
25//! A scan returns [`ScanResults<K>`], preserving the caller's source key `K`.
26//! Each source owns an immutable [`ScanReport`], whose [`Finding`] values expose
27//! rule metadata, severity, confidence, optional [`Remediation`] and a
28//! [`Location`].
29//!
30//! Source coordinates use:
31//!
32//! - zero-based, half-open UTF-8 byte offsets;
33//! - one-based lines;
34//! - one-based Unicode scalar columns.
35//!
36//! Findings intentionally do not contain the matched source value.
37//!
38//! # Querying
39//!
40//! [`ScanResults::query`] builds a lazy [`ScanQuery`] over borrowed findings.
41//! Filters can be composed before optionally materializing an explicitly sorted
42//! [`SortedScanQuery`].
43//!
44//! ```
45//! use silens_scan::{ScanSort, Scanner, Severity};
46//!
47//! let scanner = Scanner::default();
48//! let results = scanner.scan([("config.env", "TOKEN=example")]);
49//!
50//! let findings = results
51//! .query()
52//! .minimum_severity(Severity::High)
53//! .sort(ScanSort::Location);
54//!
55//! for (source, finding) in findings.iter() {
56//! println!("{source}: {}", finding.rule_id());
57//! }
58//! ```
59//!
60//! # Transformations
61//!
62//! [`transform`] provides explicit share-safe transformations:
63//!
64//! - [`transform::redact`] for conservative replacement;
65//! - [`transform::template`] for semantic placeholders;
66//! - [`transform::pseudonymize`] for deterministic keyed pseudonyms;
67//! - [`transform::synthesize`] for deterministic keyed synthetic values;
68//! - [`transform::ShareBundle`] for transformed keyed batches plus manifest
69//! metadata.
70//!
71//! ```
72//! use silens_scan::{Rule, Scanner, Severity, transform::redact};
73//!
74//! let scanner = Scanner::builder()
75//! .rule(Rule::literal("credential", "SECRET", Severity::High))
76//! .build()?;
77//!
78//! let source = "TOKEN=SECRET";
79//! let results = scanner.scan([("memory", source)]);
80//! let report = results.single_report().expect("one report");
81//!
82//! assert_eq!(redact(source, report)?, "TOKEN=[REDACTED]");
83//!
84//! # Ok::<(), Box<dyn std::error::Error>>(())
85//! ```
86//!
87//! # Optional features
88//!
89//! `serde` enables serialization support for public data contracts.
90//!
91//! `parallel` enables [`Scanner::parallel_scan`], which distributes independent
92//! inputs through Rayon while preserving input order and the same per-source
93//! semantics as serial scanning.
94//!
95//! # Application boundary
96//!
97//! File loading, network access, repository integration, authentication,
98//! persistence and UI are intentionally outside this crate. This keeps the
99//! scanner reusable in local-first native, WASM/PWA, desktop and service
100//! applications.
101
102#![forbid(unsafe_code)]
103#![warn(missing_docs)]
104
105//! Privacy-first Rust engine for detecting secrets and sensitive data.
106//!
107//! Silens Scan is a deterministic, local-first scanning core. It accepts UTF-8
108//! text and returns structured findings without filesystem, network, terminal,
109//! browser or cloud responsibilities.
110//!
111//! # Example
112//!
113//! ```
114//! use silens_scan::{Rule, Scanner, Severity};
115//!
116//! let scanner = Scanner::builder()
117//! .rule(Rule::prefix(
118//! "example-token",
119//! "example_live_",
120//! Severity::Critical,
121//! ))
122//! .build()?;
123//!
124//! let results = scanner.scan([
125//! ("memory", "TOKEN=example_live_123456"),
126//! ]);
127//!
128//! let report = results.single_report().expect("one source was scanned");
129//! assert_eq!(report.len(), 1);
130//!
131//! # Ok::<(), silens_scan::ScannerBuildError>(())
132//! ```
133//!
134//! With the optional `parallel` feature, the same batch can be scanned with
135//! [`Scanner::parallel_scan`] while preserving input order.
136
137pub mod builtins;
138mod compiled_rule;
139mod confidence;
140mod finding;
141mod location;
142mod redaction;
143mod remediation;
144mod rule;
145mod scan_entry;
146mod scan_query;
147mod scan_report;
148mod scan_results;
149mod scan_sort;
150mod scan_summary;
151mod scanner;
152mod scanner_builder;
153mod severity;
154pub mod transform;
155mod validators;
156
157pub use confidence::Confidence;
158pub use finding::Finding;
159pub use location::Location;
160pub use redaction::Redaction;
161pub use remediation::Remediation;
162pub use rule::{Rule, RuleError, RuleId, RuleKind, RuleSpec};
163pub use scan_entry::ScanEntry;
164pub use scan_query::{ScanQuery, SortedScanQuery};
165pub use scan_report::ScanReport;
166pub use scan_results::ScanResults;
167pub use scan_sort::ScanSort;
168pub use scan_summary::ScanSummary;
169pub use scanner::Scanner;
170pub use scanner_builder::{ScannerBuildError, ScannerBuilder};
171pub use severity::Severity;
172pub use transform::redact;