Excititor Provider Credential Entry

Audience: Operators supplying credentials, source URLs, and trust material for Excititor VEX providers.

Last updated: 2026-07-14

For the readiness model, run counters, and the full provider inventory, see the Provider Control Plane guide.

1. Purpose

Excititor supports operator-supplied provider settings through the product surfaces operators already use:

• Web UI provider management
• stella vex providers configure ... in the CLI

Host configuration and environment variables remain compatibility fallbacks, but the primary operator path for supported credential-sensitive Excititor providers is persisted provider configuration owned by Stella Ops itself.

Credential custody

Red Hat’s optional subscriptionToken is never persisted as plaintext by a production Excititor host. excititor-web seals a newly submitted value before it writes vex.provider_settings; its idempotent startup migration converts any legacy plaintext value to a builtin:// reference and performs a residual-plaintext sweep. An operator-supplied builtin://, vault://, or other supported secret reference is retained as a reference rather than re-sealed.

Both excititor-web (manual/API ingest) and excititor-worker (scheduled ingest) resolve the stored reference only into the short-lived in-memory settings passed to the Red Hat connector. The persisted row and runtime settings cache retain the reference, resolution fails closed, and secret bytes are not logged. excititor-web is the sole migration owner so simultaneous host startup cannot double-seal the same row.

Both hosts need a usable KEK source. Resolution order is Excititor:SecretProtectionKey, Platform:Setup:SecretProtectionKey, STELLAOPS_SECRETS_ENCRYPTION_KEY, then STELLAOPS_BOOTSTRAP_KEY; Vault remains available through the configured secret-provider registry. A startup probe refuses to start the host when KEK material is empty or the selected secret backend does not match configuration.

2. Operator entry paths

Web UI

Use:

• Ops -> Integrations -> Advisory & VEX Sources -> VEX Providers

Then:

1. Open the provider card.
2. Open Provider Configuration.
3. Enter or update the provider fields.
4. Save the configuration.

Sensitive values never round-trip back to the browser. A stored secret is shown only as retained state. Leaving a password field blank keeps the retained secret. Explicitly checking the clear control removes the stored secret.

CLI

Inspect current persisted provider configuration:

stella vex providers configure excititor:cisco --server https://excititor.example.internal
stella vex providers configure excititor:msrc --server https://excititor.example.internal
stella vex providers configure excititor:oci-openvex --server https://excititor.example.internal

Update a provider:

stella vex providers configure excititor:cisco \
  --server https://excititor.example.internal \
  --set metadataUri=https://mirror.example.internal/cisco/provider-metadata.json \
  --set apiToken=...

stella vex providers configure excititor:msrc \
  --server https://excititor.example.internal \
  --set authMode=ClientCredentials \
  --set tenantId=... \
  --set clientId=... \
  --set clientSecret=...

Clear stored fields:

stella vex providers configure excititor:msrc \
  --server https://excititor.example.internal \
  --clear clientSecret

Notes:

• --set accepts key=value.
• The current CLI path places literal values on the command line. If shell-history exposure is unacceptable for a secret, prefer the Web UI path or use an operator-approved secure shell/history procedure.

3. Blocked providers

If an operator enables a provider that still lacks required credentials or has an invalid persisted configuration, Excititor preserves the enable intent but reports the provider as blocked.

• enabled=true means the operator wants the provider scheduled once it becomes usable.
• readiness=blocked means the provider is intentionally on hold because required configuration is still missing or invalid.
• Manual provider runs and batch ingest flows return a blocked result instead of pretending the provider is runnable.
• Scheduled worker runs skip blocked providers and record the configuration reason instead of treating missing credentials as transient retry failures.

Current blocked codes:

• PROVIDER_CONFIG_REQUIRED
• PROVIDER_CONFIG_INVALID
• PROVIDER_SOURCE_URL_REQUIRED
• PROVIDER_SOURCE_URL_NOT_HTTPS
• PROVIDER_SOURCE_URL_CONFIRMATION_REQUIRED
• PROVIDER_TRUST_MATERIAL_REQUIRED

4. Credential acquisition matrix

5. What operators should actually look for

Cisco CSAF

• No login is needed for the default public Cisco CSAF metadata path.
• Only collect metadataUri when pointing Excititor at an approved internal mirror.
• Only collect apiToken when your Cisco-side path or mirror explicitly requires a bearer token.

Microsoft MSRC

• Start with authMode=Public unless your deployment or mirror requires bearer-token authentication.
• For authMode=ClientCredentials, collect the Microsoft Entra Directory (tenant) ID, Application (client) ID, and a newly created Client secret value.
• For authMode=OfflineToken, collect either a server-side offlineTokenPath or a short-lived staticAccessToken staged through the approved secret path.
• Confirm the app consent and scope expected by your MSRC or mirror onboarding process before storing client-credential values in Stella Ops.

Red Hat CSAF

• No credential is required for the default public metadata path.
• Use subscriptionToken only when the selected internal mirror or entitled endpoint requires bearer authentication.
• Enter a literal token through the Web UI when shell-history exposure is unacceptable; the production control plane seals it before persistence.
• Advanced operators may submit a supported secret reference instead of literal token material. An unresolved reference blocks the pull; it is never sent as the Authorization value.

Custody verification

After deployment, verify the Red Hat slot without selecting or printing the token itself:

