mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
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
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
//! Removing secrets from anything on its way to a diagnostic.
//!
//! A secret in a diagnostic is worse than a secret on a screen. The screen is
//! gone when the terminal closes; the diagnostic is written to a file, kept for
//! days by the retention policy, and pasted into a bug report by the person
//! asking for help. It also outlives the credential rotation that was supposed
//! to make it harmless.
//!
//! So the scrub happens here, on the text, rather than at each call site that
//! might remember to do it. Four shapes carry secrets in practice and all four
//! are covered: a password inside a destination text, the value of a parameter
//! whose name says it is sensitive, the body of a certificate, and the clause
//! that sets a credential inside a statement.
//!
//! # Where this runs
//!
//! On every line of the auxiliary channel, at the destination, wrapped around
//! both the screen and the file by [`super::tracing::install`]. That is the
//! only place that sees a line whoever wrote it, and most of these lines are
//! not written by this product: at the levels a person asks for while
//! diagnosing, the driver writes the statement it is about to send, and a
//! statement that sets a credential carries one in plain text.

use crate::config::secret::REDACTION;

/// Parameter names whose value is never shown.
///
/// The list is matched without regard to case and as a substring, so
/// `db_password` and `SSL_KEY_FILE` are both caught without an entry each.
pub const SENSITIVE_NAMES: [&str; 9] = [
    "password",
    "passwd",
    "secret",
    "token",
    "credential",
    "private_key",
    "privatekey",
    "certificate",
    "ssl_key",
];

/// Whether a parameter of this name may ever have its value shown.
#[must_use]
pub fn is_sensitive(name: &str) -> bool {
    let folded = name.to_ascii_lowercase();
    SENSITIVE_NAMES
        .iter()
        .any(|candidate| folded.contains(candidate))
}

/// One parameter as it may appear in a diagnostic.
///
/// Returns the value untouched when the name says nothing sensitive, and the
/// fixed mark when it does. The mark never grows with the value, so its length
/// is not published either.
#[must_use]
pub fn parameter(name: &str, value: &str) -> String {
    if is_sensitive(name) {
        return REDACTION.to_owned();
    }
    value.to_owned()
}

/// Scrubs every secret this module knows how to find out of free text.
///
/// The passes run in a fixed order because they overlap: a certificate body
/// contains characters the other two passes look for, so it is removed first.
#[must_use]
pub fn scrub(text: &str) -> String {
    let without_certificates = scrub_certificates(text);
    let without_destinations = scrub_destinations(&without_certificates);
    let without_clauses = scrub_credential_clauses(&without_destinations);
    scrub_assignments(&without_clauses)
}

/// The opening marker of a certificate or key block.
const BLOCK_OPEN: &str = "-----BEGIN";

/// The closing marker of a certificate or key block.
const BLOCK_CLOSE: &str = "-----END";

/// The marker that ends either boundary line.
const BLOCK_EDGE: &str = "-----";

/// Replaces whole certificate and key blocks with the fixed mark.
fn scrub_certificates(text: &str) -> String {
    let mut out = String::with_capacity(text.len());
    let mut rest = text;

    while let Some(start) = rest.find(BLOCK_OPEN) {
        out.push_str(&rest[..start]);
        out.push_str(REDACTION);

        let after_open = &rest[start + BLOCK_OPEN.len()..];
        let Some(close) = after_open.find(BLOCK_CLOSE) else {
            return out;
        };
        let after_close = &after_open[close + BLOCK_CLOSE.len()..];
        let Some(edge) = after_close.find(BLOCK_EDGE) else {
            return out;
        };
        rest = &after_close[edge + BLOCK_EDGE.len()..];
    }

    out.push_str(rest);
    out
}

/// Replaces the password inside every destination text.
///
/// A destination is written as `scheme://user:password@host`, so the password
/// is whatever sits between the first colon after the scheme and the at sign
/// that closes the credential part.
fn scrub_destinations(text: &str) -> String {
    const SCHEME_END: &str = "://";
    let mut out = String::with_capacity(text.len());
    let mut rest = text;

    while let Some(mark) = rest.find(SCHEME_END) {
        let start = mark + SCHEME_END.len();
        out.push_str(&rest[..start]);

        let after = &rest[start..];
        let end = after
            .find(|character: char| character.is_whitespace() || character == '/')
            .unwrap_or(after.len());
        let authority = &after[..end];

        match split_credential(authority) {
            Some((colon, at)) => {
                out.push_str(&authority[..=colon]);
                out.push_str(REDACTION);
                out.push_str(&authority[at..]);
            }
            None => out.push_str(authority),
        }
        rest = &after[end..];
    }

    out.push_str(rest);
    out
}

/// The colon that opens the password and the at sign that closes it.
fn split_credential(authority: &str) -> Option<(usize, usize)> {
    let at = authority.find('@')?;
    let colon = authority[..at].find(':')?;
    Some((colon, at))
}

