notify doctors work, audit work, new product advisory sprints

2026-01-13 08:36:29 +02:00
parent b8868a5f13
commit 9ca7cb183e
343 changed files with 24492 additions and 3544 deletions
--- a/docs/modules/attestor/rekor-verification-design.md
+++ b/docs/modules/attestor/rekor-verification-design.md
@@ -1,19 +1,20 @@
 # Rekor Verification Technical Design

 **Document ID**: DOCS-ATTEST-REKOR-001
-**Version**: 1.0
-**Last Updated**: 2025-12-14
+**Version**: 2.0
+**Last Updated**: 2026-01-13
 **Status**: Draft

 ---

 ## 1. OVERVIEW

-This document provides the comprehensive technical design for Rekor transparency log verification in StellaOps. It covers three key capabilities:
+This document provides the comprehensive technical design for Rekor transparency log verification in StellaOps. It covers four key capabilities:

 1. **Merkle Proof Verification** - Cryptographic verification of inclusion proofs
 2. **Durable Retry Queue** - Reliable submission with failure recovery
 3. **Time Skew Validation** - Replay protection via timestamp validation
+4. **Tile-Based Verification (v2)** - Support for Rekor v2 Sunlight format

 ### Related Sprints

@@ -22,6 +23,7 @@ This document provides the comprehensive technical design for Rekor transparency
 | SPRINT_3000_0001_0001 | P0 | Merkle Proof Verification |
 | SPRINT_3000_0001_0002 | P1 | Rekor Retry Queue & Metrics |
 | SPRINT_3000_0001_0003 | P2 | Time Skew Validation |
+| SPRINT_3000_0001_0004 | P1 | Rekor v2 Tile-Based Verification |

 ---

