Concelier Debian Security Tracker Connector - Operations Runbook

Last updated: 2026-06-22

This runbook is for operators who run the Debian Security Tracker connector in a Stella Ops Concelier instance. It covers configuration, offline mirroring, and the publishing-lag failure modes specific to the Debian tracker.

1. Overview

The Debian connector ingests Debian Security Tracker advisories (DSAs) and maps them to Debian package versions so the Stella Ops scanner can resolve fixed-versus-affected state per suite.

When enableJsonTracker is true, the connector also fetches the full Debian security-tracker JSON CVE corpus (tracker/data/json) and maps each affected source-package/CVE tuple through the same DebianMapper and IAdvisoryStore path as DSA advisories. This mode is off by default because it is a large corpus drain; enable it when Debian CVE parity is required.

The scheduled Debian map job is sized for that bulk path: fetch and parse keep short windows, while source:debian:map uses a 90-minute timeout and 30-minute lease so a first-time JSON corpus drain can complete without being cancelled mid-slice.

2. Authentication

No authentication required for public feeds.

3. Configuration (`concelier.yaml`)

concelier:
  sources:
    debian:
      listEndpoint: "https://salsa.debian.org/security-tracker-team/security-tracker/-/raw/master/data/DSA/list"
      detailBaseUri: "https://security-tracker.debian.org/tracker/"
      securityPageBaseUri: "https://www.debian.org/security/"
      maxAdvisoriesPerFetch: 40
      fetchTimeout: "PT45S"
      requestDelay: "PT0S"
      enableJsonTracker: false
      jsonTrackerEndpoint: "https://security-tracker.debian.org/tracker/data/json"
      jsonMaxAdvisoriesPerMapCycle: 5000
      jsonTrackerReleases: ""

JSON tracker settings:

Key	Default	Notes
`enableJsonTracker`	`false`	Enables the full Debian CVE corpus path in addition to DSA list/detail ingestion.
`jsonTrackerEndpoint`	`https://security-tracker.debian.org/tracker/data/json`	Absolute URI for the JSON corpus; can point at an internal mirror.
`jsonMaxAdvisoriesPerMapCycle`	`5000`	Maximum source-package/CVE advisories mapped per map cycle. Use `0` to drain in one cycle.
`jsonTrackerReleases`	empty	Optional comma/newline-separated release allow-list such as `bookworm,bullseye,trixie`; empty ingests every release in the feed.

4. Offline and air-gapped deployments

Mirror the DSA/list raw file, tracker detail pages, Debian security pages, and, when JSON tracker ingestion is enabled, tracker/data/json into the Offline Kit. See the mirror operations guide for staging and verification steps.
Repoint listEndpoint, detailBaseUri, securityPageBaseUri, and jsonTrackerEndpoint to the mirror. Keep the mirrored path shape for security pages as {year}/dsa-NNNN.
Keep jsonMaxAdvisoriesPerMapCycle bounded for first-time drains in smaller environments; the cursor stores jsonTrackerDocumentId and jsonTrackerMapOffset until the corpus is fully mapped.

5. Common failure modes