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

3.1 Implemented predicates (SPRINT_20260104_004_POLICY)

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

Signal	Type	Description
secret.has_finding	bool	True if any secret finding exists
secret.count	int	Total number of secret findings
secret.severity.critical	bool	True if any critical severity finding exists
secret.severity.high	bool	True if any high severity finding exists
secret.severity.medium	bool	True if any medium severity finding exists
secret.severity.low	bool	True if any low severity finding exists
secret.confidence.high	bool	True if any high confidence finding exists
secret.confidence.medium	bool	True if any medium confidence finding exists
secret.confidence.low	bool	True if any low confidence finding exists
secret.mask.applied	bool	True if masking was applied to all findings
secret.bundle.version	string	Active bundle version (YYYY.MM format)
secret.bundle.id	string	Active bundle identifier
secret.bundle.rule_count	int	Number of rules in the active bundle
secret.bundle.signer_key_id	string	Key ID used to sign the bundle
secret.aws.count	int	Count of AWS-related secret findings
secret.github.count	int	Count of GitHub-related secret findings
secret.private_key.count	int	Count of private key findings

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

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
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
Policy predicates implementation	Policy Guild	2026-01-04	DONE (SPRINT_20260104_004_POLICY)

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.