Concelier Ubuntu USN Connector - Operations Runbook

Last updated: 2026-04-21

This runbook is for operators who run the Ubuntu connector in a Stella Ops Concelier instance. It covers configuration, the Excititor VEX mirror bootstrap that shares the same feed, offline mirroring, and the failure modes specific to Ubuntu Security Notices.

1. Overview

The Concelier Ubuntu connector ingests Ubuntu Security Notices (USN) and maps advisories to Ubuntu package versions so the Stella Ops scanner can resolve fixed-versus-affected state per release.

The same public notice feed also backs the default Excititor VEX mirror bootstrap. Ubuntu does not currently publish native CSAF for this path, so Excititor synthesizes deterministic CSAF documents from the notice JSON while preserving the upstream source URI in metadata.

2. Authentication

• No authentication required for public feeds.

3. Configuration (concelier.yaml)

concelier:
  sources:
    ubuntu:
      baseUri: "<ubuntu-usn-base>"
      maxDocumentsPerFetch: 20
      fetchTimeout: "00:00:45"
      requestDelay: "00:00:00"

4. Excititor default public VEX bootstrap

• Index URI: https://ubuntu.com/security/notices.json
• Notice detail base URI: https://ubuntu.com/security/notices/
• Default page size: 20
• Default max notices per fetch: 60
• Default resume overlap: 3.00:00:00

Operational guidance:

• Keep the small page size and bounded fetch count unless Canonical publishes a stronger bulk-ingest contract. This avoids burst-fetching the full notice history during mirror bootstrap.
• Keep the resume overlap enabled so the mirror rechecks recently updated notices without needing a full backfill.
• Mirror both the paged notices.json index responses and the per-notice USN-xxxx-x.json documents for offline kits.

5. Offline and air-gapped deployments

• Mirror USN feeds into the Offline Kit and repoint baseUri to the mirror for advisory ingestion. See the mirror operations guide for staging and verification steps.
• For Excititor mirror bootstrap, mirror the notices.json index plus the per-notice JSON documents under the same path layout so synthesized CSAF documents remain deterministic.

6. Common failure modes

• USN schema updates or missing release references.
• Per-notice JSON documents lagging behind the index update window.
• Overly aggressive page sizes or fetch counts causing avoidable upstream pressure during first-run bootstrap.