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

3.1 Implemented predicates (SPRINT_20260104_004_POLICY)

The following secret-related signals are now available via StellaOps.PolicyDsl.SignalContext:

3.2 Usage in SPL policies

{
  "conditions": [
    { "field": "secret.severity.critical", "operator": "eq", "value": true },
    { "field": "secret.bundle.version", "operator": "gte", "value": "2025.01" }
  ]
}

See example policies in src/Policy/__Libraries/StellaOps.Policy/Schemas/spl-secret-block@1.json and spl-secret-warn@1.json.

3.3 Integration with SignalContext

using StellaOps.Policy.Secrets;
using StellaOps.PolicyDsl;

// Add secret evidence to policy evaluation
var signalContext = SignalContext.Builder()
    .WithSecretEvidence(secretEvidenceProvider)
    .Build();

3.4 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).

3.5 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.

3.6 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

Decision tracker

7. Next steps

1. Policy Guild drafts predicate specs + policy templates DONE — See spl-secret-block@1.json, spl-secret-warn@1.json.
2. Security Guild reviews signing + masking requirements; align with Surface.Secrets roadmap.
3. Docs Guild 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.
5. NEW: Integration testing between Scanner.Analyzers.Secrets and Policy DSL signals.

Coordination

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