use crate::rules::{builtin_rules, Rule, Severity};
use regex::Regex;
use std::borrow::Cow;
use std::ops::Range;
use std::sync::OnceLock;
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[non_exhaustive]
pub struct Finding {
pub rule: Cow<'static, str>,
pub severity: Severity,
pub span: Range<usize>,
pub validated: Option<bool>,
}
#[derive(Debug, Clone)]
pub struct Scanner {
rules: Vec<Rule>,
include_heuristics: bool,
max_input_bytes: usize,
}
impl Default for Scanner {
fn default() -> Self {
Self::new()
}
}
impl Scanner {
pub fn new() -> Self {
Scanner {
rules: builtin_rules().to_vec(),
include_heuristics: false,
max_input_bytes: 1 << 20,
}
}
pub fn with_rule(
mut self,
name: impl Into<Cow<'static, str>>,
severity: Severity,
pattern: &str,
) -> Result<Self, InvalidPattern> {
let regex = Regex::new(pattern).map_err(|source| InvalidPattern(source.to_string()))?;
self.rules.push(Rule {
name: name.into(),
severity,
regex,
validator: None,
});
Ok(self)
}
pub fn without_rule(mut self, name: &str) -> Self {
self.rules.retain(|rule| rule.name != name);
self
}
pub fn include_heuristics(mut self, on: bool) -> Self {
self.include_heuristics = on;
self
}
pub fn max_input_bytes(mut self, limit: usize) -> Self {
self.max_input_bytes = limit;
self
}
pub fn rules(&self) -> impl Iterator<Item = &Rule> {
self.rules.iter()
}
pub fn scan(&self, text: &str) -> Vec<Finding> {
let text = clamp_to_boundary(text, self.max_input_bytes);
let mut findings = Vec::new();
for rule in &self.rules {
for m in rule.regex.find_iter(text) {
findings.push(Finding {
rule: rule.name.clone(),
severity: rule.severity,
span: m.range(),
validated: rule.validator.and_then(|verify| verify(m.as_str())),
});
}
}
if self.include_heuristics {
self.scan_heuristic_tokens(text, &mut findings);
}
findings.sort_by_key(|f| (f.span.start, f.span.end));
findings
}
fn scan_heuristic_tokens(&self, text: &str, findings: &mut Vec<Finding>) {
let rule_spans: Vec<Range<usize>> = findings.iter().map(|f| f.span.clone()).collect();
for (start, end) in token_spans(text) {
let overlaps_rule_hit = rule_spans.iter().any(|span| span.start < end && start < span.end);
if !overlaps_rule_hit && crate::heuristics::is_entropy_candidate(&text[start..end]) {
findings.push(Finding {
rule: Cow::Borrowed("high-entropy-token"),
severity: Severity::Medium,
span: start..end,
validated: None,
});
}
}
}
}
pub fn scan(text: &str) -> Vec<Finding> {
default_scanner().scan(text)
}
pub(crate) fn default_scanner() -> &'static Scanner {
static SLOT: OnceLock<Scanner> = OnceLock::new();
SLOT.get_or_init(Scanner::new)
}
#[derive(Debug)]
pub struct InvalidPattern(String);
impl std::fmt::Display for InvalidPattern {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "invalid rule pattern: {}", self.0)
}
}
impl std::error::Error for InvalidPattern {}
fn clamp_to_boundary(text: &str, limit: usize) -> &str {
if text.len() <= limit {
return text;
}
let mut end = limit;
while !text.is_char_boundary(end) {
end -= 1;
}
&text[..end]
}
fn token_spans(text: &str) -> Vec<(usize, usize)> {
let mut spans = Vec::new();
let mut start = None;
for (i, c) in text.char_indices() {
if c.is_whitespace() {
if let Some(s) = start.take() {
spans.push((s, i));
}
} else if start.is_none() {
start = Some(i);
}
}
if let Some(s) = start {
spans.push((s, text.len()));
}
spans
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn spans_slice_back_to_the_matched_token() {
let text = "export GITHUB_TOKEN=ghp_16C7e42F292c6912E7710c838347Ae178B4a # deploy";
let findings = scan(text);
assert_eq!(findings.len(), 1);
let f = &findings[0];
assert_eq!(f.rule, "GitHub Token");
assert_eq!(f.severity, Severity::Critical);
assert_eq!(&text[f.span.clone()], "ghp_16C7e42F292c6912E7710c838347Ae178B4a");
}
#[test]
fn overlapping_rules_both_report() {
let text = "sk-ant-api03-abcdefghijklmnopqrstuvwxyzABCDEF";
let rules: Vec<_> = scan(text).into_iter().map(|f| f.rule).collect();
assert!(rules.contains(&Cow::Borrowed("Anthropic API Key")), "{rules:?}");
assert!(rules.contains(&Cow::Borrowed("OpenAI API Key")), "{rules:?}");
}
#[test]
fn without_rule_removes_and_with_rule_adds() {
let text = "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.dBjftJeZ4CVP";
assert!(!scan(text).is_empty());
assert!(Scanner::new().without_rule("JWT").scan(text).is_empty());
let scanner = Scanner::new()
.with_rule("ACME Key", Severity::High, r"acme_[0-9]{8}")
.unwrap();
let findings = scanner.scan("key: acme_12345678");
assert_eq!(findings.len(), 1);
assert_eq!(findings[0].rule, "ACME Key");
assert_eq!(findings[0].severity, Severity::High);
}
#[test]
fn invalid_custom_pattern_is_an_error_not_a_panic() {
assert!(Scanner::new()
.with_rule("Broken", Severity::Medium, r"(unclosed")
.is_err());
}
#[test]
fn heuristics_are_off_by_default_and_opt_in() {
let opaque = "deploy with Xk7pQm2Rv9Ls4Tz8Wn3Yb6Hd please";
assert!(
scan(opaque).is_empty(),
"Tier-2 default must stay silent on bare entropy"
);
let findings = Scanner::new().include_heuristics(true).scan(opaque);
assert_eq!(findings.len(), 1);
assert_eq!(findings[0].rule, "high-entropy-token");
assert_eq!(findings[0].severity, Severity::Medium);
assert_eq!(&opaque[findings[0].span.clone()], "Xk7pQm2Rv9Ls4Tz8Wn3Yb6Hd");
}
#[test]
fn heuristic_pass_does_not_double_report_rule_hits() {
let text = "ghp_16C7e42F292c6912E7710c838347Ae178B4a";
let findings = Scanner::new().include_heuristics(true).scan(text);
assert_eq!(findings.len(), 1);
assert_eq!(findings[0].rule, "GitHub Token");
}
#[test]
fn max_input_bytes_truncates_on_char_boundaries() {
let text = "ééééé ghp_16C7e42F292c6912E7710c838347Ae178B4a";
let findings = Scanner::new().max_input_bytes(7).scan(text);
assert!(findings.is_empty());
let findings = Scanner::new().max_input_bytes(1024).scan(text);
assert_eq!(findings.len(), 1);
}
#[cfg(feature = "serde")]
#[test]
fn finding_serde_round_trip() {
let finding = &scan("ghp_16C7e42F292c6912E7710c838347Ae178B4a")[0];
let json = serde_json::to_string(finding).unwrap();
assert!(json.contains(r#""severity":"critical""#), "{json}");
let back: Finding = serde_json::from_str(&json).unwrap();
assert_eq!(&back, finding);
}
}