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

```json
{
  "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

```csharp
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.