git.stella-ops.org/docs/modules/export-center/overview.md

Export Center Overview

The Export Center packages StellaOps evidence and policy outputs into portable, verifiable bundles. It provides one workflow for operators to deliver advisories, SBOMs, VEX statements, and policy decisions into downstream systems or air-gapped environments without rewriting data or violating the Aggregation-Only Contract (AOC).

What the Export Center delivers

• Unified export service. A dedicated exporter service coordinates profiles, runs, signing, and distribution targets with deterministic manifests.
• Profile catalogue. Out of the box variants include json:raw, json:policy, trivy:db, trivy:java-db, mirror:full, and mirror:delta, each aligned with AOC rules and downstream compatibility requirements.
• Surface parity. Operators can create, monitor, and download exports through the Web API gateway, Console workflows, and the CLI (stella export ...). All surfaces enforce tenant scope and RBAC consistently.
• Automation hooks. One-off, cron, and event triggers are orchestrated via the Scheduler/Orchestrator integration. Export telemetry (durations, bundle size, verification outcomes) feeds structured logs, metrics, and optional OpenTelemetry traces.

Profile variants at a glance

Profile	Contents	Primary scenarios	Distribution defaults
json:raw	Canonical advisories, VEX, SBOM JSONL with hashes	Downstream analytics, evidence escrow	HTTP download, object storage
json:policy	json:raw plus policy snapshot, evaluated findings	Policy attestation, audit packages	HTTP download, object storage
trivy:db / trivy:java-db	Trivy-compatible vulnerability databases	Feed external scanners and CI	OCI artifact push, download
mirror:full	Complete evidence, indexes, policy, provenance	Air-gap mirror, disaster recovery	Filesystem bundle, OCI artifact
mirror:delta	Changes relative to prior manifest	Incremental updates to mirrors	Filesystem bundle, OCI artifact

How it works end-to-end

1. Profile & scope resolution. A profile defines export type, content filters, and bundle settings. Scope selectors target tenants, artifacts, time windows, ecosystems, or SBOM subjects.
2. Ledger collection. Workers stream canonical data from Findings Ledger, VEX Lens, Conseiller feeds, and SBOM service. Policy exports pin a deterministic policy snapshot from Policy Engine.
3. Adapter execution. JSON adapters produce normalized .jsonl.zst outputs, Trivy adapters translate to the Trivy DB schema, and mirror adapters build filesystem or OCI bundle layouts.
4. Manifesting & provenance. Every run emits export.json (profile, filters, counts, checksums) and provenance.json (source artifacts, policy snapshot ids, signature references).
5. Signing & distribution. Bundles are signed via configured KMS (cosign-compatible) and distributed through HTTP streaming, OCI registry pushes, or object storage staging.

Refer to docs/modules/export-center/architecture.md (Sprint 35 task) for component diagrams and adapter internals once published.

Security and compliance guardrails

• AOC alignment. Exports bundle raw evidence and optional policy evaluations without mutating source content. Policy overlays remain attributed to Policy Engine and are clearly partitioned.
• Tenant isolation. All queries, manifests, and bundle paths carry tenant identifiers. Cross-tenant exports require explicit signed approval and ship with provenance trails.
• Signing and encryption. Manifests and payloads are signed using the platform KMS. Mirror profiles support optional in-bundle encryption (age/AES-GCM) with key wrapping.
• Determinism. Identical inputs yield identical bundles. Timestamps serialize in UTC ISO-8601; manifests include content hashes for audit replay.

See docs/security/policy-governance.md and docs/ingestion/aggregation-only-contract.md for broader guardrail context.

Operating it offline

• Offline Kit integration. Air-gapped deployments receive pre-built export profiles and object storage layout templates through the Offline Kit bundles.
• Mirror bundles. mirror:full packages raw evidence, normalized indexes, policy snapshots, and provenance in a portable filesystem layout suitable for disconnected environments. mirror:delta tracks changes relative to a prior export manifest.
• No unsanctioned egress. The exporter respects the platform allowlist. External calls (e.g., OCI pushes) require explicit configuration and are disabled by default for offline installs.

Consult docs/24_OFFLINE_KIT.md for Offline Kit delivery and docs/modules/concelier/operations/mirror.md for mirror ingestion procedures.

Getting started

1. Choose a profile. Map requirements to the profile table above. Policy-aware exports need a published policy snapshot.
2. Define selectors. Decide on tenants, products, SBOM subjects, or time windows to include. Default selectors export the entire tenant scope.
3. Run via preferred surface.
   • Console: Navigate to the Export Center view, create a run, monitor progress, and download artifacts.
   • CLI: Use stella export run --profile <name> --selector <filters> to submit a job, then stella export download.
   • API: POST to /api/export/runs with profile id and scope payload; stream results from /api/export/runs/{id}/download.
4. Verify bundles. Use the attached provenance manifest and cosign signature to validate contents before distributing downstream.

Refer to docs/modules/export-center/cli.md for detailed command syntax and automation examples.

Observability & troubleshooting

• Structured logs emit lifecycle events (fetch, adapter, sign, publish) with correlation IDs for parallel job tracing.
• Metrics exporter_run_duration_seconds, exporter_bundle_bytes_total, and exporter_run_failures_total feed Grafana dashboards defined in the deployment runbooks.
• Verification failures or schema mismatches bubble up through failure events and appear in Console/CLI with actionable error messages. Inspect the run's audit log and provenance.json for root cause.

See docs/observability/policy.md and docs/modules/devops/runbooks/deployment-upgrade.md for telemetry and operations guidance.

Imposed rule: Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.