mixle.substrate.security module

Secret detection and redaction for substrate text.

Knowledge flows into the substrate from documents, traces, and tool outputs – exactly the places a leaked credential hides. detect_secrets() scans text for well-known secret shapes (API keys, bearer tokens, AWS keys, private-key blocks, credentials embedded in URLs, and key=value assignments of sensitive names); redact_secrets() masks them in place; scan_item() / scan_substrate() sweep stored items and safe_text() gives a redact-before-store guard.

The patterns are deliberately conservative and named – each finding says which rule matched, so a

false positive is inspectable rather than mysterious. This is detection, not a vault: it catches the common leaks (a pasted key, a token in a log line) so they don’t get indexed and served, and it flags the rest for review. Redaction preserves a short prefix so a human can still recognize which key it was without exposing the secret.

class SecretFinding(rule, start, end, preview)

Bases: object

One detected secret: which rule matched, where, and a safe preview (the value stays masked).

Parameters:

• rule (str)

• start (int)

• end (int)

• preview (str)

class SecretScan(findings=<factory>)

Bases: object

The result of scanning a text: whether anything leaked and every finding.

Parameters:

findings (list[SecretFinding])

property clean: bool

Whether the scan found no secrets.

rules()

Return the sorted names of triggered secret-detection rules.

Return type:

list[str]

as_dict()

Return a JSON-serializable scan summary.

Return type:

dict[str, Any]

detect_secrets(text)

Scan text for well-known secret shapes; return a SecretScan naming each finding.

Parameters:

text (str)

Return type:

SecretScan

redact_secrets(text, *, mask='[REDACTED:{rule}]', keep_prefix=0)

Return text with every detected secret replaced by a rule-labelled mask (destructive to secrets).

keep_prefix leaves that many leading characters of the secret visible (0 = fully masked) so a reader can still tell which credential it was without recovering it.

Parameters:

• text (str)

• mask (str)

• keep_prefix (int)

Return type:

str

safe_text(text)

Redact-before-store guard: mask any secrets so they are never indexed or served.

Parameters:

text (str)

Return type:

str

scan_item(item)

Scan a substrate item’s text surface for secrets.

Parameters:

item (Any)

Return type:

SecretScan

scan_substrate(substrate, *, scope=None)

Sweep a substrate for leaked secrets and report which stored items triggered rules.

Returns {n_items, n_dirty, dirty: [{item_id, rules}]} for compatibility with existing callers; entries in dirty are the items that matched one or more secret-detection rules.

Parameters:

• substrate (Any)

• scope (str | None)

Return type:

dict[str, Any]