cribra 0.3.0

Privacy-first Rust core for detecting, querying, and safely transforming secrets and sensitive data
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147

//! Public model for structurally plausible sensitive values.
//!
//! Sensitive candidates are intentionally separate from [`Finding`](crate::Finding).
//! A candidate means that a source span has a shape worth reviewing, but the
//! scanner does not have enough evidence to classify it as a detected secret or
//! credential.
//!
//! Candidates never retain or copy the source value.

use crate::{Explanation, Location};

/// Describes the kind of sensitive value a candidate resembles.
///
/// This enum is non-exhaustive so future versions can add carefully validated
/// candidate families without forcing consumers to treat today's set as closed.
#[non_exhaustive]
#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub enum SensitiveCandidateKind {
    /// A value whose structure resembles a recovery or backup code.
    RecoveryLikeCode,
}

/// Describes the evidence that caused a value to be surfaced as a candidate.
///
/// Candidate evidence is deliberately different from
/// [`Confidence`](crate::Confidence). Confidence applies to an actual finding;
/// candidate evidence describes why a value is worth manual review before the
/// scanner has enough evidence to call it a detection.
#[non_exhaustive]
#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub enum CandidateEvidence {
    /// The value has a recognizable sensitive-looking structure, but lacks
    /// sufficient semantic context for a finding.
    Structural,
}

/// A structurally plausible sensitive value that requires manual review.
///
/// `SensitiveCandidate` is not a [`Finding`](crate::Finding):
///
/// - it has no severity;
/// - it has no finding confidence;
/// - it has no remediation;
/// - it does not imply that a credential was detected.
///
/// The candidate stores only presentation-safe metadata and an exact source
/// location. It never stores the matched source text.
#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct SensitiveCandidate {
    kind: SensitiveCandidateKind,
    location: Location,
    evidence: CandidateEvidence,
}

impl SensitiveCandidate {
    pub(crate) const fn new(
        kind: SensitiveCandidateKind,
        location: Location,
        evidence: CandidateEvidence,
    ) -> Self {
        Self {
            kind,
            location,
            evidence,
        }
    }

    /// Returns the family this candidate structurally resembles.
    #[must_use]
    pub const fn kind(&self) -> SensitiveCandidateKind {
        self.kind
    }

    /// Returns the exact source location of the candidate span.
    #[must_use]
    pub const fn location(&self) -> &Location {
        &self.location
    }

    /// Returns the evidence that caused this value to be surfaced for review.
    #[must_use]
    pub const fn evidence(&self) -> CandidateEvidence {
        self.evidence
    }

    /// Returns typed explanation facts for this review-only candidate.
    ///
    /// The explanation reuses [`CandidateEvidence`] directly. It does not
    /// assign finding severity, finding confidence, remediation, or source
    /// content to an ambiguous value.
    #[must_use]
    pub const fn explanation(&self) -> Explanation {
        Explanation::ambiguous(self.evidence)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn exposes_candidate_metadata_without_finding_semantics() {
        let candidate = SensitiveCandidate::new(
            SensitiveCandidateKind::RecoveryLikeCode,
            Location::from_span(4, 23),
            CandidateEvidence::Structural,
        );

        assert_eq!(candidate.kind(), SensitiveCandidateKind::RecoveryLikeCode);
        assert_eq!(candidate.location().start(), 4);
        assert_eq!(candidate.location().end(), 23);
        assert_eq!(candidate.evidence(), CandidateEvidence::Structural);
        assert_eq!(
            candidate.explanation(),
            Explanation::Ambiguous(CandidateEvidence::Structural)
        );
        assert_eq!(
            candidate.explanation().candidate_evidence(),
            Some(CandidateEvidence::Structural)
        );
        assert!(candidate.explanation().is_ambiguous());
        assert!(!candidate.explanation().is_classified());
    }

    #[cfg(feature = "serde")]
    #[test]
    fn serde_round_trip_preserves_candidate_metadata() {
        let candidate = SensitiveCandidate::new(
            SensitiveCandidateKind::RecoveryLikeCode,
            Location::from_span(2, 21),
            CandidateEvidence::Structural,
        );

        let json = serde_json::to_string(&candidate).expect("serialize candidate");
        let decoded: SensitiveCandidate =
            serde_json::from_str(&json).expect("deserialize candidate");

        assert_eq!(decoded, candidate);
        assert!(!json.contains("matched_value"));
        assert!(!json.contains("secret"));
    }
}