git.stella-ops.org/docs/modules/excititor/operations/ubuntu-csaf.md

Ubuntu CSAF connector runbook

Updated 2025-11-09 alongside sprint 110/120 trust-provenance work.

Purpose

• Ingest Ubuntu USN/CSAF statements via the restart-only connector (StellaOps.Excititor.Connectors.Ubuntu.CSAF).
• Preserve Aggregation-Only Contract guarantees while surfacing issuance provenance (vex.provenance.*) for VEX Lens and Policy Engine.
• Allow operators to tune trust weighting (tiers, fingerprints, cosign issuers) without recompiling the connector.

Configuration keys

Key	Default	Notes
Excititor:Connectors:Ubuntu:IndexUri	https://ubuntu.com/security/csaf/index.json	Ubuntu CSAF index. Override only when mirroring the feed.
...:Channels	["stable"]	List of channel names to poll. Order preserved for deterministic cursoring.
...:MetadataCacheDuration	4h	How long to cache catalog metadata before re-fetching.
...:PreferOfflineSnapshot / OfflineSnapshotPath / PersistOfflineSnapshot	false / null / true	Enable when running from Offline Kit bundles. Snapshot path must be reachable/read-only under sealed deployments.
...:AllowBuiltInSnapshotFallback	true	When 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.
...:TrustWeight	0.75	Baseline 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 / CosignIdentityPattern	null	Supply 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/Excititor/__Tests/StellaOps.Excititor.Connectors.Ubuntu.CSAF.Tests --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

• Root index returns 404 – with AllowBuiltInSnapshotFallback=true Excititor infers the known public Ubuntu channel catalogs (for example stable/catalog.json) from the configured IndexUri. If you mirror Ubuntu to a custom layout, either preserve the same directory shape or disable the fallback and provide an offline snapshot explicitly.
• Connector refuses to start – check logs for InvalidOperationException referencing CosignIssuer/CosignIdentityPattern or missing snapshot path; the validator enforces complete pairs and on-disk paths.
• Lens still sees default weights – confirm the Excititor deployment picked up the new settings (view /excititor/health JSON → connectors.providers[].options). Lens only overrides when the provenance payload includes vex.provenance.trust.* fields.
• PGP mismatch alerts – if Lens reports fingerprint mismatches, ensure the list ordering matches Canonical’s published order; duplicates are trimmed, so provide each fingerprint once.