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)[source]

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>)[source]

Bases: object

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

Parameters:

findings (list[SecretFinding])

findings: list[SecretFinding]
property clean: bool
rules()[source]
Return type:

list[str]

as_dict()[source]
Return type:

dict[str, Any]

detect_secrets(text)[source]

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)[source]

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:
Return type:

str

safe_text(text)[source]

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

Parameters:

text (str)

Return type:

str

scan_item(item)[source]

Scan a substrate item’s text surface for secrets.

Parameters:

item (Any)

Return type:

SecretScan

scan_substrate(substrate, *, scope=None)[source]

Sweep a substrate for leaked secrets: which items are dirty and which rules tripped.

Returns {n_items, n_dirty, dirty: [{item_id, rules}]} – a leak surface at a glance, so a pasted key or a token in a stored trace surfaces as a finding rather than sitting indexed and searchable.

Parameters:

  • substrate (Any)

  • scope (str | None)

Return type:

dict[str, Any]