Update AGENTS.md files across multiple modules to standardize task status update instructions and introduce a new document for Secret Leak Detection operations.
- Modified task status update instructions in AGENTS.md files to refer to corresponding sprint files as `/docs/implplan/SPRINT_*.md` instead of `docs/implplan/SPRINTS.md`. - Added a comprehensive document for Secret Leak Detection operations detailing scope, prerequisites, rule bundle lifecycle, enabling the analyzer, policy patterns, observability, troubleshooting, and references.
This commit is contained in:
@@ -1,11 +1,13 @@
|
||||
# Secret Handling
|
||||
# Secret Handling & Leak Detection
|
||||
|
||||
## StellaOps approach
|
||||
- Detailed Policy/Security briefing: `../../modules/policy/secret-leak-detection-readiness.md`.
|
||||
- Secrets treated as operational inputs delivered through Surface.Secrets (`src/Scanner/__Libraries/StellaOps.Scanner.Surface.Secrets` and documented in `docs/modules/scanner/design/surface-secrets.md`).
|
||||
- Providers support Kubernetes Secrets, file-based bundles, and inline definitions; configuration resolved via Surface.Env with validation gates from Surface.Validation.
|
||||
- Secret placeholders (`secret://type/name`) are resolved before analyzers execute, with results wrapped in secure handles and rotation metadata checked at startup.
|
||||
- Scanner deliberately avoids scanning artefacts for secret disclosure to preserve deterministic SBOM pipelines and avoid exposing sensitive payloads.
|
||||
## StellaOps approach (2025.11 release)
|
||||
- Read the Policy/Security briefing: `../../modules/policy/secret-leak-detection-readiness.md`.
|
||||
- Operational runbook: `../../modules/scanner/operations/secret-leak-detection.md`.
|
||||
- Surface.Secrets continues to deliver operational credentials through secure handles (`docs/modules/scanner/design/surface-secrets.md`), with providers supporting Kubernetes Secrets, file bundles, and inline definitions validated by Surface.Validation.
|
||||
- New `StellaOps.Scanner.Analyzers.Secrets` plug-in executes DSSE-signed rule bundles (`offline/rules/secrets/<version>/`) with deterministic regex/entropy detectors. Bundles load at worker start and emit masked findings.
|
||||
- Findings flow into `ScanAnalysisStore` as `secret.leak` evidence, propagated to policy overlays, CLI/export artifacts, and Explain traces. Payloads remain masked (`AKIA****B7` format) and are never persisted in plaintext.
|
||||
- Policy Engine introduces `secret.*` helpers so tenants can block, warn, or waive based on rule ID, severity, confidence, and bundle version.
|
||||
- Offline parity remains intact: rule bundles, DSSE manifests, and optional Rekor proofs ship with the Offline Kit; deployments can operate fully air-gapped.
|
||||
|
||||
## Trivy approach
|
||||
- Secret scanning integrated as an analyzer under `pkg/fanal/secret`, applying regex-based detectors across plaintext files and certain bytecode (e.g., `.pyc`).
|
||||
@@ -23,15 +25,15 @@
|
||||
- Operators must rely on external tooling for leak detection while Grype focuses exclusively on vulnerability matching.[g1]
|
||||
|
||||
## Key differences
|
||||
- **Purpose**: StellaOps focuses on secure retrieval/validation of operational secrets; Trivy and Snyk Code detect leaked secrets, whereas Grype omits secret detection entirely.
|
||||
- **Workflow**: StellaOps’ secret lifecycle is pre-scan configuration; Trivy and Snyk analyse content at scan time (Snyk requiring SaaS connectivity), and Grype requires external tooling for leak detection.
|
||||
- **Determinism**: StellaOps avoids non-deterministic leak scans; Trivy and Snyk’s detectors may evolve with rule updates; Grype remains deterministic by not attempting secret discovery.
|
||||
- **Purpose**: StellaOps now covers both operational secret retrieval *and* deterministic leak detection; Trivy and Snyk focus exclusively on leak detection while Grype omits it.
|
||||
- **Workflow**: StellaOps performs leak detection in-line during scans with offline rule bundles and policy-aware outcomes; Trivy/Snyk rely on mutable rule packs or SaaS classifiers; Grype delegates to external tools.
|
||||
- **Determinism**: StellaOps signs every bundle and records bundle IDs in explain traces; Trivy and Snyk update rules continuously (risking drift); Grype remains deterministic by not scanning.
|
||||
|
||||
### Detection technique comparison
|
||||
| Tool | Detection technique(s) | Merge / result handling | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| **StellaOps (current)** | `Surface.Secrets` providers fetch credentials at runtime; no leak scanning today. | Secrets resolve to opaque handles stored in scan metadata; no SBOM entries emitted. | Deterministic and explainable; avoids exposing payloads. |
|
||||
| **StellaOps (planned)** | `StellaOps.Scanner.Analyzers.Secrets` plug-in executing signed rule bundles. | Findings inserted into `ScanAnalysisStore` as `secret.leak` evidence; Policy Engine merges with component context and lattice scores. | Rules packaged offline; CLI/reporting masks payloads while surfacing rule IDs. |
|
||||
| **StellaOps (≤ 2025.10)** | `Surface.Secrets` providers fetch credentials at runtime; no leak scanning. | Secrets resolve to opaque handles stored in scan metadata; no SBOM entries emitted. | Deterministic secret retrieval only (legacy behaviour). |
|
||||
| **StellaOps (2025.11+)** | `StellaOps.Scanner.Analyzers.Secrets` plug-in executes DSSE-signed rule bundles. | Findings inserted into `ScanAnalysisStore` as `secret.leak` evidence; Policy Engine merges with component context and lattice scores; CLI/export mask payloads. | Rule bundles ship offline, signatures verified locally; see operations runbook for rollout. |
|
||||
| **Trivy** | Regex + entropy detectors under `pkg/fanal/secret` (configurable via `trivy-secret.yaml`). | Detectors aggregate per file; results exported alongside vulnerability findings without provenance binding. | Ships built-in rule sets; users can add allow/block lists. |
|
||||
| **Snyk** | Snyk Code SaaS classifiers invoked by CLI plugin (`src/lib/plugins/sast`). | Source uploaded to SaaS; issues returned with severity + remediation; no offline merge with SBOM data. | Requires authenticated cloud access; rules evolve server-side. |
|
||||
| **Grype** | None (focuses on vulnerability matching). | — | Operators must integrate separate tooling for leak detection. |
|
||||
@@ -40,3 +42,4 @@
|
||||
- [s1] `/tmp/snyk-cli/src/lib/plugins/sast`
|
||||
- [s2] `/tmp/snyk-cli/README.md`
|
||||
- [g1] `/tmp/grype/README.md`
|
||||
- StellaOps runbook: `../../modules/scanner/operations/secret-leak-detection.md`
|
||||
|
||||
Reference in New Issue
Block a user