Here’s a practical, first‑time‑friendly guide to using VEX in Stella Ops, plus a concrete .NET pattern you can drop in today.

---

# VEX in a nutshell

* **VEX (Vulnerability Exploitability eXchange)**: a small JSON document that says whether specific CVEs *actually* affect a product/version.
* **OpenVEX**: SBOM‑agnostic; references products/components directly (URIs, PURLs, hashes). Great for canonical internal models.
* **CycloneDX VEX / SPDX VEX**: tie VEX statements closely to a specific SBOM instance (component BOM ref IDs). Great when the BOM is your source of truth.

**Our strategy:**

* **Store VEX separately** from SBOMs (deterministic, easier air‑gap bundling).
* **Link by strong references** (PURLs + content hashes + optional SBOM component IDs).
* **Translate on ingest** between OpenVEX ↔ CycloneDX VEX as needed so downstream tools stay happy.

---

# Translation model (OpenVEX ↔ CycloneDX VEX)

1. **Identity mapping**

   * Prefer **PURL** for packages; fallback to **SHA256 (or SHA512)** of artifact; optionally include **SBOM `bom-ref`** if known.
2. **Product scope**

   * OpenVEX “product” → CycloneDX `affects` with `bom-ref` (if available) or a synthetic ref derived from PURL/hash.
3. **Status mapping**

   * `affected | not_affected | under_investigation | fixed` map 1:1.
   * Keep **timestamps**, **justification**, **impact statement**, and **origin**.
4. **Evidence**

   * Preserve links to advisories, commits, tests; attach as CycloneDX `analysis/evidence` notes (or OpenVEX `metadata/notes`).

**Collision rules (deterministic):**

* New statement wins if:

  * Newer `timestamp` **and**
  * Higher **provenance trust** (signed by vendor/Authority) or equal with a lexicographic tiebreak (issuer keyID).

---

# Storage model (MongoDB‑friendly)

* **Collections**

  * `vex.documents` – one doc per VEX file (OpenVEX or CycloneDX VEX).
  * `vex.statements` – *flattened*, one per (product/component, vuln).
  * `artifacts` – canonical component index (PURL, hashes, optional SBOM refs).
* **Reference keys**

  * `artifactKey = purl || sha256 || (groupId:name:version for .NET/NuGet)`
  * `vulnKey = cveId || ghsaId || internalId`
* **Deterministic IDs**

  * `_id = sha256(canonicalize(statement-json-without-signature))`
* **Signatures**

  * Keep DSSE/Sigstore envelopes in `vex.documents.signatures[]` for audit & replay.

---

# Air‑gap bundling

Package **SBOMs + VEX + artifacts index + trust roots** as a single tarball:

```
/bundle/
  sboms/*.json
  vex/*.json              # OpenVEX & CycloneDX VEX allowed
  index/artifacts.jsonl   # purl, hashes, bom-ref map
  trust/rekor.merkle.roots
  trust/fulcio.certs.pem
  trust/keys/*.pub
  manifest.json           # content list + sha256 + issuedAt
```

* **Deterministic replay:** re‑ingest is pure function of bundle bytes → identical DB state.

---

# .NET 10 implementation (C#) – deterministic ingestion

### Core models

```csharp
public record ArtifactRef(
    string? Purl,
    string? Sha256,
    string? BomRef);

public enum VexStatus { Affected, NotAffected, UnderInvestigation, Fixed }

public record VexStatement(
    string StatementId,      // sha256 of canonical payload
    ArtifactRef Artifact,
    string VulnId,           // e.g., "CVE-2024-1234"
    VexStatus Status,
    string? Justification,
    string? ImpactStatement,
    DateTimeOffset Timestamp,
    string IssuerKeyId,      // from DSSE/Signing
    int    ProvenanceScore); // Authority policy
```

### Canonicalizer (stable order, no env fields)

