# 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. |
| `...: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`
```jsonc
{
  "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
- **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.