stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 Releases Wiki Activity

feat(secrets): Implement secret leak policies and signal binding

Browse Source 
- Added `spl-secret-block@1.json` to block deployments with critical or high severity secret findings.
- Introduced `spl-secret-warn@1.json` to warn on secret findings without blocking deployments.
- Created `SecretSignalBinder.cs` to bind secret evidence to policy evaluation signals.
- Developed unit tests for `SecretEvidenceContext` and `SecretSignalBinder` to ensure correct functionality.
- Enhanced `SecretSignalContextExtensions` to integrate secret evidence into signal contexts.
This commit is contained in:
StellaOps Bot
2026-01-04 15:44:49 +02:00
parent 1f33143bd1
commit f7d27c6fda
44 changed files with 2406 additions and 1107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1662
docs/full-features-list.md
View File

File diff suppressed because it is too large Load Diff

2
docs/implplan/SPRINT_20260104_001_BE_determinism_timeprovider_injection.md
View File

@@ -65,7 +65,7 @@
| 9 | DET-009 | DONE | DET-002, DET-003 | Guild | Refactor Replay module (6 files: ReplayEngine, ReplayModels, ReplayExportModels, ReplayManifestExporter, FeedSnapshotCoordinatorService, PolicySimulationInputLock) |
| 10 | DET-010 | DONE | DET-002, DET-003 | Guild | Refactor RiskEngine module (skipped - no determinism issues found) |
| 11 | DET-011 | TODO | DET-002, DET-003 | Guild | Refactor Scanner module (~45+ matches remaining) |
| 12 | DET-012 | TODO | DET-002, DET-003 | Guild | Refactor Scheduler module (~20+ matches remaining) |
| 12 | DET-012 | DONE | DET-002, DET-003 | Guild | Refactor Scheduler module (WebService, Persistence, Worker projects - 30+ files updated, tests migrated to FakeTimeProvider) |
| 13 | DET-013 | TODO | DET-002, DET-003 | Guild | Refactor Signer module (~89 matches remaining) |
| 14 | DET-014 | DONE | DET-002, DET-003 | Guild | Refactor Unknowns module (skipped - no determinism issues found) |
| 15 | DET-015 | TODO | DET-002, DET-003 | Guild | Refactor VexLens module (~76 matches remaining) |

30
docs/implplan/SPRINT_20260104_004_POLICY_secret_dsl_integration.md
View File

@@ -29,18 +29,18 @@ Extend the Policy Engine and stella-dsl with `secret.*` predicates to enable pol
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | PSD-001 | TODO | None | Policy Guild | Define ISecretEvidenceProvider interface |
| 2 | PSD-002 | TODO | PSD-001 | Policy Guild | Implement SecretEvidenceContext binding |
| 3 | PSD-003 | TODO | None | Policy Guild | Add secret.hasFinding() predicate |
| 4 | PSD-004 | TODO | None | Policy Guild | Add secret.bundle.version() predicate |
| 5 | PSD-005 | TODO | None | Policy Guild | Add secret.match.count() predicate |
| 6 | PSD-006 | TODO | None | Policy Guild | Add secret.mask.applied predicate |
| 7 | PSD-007 | TODO | None | Policy Guild | Add secret.path.allowlist() predicate |
| 8 | PSD-008 | TODO | PSD-003-007 | Policy Guild | Register predicates in PolicyDslRegistry |
| 9 | PSD-009 | TODO | PSD-008 | Policy Guild | Update DSL schema validation |
| 10 | PSD-010 | TODO | PSD-008 | Policy Guild | Create example policy templates |
| 11 | PSD-011 | TODO | All | Policy Guild | Add unit and integration tests |
| 12 | PSD-012 | TODO | All | Docs Guild | Update policy/dsl.md documentation |
| 1 | PSD-001 | DONE | None | Policy Guild | Define ISecretEvidenceProvider interface |
| 2 | PSD-002 | DONE | PSD-001 | Policy Guild | Implement SecretEvidenceContext binding |
| 3 | PSD-003 | DONE | None | Policy Guild | Add secret.hasFinding() predicate |
| 4 | PSD-004 | DONE | None | Policy Guild | Add secret.bundle.version() predicate |
| 5 | PSD-005 | DONE | None | Policy Guild | Add secret.match.count() predicate |
| 6 | PSD-006 | DONE | None | Policy Guild | Add secret.mask.applied predicate |
| 7 | PSD-007 | DONE | None | Policy Guild | Add secret.path.allowlist() predicate |
| 8 | PSD-008 | DONE | PSD-003-007 | Policy Guild | Register predicates in PolicyDslRegistry |
| 9 | PSD-009 | DONE | PSD-008 | Policy Guild | Update DSL schema validation |
| 10 | PSD-010 | DONE | PSD-008 | Policy Guild | Create example policy templates |
| 11 | PSD-011 | DONE | All | Policy Guild | Add unit and integration tests |
| 12 | PSD-012 | DONE | All | Docs Guild | Update policy/dsl.md documentation |
## Task Details
@@ -540,4 +540,10 @@ when secret.path.allowlist(["**/test/**", "**/fixtures/**"])
| Date | Action | Notes |
|------|--------|-------|
| 2026-01-04 | Sprint created | Part of secret leak detection implementation |
| 2026-01-04 | PSD-001 to PSD-008 completed | Created ISecretEvidenceProvider, SecretFinding, SecretBundleMetadata, SecretEvidenceContext, SecretSignalBinder in `src/Policy/__Libraries/StellaOps.Policy/Secrets/`. Created SecretSignalContextExtensions in PolicyDsl (moved to avoid circular dependency). |
| 2026-01-04 | PSD-009 completed | Created signals-schema@1.json, updated spl-schema@1.json with secret signal examples and new operators (matches, exists). |
| 2026-01-04 | PSD-010 completed | Created spl-secret-block@1.json and spl-secret-warn@1.json example policies. |
| 2026-01-04 | PSD-011 completed | Created unit tests in SecretEvidenceContextTests.cs, SecretSignalBinderTests.cs, SecretSignalContextExtensionsTests.cs. All 8 PolicyDsl tests pass. |
| 2026-01-04 | PSD-012 completed | Updated docs/modules/policy/secret-leak-detection-readiness.md with implemented predicates table and code examples. |
| 2026-01-04 | Sprint completed | All 12 tasks DONE. |

83
docs/modules/policy/secret-leak-detection-readiness.md
View File

@@ -23,20 +23,67 @@
- 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.
### 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.
@@ -62,16 +109,18 @@
### Decision tracker
| Decision | Owner(s) | Target date | Status |
| --- | --- | --- | --- |
| Masking depth (paths vs payloads) | Security Guild | 2025-11-10 | Pending — workshop aligned with Northwind demo |
| 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 (map to DOCS-SCANNER-BENCH-62-007 exit criteria).
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 (this task) continues maintaining `docs/benchmarks/scanner/deep-dives/secrets.md` with finalized rule taxonomy and references.
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