stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
691028fe6982aa129aebb8ad201da450b8df0a10
git.stella-ops.org/docs/modules/export-center/implementation_plan.md
master 7b5bdcf4d3 feat(docs): Add comprehensive documentation for Vexer, Vulnerability Explorer, and Zastava modules 
- Introduced AGENTS.md, README.md, TASKS.md, and implementation_plan.md for Vexer, detailing mission, responsibilities, key components, and operational notes.
- Established similar documentation structure for Vulnerability Explorer and Zastava modules, including their respective workflows, integrations, and observability notes.
- Created risk scoring profiles documentation outlining the core workflow, factor model, governance, and deliverables.
- Ensured all modules adhere to the Aggregation-Only Contract and maintain determinism and provenance in outputs.
2025-10-30 00:09:39 +02:00

5.0 KiB
Raw Blame History

Implementation plan — Export Center

Delivery phases

  • Phase 1 – JSON & mirror foundations
    Stand up the Export Center service + worker, deliver canonical JSON (json:raw, json:policy) and mirror:full profiles as download-only bundles, seed schema migrations, and publish manifest/provenance formats.
  • Phase 2 – Trivy adapters & distribution
    Implement Trivy DB / Java DB adapters, wire OCI/object storage distribution paths, and expose policy snapshot embedding + verification tooling.
  • Phase 3 – Delta, encryption, scheduling
    Release mirror deltas, bundle encryption, advanced scheduling/automation, resumable downloads, and CLI/Console verification workflows.

Component work breakdown

  • Service & worker
    • Define migrations for export_profiles, export_runs, export_inputs, export_distributions.
    • Implement planner, adapter host, signing/attestation layer, distribution engines, and deterministic manifests.
    • Enforce tenant quotas, concurrency controls, and audit logging for create/cancel/distribute events.
  • Adapters
    • JSON adapters: canonical JSONL writers, redaction guardrails, compression (zstd).
    • Trivy adapters: field mapping, schema compatibility gating, validation suite.
    • Mirror adapters: filesystem/OCI layout, delta computation, optional encryption with manifest updates.
  • Integrations
    • Findings Ledger streaming APIs for advisories, VEX, SBOMs, findings.
    • Policy Engine deterministic snapshot endpoint; VEX Lens consensus snapshot.
    • Export Center telemetry surfaced through Observability stack.
  • Surfaces
    • Console: profiles CRUD, run wizard, run detail + verification panel, distribution dashboards.
    • CLI: stella export profile|run|download|verify with resumable downloads and signature verification.
  • Security / RBAC
    • Scope enforcement per tenant, role matrix coverage, encryption key rotation tests, redaction filters.
  • Docs & ops
    • Author module dossier (overview, architecture, profiles, API, CLI, mirror bundles, Trivy adapter, provenance & signing).
    • Produce runbooks (docs/operations/export-runbook.md) and hardening guidance (docs/security/export-hardening.md).

Documentation deliverables

  • docs/modules/export-center/overview.md — responsibilities, profiles, surfaces.
  • docs/modules/export-center/architecture.md — service topology, adapters, manifests, distribution flow.
  • docs/modules/export-center/profiles.md, trivy-adapter.md, mirror-bundles.md, provenance-and-signing.md, api.md, cli.md — keep aligned with shipped features.
  • Cross-link Orchestrator, Policy, VEX Lens, CLI, and Offline Kit docs whenever exports become dependencies.

Acceptance criteria

  • Operators can create, monitor, and download an export; cosign verify (and CLI verify) succeeds against manifest + provenance, mapping back to source artifacts.
  • Trivy bundles import cleanly into Trivy across supported versions; mirror bundles run in Offline Kit reference environment (full + delta).
  • Policy snapshot runs reproduce deterministic decisions and include embedded policyVersion + inputsHash.
  • Tenant scoping and RBAC block unauthorized actions; encryption-enabled bundles lock data to recipient keys.
  • Metrics (exporter_run_duration_seconds, exporter_bundle_bytes_total, exporter_run_failures_total) and dashboards reflect live runs; alerts trigger on sustained failure rates.
  • Retried runs remain idempotent: manifests, hashes, and distribution artefacts match across identical inputs.

Risks & mitigations

  • Schema drift (Trivy / policy): versioned adapters with compatibility gates, CI integration tests, fail-fast with actionable errors.
  • Bundle bloat: zstd compression, sharding, delta exports, OCI dedupe.
  • Data leakage: strict schema allowlists, tenancy filters, redaction enforcement, encryption options.
  • Non-determinism: embed policy snapshots, enforce deterministic ordering, include content hashes in manifest.
  • Operational slowness: streaming downloads with range support, resumable CLI, concurrency limits, retry policies for workers.

Test strategy

  • Unit: adapter mapping, manifest hashing, signing/attestation, delta computation, encryption round-trips.
  • Integration: end-to-end runs for every profile, verification workflows, OCI push/pull, resume/abort scenarios.
  • Compatibility: matrix tests for Trivy versions, mirror bundle import in Offline Kit sample environment.
  • Security: tenant fuzzing, RBAC coverage, redaction/PII filters, key rotation.
  • Performance & chaos: stress exports with large datasets, simulate worker/API failures mid-run, confirm deterministic recovery.

Definition of done

  • Service, worker, and adapters deployed with telemetry & alerting.
  • CLI & Console workflows published, Offline Kit instructions updated.
  • Documentation set listed above refreshed; imposed rule statements appended where required.
  • CI pipelines include schema validation, profile verification, and determinism checks.
  • ./TASKS.md + ../../TASKS.md reflect current status for in-flight stories.