up

docs/modules/scanner/determinism-score.md

@@ -1,6 +1,6 @@
 # Scanner Determinism Score Guide
 
-> **Status:** Draft – Sprint 186/202/203  
+> **Status:** Stable (2025-11)  
 > **Owners:** Scanner Guild · QA Guild · DevEx/CLI Guild · DevOps Guild
 
 ## 1. Goal
@@ -22,36 +22,29 @@ Quantify how repeatable a scanner release is by re-running scans under frozen co
 
 The harness persists the full run set under CAS, allowing regression tests and Offline kit inclusion.
 
-## 3. Output artefacts (`SCAN-DETER-186-010`)
+## 3. determinism.json schema (`SCAN-DETER-186-010`)
 
-* `determinism.json` – per-image runs, identical counts, score, policy/feed hashes.
-* `run_i/*.json` – canonicalised outputs for debugging.
-* `diffs/` – optional diff samples when runs diverge.
+Required fields:
 
-Example `determinism.json`:
+- `version` (string, default `1`)
+- `release` (string; e.g., `scanner-0.14.3`)
+- `platform` (`os/arch`)
+- `policy_sha`, `feeds_sha`, `scanner_sha` (content-addressed digests)
+- `images[]`:
+  - `digest` (image digest)
+  - `runs` (int), `identical` (int), `score` (float 0–1)
+  - `artifact_hashes` (map filename → sha256)
+  - `non_deterministic` (array of artefact names when diverged)
+  - `notes` (optional string)
+- `overall_score` (float 0–1)
+- `thresholds` { `image_min`:0.90, `overall_min`:0.95 }
+- `generated_at` (UTC ISO-8601)
 
-```json
-{
-  "release": "scanner-0.14.3",
-  "platform": "linux/amd64",
-  "policy_sha": "a1b2c3…",
-  "feeds_sha": "d4e5f6…",
-  "images": [
-    {
-      "digest": "sha256:abc…",
-      "runs": 10,
-      "identical": 10,
-      "score": 1.0,
-      "artifact_hashes": {
-        "sbom.cdx.json": "sha256:11…",
-        "vex.json": "sha256:22…",
-        "findings.json": "sha256:33…"
-      }
-    }
-  ],
-  "overall_score": 1.0
-}
-```
+Output bundle layout:
+
+- `determinism.json` – schema above
+- `run_i/*.json` – canonicalised artefacts per run
+- `diffs/` – minimal diffs when divergence occurs
 
 ## 4. CI integration (`DEVOPS-SCAN-90-004`)
 
@@ -71,8 +64,12 @@ Example `determinism.json`:
 
 ## 7. Evidence & replay
 
-* Include `determinism.json` and canonical run outputs in Replay bundles (`docs/replay/DETERMINISTIC_REPLAY.md`).
-* DSSE-sign determinism results before adding them to Evidence Locker.
+Replay instructions (deterministic, offline-friendly):
+
+1. Fetch a published determinism bundle (`determinism.json` + `run_*`) and the corresponding scanner image.
+2. Run `scripts/scanner/determinism-run.sh --replay --bundle path/to/bundle --image sha256:...` (uses fixed clock/seed).
+3. Verify hashes match the recorded `artifact_hashes`; tool exits non-zero on mismatch.
+4. Attach the bundle to Evidence Locker with DSSE signature before export.
 
 ## 8. Implementation checklist
 

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