50 lines
5.2 KiB
Markdown
50 lines
5.2 KiB
Markdown
# Secret Handling & Leak Detection
|
||
|
||
> **Implementation Status:** Secret leak detection (`StellaOps.Scanner.Analyzers.Secrets`) is **NOT YET IMPLEMENTED**.
|
||
> Only Surface.Secrets (operational credential management) is currently available.
|
||
> See implementation sprints: SPRINT_20260104_002 through SPRINT_20260104_005.
|
||
|
||
## StellaOps approach (TARGET - 2026.01+ 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 currently provides operational secret retrieval only; leak detection is **PLANNED** (see implementation sprints). Trivy and Snyk focus exclusively on leak detection while Grype omits it.
|
||
- **Workflow**: StellaOps will perform leak detection in-line during scans with offline rule bundles and policy-aware outcomes (when implemented); Trivy/Snyk rely on mutable rule packs or SaaS classifiers; Grype delegates to external tools.
|
||
- **Determinism**: StellaOps will sign every bundle and record bundle IDs in explain traces (when implemented); 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. **This is the current implementation.** |
|
||
| **StellaOps (PLANNED)** | `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. | **NOT YET IMPLEMENTED** - See SPRINT_20260104_002 through SPRINT_20260104_005. |
|
||
| **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`
|