838257245a
Closes the last open task in SPRINT_20260422_003. Persisted operator
enablement is now separated from runtime readiness so credential-gated
sources can show an explicit blocked state instead of collapsing into a
generic failed/disabled shape.
Readiness model:
- new SourceReadiness constants class: Disabled | Unsupported | Blocked | Ready
- ConfiguredAdvisorySourceStatus gains Readiness + BlockedReason alongside
existing SyncState (kept as backward-compatible alias)
- enabled = persisted operator intent (untouched)
- readiness = blocked when persisted-enabled and credentials/URIs missing
- blockedReason = free-form list of missing fields
- blockingReason.errorCode = SOURCE_CONFIG_REQUIRED for structured drill-down
Endpoint propagation:
- /status: persisted enabled=true kept; readiness=blocked; readyForSync=false
- /{id}/enable: 200 with readiness=blocked; sourceRegistry left disabled
until credentials land (pre-existing behaviour retained)
- /{id}/sync: 422 readiness=blocked + SOURCE_CONFIG_REQUIRED;
**connector never invoked**, no job run created
- /sync (batch): per-result outcome=blocked with readiness/errorCode/
blockedReason; excluded from totalTriggered; other sources proceed
- Transition: PUT /{id}/configuration with missing credential →
runtimeOptionsInvalidator.Invalidate → next /status flips to ready.
No disable/re-enable cycle needed.
Tests: 8 targeted xUnit methods via scripts/test-targeted-xunit.ps1,
8/8 pass. Includes: blocked status exposure, blocked-to-ready transition
on persisted credential, connector-not-invoked-when-blocked, plus 4
pre-existing SRC-CREDS-002 regression tests.
Docs:
- docs/modules/concelier/connectors.md — new "Blocked / sleeping
readiness state" section with field contract, per-endpoint behaviour
table, UI/CLI rendering guidance, resolution flow
- docs/modules/cli/guides/commands/db.md — short note under
`db connectors configure` cross-linking the connectors.md contract
Sprint SPRINT_20260422_003 archived — all 5 tasks DONE.
New fields are additive; existing UI types in
source-management.api.ts ignore unknown fields so no UI breakage. A
future FE pass can wire explicit readiness/blockedReason rendering.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
19 KiB
Concelier Connectors
This index lists Concelier connectors, their status, authentication expectations, and links to operational runbooks. For procedures and alerting, see docs/modules/concelier/operations/connectors/.
Operator configuration note:
- Supported advisory source credentials and endpoint overrides can now be supplied through the Web UI or
stella db connectors configure .... - GHSA, Cisco, and Microsoft use operator-supplied credentials through that path.
- Oracle, Adobe, and Chromium use public defaults and only need UI or CLI input when you override or mirror the upstream endpoints.
- See source-credentials.md.
Blocked / sleeping readiness state
Each advisory source has two independent flags in its status response:
| Field | Meaning |
|---|---|
enabled |
Persisted operator intent. true means "the operator asked for this source to run". Survives restarts, backfills, and connectivity checks. |
readiness |
Runtime readiness. One of ready, blocked, disabled, or unsupported. Computed live from connector configuration. |
The blocked state is reserved for credential-gated or URI-gated sources that are persisted-enabled but missing required configuration. In this state:
enabledremainstrue— the operator's intent is preserved across restarts.readiness(aliassyncState) isblocked.blockedReasonis a free-form human-readable message naming the missing field(s) (for example,"GitHub Security Advisories requires an API token before sync can run.").blockingReasoncarries the structured diagnostics object:errorCode = SOURCE_CONFIG_REQUIRED,possibleReasons, and orderedremediationSteps.- The scheduler and the manual
/syncand/sync-allendpoints short-circuit — the connector is never invoked, so the operator does not see a generic scheduler failure or a misleading "last run succeeded" state.
Endpoint-by-endpoint contract
| Endpoint | Blocked behaviour |
|---|---|
GET /api/v1/advisory-sources/status |
Per-source readiness = "blocked", blockedReason populated, readyForSync = false, enabled = true. |
POST /api/v1/advisory-sources/{sourceId}/enable |
Returns 200 OK with { enabled: true, readiness: "blocked", blockingReason, blockedReason }. The persisted row is enabled but the source registry is left disabled until credentials land. |
POST /api/v1/advisory-sources/{sourceId}/sync |
Returns 422 Unprocessable Entity with { error: "source_config_required", readiness: "blocked", code: "SOURCE_CONFIG_REQUIRED", blockedReason }. The connector is not invoked and no job run is created. |
POST /api/v1/advisory-sources/sync |
Each blocked source is reported inside results[] with outcome: "blocked", readiness: "blocked", errorCode: "SOURCE_CONFIG_REQUIRED", blockedReason; it is excluded from totalTriggered. Other sources in the batch still run normally. |
POST /api/v1/advisory-sources/check |
Blocked sources keep their persisted enabled value instead of being auto-disabled by the periodic connectivity check, so the status continues to reflect operator intent until credentials are supplied. |
Resolving the blocked state
The operator resolves a blocked source by supplying the missing configuration through either entry path:
- Web UI:
Integrations -> Advisory sources, open the source card, fill in the fields under Configuration, save. - CLI:
stella db connectors configure <source> --set <field>=<value>(seedocs/modules/cli/guides/commands/db.md).
On the next /status call the source's readiness flips to ready, blockedReason becomes null, and readyForSync becomes true. No disable/re-enable dance is required — the runtime settings cache picks up the persisted change through the options-invalidator and the connector runs on the next scheduler tick or manual trigger.
UI/CLI rendering guidance:
- Render
enabledandreadinessas two separate indicators. Anenabledtoggle that silently collapses to a "disabled" or "failed" visualisation hides operator intent from the next operator on shift. - Prefer
blockedReason(short human sentence) for the visible row and fall back toblockingReason.possibleReasons/remediationStepsfor an expanded drawer. - Do not treat
blockedas an error state for alerting purposes — it is an expected "sleeping" state on fresh installs and on hosts that have not yet received the credential set.
The catalog currently contains 78 source definitions across 14 categories. The authoritative source list is defined in src/Concelier/__Libraries/StellaOps.Concelier.Core/Sources/SourceDefinitions.cs.
Canonical runtime note: the operator-facing source IDs in this index are the only scheduler/catalog IDs that should be used for Concelier jobs and setup. Legacy connector aliases such as ics-cisa, ics-kaspersky, ru-bdu, ru-nkcki, vndr-adobe, vndr-apple, vndr-chromium, vndr-cisco, vndr-oracle, and vndr.msrc remain compatibility-only aliases inside normalization paths and must not appear as primary runtime job keys.
Runtime note: the Concelier advisory catalog and the Excititor default VEX mirror bootstrap share some upstream vendors but are not the same pipeline. The default public VEX bootstrap currently seeds only redhat, ubuntu, oracle, and cisco, uses their public CSAF/notice endpoints, and staggers initial runs (5m, 7m, 9m, 11m) to avoid burst-fetching multiple upstreams at the same instant.
Source categories
| Category | Description | Source count |
|---|---|---|
| Primary | Core vulnerability databases (NVD, OSV, GHSA, CVE) | 4 |
| Threat | Threat intelligence, exploit prediction, and known-exploited (EPSS, KEV, MITRE ATT&CK, D3FEND) | 4 |
| Vendor | Vendor PSIRTs and cloud provider security bulletins | 16 |
| Distribution | Linux distribution security trackers | 10 |
| Ecosystem | Language-ecosystem advisory feeds via OSV/GHSA | 9 |
| PackageManager | Native package manager advisory databases (cargo-audit, pip-audit, govulncheck, bundler-audit) | 4 |
| Csaf | CSAF/VEX structured document sources | 3 |
| Exploit | Exploit databases and proof-of-concept repositories | 3 |
| Container | Container image advisory sources | 2 |
| Hardware | Hardware and firmware PSIRT advisories | 3 |
| Ics | Industrial control systems and SCADA advisories | 2 |
| Cert | National CERTs and government CSIRTs | 15 |
| Mirror | StellaOps pre-aggregated mirrors | 1 |
| Other | Uncategorized sources | 0 |
Primary Databases
| Connector | Source ID | Status | Auth | Priority | Ops Runbook |
|---|---|---|---|---|---|
| NVD (NIST) | nvd |
stable | api-key (optional) | 10 | nvd.md |
| OSV (Google) | osv |
stable | none | 15 | osv.md |
| GitHub Security Advisories | ghsa |
stable | api-token | 20 | ghsa.md |
| CVE.org (MITRE) | cve |
stable | none | 5 | cve.md |
Threat Intelligence & Exploit Scoring
| Connector | Source ID | Status | Auth | Priority | Ops Runbook |
|---|---|---|---|---|---|
| EPSS (FIRST) | epss |
stable | none | 50 | epss.md |
| CISA KEV | kev |
stable | none | 25 | cve-kev.md |
| MITRE ATT&CK | mitre-attack |
stable | none | 140 | -- |
| MITRE D3FEND | mitre-d3fend |
stable | none | 142 | -- |
MITRE ATT&CK provides adversary tactics and techniques in STIX format from the mitre/cti GitHub repository. D3FEND provides the complementary defensive techniques knowledge base. Both are tagged threat-intel and consumed via the SourceType.Upstream connector. For future STIX/TAXII protocol feeds, the SourceType.StixTaxii enum value is available for connector extensibility.
Vendor Advisories
| Connector | Source ID | Status | Auth | Priority | Ops Runbook |
|---|---|---|---|---|---|
| Red Hat Security | redhat |
stable | none | 30 | redhat.md |
| Microsoft Security (MSRC) | microsoft |
stable | oauth | 35 | msrc.md |
| Amazon Linux Security | amazon |
stable | none | 40 | -- |
| Google Security | google |
stable | none | 45 | -- |
| Oracle Security | oracle |
stable | none | 50 | oracle.md |
| Adobe Security | adobe |
stable | none | 52 | adobe.md |
| Apple Security | apple |
stable | none | 55 | apple.md |
| Chromium Stable Channel Updates | chromium |
stable | none | 57 | chromium.md |
| Cisco Security | cisco |
stable | oauth | 60 | cisco.md |
| Fortinet PSIRT | fortinet |
stable | none | 65 | -- |
| Juniper Security | juniper |
stable | none | 70 | -- |
| Palo Alto Security | paloalto |
stable | none | 75 | -- |
| VMware Security | vmware |
stable | none | 80 | vmware.md |
| AWS Security Bulletins | aws |
stable | none | 81 | -- |
| Azure Security Advisories | azure |
stable | none | 82 | -- |
| GCP Security Bulletins | gcp |
stable | none | 83 | -- |
AWS, Azure, and GCP cloud provider advisories were added in Sprint 007. They track platform-level security bulletins for cloud infrastructure components and are categorized under Vendor alongside traditional PSIRTs.
Mirror bootstrap note:
oracledefault VEX bootstrap discovery uses Oracle's public security RSS feed and derived*csaf.jsondocuments.ciscodefault VEX bootstrap uses Cisco's public CSAF provider metadata and does not require the OAuth credentials used by the Concelier openVuln connector.- If Cisco's public paged catalog is unavailable, the bootstrap falls back to
changes.csvand thenindex.txt, prefers newer candidates first, and checkpoints seen or permanently inaccessible legacy paths so hourly runs do not re-download or stall on the full historical corpus.
Linux Distributions
| Connector | Source ID | Status | Auth | Priority | Regions | Ops Runbook |
|---|---|---|---|---|---|---|
| Debian Security Tracker | debian |
stable | none | 30 | -- | debian.md |
| Ubuntu Security Notices | ubuntu |
stable | none | 32 | -- | ubuntu.md |
| Alpine SecDB | alpine |
stable | none | 34 | -- | alpine.md |
| SUSE Security | suse |
stable | none | 36 | -- | suse.md |
| RHEL Security | rhel |
stable | none | 38 | -- | -- |
| CentOS Security | centos |
stable | none | 40 | -- | -- |
| Fedora Security | fedora |
stable | none | 42 | -- | -- |
| Arch Security | arch |
stable | none | 44 | -- | -- |
| Gentoo Security | gentoo |
stable | none | 46 | -- | -- |
| Astra Linux Security | astra |
stable | none | 48 | RU, CIS | astra.md |
Mirror bootstrap note:
ubuntudefault VEX bootstrap readshttps://ubuntu.com/security/notices.jsonand synthesizes deterministic CSAF documents from the per-notice JSON payloads because Canonical's public path is notice JSON rather than native CSAF.
Language Ecosystems
| Connector | Source ID | Status | Auth | Priority | Ops Runbook |
|---|---|---|---|---|---|
| npm Advisories | npm |
stable | none | 50 | -- |
| PyPI Advisories | pypi |
stable | none | 52 | -- |
| Go Advisories | go |
stable | none | 54 | -- |
| RubyGems Advisories | rubygems |
stable | none | 56 | -- |
| NuGet Advisories | nuget |
stable | api-token | 58 | -- |
| Maven Advisories | maven |
stable | none | 60 | -- |
| Crates.io Advisories | crates |
stable | none | 62 | -- |
| Packagist Advisories | packagist |
stable | none | 64 | -- |
| Hex.pm Advisories | hex |
stable | none | 66 | -- |
Ecosystem connectors use OSV or GHSA GraphQL as the underlying data source. NuGet requires a GITHUB_PAT for GHSA GraphQL access.
Package Manager Native Advisories
| Connector | Source ID | Status | Auth | Priority | Ops Runbook |
|---|---|---|---|---|---|
| RustSec Advisory DB (cargo-audit) | rustsec |
stable | none | 63 | -- |
| PyPA Advisory DB (pip-audit) | pypa |
stable | none | 53 | -- |
| Go Vuln DB (govulncheck) | govuln |
stable | none | 55 | -- |
| Ruby Advisory DB (bundler-audit) | bundler-audit |
stable | none | 57 | -- |
Package manager native advisory databases provide language-specific vulnerability data curated by the respective package manager maintainers. These complement the ecosystem feeds (OSV/GHSA) by providing authoritative tool-native data used by cargo-audit, pip-audit, govulncheck, and bundler-audit. They are categorized separately under PackageManager to allow targeted mirror export filtering.
CSAF/VEX Sources
| Connector | Source ID | Status | Auth | Priority | Ops Runbook |
|---|---|---|---|---|---|
| CSAF Aggregator | csaf |
stable | none | 70 | -- |
| CSAF TC Trusted Publishers | csaf-tc |
stable | none | 72 | -- |
| VEX Hub | vex |
stable | none | 74 | -- |
Exploit Databases
| Connector | Source ID | Status | Auth | Priority | Ops Runbook |
|---|---|---|---|---|---|
| Exploit-DB | exploitdb |
stable | none | 110 | -- |
| PoC-in-GitHub | poc-github |
stable | api-token | 112 | -- |
| Metasploit Modules | metasploit |
stable | none | 114 | -- |
Exploit databases track publicly available proof-of-concept code and exploit modules. Exploit-DB is sourced from the Offensive Security GitLab mirror. PoC-in-GitHub uses the GitHub search API to discover repositories containing vulnerability PoCs (requires GITHUB_PAT). Metasploit tracks Rapid7 Metasploit Framework module metadata for CVE-to-exploit correlation.
Container Sources
| Connector | Source ID | Status | Auth | Priority | Ops Runbook |
|---|---|---|---|---|---|
| Docker Official CVEs | docker-official |
stable | none | 120 | -- |
| Chainguard Advisories | chainguard |
stable | none | 122 | -- |
Container-specific advisory sources track vulnerabilities in base images and hardened container distributions. Docker Official CVEs covers the Docker Hub official images program. Chainguard Advisories covers hardened distroless and Wolfi-based images.
Hardware/Firmware
| Connector | Source ID | Status | Auth | Priority | Ops Runbook |
|---|---|---|---|---|---|
| Intel PSIRT | intel |
stable | none | 130 | -- |
| AMD Security | amd |
stable | none | 132 | -- |
| ARM Security Center | arm |
stable | none | 134 | -- |
Hardware PSIRT advisories cover CPU microcode, firmware, and silicon-level vulnerabilities from the three major processor vendors. These sources are especially relevant for infrastructure operators tracking speculative execution (Spectre/Meltdown class) and firmware supply chain issues.
ICS/SCADA
| Connector | Source ID | Status | Auth | Priority | Regions | Ops Runbook |
|---|---|---|---|---|---|---|
| Siemens ProductCERT | siemens |
stable | none | 136 | -- | -- |
| Kaspersky ICS-CERT | kaspersky-ics |
stable | none | 102 | RU, CIS, GLOBAL | kaspersky-ics.md |
Industrial control systems advisories cover SCADA and operational technology vulnerabilities. Siemens ProductCERT publishes CSAF-format advisories. Kaspersky ICS-CERT was promoted from beta to stable in Sprint 007 after endpoint stability verification.
National CERTs
| Connector | Source ID | Status | Auth | Priority | Regions | Ops Runbook |
|---|---|---|---|---|---|---|
| CERT-FR | cert-fr |
stable | none | 80 | FR, EU | cert-fr.md |
| CERT-Bund (Germany) | cert-de |
stable | none | 82 | DE, EU | certbund.md |
| CERT.at (Austria) | cert-at |
stable | none | 84 | AT, EU | -- |
| CERT.be (Belgium) | cert-be |
stable | none | 86 | BE, EU | -- |
| NCSC-CH (Switzerland) | cert-ch |
stable | none | 88 | CH | -- |
| CERT-EU | cert-eu |
stable | none | 90 | EU | -- |
| CCCS (Canada) | cccs |
stable | none | 91 | CA, NA | cccs.md |
| JPCERT/CC (Japan) | jpcert |
stable | none | 92 | JP, APAC | jvn.md |
| CERT/CC | cert-cc |
stable | none | 93 | US, NA | cert-cc.md |
| CISA (US-CERT) | us-cert |
stable | none | 94 | US, NA | ics-cisa.md |
| CERT-UA (Ukraine) | cert-ua |
stable | none | 95 | UA | -- |
| CERT.PL (Poland) | cert-pl |
stable | none | 96 | PL, EU | -- |
| AusCERT (Australia) | auscert |
stable | none | 97 | AU, APAC | -- |
| KrCERT/CC (South Korea) | krcert |
stable | none | 98 | KR, APAC | kisa.md |
| CERT-In (India) | cert-in |
stable | none | 99 | IN, APAC | cert-in.md |
Seven additional CERTs beyond the original European/Japanese set are now defined in the catalog: CCCS (Canada), CERT/CC, CERT-UA, CERT.PL, AusCERT, KrCERT/CC, and CERT-In, extending coverage to North America, Eastern Europe, Oceania, and South/East Asia.
Russian/CIS Sources
| Connector | Source ID | Status | Auth | Priority | Regions | Ops Runbook |
|---|---|---|---|---|---|---|
| FSTEC BDU | fstec-bdu |
stable | none | 100 | RU, CIS | fstec-bdu.md |
| NKCKI | nkcki |
stable | none | 101 | RU, CIS | nkcki.md |
FSTEC BDU and NKCKI were promoted from beta to stable in Sprint 007. FSTEC BDU (Bank of Security Threats) provides vulnerability data maintained by Russia's Federal Service for Technical and Export Control. NKCKI is the National Coordination Center for Computer Incidents. Kaspersky ICS-CERT and Astra Linux are listed in their respective category sections above.
StellaOps Mirror
| Connector | Source ID | Status | Auth | Priority | Ops Runbook |
|---|---|---|---|---|---|
| StellaOps Mirror | stella-mirror |
stable | none (configurable) | 1 | -- |
The StellaOps Mirror connector consumes pre-aggregated advisory data from a StellaOps mirror instance. When using mirror mode, this source takes highest priority (1) and replaces direct upstream connections. See docs/modules/excititor/mirrors.md for mirror configuration details.
Reason Codes Reference: docs/modules/concelier/operations/connectors/reason-codes.md