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

finish secrets finding work and audit remarks work save

Browse Source
This commit is contained in:
StellaOps Bot
2026-01-04 21:48:13 +02:00
parent 75611a505f
commit 8862e112c4
157 changed files with 11702 additions and 416 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/modules/scanner/architecture.md
View File

@@ -32,6 +32,7 @@ src/
├─ StellaOps.Scanner.Analyzers.OS.[Apk|Dpkg|Rpm]/
├─ StellaOps.Scanner.Analyzers.Lang.[Java|Node|Bun|Python|Go|DotNet|Rust|Ruby|Php]/
├─ StellaOps.Scanner.Analyzers.Native.[ELF|PE|MachO]/ # PE/Mach-O planned (M2)
├─ StellaOps.Scanner.Analyzers.Secrets/ # Secret leak detection (2026.01)
├─ StellaOps.Scanner.Symbols.Native/ # NEW – native symbol reader/demangler (Sprint 401)
├─ StellaOps.Scanner.CallGraph.Native/ # NEW – function/call-edge builder + CAS emitter
├─ StellaOps.Scanner.Emit.CDX/ # CycloneDX (JSON + Protobuf)

103
docs/modules/scanner/operations/secret-leak-detection.md
View File

@@ -1,22 +1,23 @@
# Secret Leak Detection (Scanner Operations)
> **Status:** PLANNED - Implementation in progress. See implementation sprints below.
>
> **Previous status:** Preview (Sprint 132). Requires `SCANNER-ENG-0007`/`POLICY-READINESS-0001` release bundle and the experimental flag `secret-leak-detection`.
> **Status:** IMPLEMENTED (2026-01-04). Feature is production-ready.
>
> **Audience:** Scanner operators, Security Guild, Docs Guild, Offline Kit maintainers.
## Implementation Status
| Component | Status | Sprint |
|-----------|--------|--------|
| `StellaOps.Scanner.Analyzers.Secrets` plugin | NOT IMPLEMENTED | [SPRINT_20260104_002](../../../implplan/SPRINT_20260104_002_SCANNER_secret_leak_detection_core.md) |
| Rule bundle infrastructure | NOT IMPLEMENTED | [SPRINT_20260104_003](../../../implplan/SPRINT_20260104_003_SCANNER_secret_rule_bundles.md) |
| Policy DSL predicates (`secret.*`) | NOT IMPLEMENTED | [SPRINT_20260104_004](../../../implplan/SPRINT_20260104_004_POLICY_secret_dsl_integration.md) |
| Offline Kit integration | NOT IMPLEMENTED | [SPRINT_20260104_005](../../../implplan/SPRINT_20260104_005_AIRGAP_secret_offline_kit.md) |
| Component | Status | Sprint (Archived) |
|-----------|--------|-------------------|
| `StellaOps.Scanner.Analyzers.Secrets` plugin | IMPLEMENTED | [SPRINT_20260104_002](../../../implplan/archived/2026-01-04-secret-detection/SPRINT_20260104_002_SCANNER_secret_leak_detection_core.md) |
| Rule bundle infrastructure | IMPLEMENTED | [SPRINT_20260104_003](../../../implplan/archived/2026-01-04-secret-detection/SPRINT_20260104_003_SCANNER_secret_rule_bundles.md) |
| Policy DSL predicates (`secret.*`) | IMPLEMENTED | [SPRINT_20260104_004](../../../implplan/archived/2026-01-04-secret-detection/SPRINT_20260104_004_POLICY_secret_dsl_integration.md) |
| Offline Kit integration | IMPLEMENTED | [SPRINT_20260104_005](../../../implplan/archived/2026-01-04-secret-detection/SPRINT_20260104_005_AIRGAP_secret_offline_kit.md) |
| Configuration API | IMPLEMENTED | [SPRINT_20260104_006](../../../implplan/archived/2026-01-04-secret-detection/SPRINT_20260104_006_BE_secret_detection_config_api.md) |
| Alert Integration | IMPLEMENTED | [SPRINT_20260104_007](../../../implplan/archived/2026-01-04-secret-detection/SPRINT_20260104_007_BE_secret_detection_alerts.md) |
| UI Components | IMPLEMENTED | [SPRINT_20260104_008](../../../implplan/archived/2026-01-04-secret-detection/SPRINT_20260104_008_FE_secret_detection_ui.md) |
| Surface.Secrets (credential delivery) | IMPLEMENTED | N/A (already complete) |
**Note:** The remainder of this document describes the TARGET SPECIFICATION for secret leak detection. The feature is not yet available. Surface.Secrets (operational credential management) is fully implemented and separate from secret leak detection.
**Note:** All secret leak detection components are now fully implemented and production-ready. Surface.Secrets (operational credential management) remains a separate, independent feature.
---
@@ -182,21 +183,60 @@ See [secrets-bundle-rotation.md](./secrets-bundle-rotation.md) for rotation proc
4. **Roll scanner hosts**. Apply the configuration, roll WebService first, then Workers. Verify the startup logs contain `SecretsAnalyzerHost` and `SecretLeakDetection: Enabled`.
## 5. Policy patterns
## 5. Configuration API
The secret detection feature provides a REST API for per-tenant configuration:
### 5.1 Settings Endpoints
```
GET /api/v1/tenants/{tenantId}/secrets/config/settings
PUT /api/v1/tenants/{tenantId}/secrets/config/settings
PATCH /api/v1/tenants/{tenantId}/secrets/config/settings
```
### 5.2 Exception Pattern Endpoints
```
GET /api/v1/tenants/{tenantId}/secrets/config/exceptions
POST /api/v1/tenants/{tenantId}/secrets/config/exceptions
DELETE /api/v1/tenants/{tenantId}/secrets/config/exceptions/{exceptionId}
```
### 5.3 Revelation Policy
Control how detected secrets appear in different contexts:
| Policy | Display | Use Case |
|--------|---------|----------|
| `FullMask` | `[REDACTED]` | Maximum security, compliance reports |
| `PartialReveal` | `AKIA****WXYZ` | Default for UI, allows identification |
| `FullReveal` | Full value | Incident response (requires elevated permissions) |
### 5.4 Alert Configuration
Configure alerting for secret findings via the Notify service:
- **Destinations**: Slack, Teams, Email, Webhook, PagerDuty
- **Rate Limiting**: Max alerts per scan (default: 10)
- **Deduplication**: 24-hour window to prevent duplicate alerts
- **Severity Routing**: Route critical findings to different channels
## 6. Policy patterns
The analyzer emits `secret.leak` evidence with the shape:
```json
{
"ruleId": "stellaops.secrets.aws-access-key",
"ruleVersion": "2025.11.0",
"ruleVersion": "2026.01.0",
"severity": "high",
"confidence": "high",
"file": "/app/config.yml",
"line": 42,
"mask": "AKIA********B7",
"bundleId": "secrets.ruleset",
"bundleVersion": "2025.11"
"bundleVersion": "2026.01"
}
```
@@ -207,6 +247,8 @@ Policy DSL helpers introduced with this release:
| `secret.hasFinding(ruleId?, severity?, confidence?)` | Returns true if any finding matches the filter. |
| `secret.bundle.version(requiredVersion)` | Ensures the active bundle meets or exceeds a version. |
| `secret.match.count(ruleId?)` | Returns the number of findings (useful for thresholds). |
| `secret.mask.applied` | Returns true if masking was successfully applied. |
| `secret.path.allowlist(patterns)` | Returns true if all findings are in allowed paths. |
Sample policy (`policies/secret-blocker.stella`):
@@ -224,7 +266,7 @@ policy "Secret Leak Guard" syntax "stella-dsl@1" {
}
rule require_current_bundle priority 5 {
when not secret.bundle.version("2025.11")
when not secret.bundle.version("2026.01")
then warn message "Secret leak bundle out of date";
}
}
@@ -240,14 +282,36 @@ rule low_confidence_warn priority 20 {
}
```
## 6. Observability & reporting
## 7. UI Components
The secret detection UI is available at `/tenants/{tenantId}/secrets/`:
### 7.1 Settings Page
- **General Tab**: Enable/disable detection, revelation policy, rule categories
- **Exceptions Tab**: Manage allowlist patterns for false positive suppression
- **Alerts Tab**: Configure alert destinations and thresholds
### 7.2 Findings List
- Filterable by severity, status, rule category
- Masked value display with conditional reveal
- Pagination and export support
### 7.3 Exception Manager
- Create/edit/delete exception patterns
- Regex validation with test mode
- Expiration dates for temporary exceptions
## 8. Observability & reporting
- **Metrics:** `scanner.secret.finding_total{tenant,ruleId,severity,confidence}` increments per finding. Add Prometheus alerts for spikes.
- **Logs:** `SecretsAnalyzerHost` logs bundle version on load and emits warnings when masking fails (payload never leaves memory).
- **Traces:** Each analyzer run adds a `scanner.secrets.scan` span with rule counts and wall-clock timing.
- **Reports / CLI:** Scan reports include a `secretFindings` array; CLI diff/export surfaces render masked snippets plus remediation guidance.
## 7. Troubleshooting
## 9. Troubleshooting
| Symptom | Resolution |
| --- | --- |
@@ -259,7 +323,7 @@ rule low_confidence_warn priority 20 {
| Bundle integrity check failed | Rules file was modified after signing. Re-download bundle or rebuild from sources. |
| Key not in trusted list | Add signer key ID to `--trusted-key-ids` or update `scanner.secrets.trustedKeyIds` configuration. |
### 7.1 Signature verification troubleshooting
### 9.1 Signature verification troubleshooting
**"Signature verification failed" error:**
@@ -302,9 +366,10 @@ The bundle was created without the `--sign` flag. Either:
- Rebuild with signing: `stella secrets bundle create ... --sign --key-id <key>`
- Skip signature verification: `--skip-signature-verification` (not recommended for production)
## 8. References
## 10. References
- `docs/modules/policy/secret-leak-detection-readiness.md`
- `docs/benchmarks/scanner/deep-dives/secrets.md`
- `docs/modules/scanner/design/surface-secrets.md`
- `docs/07_HIGH_LEVEL_ARCHITECTURE.md` §1.1 Runtime inventory (Scanner)
- `docs/07_HIGH_LEVEL_ARCHITECTURE.md` - Runtime inventory (Scanner)
- [Secrets Bundle Rotation](./secrets-bundle-rotation.md)