component_architecture_mirror.md - Stella Ops Mirror (2025Q4)

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 bundle import.

Boundaries.

Mirror caches upstream feeds; it does not originate vulnerability data.
Mirror produces bundles for air-gapped distribution.
Feeds are cryptographically verified before distribution.

1) Integration with Concelier

Mirror is primarily integrated as part of Concelier's federation layer:

src/Concelier/__Libraries/
 └─ StellaOps.Concelier.Federation/    # Bundle export/import for offline

The StellaOpsMirror connector in Concelier handles:

Upstream feed synchronization
Local cache management
Bundle generation for offline distribution

2) Bundle Format

{
  "bundleId": "mirror-nvd-2025-01-15",
  "source": "nvd",
  "timestamp": "2025-01-15T10:30:00Z",
  "contents": [
    {
      "path": "nvd/CVE-2025-*.json",
      "digest": "sha256:abc123..."
    }
  ],
  "signature": { /* DSSE envelope */ }
}

Concelier: ../concelier/architecture.md
AirGap: ../airgap/architecture.md
Provenance observers: ./provenance/observers.md

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

Sprint SPRINT_20260208_041_Mirror_mirror_creator adds a deterministic core library at:

src/Mirror/StellaOps.Mirror.Creator/StellaOps.Mirror.Creator.Core.csproj

Implemented Contracts

IMirrorCreatorService
- UpsertSourceAsync(MirrorSourceConfiguration source, CancellationToken cancellationToken = default)
- GetSourcesAsync(string tenantId, CancellationToken cancellationToken = default)
- CreateSyncPlanAsync(MirrorSyncRequest request, CancellationToken cancellationToken = default)
- RecordSyncResultAsync(MirrorSyncResult result, CancellationToken cancellationToken = default)
Model types in MirrorModels.cs:
- MirrorSourceConfiguration
- MirrorSyncRequest
- MirrorSyncPlan and MirrorSyncPlanItem
- MirrorSyncResult
- MirrorContentKind and MirrorSyncMode
Options in MirrorCreatorOptions with configurable OutputRoot.
DI registration in MirrorServiceCollectionExtensions.AddMirrorCreator(...).

Determinism Guarantees

Tenant and source IDs are normalized to lowercase-trimmed values.
Source ordering is stable (ordinal sort by source ID per tenant).
Plan IDs are generated from canonical plan content using SHA-256.
Output bundle path format is stable:
- <outputRoot>/<tenant>/<source>/<yyyyMMddHHmmss>.bundle.json
Sync mode behavior:
- Full when no prior cursor exists.
- Incremental after successful cursor recording via RecordSyncResultAsync.

Test Evidence

Test project: src/Mirror/__Tests/StellaOps.Mirror.Creator.Core.Tests/
Executed: dotnet test src/Mirror/__Tests/StellaOps.Mirror.Creator.Core.Tests/StellaOps.Mirror.Creator.Core.Tests.csproj
Result on 2026-02-08: Passed 4/4 tests.

Current Boundaries

Implementation is currently in-memory and does not persist checkpoints to a backing store.
No dedicated HTTP endpoints or CLI command group are added in this sprint.
Runtime mirror transport/execution remains the responsibility of future integration work.

3.5 KiB Raw Blame History