UP

docs/08_MODULE_SPECIFICATIONS.md

@@ -154,9 +154,12 @@ Each connector ships fixtures/tests under the matching `*.Tests` project.
 * **Connector/exporter packages** – each source/exporter can ship as a plug-in
   assembly with its own options and HttpClient configuration, keeping the core
   image minimal.
-* **Stella CLI (agent)** – triggers feed-related jobs (`stella db fetch/merge/export`)
-  and consumes the exported JSON/Trivy DB artefacts, aligning with the SBOM-first
-  workflow described in `AGENTS.md`.
+* **StellaOps CLI (agent)** – new `StellaOps.Cli` module that exposes
+  `scanner`, `scan`, and `db` verbs (via System.CommandLine 2.0) to download
+  scanner container bundles, install them locally, execute scans against target
+  directories, automatically upload results, and trigger Feedser jobs (`db
+  fetch/merge/export`) aligned with the SBOM-first workflow described in
+  `AGENTS.md`.
 * **Offline Kit** – bundles Feedser plug-ins, JSON tree, Trivy DB, and export
   manifests so air-gapped sites can load the latest vulnerability data without
   outbound connectivity.

docs/09_API_CLI_REFERENCE.md

@@ -183,21 +183,79 @@ Validation errors come back as:
 
 ---
 
-### 2.4 Attestation (Planned – Q1‑2026)
-
-```
-POST /attest
-```
+### 2.4 Attestation (Planned – Q1‑2026)
+
+```
+POST /attest
+```
 
 | Param       | Purpose                               |
 | ----------- | ------------------------------------- |
 | body (JSON) | SLSA v1.0 provenance doc              |
 |             | Signed + stored in local Rekor mirror |
-
-Returns `202 Accepted` and `Location: /attest/{id}` for async verify.
-
----
-
+
+Returns `202 Accepted` and `Location: /attest/{id}` for async verify.
+
+---
+
+## 3 StellaOps CLI (`stellaops-cli`)
+
+The new CLI is built on **System.CommandLine 2.0.0‑beta5** and mirrors the Feedser backend REST API.  
+Configuration follows the same precedence chain everywhere:
+
+1. Environment variables (e.g. `API_KEY`, `STELLAOPS_BACKEND_URL`, `StellaOps:ApiKey`)  
+2. `appsettings.json` → `appsettings.local.json`  
+3. `appsettings.yaml` → `appsettings.local.yaml`  
+4. Defaults (`ApiKey = ""`, `BackendUrl = ""`, cache folders under the current working directory)
+
+| Command | Purpose | Key Flags / Arguments | Notes |
+|---------|---------|-----------------------|-------|
+| `stellaops-cli scanner download` | Fetch and install scanner container | `--channel <stable\|beta\|nightly>` (default `stable`)<br>`--output <path>`<br>`--overwrite`<br>`--no-install` | Saves artefact under `ScannerCacheDirectory`, verifies digest/signature, and executes `docker load` unless `--no-install` is supplied. |
+| `stellaops-cli scan run` | Execute scanner container against a directory (auto-upload) | `--target <directory>` (required)<br>`--runner <docker\|dotnet\|self>` (default from config)<br>`--entry <image-or-entrypoint>`<br>`[scanner-args...]` | Runs the scanner, writes results into `ResultsDirectory`, and automatically uploads the artefact when the exit code is `0`. |
+| `stellaops-cli scan upload` | Re-upload existing scan artefact | `--file <path>` | Useful for retries when automatic upload fails or when operating offline. |
+| `stellaops-cli db fetch` | Trigger connector jobs | `--source <id>` (e.g. `redhat`, `osv`)<br>`--stage <fetch\|parse\|map>` (default `fetch`)<br>`--mode <resume|init|cursor>` | Translates to `POST /jobs/source:{source}:{stage}` with `trigger=cli` |
+| `stellaops-cli db merge` | Run canonical merge reconcile | — | Calls `POST /jobs/merge:reconcile`; exit code `0` on acceptance, `1` on failures/conflicts |
+| `stellaops-cli db export` | Kick JSON / Trivy exports | `--format <json\|trivy-db>` (default `json`)<br>`--delta` | Sets `{ delta = true }` parameter when requested |
+| `stellaops-cli config show` | Display resolved configuration | — | Masks secret values; helpful for air‑gapped installs |
+
+**Logging & exit codes**
+
+- Structured logging via `Microsoft.Extensions.Logging` with single-line console output (timestamps in UTC).  
+- `--verbose / -v` raises log level to `Debug`.  
+- Command exit codes bubble up: backend conflict → `1`, cancelled via `CTRL+C` → `130`, scanner exit codes propagate as-is.
+
+**Artifact validation**
+
+- Downloads are verified against the `X-StellaOps-Digest` header (SHA-256). When `StellaOps:ScannerSignaturePublicKeyPath` points to a PEM-encoded RSA key, the optional `X-StellaOps-Signature` header is validated as well.
+- Metadata for each bundle is written alongside the artefact (`*.metadata.json`) with digest, signature, source URL, and timestamps.
+- Retry behaviour is controlled via `StellaOps:ScannerDownloadAttempts` (default **3** with exponential backoff).
+- Successful `scan run` executions create timestamped JSON artefacts inside `ResultsDirectory`; these are posted back to Feedser automatically.
+
+**Authentication**
+
+- API key is sent as `Authorization: Bearer <token>` automatically when configured.  
+- Anonymous operation (empty key) is permitted for offline use cases but backend calls will fail with 401 unless the Feedser instance allows guest access.
+
+**Configuration file template**
+
+```jsonc
+{
+  "StellaOps": {
+    "ApiKey": "your-api-token",
+    "BackendUrl": "https://feedser.example.org",
+    "ScannerCacheDirectory": "scanners",
+    "ResultsDirectory": "results",
+    "DefaultRunner": "docker",
+    "ScannerSignaturePublicKeyPath": "",
+    "ScannerDownloadAttempts": 3
+  }
+}
+```
+
+Drop `appsettings.local.json` or `.yaml` beside the binary to override per environment.
+
+---
+
 ### 2.5 Misc Endpoints
 
 | Path       | Method | Description                  |

