90c244948a
- 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.
46 lines
4.8 KiB
Markdown
46 lines
4.8 KiB
Markdown
# Secret Handling & Leak Detection
|
||
|
||
## 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`).
|
||
- Builtin rule sets detect common credentials (AWS, GCP, GitHub PATs, private keys) with allow/deny configurations (`pkg/fanal/secret/builtin-allow-rules.go`) and support custom rule packs via `trivy-secret.yaml`.
|
||
- Findings include file path, line number, severity, and match; operators fine-tune via CLI options (`--secret-config`, `--skip-dirs`, `enable-builtin-rules`).
|
||
- Secret storage/rotation is outside Trivy scope; deployments manage credentials independently.
|
||
|
||
## Snyk approach
|
||
- Secret detection is available through Snyk Code scans (`snyk code test`), invoked from the CLI via the Snyk Code plugin stack (`src/lib/plugins/sast`).[s1]
|
||
- CLI usage requires authentication and uploads code to Snyk’s SaaS backend (per README guidance), so offline workflows are not supported.[s2]
|
||
- Results focus on issue listings from the service; operational secret management is not part of the CLI.
|
||
|
||
## Grype approach
|
||
- Grype does not ship a secret-scanning analyzer; secrets surface only as credentials for registry access (`cmd/grype/cli/options/secret.go`, README sections on mounting Kubernetes secrets).
|
||
- Operators must rely on external tooling for leak detection while Grype focuses exclusively on vulnerability matching.[g1]
|
||
|
||
## Key differences
|
||
- **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 (≤ 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. |
|
||
|
||
### References
|
||
- [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`
|