/// The clause that sets a credential inside a statement.
const CREDENTIAL_CLAUSE: &str = "identified by";

/// Replaces the literal that follows a credential clause in a statement.
///
/// This is the shape a secret takes when it is neither configuration nor a
/// destination but the statement itself: `CREATE USER ... IDENTIFIED BY 'x'`
/// carries the password in plain text, and the driver writes that statement to
/// the auxiliary channel at the levels a person asks for while diagnosing.
///
/// Only whitespace and bare words may sit between the clause and the literal,
/// which is what lets `IDENTIFIED BY PASSWORD 'hash'` be caught while stopping
/// the search from reaching across unrelated text to some later quotation.
fn scrub_credential_clauses(text: &str) -> String {
    let folded = text.to_ascii_lowercase();
    let mut out = String::with_capacity(text.len());
    let mut from = 0_usize;

    while let Some(found) = folded[from..].find(CREDENTIAL_CLAUSE) {
        let clause_end = from + found + CREDENTIAL_CLAUSE.len();
        let Some(open) = quoted_value_start(&text[clause_end..]).map(|at| clause_end + at) else {
            break;
        };
        let quote = text[open..].chars().next().unwrap_or('\'');

        out.push_str(&text[from..=open]);
        out.push_str(REDACTION);
        match text[open + quote.len_utf8()..].find(quote) {
            Some(close) => from = open + quote.len_utf8() + close,
            // An unterminated literal is the whole rest of the line, and none
            // of it may leave. Stopping here is what drops it.
            None => return out,
        }
    }

    out.push_str(&text[from..]);
    out
}

/// Where the literal that a credential clause introduces opens.
///
/// Returns `None` when anything other than whitespace or a bare word stands
/// between the clause and the opening quote, because then the quotation belongs
/// to something else.
fn quoted_value_start(after: &str) -> Option<usize> {
    after.char_indices().find_map(|(at, character)| {
        match character {
            '\'' | '"' => Some(Some(at)),
            _ if character.is_whitespace() || character.is_alphanumeric() || character == '_' => {
                None
            }
            // Anything else ends the search: this clause introduced no literal.
            _ => Some(None),
        }
    })?
}

/// Characters that end the value of an assignment.
const VALUE_END: [char; 10] = [' ', '\t', '\n', ',', ';', '&', ')', '}', '"', '\''];

/// Replaces the value of every assignment whose name says it is sensitive.
fn scrub_assignments(text: &str) -> String {
    let mut out = String::with_capacity(text.len());
    let mut rest = text;

    while let Some((at, length)) = earliest_name(rest) {
        let name_end = at + length;
        out.push_str(&rest[..name_end]);

        let after = &rest[name_end..];
        let Some(value_start) = value_start(after) else {
            rest = after;
            continue;
        };
        out.push_str(&after[..value_start]);
        out.push_str(REDACTION);

        let value = &after[value_start..];
        let end = value.find(VALUE_END).unwrap_or(value.len());
        rest = &value[end..];
    }

    out.push_str(rest);
    out
}

/// Where the first sensitive name starts, and how long it is.
fn earliest_name(haystack: &str) -> Option<(usize, usize)> {
    // Folding only the ASCII letters keeps every byte offset of the original,
    // so a position found here still points at the same place in the source.
    let folded = haystack.to_ascii_lowercase();
    SENSITIVE_NAMES
        .iter()
        .filter_map(|name| folded.find(name).map(|at| (at, name.len())))
        .min_by_key(|(at, _)| *at)
}

/// Where the value of an assignment starts, when this really is one.
///
/// A name written inside a structured document is closed by a quote before the
/// separator arrives, and the value that follows opens with one too, so both
/// quotes are stepped over rather than treated as the value itself.
fn value_start(after: &str) -> Option<usize> {
    let bytes = after.as_bytes();
    let mut cursor = skip_spaces(bytes, 0);

    if matches!(bytes.get(cursor), Some(b'"' | b'\'')) {
        cursor = skip_spaces(bytes, cursor + 1);
    }
    match bytes.get(cursor) {
        Some(b'=' | b':') => cursor += 1,
        _ => return None,
    }
    cursor = skip_spaces(bytes, cursor);
    if matches!(bytes.get(cursor), Some(b'"' | b'\'')) {
        cursor += 1;
    }
    Some(cursor)
}

