git.stella-ops.org/docs/modules/policy/secret-leak-detection-readiness.md

Secret Leak Detection Readiness — Policy & Security Brief

Audience: Policy Guild, Security Guild
Related backlog: SCANNER-ENG-0007 (deterministic leak detection pipeline), DOCS-SCANNER-BENCH-62-007 (rule bundle documentation), SCANNER-SECRETS-01..03 (Surface.Secrets alignment)

1. Goal & scope

• Provide a shared understanding of how the planned StellaOps.Scanner.Analyzers.Secrets plug-in will operate so Policy/Security can prepare governance controls in parallel with engineering delivery.
• Document evidence flow, policy predicates, and offline distribution requirements to minimise lead time once implementation lands.
• Capture open questions requiring Policy/Security sign-off (masking rules, tenancy constraints, waiver workflows).

2. Proposed evidence pipeline

1. Source resolution
   • Surface.Secrets providers (Kubernetes, file bundle, inline) continue to resolve operational credentials. Handles remain opaque and never enter analyzer outputs.
2. Deterministic scanning
   • New plug-in executes signed rule bundles (regex + entropy signatures) stored under scanner/rules/secrets/.
   • Execution context restricted to read-only layer mount; analyzers emit secret.leak evidence with: {rule.id, rule.version, confidence, severity, mask, file, line}.
3. Analysis store persistence
   • Findings are written into ScanAnalysisStore (ScanAnalysisKeys.secretFindings) so Policy Engine can ingest them alongside component fragments.
4. Policy overlay
   • Policy predicates (see §3) evaluate evidence, lattice scores, and tenant-scoped allow/deny lists.
   • CLI/export surfaces show masked snippets and remediation hints.
5. Offline parity
   • Rule bundles, signature manifests, and validator hash lists ship with Offline Kit; rule updates must be signed and versioned to preserve determinism.

3. Policy Engine considerations

• New predicates
  • secret.hasFinding(ruleId?, severity?, confidence?)
  • secret.bundle.version(requiredVersion)
  • secret.mask.applied (bool) — verify masking for high severity hits.
  • secret.path.allowlist — tenant-configured allow list keyed by digest/path.
• Lattice weight suggestions
  • High severity & high confidence → escalate to block unless waived.
  • Low confidence → default to warn with optional escalation when multiple matches occur (secret.match.count >= N).
• Waiver workflow
  • Reuse VEX-first lattice approach: require attach of remediation note, ticket reference, and expiration date.
  • Ensure waivers attach rule version so upgraded rules re-evaluate automatically.
• Masking / privacy
  • Minimum masking: first and last 2 characters retained; remainder replaced with *.
  • Persist masked payload only; full value never leaves scanner context.

4. Security guardrails

• Rule bundle signing: Signer issues DSSE envelope for each ruleset; Policy must verify signature before enabling new bundle.
• Tenant isolation: bundle enablement scoped per tenant; defaults deny unknown bundles.
• Telemetry: emit scanner.secret.finding_total{tenant, ruleId, severity} with masking applied after count aggregation.
• Access control: restrict retrieval of raw finding payloads to roles with scanner.secret.read scope; audits log query + tenant + rule id.

5. Offline & update flow

1. Engineering publishes new bundle → Signer signs → Offline Kit includes bundle + manifest.
2. Operators import bundle via CLI (stella secrets bundle install --path <bundle>).
   • CLI verifies signature, version monotonicity, and rule hash list.
3. Policy update: push config snippet enabling bundle, severity mapping, and waiver templates.
4. Run stella secrets scan --dry-run to verify deterministic output against golden fixtures before enabling in production.

6. Open questions / owners

Topic	Question	Owner	Target decision
Masking depth	Do we mask file paths or only payloads?	Security Guild	Sprint 132 design review
Telemetry retention	Should secret finding metrics be sampled or full fidelity?	Policy + Observability Guild	Sprint 132
Default bundles	Which rule families ship enabled-by-default (cloud creds, SSH keys, JWT)?	Security Guild	Sprint 133
Tenant overrides	Format for per-tenant allow lists (path glob vs digest)?	Policy Guild	Sprint 133

Decision tracker

Decision	Owner(s)	Target date	Status
Masking depth (paths vs payloads)	Security Guild	2025-11-10	Pending — workshop aligned with Northwind demo
Telemetry retention granularity	Policy + Observability Guild	2025-11-10	Pending
Default rule bundles (cloud creds/SSH/JWT)	Security Guild	2025-11-10	Draft proposals under review
Tenant override format	Policy Guild	2025-11-10	Pending

7. Next steps

1. Policy Guild drafts predicate specs + policy templates (map to DOCS-SCANNER-BENCH-62-007 exit criteria).
2. Security Guild reviews signing + masking requirements; align with Surface.Secrets roadmap.
3. Docs Guild (this task) continues maintaining docs/benchmarks/scanner/deep-dives/secrets.md with finalized rule taxonomy and references.
4. Engineering provides prototype fixture outputs for review once SCANNER-ENG-0007 spikes begin.

Coordination

• Capture macOS customer requirements via docs/benchmarks/scanner/windows-macos-demand.md (Northwind Health Services).
• Update dashboard (docs/api/scanner/windows-macos-summary.md) after readiness decisions.
• Share outcomes from 2025-11-10 macOS demo before finalising POLICY-READINESS-0001.