# 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`