feat: Implement vulnerability token signing and verification utilities
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- Added VulnTokenSigner for signing JWT tokens with specified algorithms and keys. - Introduced VulnTokenUtilities for resolving tenant and subject claims, and sanitizing context dictionaries. - Created VulnTokenVerificationUtilities for parsing tokens, verifying signatures, and deserializing payloads. - Developed VulnWorkflowAntiForgeryTokenIssuer for issuing anti-forgery tokens with configurable options. - Implemented VulnWorkflowAntiForgeryTokenVerifier for verifying anti-forgery tokens and validating payloads. - Added AuthorityVulnerabilityExplorerOptions to manage configuration for vulnerability explorer features. - Included tests for FilesystemPackRunDispatcher to ensure proper job handling under egress policy restrictions.
This commit is contained in:
80
docs/modules/policy/secret-leak-detection-readiness.md
Normal file
80
docs/modules/policy/secret-leak-detection-readiness.md
Normal file
@@ -0,0 +1,80 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user