docs/ARCHITECTURE_FEEDSER.md

@@ -47,14 +47,14 @@ StellaOps.Feedser.Source.Ru.Nkcki/   # PDF/HTML bulletins → structured
 StellaOps.Feedser.Source.Vndr.Msrc/
 StellaOps.Feedser.Source.Vndr.Cisco/
 StellaOps.Feedser.Source.Vndr.Oracle/
-StellaOps.Feedser.Source.Vndr.Adobe/
+StellaOps.Feedser.Source.Vndr.Adobe/   # APSB ingest; emits vendor RangePrimitives with adobe.track/platform/priority telemetry + fixed-status provenance.
 StellaOps.Feedser.Source.Vndr.Apple/
 StellaOps.Feedser.Source.Vndr.Chromium/
 StellaOps.Feedser.Source.Vndr.Vmware/
 StellaOps.Feedser.Source.Distro.RedHat/
-StellaOps.Feedser.Source.Distro.Ubuntu/
-StellaOps.Feedser.Source.Distro.Debian/
-StellaOps.Feedser.Source.Distro.Suse/
+StellaOps.Feedser.Source.Distro.Debian/    # Fetches DSA list + detail HTML, emits EVR RangePrimitives with per-release provenance and telemetry.
+StellaOps.Feedser.Source.Distro.Ubuntu/   # Ubuntu Security Notices connector (JSON index → EVR ranges with ubuntu.pocket telemetry).
+StellaOps.Feedser.Source.Distro.Suse/     # CSAF fetch pipeline emitting NEVRA RangePrimitives with suse.status vendor telemetry.
 StellaOps.Feedser.Source.Ics.Cisa/
 StellaOps.Feedser.Source.Ics.Kaspersky/
 StellaOps.Feedser.Normalization/     # Canonical mappers, validators, version-range normalization
@@ -169,7 +169,7 @@ public interface IFeedConnector {
 ## 8) Observability
 
 * Serilog structured logging with enrichment fields (`source`, `uri`, `stage`, `durationMs`).
-* OpenTelemetry traces around fetch/parse/map/export; metrics for rate limit hits, schema failures, dedupe ratios, package size.
+* OpenTelemetry traces around fetch/parse/map/export; metrics for rate limit hits, schema failures, dedupe ratios, package size. Connector HTTP metrics are emitted via the shared `feedser.source.http.*` instruments tagged with `feedser.source=<connector>` so per-source dashboards slice on that label instead of bespoke metric names.
 * Prometheus scraping endpoint served by WebService.
 
 ---