SELECT tenant_id,
       provider_id,
       CASE
         WHEN COALESCE(settings->>'subscriptionToken', '') = '' THEN 'absent'
         WHEN settings->>'subscriptionToken' ~ '^[a-z][a-z0-9+.-]*://' THEN 'reference'
         ELSE 'plaintext'
       END AS custody_state
FROM vex.provider_settings
WHERE provider_id = 'excititor:redhat';

Every returned credential-bearing row must report reference; plaintext is a failed seal sweep and must be treated as an operational incident. An empty result is clean but does not exercise the migration forcing function.

OCI OpenVEX

Sprint 20260423_001 OCI-CFG-001/002/003 wired the artifact-backed configuration path.

The OCI OpenVEX provider carries configuration shapes the scalar settings store cannot cleanly absorb: a variable-length list of image subscriptions and binary cosign / TUF material that must not round-trip on reads. The implementation keeps the scalar settings JSONB column a flat string map and introduces a sibling artifact-reference store (vex.provider_artifact_refs) for binary material. The settings JSONB references artifact rows by opaque GUID.

5.1 Shape of the configuration

5.2 Artifact-staging API

Size caps: 10 MiB per artifact, 50 MiB per provider total. Tunable via Excititor:ProviderArtifacts:MaxArtifactSizeBytes / MaxProviderTotalSizeBytes environment settings. Cap violations surface as HTTP 400 with error codes ARTIFACT_TOO_LARGE / ARTIFACT_PROVIDER_QUOTA_EXCEEDED. Tenant isolation is enforced via RLS on vex.provider_artifact_refs.tenant_id.

At runtime, cosign/TUF verification libraries need on-disk paths. The effective-settings resolver materializes referenced artifacts to a per-request scratch directory (chmod 0700 on POSIX) and cleans up on session dispose — see VexProviderArtifactMaterializer.

5.3 Canonical setup flows

A. Keyless Sigstore, single image, default registry:

stella vex providers configure excititor:oci-openvex \
  --server https://excititor.example.internal \
  --image ghcr.io/acme/app:v1.2.3 \
  --set cosignMode=Keyless \
  --set cosignIssuer=https://token.actions.githubusercontent.com \
  --set cosignSubject='https://github.com/acme/repo/.github/workflows/release.yml@refs/tags/v1.*'

B. KeyPair cosign verification with operator-supplied public key:

stella vex providers configure excititor:oci-openvex \
  --server https://excititor.example.internal \
  --image ghcr.io/acme/app:v1 \
  --image ghcr.io/acme/sidecar:v1 \
  --set cosignMode=KeyPair \
  --upload-artifact cosignKey=@/secure/cosign/cosign.pub \
  --upload-artifact cosignCertificate=@/secure/cosign/cosign.crt

C. TUF trust roots + offline bundle:

stella vex providers configure excititor:oci-openvex \
  --server https://excititor.example.internal \
  --image registry.example.com/platform/base@sha256:... \
  --upload-artifact tufRoots=@/air-gap/tuf/root.json \
  --set offlineBundleRoot=/var/lib/stella/offline/openvex

D. Private registry with basic auth:

stella vex providers configure excititor:oci-openvex \
  --server https://excititor.example.internal \
  --image internal.registry.example.com/team/app:v3 \
  --set registryAuthority=internal.registry.example.com:5000 \
  --set registryUsername=stella-reader \
  --set registryPassword=<token>

5.4 Host-path compatibility (CLI only)

The CLI exposes --host-path-compat to preserve the legacy flow where cosign/TUF material is referenced by absolute path instead of uploaded as an artifact. Use it only when the Excititor server shares a filesystem with the operator workstation (typically a single-node sealed deployment). The UI deliberately never surfaces file-path inputs because the server cannot read arbitrary host paths in production-scale deployments. Host-path mode is visible in CLI --help as a compatibility-only flag.

5.5 Listing and clearing staged artifacts

# Show all artifacts staged against a provider
stella vex providers artifacts excititor:oci-openvex

# Clear a field's artifact binding (leaves the staged blob — delete the blob separately if unused)
stella vex providers configure excititor:oci-openvex --clear-artifact cosignCertificate

5.6 UI

The Web panel renders conditionally from the existing Advisory & VEX Sources detail flow when provider.kind === 'oci-openvex' (or the provider id matches excititor:oci-openvex). It provides the image-subscription list editor, artifact-reference slots with upload + staged-meta rendering, and a readiness hint surface for the OCI-specific blocked sub-codes. File-path inputs are intentionally omitted from the UI — use the CLI for host-path compat when that flow is needed.

6. Source confirmation and trust posture

Oracle and SUSE Rancher are configuration choices, but their required setup is not a normal username/password credential flow. They are blocked by source and trust posture until an operator records an explicit decision.

CLI examples:

stella vex providers configure oracle \
  --source-url https://www.oracle.com/ocom/groups/public/@otn/documents/webcontent/rss-otn-sec.xml \
  --confirm-source-url \
  --trust-mode cache-only

stella vex providers configure suse-rancher \
  --source-url https://mirror.example.internal/rancher-hub.json \
  --confirm-source-url \
  --trust-mode signed-required \
  --pgp-fingerprint <fingerprint>

7. References

• Microsoft Entra app registration quickstart: https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app
• Microsoft Entra application credentials: https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials