Skip to main content

memfork/
secrets.rs

1//! Keeping credentials out of shared memory (DESIGN §6.10).
2//!
3//! Memory is read by every tool on the machine and shown to people, so a key
4//! pasted into it has leaked. Every write — through the tools, the command
5//! line and plan files — is checked against the rules in `secret_rules.toml`
6//! before anything is stored, and a match refuses the write.
7//!
8//! A refusal names the rule, the field and where in the field the match
9//! starts. It never contains the matched text, and neither does anything
10//! MemFork logs or publishes about it. A false positive is written anyway by
11//! naming its rule (`allow_secret`, or `--allow-secret` on the command line).
12//!
13//! The rules are data and the checks are deterministic: the same text gives
14//! the same answer on every OS.
15
16use std::sync::OnceLock;
17
18use regex_lite::Regex;
19use serde::Deserialize;
20use serde_json::{json, Value as Json};
21
22/// The rules, as shipped.
23const RULES: &str = include_str!("secret_rules.toml");
24
25/// Shortest value the name-and-value rule counts.
26const MIN_VALUE_CHARS: usize = 16;
27
28/// Fewest kinds of character (lower, upper, digit, other) such a value needs.
29const MIN_CLASSES: usize = 3;
30
31/// Fewest different characters such a value needs.
32const MIN_DISTINCT: usize = 10;
33
34#[derive(Deserialize)]
35struct RuleFile {
36    rule: Vec<RuleSpec>,
37}
38
39#[derive(Deserialize)]
40struct RuleSpec {
41    id: String,
42    description: String,
43    pattern: String,
44    #[serde(default)]
45    value_group: bool,
46}
47
48/// One compiled rule.
49#[derive(Debug)]
50pub struct Rule {
51    /// What a refusal names, and an override gives back.
52    pub id: String,
53    /// What it looks for, in words.
54    pub description: String,
55    pattern: Regex,
56    value_group: bool,
57}
58
59/// Something that looked like a secret.
60#[derive(Debug, Clone, PartialEq, Eq)]
61pub struct Found {
62    /// The rule that matched.
63    pub rule: String,
64    /// What the rule looks for, in words.
65    pub description: String,
66    /// Which part of the write it was in, such as `value` or `tasks[2].detail`.
67    pub field: String,
68    /// The line of the field the match starts on, from 1.
69    pub line: usize,
70    /// The column on that line, in characters, from 1.
71    pub column: usize,
72}
73
74impl Found {
75    /// What to tell whoever tried to write it. Never the matched text.
76    pub fn message(&self) -> String {
77        format!(
78            "`{field}` looks like it holds {what} (rule `{rule}`, line {line}, column {column}), \
79             so nothing was stored: memory is shared with every tool on this machine and shown \
80             to people, so keep credentials out of it. If it is not a secret, write it again \
81             with allow_secret: \"{rule}\" (on the command line, --allow-secret {rule}).",
82            field = self.field,
83            what = self.description,
84            rule = self.rule,
85            line = self.line,
86            column = self.column,
87        )
88    }
89
90    /// The refusal as data, for answers and `--json`.
91    pub fn to_json(&self) -> Json {
92        json!({
93            "rule": self.rule,
94            "field": self.field,
95            "line": self.line,
96            "column": self.column,
97        })
98    }
99}
100
101/// Why a write was refused.
102#[derive(Debug, Clone, PartialEq, Eq)]
103pub enum Refused {
104    /// Something in it looked like a secret.
105    Secret(Found),
106    /// The override named a rule that does not exist.
107    UnknownRule(String),
108    /// The machine policy does not allow overrides at all.
109    Forbidden(String),
110    /// The shipped rules did not load. A test keeps this from happening.
111    Rules(String),
112}
113
114impl std::fmt::Display for Refused {
115    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
116        match self {
117            Refused::Secret(found) => write!(f, "{}", found.message()),
118            Refused::UnknownRule(id) => write!(
119                f,
120                "`{id}` is not a secret rule; the rules are: {}",
121                ids().join(", ")
122            ),
123            Refused::Rules(why) => write!(f, "the secret rules did not load: {why}"),
124            Refused::Forbidden(why) => write!(f, "{why}"),
125        }
126    }
127}
128
129fn load() -> Result<Vec<Rule>, String> {
130    let file: RuleFile = toml::from_str(RULES).map_err(|e| e.to_string())?;
131    file.rule
132        .into_iter()
133        .map(|spec| {
134            let pattern =
135                Regex::new(&spec.pattern).map_err(|e| format!("rule `{}`: {e}", spec.id))?;
136            Ok(Rule {
137                id: spec.id,
138                description: spec.description,
139                pattern,
140                value_group: spec.value_group,
141            })
142        })
143        .collect()
144}
145
146fn rules() -> Result<&'static [Rule], Refused> {
147    static LOADED: OnceLock<Result<Vec<Rule>, String>> = OnceLock::new();
148    match LOADED.get_or_init(load) {
149        Ok(rules) => Ok(rules),
150        Err(why) => Err(Refused::Rules(why.clone())),
151    }
152}
153
154/// Every rule id, in the order the rules are checked.
155pub fn ids() -> Vec<String> {
156    rules()
157        .map(|r| r.iter().map(|r| r.id.clone()).collect())
158        .unwrap_or_default()
159}
160
161/// Every rule, for `--help` and the docs.
162pub fn all() -> Result<&'static [Rule], Refused> {
163    rules()
164}
165
166/// Rules a write has been told to let through.
167#[derive(Debug, Clone, Default, PartialEq, Eq)]
168pub struct Allow(Vec<String>);
169
170impl Allow {
171    /// From an override: one rule id, or several separated by commas. An id
172    /// that is not a rule is refused rather than ignored, so a typo cannot
173    /// look like an override that worked.
174    pub fn parse(raw: Option<&str>) -> Result<Allow, Refused> {
175        let Some(raw) = raw else {
176            return Ok(Allow::default());
177        };
178        // The one place an override is read, so the machine policy's answer
179        // reaches the tools, the command line and plan files alike.
180        if !crate::policy::allows(crate::policy::Feature::SecretOverrides) {
181            return Err(Refused::Forbidden(crate::policy::refusal(
182                crate::policy::Feature::SecretOverrides,
183            )));
184        }
185        let known = ids();
186        let mut out = Vec::new();
187        for id in raw.split(',').map(str::trim).filter(|s| !s.is_empty()) {
188            if !known.iter().any(|k| k == id) {
189                return Err(Refused::UnknownRule(id.to_owned()));
190            }
191            out.push(id.to_owned());
192        }
193        Ok(Allow(out))
194    }
195
196    fn allows(&self, id: &str) -> bool {
197        self.0.iter().any(|a| a == id)
198    }
199}
200
201/// Whether a value counts for the name-and-value rule: long, and mixed
202/// enough to look random rather than like a word or a path.
203fn looks_random(value: &str) -> bool {
204    let chars: Vec<char> = value.chars().collect();
205    if chars.len() < MIN_VALUE_CHARS {
206        return false;
207    }
208    let mut classes = [false; 4];
209    for c in &chars {
210        let class = if c.is_ascii_lowercase() {
211            0
212        } else if c.is_ascii_uppercase() {
213            1
214        } else if c.is_ascii_digit() {
215            2
216        } else {
217            3
218        };
219        classes[class] = true;
220    }
221    let mut distinct = chars.clone();
222    distinct.sort_unstable();
223    distinct.dedup();
224    classes.iter().filter(|c| **c).count() >= MIN_CLASSES && distinct.len() >= MIN_DISTINCT
225}
226
227/// Line and column, from 1, of byte offset `at` in `text`.
228fn position(text: &str, at: usize) -> (usize, usize) {
229    let before = &text[..at.min(text.len())];
230    let line = before.matches('\n').count() + 1;
231    let column = before.rsplit('\n').next().map_or(0, |l| l.chars().count()) + 1;
232    (line, column)
233}
234
235/// Check one field of a write. The first rule, in file order, that matches
236/// anywhere in it and is not allowed refuses it.
237pub fn check(field: &str, text: &str, allow: &Allow) -> Result<(), Refused> {
238    for rule in rules()? {
239        if allow.allows(&rule.id) {
240            continue;
241        }
242        let at = if rule.value_group {
243            rule.pattern
244                .captures_iter(text)
245                .filter_map(|c| c.get(1))
246                .find(|m| looks_random(m.as_str()))
247                .map(|m| m.start())
248        } else {
249            rule.pattern.find(text).map(|m| m.start())
250        };
251        if let Some(at) = at {
252            let (line, column) = position(text, at);
253            return Err(Refused::Secret(Found {
254                rule: rule.id.clone(),
255                description: rule.description.clone(),
256                field: field.to_owned(),
257                line,
258                column,
259            }));
260        }
261    }
262    Ok(())
263}
264
265/// Check several fields, in order.
266pub fn check_all<'a>(
267    fields: impl IntoIterator<Item = (String, &'a str)>,
268    allow: &Allow,
269) -> Result<(), Refused> {
270    for (field, text) in fields {
271        check(&field, text, allow)?;
272    }
273    Ok(())
274}
275
276#[cfg(test)]
277mod tests {
278    use super::*;
279
280    fn refused(text: &str) -> Option<String> {
281        match check("value", text, &Allow::default()) {
282            Ok(()) => None,
283            Err(Refused::Secret(f)) => Some(f.rule),
284            Err(other) => panic!("{other}"),
285        }
286    }
287
288    // Built at run time so this file never holds anything shaped like a key.
289    fn fake(prefix: &str, body: &str, n: usize) -> String {
290        format!("{prefix}{}", body.repeat(n))
291    }
292
293    #[test]
294    fn the_shipped_rules_load() {
295        let rules = all().expect("rules load");
296        assert!(rules.len() >= 12);
297        let mut ids: Vec<&str> = rules.iter().map(|r| r.id.as_str()).collect();
298        ids.sort_unstable();
299        ids.dedup();
300        assert_eq!(ids.len(), rules.len(), "two rules share an id");
301    }
302
303    #[test]
304    fn each_rule_catches_its_shape() {
305        let cases = [
306            (
307                format!("-----BEGIN {}PRIVATE KEY-----\nabc", "RSA "),
308                "private-key",
309            ),
310            (fake("AKIA", "ABCD2345", 2), "aws-access-key"),
311            (fake("ghp_", "aB3dE6gH9j", 4), "github-token"),
312            (fake("glpat-", "aB3dE6gH9j", 2), "gitlab-token"),
313            (fake("xoxb-", "12345-abcde", 2), "slack-token"),
314            (
315                fake(&format!("sk_{}_", ["li", "ve"].concat()), "aB3dE6gH", 3),
316                "stripe-key",
317            ),
318            (
319                fake("AIza", "aB3dE6gH9jK", 4)[..39].to_owned(),
320                "google-api-key",
321            ),
322            (fake("npm_", "aB3dE6gH9jKl", 3), "npm-token"),
323            (fake("pypi-AgE", "aB3dE6gH9j", 6), "pypi-token"),
324            (fake("sk-", "aB3dE6gH9j", 4), "sk-api-key"),
325            (
326                format!(
327                    "{}.{}.{}",
328                    fake("eyJ", "hbGciOiJ", 2),
329                    fake("eyJ", "zdWIiOiI", 2),
330                    "sIgnAtUrE_x9"
331                ),
332                "jwt",
333            ),
334            (
335                format!("password = \"{}\"", "Zq8!rT2#vL5@nW9x"),
336                "assigned-secret",
337            ),
338        ];
339        for (text, rule) in cases {
340            assert_eq!(refused(&text).as_deref(), Some(rule), "{rule}");
341        }
342    }
343
344    #[test]
345    fn ordinary_writing_passes() {
346        for text in [
347            "Hosted checkout: no card data on our servers.",
348            "the token budget is 4096 bytes",
349            "password: see the team vault",
350            "secret = \"aaaaaaaaaaaaaaaaaaaa\"",
351            "api_key = \"read-it-from-the-environment\"",
352            "src/auth/login.rs handles sessions",
353            "sk-short",
354            "commit 58e8aed8d4569934d42c2cbcfc5d6be41ccbcc6073bbf50dca27b368a53c449e",
355        ] {
356            assert_eq!(refused(text), None, "{text}");
357        }
358    }
359
360    #[test]
361    fn a_refusal_says_where_and_never_what() {
362        let key = fake("ghp_", "aB3dE6gH9j", 4);
363        let text = format!("line one\nuse {key} here");
364        let Err(Refused::Secret(found)) = check("tasks[1].detail", &text, &Allow::default()) else {
365            panic!("not refused");
366        };
367        assert_eq!((found.line, found.column), (2, 5));
368        assert_eq!(found.field, "tasks[1].detail");
369        let message = found.message();
370        assert!(
371            !message.contains(&key) && !message.contains("aB3dE6"),
372            "{message}"
373        );
374        assert!(
375            message.contains("allow_secret: \"github-token\""),
376            "{message}"
377        );
378        assert!(!found.to_json().to_string().contains("aB3dE6"));
379    }
380
381    #[test]
382    fn an_override_names_the_rule_and_only_that_rule() {
383        let text = fake("ghp_", "aB3dE6gH9j", 4);
384        let allow = Allow::parse(Some("github-token")).expect("parsed");
385        assert!(check("value", &text, &allow).is_ok());
386        let other = Allow::parse(Some("jwt, slack-token")).expect("parsed");
387        assert!(check("value", &text, &other).is_err());
388        assert_eq!(
389            Allow::parse(Some("github-tokn")),
390            Err(Refused::UnknownRule("github-tokn".to_owned()))
391        );
392    }
393}