up

docs/modules/scanner/entropy.md

@@ -1,6 +1,7 @@
 # Entropy Analysis for Executable Layers
 
-> **Status:** Draft – Sprint 186/209  
+> **Imposed rule:** Entropy evidence must be included in scan exports and DSSE attestations; opaque regions without provenance cannot be whitelisted without an explicit policy waiver.
+> **Status:** Stable (2025-11)  
 > **Owners:** Scanner Guild · Policy Guild · UI Guild · Docs Guild
 
 ## 1. Overview
@@ -25,10 +26,11 @@ Entropy analysis highlights opaque regions inside container layers (packed binar
   * Flag entire files with no symbols or stripped debug info.
   * Detect known packer section names (`.UPX*`, `.aspack`, etc.).
   * Record offsets, window sizes, and entropy values to support explainability.
-* **Outputs:**
-  * `entropy.report.json` (per-file details, windows, hints).
-  * `layer_summary.json` (opaque byte ratios per layer and overall image).
-  * Penalty score contributed to the trust algebra (`entropy_penalty`).
+* **Outputs (all canonical, UTF-8, sorted keys):**
+  * `entropy.report.json` (per-file details, windows, hints; schema `stellaops.entropy/report@1`).
+  * `layer_summary.json` (opaque byte ratios per layer and overall image; schema `stellaops.entropy/layer-summary@1`).
+  * `entropy_penalty` scalar injected into trust lattice inputs.
+* All outputs are signed within the scan DSSE bundle and exported in Offline/Replay kits.
 
 All JSON output is canonical (sorted keys, UTF-8) and included in DSSE attestations/replay bundles.
 
@@ -39,6 +41,7 @@ All JSON output is canonical (sorted keys, UTF-8) and included in DSSE attestati
 ```jsonc
 {
   "schema": "stellaops.entropy/report@1",
+  "generatedAt": "2025-11-26T12:00:00Z",
   "imageDigest": "sha256:…",
   "layerDigest": "sha256:…",
   "files": [
@@ -62,6 +65,7 @@ All JSON output is canonical (sorted keys, UTF-8) and included in DSSE attestati
 ```jsonc
 {
   "schema": "stellaops.entropy/layer-summary@1",
+  "generatedAt": "2025-11-26T12:00:00Z",
   "imageDigest": "sha256:…",
   "layers": [
     {
@@ -80,12 +84,13 @@ All JSON output is canonical (sorted keys, UTF-8) and included in DSSE attestati
 ## 4. Policy integration (`POLICY-RISK-90-001`)
 
 * Policy Engine receives `entropy_penalty` and per-layer ratios via scan evidence.
-* Default thresholds:
-  * Block when `imageOpaqueRatio > 0.15` and provenance unknown.
+* Default thresholds (tenant-overridable):
+  * Block when `imageOpaqueRatio > 0.15` **and** provenance unknown.
   * Warn when any executable has `opaqueRatio > 0.30`.
-* Penalty weights are configurable per tenant. Policy explanations include:
-  * Highest-entropy files and offsets.
-  * Reason code (packed, no symbols, runtime reachable).
+  * Suppress penalty when symbols are present **and** provenance attested.
+* Trust lattice mapping:
+  * `entropy_penalty` feeds the risk lattice alongside reachability, provenance, and exploitability signals; capped at 0.3.
+  * Policy explanations include highest-entropy files, offsets, and reason codes (packed, no symbols, runtime reachable).
 
 ## 5. UI experience (`UI-ENTROPY-40-001/002`)
 
@@ -97,21 +102,22 @@ All JSON output is canonical (sorted keys, UTF-8) and included in DSSE attestati
 
 ## 6. CLI / API hooks
 
-* CLI – `stella scan artifacts --entropy` option prints top opaque files and penalties.
-* API – `GET /api/v1/scans/{id}/entropy` serves summary + evidence references.
-* Notify templates can include entropy penalties to escalate opaque images.
+* CLI – `stella scan artifacts --entropy --threshold 0.15 --top 10` prints top opaque files and penalty; exits non-zero when penalty exceeds threshold.
+* CLI – `stella scan export --include entropy` bundles entropy reports with SBOM/VEX for Offline kits.
+* API – `GET /api/v1/scans/{id}/entropy` serves summary + evidence references; supports `Accept: application/json` or NDJSON stream.
+* Notify templates can include entropy penalties to escalate opaque images (channel: Ops/Sec).
 
 ## 7. Trust algebra
 
 The penalty is computed as:
 
 \[
-\text{entropyPenalty} = K \sum_{\text{layers}} \left( \frac{\text{opaqueBytes}}{\text{totalBytes}} \times \frac{\text{layerBytes}}{\text{imageBytes}} \right)
+\text{entropyPenalty} = \min\Bigg(0.3,\; K \sum_{\text{layers}} \big( \frac{\text{opaqueBytes}}{\text{totalBytes}} \times \frac{\text{layerBytes}}{\text{imageBytes}} \big)\Bigg)
 \]
 
-* Default `K = 0.5`.
-* Cap penalty at 0.3 to avoid over-weighting tiny blobs.
-* Combine with other trust signals (reachability, provenance) to prioritise audits.
+* Default `K = 0.5`; tenants can override via policy lattice config.
+* If symbols are present and attested, apply a 0.5 multiplier to the per-layer contribution.
+* Combine with reachability and provenance weights before final risk verdict.
 
 ## 8. Implementation checklist