```csharp
static string Canonicalize(VexStatement s)
{
    var payload = new {
        artifact = new { s.Artifact.Purl, s.Artifact.Sha256, s.Artifact.BomRef },
        vulnId = s.VulnId,
        status = s.Status.ToString(),
        justification = s.Justification,
        impact = s.ImpactStatement,
        timestamp = s.Timestamp.UtcDateTime
    };
    // Use System.Text.Json with deterministic ordering
    var opts = new System.Text.Json.JsonSerializerOptions {
        WriteIndented = false
    };
    string json = System.Text.Json.JsonSerializer.Serialize(payload, opts);
    // Normalize unicode + newline
    json = json.Normalize(NormalizationForm.FormKC).Replace("\r\n","\n");
    return json;
}

static string Sha256(string s)
{
    using var sha = System.Security.Cryptography.SHA256.Create();
    var bytes = sha.ComputeHash(System.Text.Encoding.UTF8.GetBytes(s));
    return Convert.ToHexString(bytes).ToLowerInvariant();
}
```

### Ingest pipeline

```csharp
public sealed class VexIngestor
{
    readonly IVexParser _parser;       // OpenVEX & CycloneDX adapters
    readonly IArtifactIndex _artifacts;
    readonly IVexRepo _repo;           // Mongo-backed
    readonly IPolicy _policy;          // tie-break rules

    public async Task IngestAsync(Stream vexJson, SignatureEnvelope? sig)
    {
        var doc = await _parser.ParseAsync(vexJson);              // yields normalized statements
        var issuer = sig?.KeyId ?? "unknown";
        foreach (var st in doc.Statements)
        {
            var canon = Canonicalize(st);
            var id = Sha256(canon);
            var withMeta = st with {
                StatementId = id,
                IssuerKeyId = issuer,
                ProvenanceScore = _policy.Score(sig, st)
            };

            // Upsert artifact (purl/hash/bomRef)
            await _artifacts.UpsertAsync(withMeta.Artifact);

            // Deterministic merge
            var existing = await _repo.GetAsync(id) 
                        ?? await _repo.FindByKeysAsync(withMeta.Artifact, st.VulnId);
            if (existing is null || _policy.IsNewerAndStronger(existing, withMeta))
                await _repo.UpsertAsync(withMeta);
        }

        if (sig is not null) await _repo.AttachSignatureAsync(doc.DocumentId, sig);
    }
}
```

### Parsers (adapters)

* `OpenVexParser` – reads OpenVEX; emits `VexStatement` with `ArtifactRef(PURL/hash)`
* `CycloneDxVexParser` – resolves `bom-ref` → look up PURL/hash via `IArtifactIndex` (if SBOM present); if not, store bom‑ref and mark artifact unresolved for later backfill.

---

# Why this works for Stella Ops

* **SBOM‑agnostic core** (OpenVEX‑first) maps cleanly to your MongoDB canonical stores and `.NET 10` services.
* **SBOM‑aware edges** (CycloneDX VEX) are still supported via adapters and `bom-ref` backfill.
* **Deterministic everything**: canonical JSON → SHA256 IDs → reproducible merges → perfect for audits and offline environments.
* **Air‑gap ready**: single bundle with trust roots, replayable on any node.

---

# Next steps (plug‑and‑play)

1. Implement the two parsers (`OpenVexParser`, `CycloneDxVexParser`).
2. Add the repo/index interfaces to your `StellaOps.Vexer` service:

   * `IVexRepo` (Mongo collections `vex.documents`, `vex.statements`)
   * `IArtifactIndex` (your canonical PURL/hash map)
3. Wire `Policy` to Authority to score signatures and apply tie‑breaks.
4. Add a `bundle ingest` CLI: `vexer ingest /bundle/manifest.json`.
5. Expose GraphQL (HotChocolate) queries:

   * `vexStatements(artifactKey, vulnId)`, `vexStatus(artifactKey)`, `evidence(...)`.

