git.stella-ops.org/docs/modules/excititor/operations/provider-control-plane.md

Excititor Provider Control Plane

This document describes the operator-facing control plane for Excititor VEX providers.

Operator entry points

• Web UI: Ops -> Integrations -> Advisory & VEX Sources -> VEX Providers
• CLI:
  • stella vex providers configure <provider> [--set key=value ...] [--clear key ...] [--format text|json]

Backend API:

• GET /excititor/providers
• GET /excititor/providers/{providerId}
• PUT /excititor/providers/{providerId}
• POST /excititor/providers/{providerId}/enable
• POST /excititor/providers/{providerId}/disable
• POST /excititor/providers/{providerId}/run
• GET /excititor/providers/{providerId}/configuration — persisted connector settings (masked secrets)
• PUT /excititor/providers/{providerId}/configuration — { values, clearKeys } request shape, retains secrets submitted blank

Persisted connector configuration (Sprint 20260422_007) is the primary operator path for credentialed VEX providers. Host-config and environment binding remain compatibility fallbacks only. Persisted settings win when both define the same key.

Related credential guide:

• docs/modules/excititor/operations/provider-credentials.md

Readiness states

Excititor providers use four runtime readiness states:

• ready: persisted-enabled and the current host has a runnable connector
• blocked: persisted-enabled but missing required persisted configuration, cooling down, or otherwise not runnable
• disabled: persisted-disabled
• planned: cataloged provider without a runnable connector registered on the current host

enabled remains the operator intent flag. A provider can be enabled=true and still show planned or blocked.

Blocked-readiness configuration codes (Sprint 20260422_007)

When a persisted-enabled provider lacks required settings or fails connector-option validation, the blocked-reason surface carries one of:

• PROVIDER_CONFIG_REQUIRED — one or more required fields (e.g. MSRC tenantId, clientId, clientSecret) are absent.
• PROVIDER_CONFIG_INVALID — settings are present but the connector's own option validator rejected them (e.g. Cisco metadataUri is not an absolute URI, Rancher hub credential set is partial).

These codes mirror the Concelier SOURCE_CONFIG_REQUIRED / SOURCE_CONFIG_INVALID contract from SRC-CREDS-005 so CLI and Web surfaces can reuse the same rendering. The /excititor/providers list response exposes them via blockingReasonCode and blockingReason.

Provider inventory

Provider ID	Kind	Default enabled	Registered in WebService	UI control plane	CLI control plane	Credential / config status	Notes
excititor:redhat	distro	true	yes	yes	yes	Public defaults; metadata and trust overrides can be persisted through the provider control plane.	Registered by default in StellaOps.Excititor.WebService.
excititor:ubuntu	distro	true	yes	yes	yes	Public defaults; metadata and trust overrides can be persisted through the provider control plane.	Registered by default in StellaOps.Excititor.WebService.
excititor:oracle	vendor	true	yes	yes	yes	Public defaults; metadata and trust overrides can be persisted through the provider control plane.	Registered by default in StellaOps.Excititor.WebService.
excititor:cisco	vendor	true	yes	yes	yes	Persisted scalar config supports metadataUri override plus optional apiToken. Default public Cisco CSAF works without credentials.	Registered by default in StellaOps.Excititor.WebService.
excititor:suse-rancher	hub	false	yes	yes	yes	Persisted scalar config supports discoveryUri, tokenEndpoint, clientId, clientSecret, and audience. Missing or partial auth settings surface as blocked instead of runtime surprise.	Registered by default in StellaOps.Excititor.WebService.
excititor:oci-openvex	attestation	false	yes	yes	yes	Provider metadata and trust overrides can be persisted. Image subscriptions, registry credentials, and cosign credential material remain host-config only today.	Registered by default in StellaOps.Excititor.WebService.
excititor:msrc	vendor	false	conditional	yes	yes	Persisted scalar config supports tenantId, clientId, clientSecret, and optional scope. Offline token-path fields still remain host-config only.	Registered only when Excititor:Connectors:Msrc exists in host configuration. Otherwise the provider remains planned.

What the current provider control plane persists

The current update-provider surface persists:

• display name
• provider kind
• base URIs
• well-known metadata URI
• ROLIE service URI
• trust weight
• PGP fingerprints
• cosign issuer
• cosign identity pattern
• enabled / disabled intent

The current provider control plane does not yet persist connector-secret fields such as:

• OCI registry username, password, identity token, refresh token, cosign key pair, or image subscription list

Those settings still come from host configuration today. The control plane is truthful about the gap by surfacing planned or blocked readiness instead of pretending the connector is runnable.

Persisted scalar-provider configuration (Sprint 20260422_007)

The following provider connector settings can now be persisted through the UI or CLI and are kept in a dedicated vex.provider_settings row (distinct from vex.providers metadata):

Provider	Persisted fields
excititor:cisco	metadataUri (optional override), apiToken (sensitive)
excititor:suse-rancher	discoveryUri, tokenEndpoint, clientId, clientSecret (sensitive), audience
excititor:msrc	tenantId, clientId, clientSecret (sensitive), scope (optional override)

Operator surfaces:

• CLI: stella vex providers configure <provider> [--set key=value ...] [--clear key ...] [--format text|json]
• Web: provider configuration panel rendering masked secret state, required-field markers, and explicit clear toggles.

Sensitive values are never re-exposed on reads — the API returns only hasValue/isSecretRetained flags. Blank submissions retain existing secrets; explicit clearKeys entries delete them.

OCI OpenVEX remains on host-config only pending the dedicated artifact-backed configuration path (EXCITITOR-CFG-04).

Host wiring notes

• StellaOps.Excititor.WebService always registers:
  • Red Hat CSAF
  • Ubuntu CSAF
  • Oracle CSAF
  • Cisco CSAF
  • SUSE Rancher VEX Hub
  • OCI OpenVEX attestations
• StellaOps.Excititor.WebService registers Microsoft MSRC CSAF only when the Excititor:Connectors:Msrc configuration section exists.
• StellaOps.Excititor.Worker seeds these public defaults when no explicit provider schedule list is supplied:
  • excititor:redhat
  • excititor:ubuntu
  • excititor:oracle
  • excititor:cisco

Verification state

Reverified in Sprint 20260422_004:

• targeted backend tests for provider management endpoints passed against StellaOps.Excititor.WebService.Tests.ProviderManagementEndpointsTests
• Angular route helper spec passed for the new VEX provider route
• Angular development build passed with the new provider catalog page
• CLI provider inspection and control verbs were added for the backend surface

The verification above covers the provider control plane and readiness behavior. It does not claim a fresh live ingest verification run for every upstream VEX provider in this sprint.