@@ -405,6 +407,225 @@ public TimeSkewResult Validate(DateTimeOffset integratedTime, DateTimeOffset loc
 }
 ```

+### 3.4 Tile-Based Verification (Rekor v2)
+
+Rekor v2 introduces a tile-based log structure following the Sunlight/C2SP `tlog-tiles` specification. This enables offline-capable verification and more efficient proof computation.
+
+#### 3.4.1 Architecture Overview
+
+In tile-based logs, the Merkle tree is stored in fixed-size chunks (tiles) of 256 entries each:
+
+```
+                    Tile Structure (256 entries/tile)
+    ───────────────────────────────────────────────────────────
+                           Level 2 (root)
+                              [Tile]
+                             /      \
+                    Level 1 (intermediate)
+                   [Tile 0]  [Tile 1]  ...
+                   /      \
+              Level 0 (leaves)
+    [Tile 0] [Tile 1] [Tile 2] [Tile 3] ...
+
+    Each tile contains up to 256 hashes (32 bytes each = 8KB max)
+```
+
+#### 3.4.2 Log Version Configuration
+
+StellaOps supports automatic version detection and explicit version selection:
+
+```csharp
+public enum RekorLogVersion
+{
+    Auto = 0,   // Auto-detect based on endpoint availability
+    V1 = 1,     // Traditional Trillian-based Rekor (API proofs)
+    V2 = 2      // Tile-based Sunlight format
+}
+```
+
+**Version Selection Logic:**
+
+| Version | PreferTileProofs | Result |
+|---------|------------------|--------|
+| V2 | (any) | Always use tile proofs |
+| V1 | (any) | Always use API proofs |
+| Auto | true | Prefer tile proofs if available |
+| Auto | false | Use API proofs (default) |
+
+#### 3.4.3 Checkpoint Format
+
+V2 checkpoints follow the `c2sp.org/tlog-tiles` format:
+
+```
+rekor.sigstore.dev - 2605736670972794746
+<tree_size>
+<root_hash_base64>
+
+- rekor.sigstore.dev <signature_base64>
+```
+
+**Checkpoint Components:**
+- **Line 1**: Origin identifier (log name + instance)
+- **Line 2**: Tree size (number of leaves)
+- **Line 3**: Root hash (base64-encoded SHA-256)
+- **Blank line**: Separator
+- **Signature lines**: One or more `- <origin> <signature>` lines
+
+#### 3.4.4 Tile Path Calculation
+
+Tiles are fetched via URL paths following the scheme:
+
+```
+GET {tile_base_url}/tile/{level}/{index:03d}[.p/{partial_width}]
+
+Examples:
+- /tile/0/000        # Level 0, tile 0 (entries 0-255)
+- /tile/0/001        # Level 0, tile 1 (entries 256-511)
+- /tile/1/000        # Level 1, tile 0 (intermediate hashes)
+- /tile/0/042.p/128  # Partial tile with 128 entries
+```
+
+#### 3.4.5 Implementation Classes
+
+**IRekorTileClient Interface:**
+
+```csharp
+public interface IRekorTileClient
+{
+    Task<RekorTileCheckpoint?> GetCheckpointAsync(
+        RekorBackend backend,
+        CancellationToken cancellationToken = default);
+
+    Task<RekorTileData?> GetTileAsync(
+        RekorBackend backend,
+        int level,
+        long index,
+        CancellationToken cancellationToken = default);
+
+    Task<RekorTileEntry?> GetEntryAsync(
+        RekorBackend backend,
+        long logIndex,
+        CancellationToken cancellationToken = default);
+
+    Task<RekorTileInclusionProof?> ComputeInclusionProofAsync(
+        RekorBackend backend,
+        long logIndex,
+        long treeSize,
+        CancellationToken cancellationToken = default);
+}
+```
+
+**RekorTileData Model:**
+
+```csharp
+public sealed class RekorTileData
+{
+    public required int Level { get; init; }
+    public required long Index { get; init; }
+    public required int Width { get; init; }  // Number of hashes (max 256)
+    public required byte[] Hashes { get; init; }  // Width * 32 bytes
+
+    public byte[] GetHash(int position)
+    {
+        if (position < 0 || position >= Width)
+            throw new ArgumentOutOfRangeException(nameof(position));
+
+        var result = new byte[32];
+        Array.Copy(Hashes, position * 32, result, 0, 32);
+        return result;
+    }
+}
+```
+
+#### 3.4.6 Proof Computation Algorithm
+
+Computing an inclusion proof from tiles:
+
+```python
+def compute_inclusion_proof(log_index, tree_size, tile_client):
+    """Compute inclusion proof by fetching necessary tiles."""
+    proof_path = []
+    level = 0
+    index = log_index
+    size = tree_size
+
+    while size > 1:
+        tile_index = index // 256
+        position_in_tile = index % 256
+
+        # Determine sibling position
+        if index % 2 == 1:
+            sibling_pos = position_in_tile - 1
+        else:
+            sibling_pos = position_in_tile + 1 if position_in_tile + 1 < size else None
+
+        if sibling_pos is not None:
+            tile = tile_client.get_tile(level, tile_index)
+            proof_path.append(tile.get_hash(sibling_pos))
+
+        index = index // 2
+        size = (size + 1) // 2
+        level += 1
+
+    return proof_path
+```
+
+#### 3.4.7 Configuration
+
+```yaml
+attestor:
+  rekor:
+    primary:
+      url: https://rekor.sigstore.dev
+      # Version: Auto, V1, or V2
+      version: Auto
+      # Custom tile base URL (optional, defaults to {url}/tile/)
+      tile_base_url: ""
+      # Log ID for multi-log environments (hex-encoded SHA-256)
+      log_id: "c0d23d6ad406973f9559f3ba2d1ca01f84147d8ffc5b8445c224f98b9591801d"
+      # Prefer tile proofs when version is Auto
+      prefer_tile_proofs: false
+```
+
+**Environment Variables:**
+
+```bash
+# Rekor v2 Configuration
+REKOR_SERVER_URL=https://rekor.sigstore.dev
+REKOR_VERSION=Auto           # Auto, V1, or V2
+REKOR_TILE_BASE_URL=         # Optional custom tile endpoint
+REKOR_LOG_ID=c0d23d6ad406973f9559f3ba2d1ca01f84147d8ffc5b8445c224f98b9591801d
+REKOR_PREFER_TILE_PROOFS=false
+```
+
+#### 3.4.8 Offline Verification Benefits
+
+Tile-based verification enables true offline capability:
+
+1. **Pre-fetch tiles**: Download all necessary tiles during online phase
+2. **Bundle checkpoint**: Include signed checkpoint with offline kit
+3. **Local proof computation**: Compute proofs entirely from local tile data
+4. **No API dependency**: Verification works without Rekor connectivity
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Offline Verification                      │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌─────────────┐     ┌──────────────┐     ┌──────────────┐  │
+│  │ Checkpoint  │────►│ Tile Cache   │────►│ Proof        │  │
+│  │ (signed)    │     │ (local)      │     │ Verifier     │  │
+│  └─────────────┘     └──────────────┘     └──────────────┘  │
+│                                                              │
+│  Advantages:                                                 │
+│  - No network round-trips for proof fetching                │
+│  - Deterministic verification (same tiles = same proof)     │
+│  - Caching efficiency (tiles are immutable)                 │
+│  - Air-gap compatible                                        │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
 ---

 ## 4. DATA FLOW
@@ -688,4 +909,7 @@ attestor:
 - [RFC 6962: Certificate Transparency](https://datatracker.ietf.org/doc/html/rfc6962)
 - [Sigstore Rekor](https://github.com/sigstore/rekor)
 - [Transparency.dev Checkpoint Format](https://github.com/transparency-dev/formats)
+- [C2SP tlog-tiles Specification](https://c2sp.org/tlog-tiles) - Tile-based transparency log format
+- [Sunlight CT Log](https://github.com/FiloSottile/sunlight) - Reference implementation for tile-based logs
+- [Sigstore Rekor v2 Announcement](https://blog.sigstore.dev/) - Official Rekor v2 migration information
 - [Advisory: Rekor Integration Technical Reference](../../../product/advisories/14-Dec-2025%20-%20Rekor%20Integration%20Technical%20Reference.md)
--- a/docs/modules/scanner/binary-diff-attestation.md
+++ b/docs/modules/scanner/binary-diff-attestation.md
@@ -0,0 +1,355 @@
+# Binary Diff Attestation
+
+## Overview
+
+Binary Diff Attestation enables verification of binary-level changes between container images, producing cryptographically signed evidence of what changed at the ELF/PE section level. This capability is essential for:
+
+- **Vendor backport detection**: Identify when a vendor has patched a binary without changing version numbers
+- **Supply chain verification**: Prove that expected changes (and no unexpected changes) occurred between releases
+- **VEX evidence generation**: Provide concrete evidence for "not_affected" or "fixed" vulnerability status claims
+- **Audit trail**: Maintain verifiable records of binary modifications across deployments
+
+### Relationship to SBOM and VEX
+
+Binary diff attestations complement SBOM and VEX documents:
+
+| Artifact | Purpose | Granularity |
+|----------|---------|-------------|
+| SBOM | Inventory of components | Package/library level |
+| VEX | Exploitability status | Vulnerability level |
+| Binary Diff Attestation | Change evidence | Section/function level |
+
+The attestation provides the *evidence* that supports VEX claims. For example, a VEX statement claiming a CVE is "fixed" due to a vendor backport can reference the binary diff attestation showing the `.text` section hash changed.
+
+## Architecture
+
+### Component Diagram
+
+```
+┌──────────────────────────────────────────────────────────────────────────────┐
+│                          Binary Diff Attestation Flow                         │
+├──────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐   │
+│  │   OCI       │    │   Layer     │    │   Binary    │    │  Section    │   │
+│  │  Registry   │───▶│ Extraction  │───▶│ Detection   │───▶│   Hash      │   │
+│  │  Client     │    │             │    │             │    │ Extractor   │   │
+│  └─────────────┘    └─────────────┘    └─────────────┘    └──────┬──────┘   │
+│                                                                   │          │
+│         Base Image ─────────────────────────────────────┐        │          │
+│         Target Image ───────────────────────────────────┤        ▼          │
+│                                                         │  ┌─────────────┐  │
+│                                                         └─▶│   Diff      │  │
+│                                                            │ Computation │  │
+│                                                            └──────┬──────┘  │
+│                                                                   │          │
+│                                                                   ▼          │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐   │
+│  │   DSSE      │◀───│  Predicate  │◀───│  Finding    │◀───│   Verdict   │   │
+│  │   Signer    │    │  Builder    │    │ Aggregation │    │ Classifier  │   │
+│  └──────┬──────┘    └─────────────┘    └─────────────┘    └─────────────┘   │
+│         │                                                                    │
+│         ▼                                                                    │
+│  ┌─────────────┐    ┌─────────────┐                                         │
+│  │   Rekor     │    │  File       │                                         │
+│  │ Submission  │    │  Output     │                                         │
+│  └─────────────┘    └─────────────┘                                         │
+│                                                                              │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Key Components
+
+| Component | Location | Responsibility |
+|-----------|----------|----------------|
+| `ElfSectionHashExtractor` | `Scanner.Analyzers.Native` | Extract per-section SHA-256 hashes from ELF binaries |
+| `BinaryDiffService` | `Cli.Services` | Orchestrate diff computation between two images |
+| `BinaryDiffPredicateBuilder` | `Attestor.StandardPredicates` | Construct BinaryDiffV1 in-toto predicates |
+| `BinaryDiffDsseSigner` | `Attestor.StandardPredicates` | Sign predicates with DSSE envelopes |
+
+### Data Flow
+
+1. **Image Resolution**: Resolve base and target image references to manifest digests
+2. **Layer Extraction**: Download and extract layers from both images
+3. **Binary Identification**: Identify ELF binaries in both filesystems
+4. **Section Hash Computation**: Compute SHA-256 for each target section in each binary
+5. **Diff Computation**: Compare section hashes between base and target
+6. **Verdict Classification**: Classify changes as patched/vanilla/unknown
+7. **Predicate Construction**: Build BinaryDiffV1 predicate with findings
+8. **DSSE Signing**: Sign predicate and optionally submit to Rekor
+
+## ELF Section Hashing
+
+### Target Sections
+
+The following ELF sections are analyzed for hash computation:
+
+| Section | Purpose | Backport Relevance |
+|---------|---------|-------------------|
+| `.text` | Executable code | **High** - Patched functions modify this section |
+| `.rodata` | Read-only data (strings, constants) | Medium - String constants may change with patches |
+| `.data` | Initialized global/static variables | Low - Rarely changes for security patches |
+| `.symtab` | Symbol table (function names, addresses) | **High** - Function signature changes |
+| `.dynsym` | Dynamic symbols (exports) | **High** - Exported API changes |
+
+### Hash Algorithm
+
+**Primary**: SHA-256
+- Industry standard, widely supported
+- Collision-resistant for security applications
+
+**Optional**: BLAKE3-256
+- Faster computation for large binaries
+- Enabled via configuration
+
+### Hash Computation
+
+```
+For each ELF binary:
+  1. Parse ELF header
+  2. Locate section headers
+  3. For each target section:
+     a. Read section contents
+     b. Compute SHA-256(contents)
+     c. Store: {name, offset, size, sha256}
+  4. Sort sections by name (lexicographic)
+  5. Return ElfSectionHashSet
+```
+
+### Determinism Guarantees
+
+All operations produce deterministic output:
+
+| Aspect | Guarantee |
+|--------|-----------|
+| Section ordering | Sorted lexicographically by name |
+| Hash format | Lowercase hexadecimal, no prefix |
+| Timestamps | From injected `TimeProvider` |
+| JSON serialization | RFC 8785 canonical JSON |
+
+## BinaryDiffV1 Predicate
+
+### Schema Overview
+
+The `BinaryDiffV1` predicate follows in-toto attestation format:
+
+```json
+{
+  "_type": "https://in-toto.io/Statement/v1",
+  "subject": [
+    {
+      "name": "docker://repo/app@sha256:target...",
+      "digest": { "sha256": "target..." }
+    }
+  ],
+  "predicateType": "stellaops.binarydiff.v1",
+  "predicate": {
+    "inputs": {
+      "base": { "digest": "sha256:base..." },
+      "target": { "digest": "sha256:target..." }
+    },
+    "findings": [...],
+    "metadata": {...}
+  }
+}
+```
+
+### Predicate Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `subjects` | array | Target image references with digests |
+| `inputs.base` | object | Base image reference |
+| `inputs.target` | object | Target image reference |
+| `findings` | array | Per-binary diff findings |
+| `metadata` | object | Tool version, timestamp, config |
+
+### Finding Structure
+
+Each finding represents a binary comparison:
+
+```json
+{
+  "path": "/usr/lib/libssl.so.3",
+  "changeType": "modified",
+  "binaryFormat": "elf",
+  "sectionDeltas": [
+    { "section": ".text", "status": "modified" },
+    { "section": ".rodata", "status": "identical" }
+  ],
+  "confidence": 0.95,
+  "verdict": "patched"
+}
+```
+
+### Verdicts
+
+| Verdict | Meaning | Confidence Threshold |
+|---------|---------|---------------------|
+| `patched` | Binary shows evidence of security patch | >= 0.90 |
+| `vanilla` | Binary matches upstream/unmodified | >= 0.95 |
+| `unknown` | Cannot determine patch status | < 0.90 |
+| `incompatible` | Cannot compare (different architecture, etc.) | N/A |
+
+## DSSE Attestation
+
+### Envelope Structure
+
+```json
+{
+  "payloadType": "stellaops.binarydiff.v1",
+  "payload": "<base64-encoded predicate>",
+  "signatures": [
+    {
+      "keyid": "...",
+      "sig": "<base64-encoded signature>"
+    }
+  ]
+}
+```
+
+### Signature Algorithm
+
+- **Default**: Ed25519
+- **Alternative**: ECDSA P-256, RSA-PSS (via `ICryptoProviderRegistry`)
+- **Keyless**: Sigstore Fulcio certificate chain
+
+### Rekor Submission
+
+When Rekor is enabled:
+
+1. DSSE envelope is submitted to Rekor transparency log
+2. Inclusion proof is retrieved
+3. Rekor metadata is stored in result
+
+```json
+{
+  "rekorLogIndex": 12345678,
+  "rekorEntryId": "abc123...",
+  "integratedTime": "2026-01-13T12:00:00Z"
+}
+```
+
+### Verification
+
+Binary diff attestations can be verified with:
+
+```bash
+# Using cosign
+cosign verify-attestation \
+  --type stellaops.binarydiff.v1 \
+  --certificate-identity-regexp '.*' \
+  --certificate-oidc-issuer-regexp '.*' \
+  docker://repo/app:1.0.1
+
+# Using stella CLI
+stella verify attestation ./binarydiff.dsse.json \
+  --type stellaops.binarydiff.v1
+```
+
+## Integration Points
+
+### VEX Mapping
+
+Binary diff evidence can support VEX claims:
+
+```json
+{
+  "vulnerability": "CVE-2024-1234",
+  "status": "fixed",
+  "justification": "vulnerable_code_not_present",
+  "detail": "Vendor backport applied; evidence in binary diff attestation",
+  "evidence": {
+    "attestationRef": "sha256:dsse-envelope-hash...",
+    "finding": {
+      "path": "/usr/lib/libssl.so.3",
+      "verdict": "patched",
+      "confidence": 0.95
+    }
+  }
+}
+```
+
+### Policy Engine
+
+Policy rules can reference binary diff evidence:
+
+```rego
+# Accept high-confidence patch verdicts as mitigation
+allow contains decision if {
+    input.binaryDiff.findings[_].verdict == "patched"
+    input.binaryDiff.findings[_].confidence >= 0.90
+    decision := {
+        "action": "accept",
+        "reason": "Binary diff shows patched code",
+        "evidence": input.binaryDiff.attestationRef
+    }
+}
+```
+
+### SBOM Properties
+
+Section hashes appear in SBOM component properties:
+
+```json
+{
+  "type": "library",
+  "name": "libssl.so.3",
+  "properties": [
+    {"name": "evidence:section:.text:sha256", "value": "abc123..."},
+    {"name": "evidence:section:.rodata:sha256", "value": "def456..."},
+    {"name": "evidence:extractor-version", "value": "1.0.0"}
+  ]
+}
+```
+
+## Configuration
+
+### Scanner Options
+
+```yaml
+scanner:
+  native:
+    sectionHashes:
+      enabled: true
+      algorithms:
+        - sha256
+        - blake3  # optional
+      sections:
+        - .text
+        - .rodata
+        - .data
+        - .symtab
+        - .dynsym
+      maxSectionSize: 104857600  # 100MB limit
+```
+
+### CLI Options
+
+See [CLI Reference](../../API_CLI_REFERENCE.md#stella-scan-diff) for full option documentation.
+
+## Limitations and Future Work
+
+### Current Limitations
+
+1. **ELF only**: PE and Mach-O support planned for M2
+2. **Single platform**: Multi-platform diff requires multiple invocations
+3. **No function-level analysis**: Section-level granularity only
+4. **Confidence scoring**: Based on section changes, not semantic analysis
+
+### Roadmap
+
+| Milestone | Capability |
+|-----------|------------|
+| M2 | PE section analysis for Windows containers |
+| M2 | Mach-O section analysis for macOS binaries |
+| M3 | Vendor backport corpus with curated test fixtures |
+| M3 | Function-level diff using DWARF debug info |
+| M4 | ML-based verdict classification |
+
+## References
+
+- [BinaryDiffV1 JSON Schema](../../schemas/binarydiff-v1.schema.json)
+- [in-toto Attestation Specification](https://github.com/in-toto/attestation)
+- [DSSE Envelope Specification](https://github.com/secure-systems-lab/dsse)
+- [ELF Specification](https://refspecs.linuxfoundation.org/elf/elf.pdf)