If you want, I can generate the exact Mongo schemas, HotChocolate types, and a minimal test bundle to validate the ingest end‑to‑end.
Below is a complete, developer-ready implementation plan for the **VEX ingestion, translation, canonicalization, storage, and merge-policy pipeline** inside **Stella Ops.Vexer**, aligned with your architecture, deterministic requirements, MongoDB model, DSSE/Authority workflow, and `.NET 10` standards.

This is structured so an average developer can follow it step-by-step without ambiguity.
It is broken into phases, each with clear tasks, acceptance criteria, failure modes, interfaces, and code pointers.

---

# Stella Ops.Vexer

## Full Implementation Plan (Developer-Executable)

---

# 1. Core Objectives

Develop a deterministic, replayable, SBOM-agnostic but SBOM-compatible VEX subsystem supporting:

* OpenVEX and CycloneDX VEX ingestion.
* Canonicalization → SHA-256 identity.
* Cross-linking to artifacts (purl, hash, bom-ref).
* Merge policies driven by Authority trust/lattice rules.
* Complete offline reproducibility.
* MongoDB canonical storage.
* Exposed through gRPC/REST/GraphQL.

---

# 2. Module Structure (to be implemented)

```
src/StellaOps.Vexer/
    Application/
        Commands/
        Queries/
        Ingest/
        Translation/
        Merge/
        Policies/
    Domain/
        Entities/
        ValueObjects/
        Services/
    Infrastructure/
        Mongo/
        AuthorityClient/
        Hashing/
        Signature/
        BlobStore/
    Presentation/
        GraphQL/
        REST/
        gRPC/
```

Every subfolder must compile in strict mode (treat warnings as errors).

---

# 3. Data Model (MongoDB)

## 3.1 `vex.statements` collection

Document schema:

```json
{
  "_id": "sha256(canonical-json)",
  "artifact": {
    "purl": "pkg:nuget/... or null",
    "sha256": "hex or null",
    "bomRef": "optional ref",
    "resolved": true | false
  },
  "vulnId": "CVE-XXXX-YYYY",
  "status": "affected | not_affected | under_investigation | fixed",
  "justification": "...",
  "impact": "...",
  "timestamp": "2024-01-01T12:34:56Z",
  "issuerKeyId": "FULCIO-KEY-ID",
  "provenanceScore": 0–100,
  "documentId": "UUID of vex.documents entry",
  "sourceFormat": "openvex|cyclonedx",
  "createdAt": "...",
  "updatedAt": "..."
}
```

## 3.2 `vex.documents` collection

```
{
  "_id": "<uuid>",
  "format": "openvex|cyclonedx",
  "rawBlobId": "<blob-id in blobstore>",
  "signatures": [
     {
        "type": "dsse",
        "verified": true,
        "issuerKeyId": "F-123...",
        "timestamp": "...",
        "bundleEvidence": {...}
     }
  ],
  "ingestedAt": "...",
  "statementIds": ["sha256-1", "sha256-2", ...]
}
```

---

# 4. Components to Implement

## 4.1 Parsing Layer

### Interfaces

```csharp
public interface IVexParser
{
    ValueTask<ParsedVexDocument> ParseAsync(Stream jsonStream);
}

public sealed record ParsedVexDocument(
    string DocumentId,
    string Format,
    IReadOnlyList<ParsedVexStatement> Statements);
```

### Tasks

1. Implement `OpenVexParser`.

   * Use System.Text.Json source generators.
   * Validate OpenVEX schema version.
   * Extract product → component mapping.
   * Map to internal `ArtifactRef`.

2. Implement `CycloneDxVexParser`.

   * Support 1.5+ “vex” extension.
   * bom-ref resolution through `IArtifactIndex`.
   * Mark unresolved `bom-ref` but store them.

### Acceptance Criteria

* Both parsers produce identical internal representation of statements.
* Unknown fields must not corrupt canonicalization.
* 100% deterministic mapping for same input.