/// The first position at or after `from` that is not a blank.
fn skip_spaces(bytes: &[u8], from: usize) -> usize {
    let mut cursor = from;
    while matches!(bytes.get(cursor), Some(b' ' | b'\t')) {
        cursor += 1;
    }
    cursor
}

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

    /// FR-051. Searching a diagnostic for the password never finds it: the
    /// destination text keeps its user, its host and its database, and carries
    /// the fixed mark where the secret was.
    #[test]
    fn a_password_inside_a_destination_never_survives() {
        let scrubbed = scrub("mysql://app:hunter2@db.internal:3306/shop");
        assert!(!scrubbed.contains("hunter2"));
        assert!(scrubbed.contains("app:"), "the user is not a secret");
        assert!(scrubbed.contains("@db.internal:3306/shop"));
    }

    #[test]
    fn a_destination_without_a_password_is_left_alone() {
        let text = "mysql://app@db.internal:3306/shop";
        assert_eq!(scrub(text), text);
    }

    #[test]
    fn a_sensitive_parameter_never_shows_its_value() {
        let scrubbed = scrub("connecting with password=hunter2 and user=app");
        assert!(!scrubbed.contains("hunter2"));
        assert!(scrubbed.contains("user=app"), "an ordinary value survives");
    }

    #[test]
    fn a_quoted_sensitive_value_never_survives_either() {
        let scrubbed = scrub("{\"token\": \"abc.def.ghi\"}");
        assert!(!scrubbed.contains("abc.def.ghi"));
    }

    #[test]
    fn a_certificate_body_never_survives() {
        let text = concat!(
            "cert is -----BEGIN CERTIFICATE-----\n",
            "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A\n",
            "-----END CERTIFICATE----- and that is all"
        );
        let scrubbed = scrub(text);
        assert!(!scrubbed.contains("MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A"));
        assert!(scrubbed.contains("and that is all"));
    }

    #[test]
    fn an_unterminated_certificate_never_leaks_its_tail() {
        let scrubbed = scrub("-----BEGIN PRIVATE KEY-----\nMIIEvQIBADAN");
        assert!(!scrubbed.contains("MIIEvQIBADAN"));
    }

    /// FR-051. The substitute is a fixed mark rather than one shaped by the
    /// secret, so a diagnostic never publishes the length of what it hid.
    #[test]
    fn the_mark_never_grows_with_the_secret() {
        let short = scrub("password=a");
        let long = scrub("password=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
        assert_eq!(short, long);
    }

    #[test]
    fn a_sensitive_name_is_recognised_however_it_is_written() {
        assert!(is_sensitive("DB_PASSWORD"));
        assert!(is_sensitive("ssl_key_file"));
        assert!(!is_sensitive("host"));
        assert!(!is_sensitive("database"));
    }

    #[test]
    fn a_parameter_that_is_not_sensitive_keeps_its_value() {
        assert_eq!(parameter("host", "db.internal"), "db.internal");
        assert_eq!(parameter("password", "hunter2"), REDACTION);
    }

    #[test]
    fn text_carrying_no_secret_comes_back_unchanged() {
        let text = "opening the connection to db.internal:3306";
        assert_eq!(scrub(text), text);
    }

    /// The statement itself carries a credential, and the driver writes the
    /// statement to the auxiliary channel while diagnosing.
    ///
    /// None of the other three passes reaches this one: there is no scheme, no
    /// certificate boundary, and the word that names the secret is not attached
    /// to it by a separator.
    #[test]
    fn a_credential_set_by_a_statement_never_survives() {
        for statement in [
            "CREATE USER 'app'@'%' IDENTIFIED BY 'hunter2'",
            "create user app identified by \"hunter2\"",
            "ALTER USER 'app'@'%' IDENTIFIED BY PASSWORD 'hunter2'",
            "GRANT ALL ON shop.* TO 'app'@'%' IDENTIFIED BY 'hunter2'",
        ] {
            let scrubbed = scrub(statement);
            assert!(
                !scrubbed.contains("hunter2"),
                "input {statement:?} gave {scrubbed:?}"
            );
            assert!(scrubbed.contains("app"), "the account name is not a secret");
        }
    }

    /// A literal that never closes is the rest of the line, and none of it may
    /// leave, because what a truncated line hides is unknowable.
    #[test]
    fn an_unterminated_credential_literal_never_leaks_its_tail() {
        let scrubbed = scrub("IDENTIFIED BY 'hunter2 and whatever followed");
        assert!(!scrubbed.contains("hunter2"));
        assert!(!scrubbed.contains("whatever"));
    }

    /// The clause introduces a literal or it introduces nothing, so the search
    /// never reaches across unrelated text to some later quotation.
    #[test]
    fn a_quotation_that_belongs_to_something_else_is_left_alone() {
        let text = "identified by nobody; SELECT 'keep me' FROM t";
        assert_eq!(scrub(text), text);
    }

    #[test]
    fn several_secrets_in_one_line_are_all_removed() {
        let scrubbed = scrub("password=one token=two user=app");
        assert!(!scrubbed.contains("one"));
        assert!(!scrubbed.contains("two"));
        assert!(scrubbed.contains("app"));
    }
}