Mirror Architecture

Vulnerability feed mirror and distribution service.

Scope. Architecture for Mirror: mirroring vulnerability feeds from upstream sources for offline distribution and reduced external dependencies.

0) Mission & boundaries

Mission. Provide local mirrors of vulnerability feeds (NVD, OSV, GHSA, etc.) for offline operation and reduced latency. Enable air-gapped deployments to receive updates via signed bundle import.

Boundaries.

1) Integration with Concelier

Mirror functionality is split across two Concelier libraries plus the standalone src/Mirror/ planning core (see §3):

src/Concelier/__Libraries/
 ├─ StellaOps.Concelier.Federation/                  # Bundle export/import (produces & ingests bundles)
 └─ StellaOps.Concelier.Connector.StellaOpsMirror/   # Feed connector that consumes a published mirror

1.1 Federation library (StellaOps.Concelier.Federation)

Produces and ingests offline federation bundles. Key components grounded in source:

1.2 Mirror connector (StellaOps.Concelier.Connector.StellaOpsMirror)

StellaOpsMirrorConnector is an IFeedConnector (source name stella-mirror) that consumes a published StellaOps mirror — it does not generate bundles. It runs the standard Fetch -> Parse -> Map pipeline:

Configuration (StellaOpsMirrorConnectorOptions, bound under Concelier:Sources:StellaopsMirror):

KeyDefaultNotes
EnabledtrueMaster toggle; false makes Fetch a no-op.
BaseAddresshttps://mirror.stella-ops.orgPlaceholder default; override via env STELLA_MIRROR_BASE_URL.
IndexPath/concelier/exports/index.jsonRelative path to the mirror index.
DomainIdprimaryPreferred mirror domain when several are published.
HttpTimeout30sPer-request timeout.
Signature.EnabledfalseRequire a valid detached JWS when true.
Signature.KeyId""Expected JWS kid.
Signature.ProvidernullCrypto provider hint.
Signature.PublicKeyPathnullFallback PEM EC public key path.

2) Bundle & index format

The shapes below are grounded in the actual records, not illustrative placeholders.

2.1 Mirror index / bundle descriptors

The connector consumes a mirror index laid out as MirrorIndexDocument -> MirrorIndexDomainEntry -> MirrorFileDescriptor (StellaOps.Concelier.Connector.StellaOpsMirror.Internal):

{
  "schemaVersion": 1,
  "generatedAt": "2025-01-15T10:30:00Z",
  "targetRepository": "primary",
  "domains": [
    {
      "domainId": "primary",
      "displayName": "Primary mirror",
      "advisoryCount": 1234,
      "manifest": { "path": "...", "sizeBytes": 0, "digest": "sha256:...", "signature": null },
      "bundle": {
        "path": "...",
        "sizeBytes": 0,
        "digest": "sha256:...",
        "signature": {
          "path": "...",
          "algorithm": "ES256",
          "keyId": "...",
          "provider": "...",
          "signedAt": "2025-01-15T10:30:00Z"
        }
      },
      "sources": [
        { "source": "nvd", "firstRecordedAt": null, "lastRecordedAt": null, "advisoryCount": 0 }
      ]
    }
  ]
}

The bundle payload itself is a MirrorBundleDocument (schemaVersion, generatedAt, targetRepository, domainId, displayName, advisoryCount, advisories[], sources[]).

Signatures are detached JWS, not DSSE. MirrorSignatureVerifier validates an unencoded-payload detached JWS (header..signature, b64=false required as a crit parameter) over the bundle bytes, supporting ES256/ES384/ES512. There is no DSSE envelope in this path.

2.2 Federation export manifest

The Federation export side emits a BundleManifest (feedser-bundle/1.0):

{
  "version": "feedser-bundle/1.0",
  "siteId": "...",
  "exportCursor": "...",
  "sinceCursor": null,
  "exportedAt": "2025-01-15T10:30:00Z",
  "counts": { "canonicals": 0, "edges": 0, "deletions": 0 },
  "bundleHash": "sha256:...",
  "signature": { "keyId": "...", "algorithm": "...", "issuer": "..." }
}

sinceCursor: null denotes a full export; a non-null value denotes a delta. counts.total is derived (canonicals + edges + deletions).

3) Mirror Creator Core (2026-02-08)

Sprint SPRINT_20260208_041_Mirror_mirror_creator adds a deterministic core library at:

Implemented Contracts

Determinism Guarantees

Test Evidence

Current Boundaries

4) Mirror seed archive — the working offline distribution path

The Mirror Creator core (§3) is a fail-closed planning stub with no runtime. The surface operators actually use to move the vulnerability corpus into an air-gapped install is the mirror seed archive, which is fully implemented. It lives across the CLI, a Concelier persistence engine, a standalone tool, and DevOps scripts — none of it under src/Mirror. This section documents that surface (added 2026-07-12, CLO-7).

4.1 CLI: stella mirror seed { export | validate | import | download }

src/Cli/StellaOps.Cli/Commands/MirrorSeedCommandGroup.cs implements the group (wired under the top-level mirror group in CommandFactory). It operates on the local advisory / VEX / scanner projection database.

4.2 Engine: StellaOps.Concelier.Persistence seed services

src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/MirrorSeed/ is the produce/import/validate implementation (schema vuln): IMirrorSeedArchiveService / PostgresMirrorSeedArchiveService, MirrorSeedManifestReader, MirrorSeedRebuildService, MirrorSeedParityReport (import parity check), MirrorSeedRemapReset, and MirrorSeedArchiveModels. An archive is a manifest.json (profile, watermarks, per-table row counts, checksums) plus compressed data chunks.

4.3 Tool and DevOps scripts

4.4 Module-boundary note

“Mirror” as a runtime lives mostly inside Concelier (Federation library + connector, §1) and Concelier.Persistence (the seed engine above); src/Mirror holds only the not-yet-wired planning core. The seed surface therefore has no single owning module dossier — this section is its architectural pointer.