Ubuntu CSAF Connector Runbook

Audience: Operators configuring, tuning, and troubleshooting the Ubuntu VEX connector in Excititor. Updated 2025-11-09 alongside Sprint 110/120 trust-provenance work.

Purpose

Configuration keys

KeyDefaultNotes
Excititor:Connectors:Ubuntu:IndexUrihttps://ubuntu.com/security/csaf/index.jsonUbuntu CSAF index. Override only when mirroring the feed.
...:Channels["stable"]List of channel names to poll. Order preserved for deterministic cursoring.
...:MetadataCacheDuration4hHow long to cache catalog metadata before re-fetching.
...:PreferOfflineSnapshot / OfflineSnapshotPath / PersistOfflineSnapshotfalse / null / trueEnable when running from Offline Kit bundles. Snapshot path must be reachable/read-only under sealed deployments.
...:AllowBuiltInSnapshotFallbacktrueWhen the public Canonical root index is unavailable and no offline snapshot exists, Excititor infers the known public channel catalog URLs from IndexUri so bootstrap does not fail on a missing discovery document alone.
...:TrustWeight0.75Baseline trust weight (0–1). Lens multiplies this by freshness/justification modifiers.
...:TrustTier"distro"Friendly tier label surfaced via vex.provenance.trust.tier (e.g., distro-trusted, community).
...:CosignIssuer / CosignIdentityPatternnullSupply when Ubuntu publishes cosign attestations (issuer URL and identity regex). Required together.
...:PgpFingerprints[]Ordered list of trusted PGP fingerprints. Emitted verbatim as vex.provenance.pgp.fingerprints.

Example appsettings.json

{
  "Excititor": {
    "Connectors": {
      "Ubuntu": {
        "IndexUri": "https://mirror.example.com/security/csaf/index.json",
        "Channels": ["stable", "esm-apps"],
        "TrustWeight": 0.82,
        "TrustTier": "distro-trusted",
        "CosignIssuer": "https://issuer.ubuntu.com",
        "CosignIdentityPattern": "spiffe://ubuntu/vex/*",
        "PgpFingerprints": [
          "0123456789ABCDEF0123456789ABCDEF01234567",
          "89ABCDEF0123456789ABCDEF0123456789ABCDEF"
        ],
        "PreferOfflineSnapshot": true,
        "OfflineSnapshotPath": "/opt/stella/offline/ubuntu/index.json"
      }
    }
  }
}

Environment variable cheatsheet

Excititor__Connectors__Ubuntu__TrustWeight=0.9
Excititor__Connectors__Ubuntu__TrustTier=distro-critical
Excititor__Connectors__Ubuntu__PgpFingerprints__0=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Excititor__Connectors__Ubuntu__PgpFingerprints__1=BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB
Excititor__Connectors__Ubuntu__CosignIssuer=https://issuer.ubuntu.com
Excititor__Connectors__Ubuntu__CosignIdentityPattern=spiffe://ubuntu/vex/*

Operational checklist

  1. Before enabling – import the Ubuntu PGP bundle (Offline Kit provides certificates/ubuntu-vex.gpg) and set the fingerprints so provenance metadata stays deterministic.
  2. Validate provenance output – run dotnet test src/Concelier/__Tests/StellaOps.Excititor.Connectors.Ubuntu.CSAF.Tests/StellaOps.Excititor.Connectors.Ubuntu.CSAF.Tests.csproj --filter FetchAsync_IngestsNewDocument to ensure the connector emits the vex.provenance.* fields expected by VEX Lens.
  3. Monitor Lens weights – Grafana panels VEX Lens / Trust Inputs show the weight/tier captured per provider. Ubuntu rows should reflect the configured TrustWeight and fingerprints.
  4. Rotate fingerprints – update PgpFingerprints when Canonical rotates signing keys. Apply the change, restart Excititor workers, verify the provenance metadata, then trigger a targeted Lens recompute for Ubuntu issuers.
  5. Offline mode – populate OfflineSnapshotPath via Offline Kit bundles before toggling PreferOfflineSnapshot. Keep snapshots in the sealed /opt/stella/offline hierarchy for auditability.

Troubleshooting