Runbook Template: Feed Connector - Vendor-Specific Connectors

Audience: Platform on-call engineers diagnosing vendor and distro advisory connectors (Red Hat, Ubuntu, Debian, Oracle, VMware, MSRC, Cisco, etc.) in Concelier, the vulnerability-feed ingestion service of the Stella Ops release control plane. This page is a reusable template: substitute the concrete source Id for <vendor> to produce or follow a per-connector runbook.

Sprint: SPRINT_20260117_029_DOCS_runbook_coverage Task: RUN-006 - Feed Connector Runbooks

Doc reconciliation (2026-05-30, re-verified 2026-05-31): This template was reconciled against the implementation in src/Concelier (connectors + StellaOps.Concelier.Core.Sources, the StellaOps.Concelier.WebService HTTP surface) and the StellaOps CLI (src/Cli/StellaOps.Cli). Most stella connector ... commands in the original draft do not exist in code — there is no connector command group. They have been replaced with the real, root-wired stella sources, stella db, and stella offline surfaces, or marked NOT IMPLEMENTED / NOT REACHABLE where no working equivalent exists. Two caveats verified against source: (1) stella feeds snapshot ... is defined in CLI source but is never wired into the root command, so it is unreachable; (2) stella admin feeds ... exists in the CLI but its /api/v1/admin/feeds* backend has no server implementation. Vendor source ids, the RequiresAuthentication flags, the diagnostic HTTP endpoints, and the authorization scopes below are verified against source.

Overview

This is a template runbook for vendor-specific advisory feed connectors (Red Hat, Ubuntu, Debian, Oracle, VMware, etc.). Use this template to create runbooks for specific vendor connectors.

The vendor connectors live under src/Concelier/__Libraries/StellaOps.Concelier.Connector.* (distro connectors under ...Connector.Distro.*, vendor PSIRTs under ...Connector.Vndr.*). The canonical catalog of source ids, categories, endpoints, and auth requirements is src/Concelier/__Libraries/StellaOps.Concelier.Core/Sources/SourceDefinitions.cs — use the exact Id value as <vendor> in every command and API call below.

Metadata Template

How vendor connectors work (ground truth)

Diagnosis is deterministic once you know the pipeline:

• Each connector runs as three jobs wired through the Concelier job scheduler: source:<vendor>:fetch, source:<vendor>:parse, and source:<vendor>:map. The job kinds (and their cron schedules) are declared in a static JobDefinitionRecord table in JobRegistrationExtensions.cs; the job implementations live in the connector libraries (e.g. RedHatFetchJob/RedHatParseJob/RedHatMapJob).
• Source configuration (base endpoint, auth, enablement) is defined statically in SourceDefinitions.cs and overlaid by DB-persisted runtime config. Most vendor connectors require no authentication (e.g. redhat, ubuntu, debian, oracle, vmware all have RequiresAuthentication = false). The only sources with RequiresAuthentication = true in SourceDefinitions.cs are microsoft (MSRC) and cisco. ghsa can accept an optional token for higher rate limits, and nuget is a GHSA-covered ecosystem filter rather than a standalone credential target. Credentials are supplied via CONCELIER__SOURCES__... environment variables, not a CLI credential store. (NB: azure reuses the MSRC base endpoint but is declared RequiresAuthentication = false, so it is not in the auth-required set despite pointing at the same upstream.)
• Diagnostic/operational HTTP lives on the Concelier WebService: /api/v1/advisory-sources* (freshness/summary, read) and /jobs* (definitions, runs, trigger). These are the surfaces the CLI and Console use.

Common Vendor Connector Issues

Authentication Failures

Only relevant for connectors with RequiresAuthentication = true in SourceDefinitions.cs - currently microsoft and cisco. The public vendor feeds (redhat, ubuntu, debian, oracle, vmware, and also azure) do not use credentials.

Symptoms:

