Secret Guardian (secret-guardian)
Overview
Scans code, configuration files and cloud-function sources for secrets (API keys, AppSecrets, database passwords, private key blocks, generic secrets) and blocks with an alert the moment plaintext leakage is found. Redaction core: scan code, not people.
Core principles: scan code, not people; block without collateral damage (commit is never blocked); dual alert channels; zero sensitive values on disk.
Use cases
- Code commits (before git push; commit is never blocked — daily dev rhythm preserved)
- Cloud function deploys (auto-triggered before deploy)
- Config file saves (triggered on modification)
Trigger mechanism (four steps: trigger → scan → verdict → block/alert)
code commit / cloud function deploy / config save
│ trigger
▼
┌──────────────────────────────┐
│ secret scanner (secret-guardian) │
│ ① scope: code + config + functions │
│ ② desensitized verdict: patterns only │
│ ③ hit verdict: plaintext secret → block│
│ ④ alert: host push + audit weekly TOP │
└──────────────────────────────┘
| Step | Action | Verdict |
|---|---|---|
| ① Scan | full / incremental (git diff, mtime fallback) / deep (base64, concat, nested) | — |
| ② Desensitize | record only "file + line + rule type", never the secret value; sensitive files flagged by name, never read | sensitive → by-name flag + CRIT |
| ③ Block | plaintext secret on git push / cloud function deploy / config save | full block (CRIT) |
| ④ Alert | host push channel + audit-base weekly exception TOP; payload pushable to audit base | immediate alert |
Red lines
- Scan code, not people: exclude key files, identity-document images/PDFs, chat logs, personal document directories; under-report rather than cross the line.
- Zero sensitive values on disk: evidence records only "secret name + configured?"; sensitive fields are recorded by name only.
- commit is never blocked: block scope = git push / cloud function deploy / config save; commit stays (dev rhythm uninterrupted).
- Only the asset owner may view/fill secrets: AI must never open, read or scan any key file or cloud key configuration (secret red line, permanent).
Rule files
assets/secret_rules.json: secret patterns / sensitive extensions / ignore rules / deep scan / incremental scan / storage / alert integration / undo (all computable, no hardcoding)assets/scripts/secret_guard.py: core script (scan + verdict + events + alerts + query/export + undo)assets/scripts/hooks/: CI/deploy integration templates (git pre-push / deploy precheck / config save, sh + ps1, with integration guide)
Event contract (16 columns, pushable to an external audit base)
| Event type | result | severity | Notes |
|---|---|---|---|
| Scan passed | secret.pass | INFO | target=scan root, status=clean |
| Plaintext secret hit | secret.found | CRIT | rule_id=hit rule (deep scan: secret-leak-deep) |
| Block action | secret.blocked | CRIT | action=block, human_decision=pending |
| Alert payload | alert JSON | — | 16 columns + anomaly_type (secret-leak/secret-block) |
Script spec
- Python 3.11+ standard library (no third-party dependencies)
- Findings default to
%LOCALAPPDATA%\SecretGuardian\findings\(--base-dirfalls back to in-package dev paths;migratecopies legacy data, source kept) --selftestgate: 8 legacy + 15 new cases (incremental/deep/alert structure/query/export/undo/desensitization/CI templates)- Block actions (push/deploy/config save) are executed by the host integration layer; this script emits verdicts + hook templates and never calls git itself
Dual-channel trigger spec (voice + click)
- Voice command table (wake word is host-customizable; "Guardian" used as example):
| Voice command | Equivalent action |
|---|---|
| "Guardian, scan for secrets" | scan --mode push (or click "Scan now") |
| "Guardian, check leaks" | query --result FOUND |
| "Guardian, export scan report" | export --format md |
| "Guardian, send secret alert" | alert --push-audit (push to audit base) |
| "Guardian, restore deleted scan record" | undo --restore <id> |
- Click entry: host security console → Secret Guardian → Scan now / View hits / Export report / Alert records
- Authorization parity: voice confirm ≡ click confirm (single execution exit); blocking is the default action needing no authorization, scan-scope changes require asset-owner confirmation
- State sync: scan/hit/block/alert events follow the 16-column contract and can be pushed to an external audit base; dual alert channels = host push + audit weekly exception TOP
- Degradation: voice-channel errors are logged only, click is the fallback; both channels down → safe default (block not executed)
