Mirror

Mirror redistributes Stella Ops advisory data as signed offline bundles so air-gapped deployments can stay current without direct network access. This page is for operators packaging mirror bundles and for engineers integrating with the planning core and federation contracts.

Status: Planning core implemented (fail-closed runtime); bundle export/import lives in Concelier Source: src/Mirror/, plus src/Concelier/__Libraries/StellaOps.Concelier.Federation/ and src/Concelier/__Libraries/StellaOps.Concelier.Connector.StellaOpsMirror/ Owner: Mirror Creator Guild (src/Mirror/StellaOps.Mirror.Creator/AGENTS.md)

Purpose

Mirror redistributes Concelier’s canonical advisory data as signed offline bundles for air-gapped deployments. It does not originate vulnerability data — it mirrors what Concelier already holds, and provides a deterministic planning core for scheduling those mirror runs.

See architecture.mdfor the source-grounded contract reference.

Components

The Mirror capability is split across three locations:

1. Mirror Creator planning core — src/Mirror/StellaOps.Mirror.Creator/

A deterministic planning library (assembly StellaOps.Mirror.Creator.Core, target net10.0). It is a class library, not a runnable host: there is no Program.cs, no HTTP endpoint. The top-level stella mirror CLI group is separate from this planning core; its create verb currently fails closed with exit code 9 and writes no artifacts.

• IMirrorCreatorService (IMirrorCreatorService.cs) — the planning contract:
  • UpsertSourceAsync(MirrorSourceConfiguration, CancellationToken)
  • GetSourcesAsync(string tenantId, CancellationToken)
  • CreateSyncPlanAsync(MirrorSyncRequest, CancellationToken)
  • RecordSyncResultAsync(MirrorSyncResult, CancellationToken)
• FailClosedMirrorCreatorService — the production default; every method throws InvalidOperationException until a durable IMirrorCreatorService is registered. There is no production in-memory/durable implementation yet.
• MirrorServiceCollectionExtensions.AddMirrorCreator(...) — DI registration that wires MirrorCreatorOptions, TimeProvider.System, and the fail-closed service.
• Model/enum types in MirrorModels.cs (see Models below).
• The deterministic in-memory implementation (InMemoryMirrorCreatorService) lives in the test project only (src/Mirror/__Tests/StellaOps.Mirror.Creator.Core.Tests/Testing/), not in any shipped assembly.

2. Bundle export/import (Concelier Federation) — StellaOps.Concelier.Federation

Produces and ingests offline federation bundles (feedser-bundle/1.0): BundleExportService, DeltaQueryService, BundleImportService, BundleReader, BundleVerifier, BundleMergeService, IBundleSigner (default NullBundleSigner), Zstandard compression, and local-disk / S3 publishers. See architecture.md §1.1.

3. Mirror feed connector — StellaOps.Concelier.Connector.StellaOpsMirror

StellaOpsMirrorConnector (IFeedConnector, source name stella-mirror) consumes a published StellaOps mirror via the standard Fetch → Parse → Map pipeline, verifying each sha256: digest and optional detached JWS signature. See architecture.md §1.2.

Scripts — src/Mirror/StellaOps.Mirror.Creator/

• make-thin-v1.sh — builds a deterministic “thin” (mirror-thin-v1) bundle: stages layers, computes a manifest, produces a reproducible tar.gz, optionally an OCI layout (OCI=1), and a bundle-level meta JSON. It shells out to scripts/mirror/sign_thin_bundle.py and scripts/mirror/verify_thin_bundle.py (see Status note).
• schedule-export-center-run.sh — curls POST {EXPORT_CENTER_BASE_URL}/export-center/runs to schedule a mirror export run and appends an audit-log entry.

Models (planning core)

Grounded in MirrorModels.cs:

• MirrorSourceConfiguration — record: TenantId, SourceId, SourceUri, TargetUri, ContentKinds, Enabled (default true); exposes normalized lowercase/trimmed NormalizedTenantId / NormalizedSourceId.
• MirrorSyncRequest — TenantId, optional RequestedAt.
• MirrorSyncPlan — PlanId, TenantId, CreatedAt, Items.
• MirrorSyncPlanItem — SourceId, Mode, ContentKinds, Cursor, OutputPath.
• MirrorSyncResult — PlanId, TenantId, SourceId, Succeeded, NewCursor, CompletedAt.
• [Flags] MirrorContentKind — Advisories=1, Vex=2, Sbom=4, Images=8, Dashboards=16.
• MirrorSyncMode — Full=0, Incremental=1 (Full until a cursor is recorded, then Incremental).

Determinism guarantees

• Tenant/source IDs normalized to lowercase, trimmed.
• Sources sorted by ordinal source ID per tenant.
• Plan IDs are SHA-256 over canonical plan content.
• Output path format: <OutputRoot>/<tenant>/<source>/<yyyyMMddHHmmss>.bundle.json.

Configuration

The planning core has no appsettings/HTTP config surface. Configuration is via the options object and (for the scripts) environment variables.

• MirrorCreatorOptions.OutputRoot (default mirror-bundles) — root for generated bundle output paths.
• make-thin-v1.sh env: CREATED, TENANT_SCOPE (default tenant-demo), ENV_SCOPE (default lab), CHUNK_SIZE (default 5242880), CHECKPOINT_FRESHNESS (default 86400), PQ_CO_SIGN_REQUIRED (0/1), SIGN_KEY, OCI, TIME_ANCHOR_FILE.
• schedule-export-center-run.sh env: EXPORT_CENTER_BASE_URL (default http://localhost:8080), EXPORT_CENTER_TENANT (default tenant-default), EXPORT_CENTER_PROJECT, EXPORT_CENTER_TOKEN, EXPORT_CENTER_ARTIFACTS_JSON, AUDIT_LOG_PATH.

Authority scopes

The planning core exposes no HTTP surface, so it declares no dedicated Authority scopes — there are no mirror:* consts in StellaOps.Auth.Abstractions.StellaOpsScopes. Bundle scheduling rides on Export Center authorization; the schedule-export-center-run.sh script passes a caller-supplied bearer token through to /export-center/runs.

Dependencies

• Concelier — canonical advisory source that Mirror redistributes.
• ExportCenter — bundle scheduling target for schedule-export-center-run.sh.
• AirGap — import/validation of bundles on the offline side.
• Microsoft.Extensions.DependencyInjection.Abstractions, Microsoft.Extensions.Options (the only NuGet references of the planning core).

Related Documentation

• Architecture (source-grounded contracts): ./architecture.md
• Thin-bundle assembler: ./thin-bundle-assembler.md, ./assembler.md
• DSSE / TUF profile + signing: ./dsse-tuf-profile.md, ./signing-runbook.md
• AirGap Module: ../airgap/
• ExportCenter: ../export-center/
• Offline Kit: ../../OFFLINE_KIT.md

Current Status

• The Mirror Creator planning core is implemented as a deterministic library, but its runtime persistence is fail-closed: production hosts must register a durable IMirrorCreatorService before any planning method will run. No durable implementation ships today.
• Real bundle export/import and mirror consumption are implemented in the Concelier Federation library and the stella-mirror connector (see architecture.md).
• Runtime mirror transport/execution from the planning core is future integration work; no HTTP endpoints exist for it yet. The discoverable stella mirror create command is not a runtime adapter for this core: it returns mirror_create_not_implemented and points to the implemented feedser bundle export and mirror seed export paths (per TASKS.md / sprint SPRINT_20260424_042).