feat(excititor): continuation — orchestrator test coverage + doc reconciliation
Follow-up to commit 7efa424fe (EXCITITOR-CFG-01/02/03). Captures the
continuation edits that landed alongside/after the initial commit:
- VexIngestOrchestrator.cs: additional effective-settings resolver
hardening (+63 lines).
- DefaultVexProviderRunner.cs: worker-path settings merge refinement.
- VexIngestOrchestratorTests.cs (new): focused test coverage for the
effective-settings + blocked-readiness path.
- DefaultVexProviderRunnerTests.cs: corresponding worker-path coverage.
- TASKS.md entries updated in both test projects.
Docs reconciliation:
- provider-credentials.md (new): operator credential-entry dossier
mirroring the Concelier source-credentials.md pattern.
- provider-control-plane.md: cross-link updates.
- ops/connector-setup-guide.md: authoritative-inventory pointers updated
to reference the new credential dossiers; microsoft-entra API-permission
steps generalized to "your MSRC onboarding flow" (MSRC Security Updates
API availability varies by tenant).
- SPRINT_20260422_007 execution log appended.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
master
@@ -6,12 +6,7 @@ This document describes the operator-facing control plane for Excititor VEX prov
|
||||
|
||||
- Web UI: `Ops -> Integrations -> Advisory & VEX Sources -> VEX Providers`
|
||||
- CLI:
|
||||
- `stella excititor list-providers`
|
||||
- `stella excititor show-provider --provider <id>`
|
||||
- `stella excititor enable-provider --provider <id>`
|
||||
- `stella excititor disable-provider --provider <id>`
|
||||
- `stella excititor run-provider --provider <id> [--since ... --window ... --force]`
|
||||
- `stella excititor update-provider --provider <id> ...`
|
||||
- `stella vex providers configure <provider> [--set key=value ...] [--clear key ...] [--format text|json]`
|
||||
|
||||
Backend API:
|
||||
|
||||
@@ -26,6 +21,10 @@ Backend API:
|
||||
|
||||
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:
|
||||
@@ -53,10 +52,10 @@ These codes mirror the Concelier `SOURCE_CONFIG_REQUIRED` / `SOURCE_CONFIG_INVAL
|
||||
| `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 | Public CSAF metadata works without a persisted secret path. Optional API token support exists in connector host options, not in the new persisted UI or CLI surface. | Registered by default in `StellaOps.Excititor.WebService`. |
|
||||
| `excititor:suse-rancher` | hub | false | yes | yes | yes | Discovery and trust metadata can be persisted. Authenticated discovery credentials remain host-config only today. Anonymous discovery can still be allowed by connector options. | 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 provider metadata exists, but MSRC connector credentials and offline token settings remain host-config only today. | Registered only when `Excititor:Connectors:Msrc` exists in host configuration. Otherwise the provider remains `planned`. |
|
||||
| `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
|
||||
|
||||
|
||||
129
docs/modules/excititor/operations/provider-credentials.md
Normal file
129
docs/modules/excititor/operations/provider-credentials.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# Excititor Provider Credential Entry
|
||||
|
||||
_Last updated: 2026-04-22_
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
Excititor now 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.
|
||||
|
||||
## 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:
|
||||
|
||||
```bash
|
||||
stella vex providers configure excititor:cisco --server https://excititor.example.internal
|
||||
stella vex providers configure excititor:suse-rancher --server https://excititor.example.internal
|
||||
stella vex providers configure excititor:msrc --server https://excititor.example.internal
|
||||
```
|
||||
|
||||
Update a provider:
|
||||
|
||||
```bash
|
||||
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:suse-rancher \
|
||||
--server https://excititor.example.internal \
|
||||
--set discoveryUri=https://mirror.example.internal/rancher/vexhub.json \
|
||||
--set tokenEndpoint=https://auth.example.internal/oauth2/token \
|
||||
--set clientId=... \
|
||||
--set clientSecret=...
|
||||
|
||||
stella vex providers configure excititor:msrc \
|
||||
--server https://excititor.example.internal \
|
||||
--set tenantId=... \
|
||||
--set clientId=... \
|
||||
--set clientSecret=...
|
||||
```
|
||||
|
||||
Clear stored fields:
|
||||
|
||||
```bash
|
||||
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`
|
||||
|
||||
## 4. Credential acquisition matrix
|
||||
|
||||
| Provider | Where to sign in or look | What to create or capture | Can the config be skipped? | Entitlement / paywall notes |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `excititor:cisco` | Public Cisco CSAF metadata by default. Optional authenticated path depends on your Cisco API / mirror arrangement. | Usually nothing for the default public path. Optionally capture `metadataUri` override and `apiToken` if your Cisco path requires bearer auth. | Yes, for the default public Cisco CSAF metadata path. Configure it only when overriding the metadata URI or when your Cisco endpoint requires a token. | No StellaOps-side paywall for the public path. Any token requirement depends on your Cisco-side arrangement, mirror, or entitlement. |
|
||||
| `excititor:suse-rancher` | Your Rancher Hub / SUSE-auth deployment, plus the corresponding identity provider or token service. | `discoveryUri`, and when auth is required: `tokenEndpoint`, `clientId`, `clientSecret`, optional `audience`. | Sometimes. Anonymous discovery is allowed only if the hub is intentionally exposed that way. Otherwise the authenticated fields are required together. | No StellaOps-side paywall. Access depends on your Rancher Hub deployment and the identity provider that fronts it. |
|
||||
| `excititor:msrc` | `https://entra.microsoft.com` -> **App registrations** | `tenantId`, `clientId`, `clientSecret`; optionally `scope` override if you are not using the default MSRC API scope. | Not for the online MSRC client-credential path. | No separate documented MSRC paywall, but you need a Microsoft Entra tenant plus permission to register the app and grant the required consent. |
|
||||
| `excititor:oci-openvex` | Registry, identity provider, cosign/PKI authority, and any offline artifact staging path used by your deployment. | Not yet supported through the persisted UI/CLI scalar config path. | No. This remains blocked pending the artifact-backed OCI configuration design. | Depends on your registry, cosign, and offline bundle environment. |
|
||||
|
||||
## 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.
|
||||
|
||||
### SUSE Rancher VEX Hub
|
||||
|
||||
- Rancher hub discovery document URI
|
||||
- OAuth or OIDC token endpoint when the hub requires authentication
|
||||
- Client ID and client secret for the hub reader application
|
||||
- Optional audience value when your token service requires it
|
||||
|
||||
### Microsoft MSRC
|
||||
|
||||
- Microsoft Entra **Directory (tenant) ID**
|
||||
- Microsoft Entra **Application (client) ID**
|
||||
- A newly created **Client secret** value
|
||||
- Confirm the app consent and scope expected by your MSRC onboarding process before storing the values in Stella Ops
|
||||
|
||||
### OCI OpenVEX
|
||||
|
||||
- No persisted UI/CLI credential path exists yet for the binary material used by OCI OpenVEX.
|
||||
- Keep using host-config compatibility mode until the artifact-backed configuration design lands.
|
||||
|
||||
## 6. 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>
|
||||
Reference in New Issue
Block a user