• Sync failing with 401/403 errors
• “authentication failed” or “invalid credentials” in the source’s lastError

Resolution: Credentials are supplied through environment variables on the Concelier service, not a CLI credential store. The exact variable names are listed per source in SourceDefinitions.cs (CredentialEnvVar), e.g. for MSRC:

CONCELIER__SOURCES__VNDR__MSRC__TENANTID
CONCELIER__SOURCES__VNDR__MSRC__CLIENTID
CONCELIER__SOURCES__VNDR__MSRC__CLIENTSECRET

After updating the environment and restarting Concelier, re-trigger the pipeline and confirm recovery (see Resolution Checklist).

NOT IMPLEMENTED: stella connector credentials show/update <vendor> and stella connector test <vendor>. There is no connector command group. For a live connectivity probe use stella sources check <vendor> (below).

Rate Limiting / Upstream Throttling

Symptoms:

• Sync failing with 429 errors
• “rate limit exceeded” in the source’s lastError

Resolution: Connectors do not perform per-request rate-limit accounting; pacing is governed by the job cron schedule and (where applicable) the fetch window size in the source’s runtime config. To reduce upstream pressure, widen the fetch interval / window via the advisory-source runtime configuration (Console Admin → Advisory Sources, or the concelier:sources:<vendor> config block) rather than a CLI rate-limit command.

NOT IMPLEMENTED: stella connector <vendor> rate-limit-status, stella connector config set <vendor>.sync_interval, and stella connector config set <vendor>.delta_sync. No such commands or config keys exist. Delta vs. full behaviour is a per-export concern (stella db export --delta), not a per-connector toggle.

Data Format Changes

Symptoms:

• Parsing errors in Concelier logs for the source
• Schema-validation failures (documents quarantined / marked Failed)

Resolution: A spike in parse/quarantine usually means an upstream format change. The connector’s parser/mapper must be updated in code (e.g. the *Parser/*Mapper in the connector library) and the Concelier image redeployed.

NOT IMPLEMENTED: stella connector <vendor> schema-check and stella upgrade --component connector-<vendor>. Connectors are not independently upgradable components; they ship inside the Concelier service image. The only self-update command is stella self update (for the CLI binary itself).

Offline Bundle Refresh (air-gap)

Resolution: The reachable offline-kit path is the platform offline command group, which exposes only import and status (see OfflineCommandGroup — BuildOfflineImportCommand, BuildOfflineStatusCommand):

stella offline import <offline-kit.tar.gz>   # import + verify a kit
stella offline status                        # show current offline-kit state

For a downstream / air-gap relay that pulls a pre-aggregated advisory bundle from a parent Stella Ops deployment, use the stella-mirrorsource (source id stella-mirror, default disabled): set STELLA_MIRROR_BASE_URL to the parent’s evidence-locker / mirror root, enable the source (stella sources enable stella-mirror), then drive its pipeline like any other source via the /jobs triggers below.

NOT IMPLEMENTED / NOT REACHABLE — stella feeds snapshot ...: a FeedsCommandGroup defining feeds snapshot create|list|export|import|validate exists in the CLI source (src/Cli/StellaOps.Cli/Commands/FeedsCommandGroup.cs) but it is never wired into the root command (CommandFactory does not call FeedsCommandGroup.BuildFeedsCommand; the class is unreferenced). There is no top-level stella feeds command. Do not document or instruct operators to use stella feeds snapshot — it is unreachable today. (stella config feeds and stella admin feeds are unrelated command groups; see the CLI surface note below.)

NOT IMPLEMENTED: stella offline sync --feeds <vendor> and stella offline load --source <vendor>. The offline group exposes only import and status.

Vendor-Specific Notes

Use this template to create runbooks for the following sources. Source ids and the RequiresAuthentication flag are taken from SourceDefinitions.cs.

Red Hat Security Data

Source id: redhat (and distro id rhel) Configured endpoint: https://access.redhat.com/hydra/rest/securitydata/ Authentication: None (public) Connector: StellaOps.Concelier.Connector.Distro.RedHat

Key commands:

stella sources check redhat                 # live connectivity probe
stella db fetch --source redhat --stage fetch   # trigger fetch (then parse, map)

Ubuntu Security Notices

Source id: ubuntu Configured endpoint: https://ubuntu.com/security/cves.json Authentication: None (public) Connector: StellaOps.Concelier.Connector.Distro.Ubuntu

Key commands:

stella sources check ubuntu
stella db fetch --source ubuntu --stage fetch

Debian Security Tracker

Source id: debian Configured endpoint: https://security-tracker.debian.org/tracker/data/json Authentication: None (public) Connector: StellaOps.Concelier.Connector.Distro.Debian

Key commands:

stella sources check debian
stella db fetch --source debian --stage fetch

Oracle Security Alerts

Source id: oracle Configured endpoint: https://www.oracle.com/security-alerts/ (health check via https://linux.oracle.com/...) Authentication: None (public) Connector: StellaOps.Concelier.Connector.Vndr.Oracle

Key commands:

stella sources check oracle
stella db fetch --source oracle --stage fetch

VMware Security Advisories

Source id: vmware Configured endpoint: https://www.vmware.com/security/advisories.html Authentication: None (public) Connector: StellaOps.Concelier.Connector.Vndr.Vmware

Key commands:

stella sources check vmware
stella db fetch --source vmware --stage fetch

NOT IMPLEMENTED: the per-vendor status verbs in the original draft (stella connector redhat cve-map-status, stella connector ubuntu usn-status, stella connector debian dla-status, stella connector oracle cpu-status, stella connector vmware vmsa-status) do not exist. Use the freshness API and job-run endpoints in the Diagnosis Checklist for per-source status.

Diagnosis Checklist

For any vendor connector issue (<vendor> = the source Id, e.g. redhat):

1. List sources and their freshness state (Concelier WebService):

   curl -s -H "Authorization: Bearer $TOKEN" \
     https://<concelier-host>/api/v1/advisory-sources | jq
   

2. Check freshness for one source (last sync, last success, last error, SLA):

   curl -s -H "Authorization: Bearer $TOKEN" \
     https://<concelier-host>/api/v1/advisory-sources/<vendor>/freshness | jq
   

   Look for lastSyncAt, lastSuccessAt, lastError, errorCount, freshnessStatus.

3. Live connectivity probe from the CLI (hits the source’s health-check endpoint):

   stella sources check <vendor>
   

4. Check the connector job definitions and recent runs:

   curl -s -H "Authorization: Bearer $TOKEN" \
     https://<concelier-host>/jobs/definitions/source:<vendor>:fetch | jq
   curl -s -H "Authorization: Bearer $TOKEN" \
     "https://<concelier-host>/jobs/definitions/source:<vendor>:fetch/runs?limit=10" | jq
   

   Repeat for :parse and :map. Look for Failed outcomes.

5. Check Concelier service logs for the source (transport, schema, parse errors).

Resolution Checklist

1. Force a fetch/parse/map cycle (CLI triggers the backing jobs):

   stella db fetch --source <vendor> --stage fetch
   stella db fetch --source <vendor> --stage parse
   stella db fetch --source <vendor> --stage map
   

   Equivalently, trigger the jobs directly on the Concelier WebService:

   curl -s -X POST -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json' -d '{"trigger":"runbook"}' \
     https://<concelier-host>/jobs/source:<vendor>:fetch
   

2. Re-run canonical merge after fetch/parse/map (if downstream advisories look stale):

   stella db merge
   

3. Update credentials (auth-required sources only): set the CONCELIER__SOURCES__... environment variables for the source and restart Concelier.

4. Update the connector (if upstream format changed): patch the connector parser/mapper in src/Concelier and redeploy the Concelier image (no independent per-connector upgrade command exists).

5. Air-gap / disaster recovery: import an offline kit (the reachable path):

   stella offline import <offline-kit.tar.gz>
   stella offline status
   

   (For a parent-relay sync, enable and drive the stella-mirror source as described under Offline Bundle Refresh above. stella feeds snapshot import is not reachable — see that section.)

Authorization

Scope constants live in src/Authority/StellaOps.Authority/StellaOps.Auth.Abstractions/StellaOpsScopes.cs (ConcelierJobsRead = "concelier.jobs.read", ConcelierJobsTrigger = "concelier.jobs.trigger", AdvisoryRead = "advisory:read"). The GET /jobs* endpoints map to policy Concelier.Jobs.Read; trigger endpoints retain Concelier.Jobs.Trigger. The advisory-source read endpoints map to Concelier.Advisories.Read (AdvisoryReadPolicyName) and are tenant-scoped (RequireTenant()).

CLI surface (verified)

# Advisory-source management (SourcesCommandGroup; wired via CommandFactory.BuildSourcesCommand):
stella sources list [--category <c>] [--enabled-only] [--json]
stella sources check [<vendor>] [--all] [--parallel <n>] [--timeout <s>] [--auto-disable] [--json]
stella sources enable <vendor> [<vendor> ...] [--json]
stella sources disable <vendor> [<vendor> ...] [--json]
stella sources status [--json]
stella sources ingest --dry-run --source <vendor> --input <path-or-uri> [--tenant <t>] [--format table|json] [--output <file>]
                                   # only --dry-run mode is implemented today

# Connector job triggers (Concelier db command group; CommandFactory.BuildDatabaseCommand):
stella db fetch --source <vendor> --stage fetch|parse|map [--mode init|resume|cursor]
stella db merge                            # triggers the merge:reconcile job
stella db export [--format json|trivy-db] [--delta]

# Offline kit (reachable air-gap path; OfflineCommandGroup):
stella offline import <offline-kit>
stella offline status

# Diagnostics:
stella doctor run [--check <id>]   # NB: no per-connector check id exists

NOT IMPLEMENTED (invented in the original draft, no connector command group exists): stella connector test|credentials|config|logs|rate-limit-status| schema-check|<vendor> ..., stella upgrade --component connector-<vendor>, stella offline sync|load, and stella doctor --check check.connector.<vendor>-health (use stella doctor run --check <id>; the connector check id does not exist).

NOT REACHABLE — stella feeds snapshot ...: the FeedsCommandGroup (feeds snapshot create|list|export|import|validate) is defined in CLI source but is never added to the root command, so there is no top-level stella feeds command. Use stella offline import|status (above) for the offline path. See Offline Bundle Refresh.

CLI-vs-backend gap — stella admin feeds: the stella admin feeds list|status|refresh|history commands exist in the CLI (AdminCommandGroup) and call backend endpoints /api/v1/admin/feeds*, but no implementation of those endpoints exists in src(only AdminCommandHandlers.cs references them). They will not work today. Use /api/v1/advisory-sources* and /jobs* (above) for status and refresh.

stella config feedsis a third, unrelated command group that prints a hardcoded demo feed list (CommandFactory.BuildConfigFeedsCommand); it is not an operational source-management surface.

Related Resources

• Connector libraries: src/Concelier/__Libraries/StellaOps.Concelier.Connector.*
• Source catalog (ids/endpoints/auth): src/Concelier/__Libraries/StellaOps.Concelier.Core/Sources/SourceDefinitions.cs
• Job registration / cron: src/Concelier/StellaOps.Concelier.WebService/Extensions/JobRegistrationExtensions.cs
• Connector architecture: docs/modules/concelier/connectors.md
• Vendor connector configs: docs/modules/concelier/operations/connectors/
• Related runbooks: connector-nvd.md, connector-ghsa.md, connector-osv.md