chore(docs+devops): cross-module doc sync + sprint archival moves + compose updates

Bundled pre-session doc + ops work:
- docs/modules/**: sync across advisory-ai, airgap, cli, excititor,
  export-center, findings-ledger, notifier, notify, platform, router,
  sbom-service, ui, web (architectural + operational updates)
- docs/features/**: updates to checked excititor vex pipeline,
  developer workspace, quick verify drawer
- docs top-level: README, quickstart, API_CLI_REFERENCE, UI_GUIDE,
  code-of-conduct/TESTING_PRACTICES updates
- docs/qa/feature-checks/: FLOW.md + excititor state update
- docs/implplan/: remaining sprint updates + new Concelier source
  credentials sprint (SPRINT_20260422_003)
- docs-archived/implplan/: 30 sprint archival moves (ElkSharp series,
  misc completed sprints)
- devops/compose: .env + services compose + env example + router gateway
  config updates

File-level granularity preserved.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
master
2026-04-22 16:06:39 +03:00
parent ad77711ac2
commit 7943cfb3af
121 changed files with 10483 additions and 387 deletions

View File

@@ -0,0 +1,47 @@
{
"type": "source",
"capturedAtUtc": "2026-04-22T07:40:37.2236785Z",
"featureFile": "docs/features/checked/excititor/vex-source-registration-and-verification-pipeline.md",
"filesChecked": [
"src/Concelier/StellaOps.Excititor.Worker/Scheduling/VexWorkerHostedService.cs",
"src/Concelier/StellaOps.Excititor.Worker/Scheduling/DefaultVexProviderRunner.cs",
"src/Concelier/StellaOps.Excititor.Worker/Orchestration/OrchestratorVexProviderRunner.cs",
"src/Concelier/StellaOps.Excititor.Worker/Orchestration/VexWorkerOrchestratorClient.cs",
"src/Concelier/StellaOps.Excititor.Worker/Orchestration/VexWorkerHeartbeatService.cs",
"src/Concelier/StellaOps.Excititor.Worker/Plugins/VexWorkerPluginCatalogLoader.cs",
"src/Concelier/StellaOps.Excititor.Worker/Signature/WorkerSignatureVerifier.cs",
"src/Concelier/StellaOps.Excititor.Worker/Scheduling/VexWorkerSchedule.cs",
"src/Concelier/StellaOps.Excititor.WebService/Endpoints/MirrorRegistrationEndpoints.cs",
"src/Concelier/__Libraries/StellaOps.Excititor.Connectors.Abstractions/VexConnectorBase.cs",
"src/Concelier/__Libraries/StellaOps.Excititor.Connectors.Abstractions/VexConnectorDescriptor.cs",
"src/Concelier/__Libraries/StellaOps.Excititor.Connectors.Cisco.CSAF/CiscoCsafConnector.cs",
"src/Concelier/__Tests/StellaOps.Excititor.Worker.Tests/Orchestration/VexWorkerOrchestratorClientTests.cs",
"src/Concelier/__Tests/StellaOps.Excititor.Connectors.Cisco.CSAF.Tests/Connectors/CiscoCsafConnectorTests.cs"
],
"found": [
"src/Concelier/StellaOps.Excititor.Worker/Scheduling/VexWorkerHostedService.cs",
"src/Concelier/StellaOps.Excititor.Worker/Scheduling/DefaultVexProviderRunner.cs",
"src/Concelier/StellaOps.Excititor.Worker/Orchestration/OrchestratorVexProviderRunner.cs",
"src/Concelier/StellaOps.Excititor.Worker/Orchestration/VexWorkerOrchestratorClient.cs",
"src/Concelier/StellaOps.Excititor.Worker/Orchestration/VexWorkerHeartbeatService.cs",
"src/Concelier/StellaOps.Excititor.Worker/Plugins/VexWorkerPluginCatalogLoader.cs",
"src/Concelier/StellaOps.Excititor.Worker/Signature/WorkerSignatureVerifier.cs",
"src/Concelier/StellaOps.Excititor.Worker/Scheduling/VexWorkerSchedule.cs",
"src/Concelier/StellaOps.Excititor.WebService/Endpoints/MirrorRegistrationEndpoints.cs",
"src/Concelier/__Libraries/StellaOps.Excititor.Connectors.Abstractions/VexConnectorBase.cs",
"src/Concelier/__Libraries/StellaOps.Excititor.Connectors.Abstractions/VexConnectorDescriptor.cs",
"src/Concelier/__Libraries/StellaOps.Excititor.Connectors.Cisco.CSAF/CiscoCsafConnector.cs",
"src/Concelier/__Tests/StellaOps.Excititor.Worker.Tests/Orchestration/VexWorkerOrchestratorClientTests.cs",
"src/Concelier/__Tests/StellaOps.Excititor.Connectors.Cisco.CSAF.Tests/Connectors/CiscoCsafConnectorTests.cs"
],
"missing": [],
"legacyReferencedPathsMissing": [
"src/Excititor/StellaOps.Excititor.Worker/Scheduling/VexWorkerHostedService.cs",
"src/Excititor/__Libraries/StellaOps.Excititor.Connectors.Abstractions/VexConnectorBase.cs"
],
"verdict": "pass",
"notes": [
"Current source of truth for the VEX worker and connector runtime is under src/Concelier/...",
"The checked feature file still carried legacy src/Excititor/... paths from run-001 and was normalized as part of run-002."
]
}

View File

@@ -0,0 +1,56 @@
{
"type": "build-and-targeted-tests",
"capturedAtUtc": "2026-04-22T07:41:30Z",
"project": "src/Concelier/StellaOps.Excititor.Worker/StellaOps.Excititor.Worker.csproj",
"build": {
"command": "dotnet build \"src/Concelier/StellaOps.Excititor.Worker/StellaOps.Excititor.Worker.csproj\" --nologo -v minimal",
"result": "pass",
"warnings": 0,
"errors": 0,
"outputSnippet": [
"Build succeeded.",
"0 Warning(s)",
"0 Error(s)",
"Time Elapsed 00:00:14.24"
]
},
"targetedRuns": [
{
"runner": "scripts/test-targeted-xunit.ps1",
"project": "src/Concelier/__Tests/StellaOps.Excititor.Connectors.Cisco.CSAF.Tests/StellaOps.Excititor.Connectors.Cisco.CSAF.Tests.csproj",
"class": "StellaOps.Excititor.Connectors.Cisco.CSAF.Tests.Connectors.CiscoCsafConnectorTests",
"command": "powershell -ExecutionPolicy Bypass -File .\\scripts\\test-targeted-xunit.ps1 -Project \"src/Concelier/__Tests/StellaOps.Excititor.Connectors.Cisco.CSAF.Tests/StellaOps.Excititor.Connectors.Cisco.CSAF.Tests.csproj\" -Class \"StellaOps.Excititor.Connectors.Cisco.CSAF.Tests.Connectors.CiscoCsafConnectorTests\"",
"testsRun": 8,
"testsPassed": 8,
"testsFailed": 0,
"outputSnippet": [
"Build succeeded.",
"Total: 8, Errors: 0, Failed: 0, Skipped: 0, Not Run: 0, Time: 6.570s",
"FetchAsync_IncrementalChangesBackfill_CheckpointsForbiddenTimestampedDocumentsAndContinues",
"FetchAsync_IndexFallback_BootstrapSkipsForbiddenDocumentsAndContinues",
"FetchAsync_InitialChangesBackfill_UsesPathCheckpointAcrossBoundedRuns"
]
},
{
"runner": "scripts/test-targeted-xunit.ps1",
"project": "src/Concelier/__Tests/StellaOps.Excititor.Worker.Tests/StellaOps.Excititor.Worker.Tests.csproj",
"class": "StellaOps.Excititor.Worker.Tests.Orchestration.VexWorkerOrchestratorClientTests",
"command": "powershell -ExecutionPolicy Bypass -File .\\scripts\\test-targeted-xunit.ps1 -Project \"src/Concelier/__Tests/StellaOps.Excititor.Worker.Tests/StellaOps.Excititor.Worker.Tests.csproj\" -Class \"StellaOps.Excititor.Worker.Tests.Orchestration.VexWorkerOrchestratorClientTests\"",
"testsRun": 10,
"testsPassed": 10,
"testsFailed": 0,
"outputSnippet": [
"Build succeeded.",
"Total: 10, Errors: 0, Failed: 0, Skipped: 0, Not Run: 0, Time: 0.294s",
"CompleteJobAsync_PreservesConnectorManagedLastUpdated",
"CompleteJobAsync_UpdatesStateWithResults",
"SendHeartbeatAsync_UpdatesConnectorState"
]
}
],
"verdict": "pass",
"notes": [
"Targeted xUnit helper runs were used instead of solution filters so the requested classes were actually filtered and counted.",
"The Cisco class covers the anonymous 403 checkpoint regression path, and the worker class covers cursor preservation on successful job completion."
]
}

View File

@@ -0,0 +1,89 @@
{
"type": "integration",
"capturedAtUtc": "2026-04-22T07:42:44Z",
"providerId": "excititor:cisco",
"environment": {
"longLivedWorker": "stellaops-excititor-worker",
"disposableWorker": "stellaops-excititor-worker-cisco-qa-check",
"workerImage": "stellaops/excititor-worker:dev",
"databaseContainer": "stellaops-postgres"
},
"steps": [
{
"name": "long-lived-worker-health",
"command": "docker ps --filter name=stellaops-excititor-worker --format \"table {{.Names}}\\t{{.Status}}\\t{{.Image}}\"",
"result": "pass",
"evidence": [
"stellaops-excititor-worker Up 9 minutes (healthy) stellaops/excititor-worker:dev"
]
},
{
"name": "pre-run-state",
"command": "docker exec -i stellaops-postgres psql -U stellaops -d stellaops_platform -v ON_ERROR_STOP=1 -c \"SELECT connector_id, last_updated, array_length(document_digests,1) AS digests, COALESCE((SELECT COUNT(*) FROM jsonb_each(resume_tokens)),0) AS resume_tokens, next_eligible_run, failure_count FROM vex.connector_states WHERE connector_id = 'excititor:cisco';\"",
"result": "pass",
"state": {
"lastUpdated": "2026-04-22 07:25:53.884862+00",
"documentDigests": 4,
"resumeTokens": 1,
"nextEligibleRun": null,
"failureCount": 0
}
},
{
"name": "disposable-cisco-only-run",
"command": "docker compose -f devops/compose/docker-compose.stella-services.yml run --rm --no-deps -d --name stellaops-excititor-worker-cisco-qa-check -e Excititor__Worker__Providers__0__ProviderId=excititor:cisco -e Excititor__Worker__Providers__0__InitialDelay=00:00:00 -e Excititor__Worker__Providers__0__Interval=24:00:00 -e Excititor__Worker__Providers__0__Settings__MaxDocumentsPerFetch=2 -e Excititor__Worker__Providers__0__Settings__RequestDelay=00:00:00 excititor-worker",
"result": "pass",
"containerId": "86b49750fece2cce53fb3b053b83a6f5050d2c2c1c4d1c8fcd8922f2f6451878"
},
{
"name": "runtime-logs",
"command": "docker logs -f stellaops-excititor-worker-cisco-qa-check",
"result": "pass",
"runId": "eddb0e0b-26b1-4b9c-b08d-679413905795",
"evidence": [
"Provider excititor:cisco run started at 04/22/2026 07:42:38 +00:00",
"GET https://www.cisco.com/.well-known/csaf/provider-metadata.json -> 200",
"GET https://www.cisco.com/.well-known/csaf/index.json -> 404",
"GET https://www.cisco.com/.well-known/csaf/changes.csv -> 200",
"Cisco advisory change index https://www.cisco.com/.well-known/csaf/changes.csv yielded 2747 candidate advisory document(s).",
"Connector excititor:cisco persisted 0 raw document(s) this run.",
"Orchestrator job completed: runId=eddb0e0b-26b1-4b9c-b08d-679413905795 connector=excititor:cisco documents=0 claims=0 duration=00:00:01.6892442",
"Provider excititor:cisco run completed at 04/22/2026 07:42:41 +00:00"
]
},
{
"name": "post-run-state",
"command": "docker exec -i stellaops-postgres psql -U stellaops -d stellaops_platform -v ON_ERROR_STOP=1 -c \"SELECT connector_id, last_updated, array_length(document_digests,1) AS digests, COALESCE((SELECT COUNT(*) FROM jsonb_each(resume_tokens)),0) AS resume_tokens, next_eligible_run, failure_count FROM vex.connector_states WHERE connector_id = 'excititor:cisco'; SELECT provider_id, COUNT(*) AS docs FROM vex.vex_raw_documents WHERE provider_id = 'excititor:cisco' GROUP BY provider_id;\"",
"result": "pass",
"state": {
"lastUpdated": "2026-04-22 07:25:53.884862+00",
"documentDigests": 4,
"resumeTokens": 1,
"nextEligibleRun": null,
"failureCount": 0,
"rawDocuments": 4
},
"assertions": [
"last_updated remained unchanged across successful completion",
"failure_count stayed at 0",
"next_eligible_run remained null",
"raw document count stayed stable at 4"
]
},
{
"name": "cleanup",
"command": "docker stop stellaops-excititor-worker-cisco-qa-check",
"result": "pass",
"evidence": [
"stellaops-excititor-worker-cisco-qa-check"
]
}
],
"behaviorVerified": [
"Cisco worker fallback from index.json to changes.csv is healthy in the live environment.",
"Successful worker completion does not overwrite connector-managed LastUpdated.",
"Cisco connector remained out of backoff with next_eligible_run unset and failure_count equal to 0.",
"Anonymous 403 checkpoint handling was covered in the fresh targeted Cisco connector class run from the same QA cycle even though this live run did not encounter a new 403."
],
"verdict": "pass"
}

View File

@@ -0,0 +1,27 @@
{
"type": "source",
"capturedAtUtc": "2026-04-22T08:08:08.8206436Z",
"featureFile": "docs/features/checked/excititor/vex-source-registration-and-verification-pipeline.md",
"filesChecked": [
"src/Concelier/__Libraries/StellaOps.Excititor.Connectors.Oracle.CSAF/OracleCsafConnector.cs",
"src/Concelier/__Libraries/StellaOps.Excititor.Connectors.Oracle.CSAF/Configuration/OracleConnectorOptions.cs",
"src/Concelier/__Libraries/StellaOps.Excititor.Connectors.Oracle.CSAF/Metadata/OracleCatalogLoader.cs",
"src/Concelier/__Tests/StellaOps.Excititor.Connectors.Oracle.CSAF.Tests/Metadata/OracleCatalogLoaderTests.cs",
"src/Concelier/__Tests/StellaOps.Excititor.Connectors.Oracle.CSAF.Tests/Connectors/OracleCsafConnectorTests.cs",
"src/Concelier/StellaOps.Excititor.Worker/Options/BuiltInVexProviderDefaults.cs"
],
"found": [
"src/Concelier/__Libraries/StellaOps.Excititor.Connectors.Oracle.CSAF/OracleCsafConnector.cs",
"src/Concelier/__Libraries/StellaOps.Excititor.Connectors.Oracle.CSAF/Configuration/OracleConnectorOptions.cs",
"src/Concelier/__Libraries/StellaOps.Excititor.Connectors.Oracle.CSAF/Metadata/OracleCatalogLoader.cs",
"src/Concelier/__Tests/StellaOps.Excititor.Connectors.Oracle.CSAF.Tests/Metadata/OracleCatalogLoaderTests.cs",
"src/Concelier/__Tests/StellaOps.Excititor.Connectors.Oracle.CSAF.Tests/Connectors/OracleCsafConnectorTests.cs",
"src/Concelier/StellaOps.Excititor.Worker/Options/BuiltInVexProviderDefaults.cs"
],
"missing": [],
"verdict": "pass",
"notes": [
"The Oracle CSAF connector, its catalog loader, and the targeted Oracle test classes are present in the current src/Concelier layout.",
"BuiltInVexProviderDefaults still seeds excititor:oracle as one of the default public providers."
]
}

View File

@@ -0,0 +1,53 @@
{
"type": "build-and-targeted-tests",
"capturedAtUtc": "2026-04-22T08:07:05Z",
"project": "src/Concelier/__Tests/StellaOps.Excititor.Connectors.Oracle.CSAF.Tests/StellaOps.Excititor.Connectors.Oracle.CSAF.Tests.csproj",
"targetedRuns": [
{
"runner": "scripts/test-targeted-xunit.ps1",
"class": "StellaOps.Excititor.Connectors.Oracle.CSAF.Tests.Metadata.OracleCatalogLoaderTests",
"command": "powershell -ExecutionPolicy Bypass -File .\\scripts\\test-targeted-xunit.ps1 -Project \"src/Concelier/__Tests/StellaOps.Excititor.Connectors.Oracle.CSAF.Tests/StellaOps.Excititor.Connectors.Oracle.CSAF.Tests.csproj\" -Class \"StellaOps.Excititor.Connectors.Oracle.CSAF.Tests.Metadata.OracleCatalogLoaderTests\"",
"buildResult": "pass",
"warnings": 0,
"errors": 0,
"testsRun": 3,
"testsPassed": 3,
"testsFailed": 0,
"outputSnippet": [
"Build succeeded.",
"0 Warning(s)",
"0 Error(s)",
"Total: 3, Errors: 0, Failed: 0, Skipped: 0, Not Run: 0, Time: 0.400s",
"LoadAsync_FetchesAndCachesCatalog",
"LoadAsync_UsesOfflineSnapshotWhenNetworkFails",
"LoadAsync_ThrowsWhenOfflinePreferredButMissing"
]
},
{
"runner": "scripts/test-targeted-xunit.ps1",
"class": "StellaOps.Excititor.Connectors.Oracle.CSAF.Tests.Connectors.OracleCsafConnectorTests",
"command": "powershell -ExecutionPolicy Bypass -File .\\scripts\\test-targeted-xunit.ps1 -Project \"src/Concelier/__Tests/StellaOps.Excititor.Connectors.Oracle.CSAF.Tests/StellaOps.Excititor.Connectors.Oracle.CSAF.Tests.csproj\" -Class \"StellaOps.Excititor.Connectors.Oracle.CSAF.Tests.Connectors.OracleCsafConnectorTests\"",
"buildResult": "pass",
"warnings": 0,
"errors": 0,
"testsRun": 4,
"testsPassed": 4,
"testsFailed": 0,
"outputSnippet": [
"Build succeeded.",
"0 Warning(s)",
"0 Error(s)",
"Total: 4, Errors: 0, Failed: 0, Skipped: 0, Not Run: 0, Time: 1.235s",
"FetchAsync_NewEntry_PersistsDocumentAndUpdatesState",
"FetchAsync_ChecksumMismatch_SkipsDocument",
"FetchAsync_MissingHistoricalDocument_SkipsAndContinues",
"FetchAsync_EmptyDigestCheckpoint_DoesNotSuppressInitialBackfill"
]
}
],
"verdict": "pass",
"notes": [
"The Oracle targeted test pass covers both live-catalog metadata behavior and connector fetch safety paths.",
"The missing historical document case directly backs the live Oracle run behavior where several old Oracle CSAF URLs returned 404 but the provider still completed."
]
}

View File

@@ -0,0 +1,94 @@
{
"type": "integration",
"capturedAtUtc": "2026-04-22T08:07:25Z",
"providerId": "excititor:oracle",
"environment": {
"longLivedWorker": "stellaops-excititor-worker",
"disposableWorker": "stellaops-excititor-worker-oracle-qa-check",
"workerImage": "stellaops/excititor-worker:dev",
"databaseContainer": "stellaops-postgres"
},
"steps": [
{
"name": "long-lived-worker-health",
"command": "docker ps --filter name=stellaops-excititor-worker --format \"table {{.Names}}\\t{{.Status}}\\t{{.Image}}\"",
"result": "pass",
"evidence": [
"stellaops-excititor-worker Up 33 minutes (healthy) stellaops/excititor-worker:dev"
]
},
{
"name": "pre-run-state",
"command": "docker exec -i stellaops-postgres psql -U stellaops -d stellaops_platform -v ON_ERROR_STOP=1 -c \"SELECT connector_id, last_updated, array_length(document_digests,1) AS digests, COALESCE((SELECT COUNT(*) FROM jsonb_each(resume_tokens)),0) AS resume_tokens, next_eligible_run, failure_count FROM vex.connector_states WHERE connector_id = 'excititor:oracle'; SELECT provider_id, COUNT(*) AS docs FROM vex.vex_raw_documents WHERE provider_id = 'excititor:oracle' GROUP BY provider_id;\"",
"result": "pass",
"state": {
"lastUpdated": "2026-04-22 06:46:15.261191+00",
"documentDigests": 1,
"resumeTokens": 0,
"nextEligibleRun": null,
"failureCount": 0,
"rawDocuments": 1
}
},
{
"name": "disposable-oracle-only-run",
"command": "docker compose -f devops/compose/docker-compose.stella-services.yml run --rm --no-deps -d --name stellaops-excititor-worker-oracle-qa-check -e Excititor__Worker__Providers__0__ProviderId=excititor:oracle -e Excititor__Worker__Providers__0__InitialDelay=00:00:00 -e Excititor__Worker__Providers__0__Interval=24:00:00 -e Excititor__Worker__Providers__0__Settings__RequestDelay=00:00:00.2500000 excititor-worker",
"result": "pass",
"containerId": "4f7a034ca740bfd715e25fdd8606d5e72ae9cd204091742357fdb39d2ef518c8"
},
{
"name": "runtime-logs",
"command": "docker logs stellaops-excititor-worker-oracle-qa-check",
"result": "pass",
"runId": "5fa3edb0-a3af-4ec1-b9bb-dce9baa32d09",
"evidence": [
"Provider excititor:oracle run started at 04/22/2026 08:07:11 +00:00. Interval=24.00:00:00.",
"GET https://www.oracle.com/ocom/groups/public/@otn/documents/webcontent/rss-otn-sec.xml -> 200",
"Oracle CSAF catalogue loaded.",
"GET https://www.oracle.com/docs/tech/security-alerts/cpujul2019-5072835csaf.json -> 404",
"GET https://www.oracle.com/docs/tech/security-alerts/cve-2016-0603-2874360csaf.json -> 404",
"GET https://www.oracle.com/docs/tech/security-alerts/cve-2017-10269-4021872csaf.json -> 404",
"GET https://www.oracle.com/docs/tech/security-alerts/cve-2019-2729-5570780csaf.json -> 404",
"GET https://www.oracle.com/docs/tech/security-alerts/cve-2020-14750csaf.json -> 404",
"Oracle CSAF document URI is unavailable; entry skipped.",
"Connector excititor:oracle persisted 0 raw document(s) this run.",
"Orchestrator job completed: runId=5fa3edb0-a3af-4ec1-b9bb-dce9baa32d09 connector=excititor:oracle documents=0 claims=0 duration=00:00:03.6134483",
"Provider excititor:oracle run completed at 04/22/2026 08:07:19 +00:00 (duration 00:00:07.8903177)."
]
},
{
"name": "post-run-state",
"command": "docker exec -i stellaops-postgres psql -U stellaops -d stellaops_platform -v ON_ERROR_STOP=1 -c \"SELECT connector_id, last_updated, array_length(document_digests,1) AS digests, COALESCE((SELECT COUNT(*) FROM jsonb_each(resume_tokens)),0) AS resume_tokens, next_eligible_run, failure_count FROM vex.connector_states WHERE connector_id = 'excititor:oracle'; SELECT provider_id, COUNT(*) AS docs FROM vex.vex_raw_documents WHERE provider_id = 'excititor:oracle' GROUP BY provider_id;\"",
"result": "pass",
"state": {
"lastUpdated": "2026-04-22 06:46:15.261191+00",
"documentDigests": 1,
"resumeTokens": 0,
"nextEligibleRun": null,
"failureCount": 0,
"rawDocuments": 1
},
"assertions": [
"last_updated remained unchanged across successful completion",
"failure_count stayed at 0",
"raw document count stayed stable at 1",
"historical 404s did not move the provider into backoff"
]
},
{
"name": "cleanup",
"command": "docker stop stellaops-excititor-worker-oracle-qa-check",
"result": "pass",
"evidence": [
"stellaops-excititor-worker-oracle-qa-check"
]
}
],
"behaviorVerified": [
"The Oracle CSAF provider remains installed and runnable in the live Excititor worker.",
"Historical Oracle CSAF URLs that now return 404 are skipped cleanly without failing the provider run.",
"A successful Oracle worker completion preserves connector-managed cursor state and does not create duplicate raw documents.",
"The current Oracle state remains healthy for mirror operation: one stored raw document, no backoff, and no failure accumulation."
],
"verdict": "pass"
}