---

## 4.2 Canonicalizer

Implement deterministic ordering, UTF-8 normalization, stable JSON.

### Tasks

1. Create `Canonicalizer` class.
2. Apply:

   * Property order: artifact, vulnId, status, justification, impact, timestamp.
   * Remove optional metadata (issuerKeyId, provenance).
   * Normalize Unicode → NFKC.
   * Replace CRLF → LF.
3. Generate SHA-256.

### Interface

```csharp
public interface IVexCanonicalizer
{
    string Canonicalize(VexStatement s);
    string ComputeId(string canonicalJson);
}
```

### Acceptance Criteria

* Hash identical on all OS, time, locale, machines.
* Replaying the same bundle yields same `_id`.

---

## 4.3 Authority / Signature Verification

### Tasks

1. Implement DSSE envelope reader.
2. Integrate Authority client:

   * Verify certificate chain (Fulcio/GOST/eIDAS etc).
   * Obtain trust lattice score.
   * Produce `ProvenanceScore`: int.

### Interface

```csharp
public interface ISignatureVerifier
{
    ValueTask<SignatureVerificationResult> VerifyAsync(Stream payload, Stream envelope);
}
```

### Acceptance Criteria

* If verification fails → Vexer stores document but flags signature invalid.
* Scores map to priority in merge policy.

---

## 4.4 Merge Policies

### Implement Default Policy

1. Newer timestamp wins.
2. If timestamps equal:

   * Higher provenance score wins.
   * If both equal, lexicographically smaller issuerKeyId wins.

### Interface

```csharp
public interface IVexMergePolicy
{
    bool ShouldReplace(VexStatement existing, VexStatement incoming);
}
```

### Acceptance Criteria

* Merge decisions reproducible.
* Deterministic ordering even when values equal.

---

## 4.5 Ingestion Pipeline

### Steps

1. Accept `multipart/form-data` or referenced blob ID.
2. Parse via correct parser.
3. Verify signature (optional).
4. For each statement:

   * Canonicalize.
   * Compute `_id`.
   * Upsert artifact into `artifacts` (via `IArtifactIndex`).
   * Resolve bom-ref (if CycloneDX).
   * Existing statement? Apply merge policy.
   * Insert or update.
5. Create `vex.documents` entry.

### Class

`VexIngestService`

### Required Methods

```csharp
public Task<IngestResult> IngestAsync(VexIngestRequest request);
```

### Acceptance Tests

* Idempotent: ingesting same VEX repeated → DB unchanged.
* Deterministic under concurrency.
* Air-gap replay produces identical DB state.

---

## 4.6 Translation Layer

### Implement two converters:

* `OpenVexToCycloneDxTranslator`
* `CycloneDxToOpenVexTranslator`

### Rules

* Prefer PURL → hash → synthetic bom-ref.
* Single VEX statement → one CycloneDX “analysis” entry.
* Preserve justification, impact, notes.

### Acceptance Criteria

* Round-trip OpenVEX → CycloneDX → OpenVEX produces equal canonical hashes (except format markers).

---

## 4.7 Artifact Index Backfill

### Reason

CycloneDX VEX may refer to bom-refs not yet known at ingestion.

### Tasks

1. Store unresolved artifacts.
2. Create background `BackfillWorker`:

   * Watches `sboms.documents` ingestion events.
   * Matches bom-refs.
   * Updates statements with resolved PURL/hashes.
   * Recomputes canonical JSON + SHA-256 (new version stored as new ID).
3. Marks old unresolved statement as superseded.

### Acceptance Criteria

* Backfilling is monotonic: no overwriting original.
* Deterministic after backfill: same SBOM yields same final ID.

---

## 4.8 Bundle Ingestion (Air-Gap Mode)

### Structure

```
bundle/
  sboms/*.json
  vex/*.json
  index/artifacts.jsonl
  trust/*
  manifest.json
```

### Tasks

1. Implement `BundleIngestService`.
2. Stages:

   * Validate manifest + hashes.
   * Import trust roots (local only).
   * Ingest SBOMs first.
   * Ingest VEX documents.
3. Reproduce same IDs on all nodes.

### Acceptance Criteria

* Byte-identical bundle → byte-identical DB.
* Works offline completely.

---

# 5. Interfaces for GraphQL/REST/gRPC

Expose:

## Queries

* `vexStatement(id)`
* `vexStatementsByArtifact(purl/hash)`
* `vexStatus(purl)` → latest merged status
* `vexDocument(id)`
* `affectedComponents(vulnId)`

## Mutations

* `ingestVexDocument`
* `translateVex(format)`
* `exportVexDocument(id, targetFormat)`
* `replayBundle(bundleId)`

All responses must include deterministic IDs.

---

# 6. Detailed Developer Tasks by Sprint

## Sprint 1: Foundation

1. Create solution structure.
2. Add Mongo DB contexts.
3. Implement data entities.
4. Implement hashing + canonicalizer.
5. Implement IVexParser interface.

## Sprint 2: Parsers

1. Implement OpenVexParser.
2. Implement CycloneDxParser.
3. Develop strong unit tests for JSON normalization.

## Sprint 3: Signature & Authority

1. DSSE envelope reader.
2. Call Authority to verify signatures.
3. Produce provenance scores.

## Sprint 4: Merge Policy Engine

1. Implement deterministic lattice merge.
2. Unit tests: 20+ collision scenarios.

## Sprint 5: Ingestion Pipeline

1. Implement ingest service end-to-end.
2. Insert/update logic.
3. Add GraphQL endpoints.

## Sprint 6: Translation Layer

1. OpenVEX↔CycloneDX converter.
2. Tests for round-trip.

## Sprint 7: Backfill System

1. Bom-ref resolver worker.
2. Rehashing logic for updated artifacts.
3. Events linking SBOM ingestion to backfill.

## Sprint 8: Air-Gap Bundle

1. BundleIngestService.
2. Manifest verification.
3. Trust root local loading.

## Sprint 9: Hardening

1. Fuzz parsers.
2. Deterministic stress tests.
3. Concurrency validation.
4. Storage compaction.

---

# 7. Failure Handling Matrix

| Failure             | Action                                 | Logged? | Retries |
| ------------------- | -------------------------------------- | ------- | ------- |
| Invalid JSON        | Reject document                        | Yes     | 0       |
| Invalid schema      | Reject                                 | Yes     | 0       |
| Signature invalid   | Store document, mark signature invalid | Yes     | 0       |
| Artifact unresolved | Store unresolved, enqueue backfill     | Yes     | 3       |
| Merge conflict      | Apply policy                           | Yes     | 0       |
| Canonical mismatch  | Hard fail                              | Yes     | 0       |

---

# 8. Developer Unit Test Checklist

### must have tests for:

* Canonicalization stability (100 samples).
* Identical input twice → identical `_id`.
* Parsing OpenVEX with multi-product definitions.
* Parsing CycloneDX with missing bom-refs.
* Merge policy tie-breakers.
* Air-gap replay reproducibility.
* Translation equivalence.

---

# 9. Deliverables for Developers

They must produce:

1. Interfaces + DTOs + document schemas.
2. Canonicalizer with 100% deterministic output.
3. Two production-grade parsers.
4. Signature verification pipeline.
5. Merge policies aligned with Authority trust model.
6. End-to-end ingestion service.
7. Translation layer.
8. Backfill worker.
9. Air-gap bundle script + service.
10. GraphQL APIs.

---

If you want, I can next produce:

* A full **developer handbook** (60–90 pages).
* Full **technical architecture ADRs**.
* A concrete **scaffold** with compiles-clean `.NET 10` project.
* Complete **test suite specification**.
* A **README.md** for new joiners.