31 lines
2.0 KiB
Markdown
31 lines
2.0 KiB
Markdown
# Decision Record: Establish SHHH Sentinel Foundations
|
|
|
|
- **Date:** 2025-02-16
|
|
- **Status:** Accepted
|
|
- **Context:** CHORUS roadmap Phase 1 requires a secrets sentinel (`pkg/shhh`) before we wire COOEE/WHOOSH telemetry and audit plumbing. The runtime previously emitted placeholder TODOs and logged sensitive payloads without guard rails.
|
|
|
|
## Problem
|
|
- We lacked a reusable component to detect and redact secrets prior to log/telemetry fan-out.
|
|
- Without a dedicated sentinel we could not attach audit sinks or surface metrics for redaction events, blocking roadmap item `SEC-SHHH`.
|
|
|
|
## Decision
|
|
- Introduce `pkg/shhh` as the SHHH sentinel with:
|
|
- Curated default rules (API keys, bearer/OAuth tokens, private key PEM blocks, OpenAI secrets).
|
|
- Extensible configuration for custom regex rules and per-rule severity/tags.
|
|
- Optional audit sink and statistics collection for integration with COOEE/WHOOSH pipelines.
|
|
- Helpers to redact free-form text and `map[string]any` payloads used by our logging pipeline.
|
|
|
|
## Rationale
|
|
- Starting with a focused set of high-signal rules gives immediate coverage for the most damaging leak classes without delaying larger SLURP/SHHH workstreams.
|
|
- The API mirrors other CHORUS subsystems (options, config structs, stats snapshots) so existing operators can plug metrics/audits without bespoke glue.
|
|
- Providing deterministic findings/locations simplifies future enforcement (e.g., WHOOSH UI badges, COOEE replay) while keeping implementation lean.
|
|
|
|
## Impact
|
|
- Runtime components can now instantiate SHHH and guarantee `[REDACTED]` placeholders for sensitive fields.
|
|
- Audit/event plumbing can be wired incrementally—hashes are emitted for replay without storing raw secrets.
|
|
- Future roadmap tasks (policy driven rules, replay, UCXL evidence) can extend `pkg/shhh` rather than implementing ad-hoc redaction in each subsystem.
|
|
|
|
## Related Work
|
|
- Roadmap: `docs/progress/CHORUS-WHOOSH-roadmap.md` (Phase 1.2 `SEC-SHHH`).
|
|
- README coverage gap noted in `README.md` table (SHHH not implemented).
|