108 lines
3.5 KiB
Markdown
108 lines
3.5 KiB
Markdown
# 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
|
|
|
|
```json
|
|
{
|
|
"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 */ }
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Related Documentation
|
|
|
|
* 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.
|