stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
02e384a7d64ebbc66fcde3c206f5b9e7f87e4b17
git.stella-ops.org/docs/modules/scanner/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

4.3 KiB
Raw Blame History

Implementation plan — Scanner

Delivery phases

  • Phase 1 – Control plane & job queue
    Finalise Scanner WebService, queue abstraction (Redis/NATS), job leasing, CAS layer cache, artifact catalog, and API endpoints.
  • Phase 2 – Analyzer parity & SBOM assembly
    Implement OS/Lang/Native analyzers, inventory/usage SBOM views, entry trace resolution, deterministic component identity.
  • Phase 3 – Diff & attestations
    Deliver three-way diff engine, DSSE SBOM/report signing pipeline, attestation hand-off (Signer→Attestor), metadata for Export Center.
  • Phase 4 – Integrations & exports
    Integrate with Policy Engine, Vuln Explorer, Export Center, CLI/Console; provide buildx plugin, CLI commands, and offline scanning support.
  • Phase 5 – Observability & resilience
    Metrics/logs/traces, queue backpressure handling, cache eviction, runbooks, smoke tests, SLO dashboards.

Work breakdown

  • Control plane
    • REST API for scan requests, diff, catalog listing, artifact retrieval.
    • Queue service with idempotency, retries, dead-letter handling; worker scaling.
    • CAS storage (RustFS + S3 fallback), GC, ILM policies, offline mode.
  • Analyzers
    • OS (apk/dpkg/rpm), language (Java/Node/Python/Go/DotNet/Rust), native (ELF/PE/MachO).
    • Deterministic metadata (purl, version, source location), heuristics optional under flags.
    • Entry trace/usage analysis, dependency resolution, license detection.
  • SBOM & diff
    • Inventory/usage SBOM assembly, CycloneDX/SPDX emitters, schema validation.
    • Three-way diff (base, target, runtime), evidence linking, JSON export.
  • Attestation & export
    • DSSE bundle signing, attestation metadata for Signer/Attestor, provenance summary.
    • Export Center integration (SBOM/diff artifacts, manifests), CLI builder plugin (buildx).
  • CLI/Console
    • CLI commands stella scan, stella sbom diff, stella sbom export, offline caching.
    • Console flows for scan requests, diff viewer, SBOM downloads, attestation status.
  • Observability & ops
    • Metrics (queue depth, scan latency, cache hit/miss, analyzer timing), logs/traces with job IDs.
    • Alerts for backlog, failed scans, attestation issues, storage pressure.
    • Runbooks for stuck jobs, cache corruption, analyzer regressions, offline mode.

Acceptance criteria

  • Scans produce deterministic SBOM inventory/usage views with component identity stability and reproducible diffs.
  • Queue/worker pipeline handles retries, backpressure, offline kits, and exports DSSE attestations for Signer/Attestor.
  • Export Center consumes SBOM/diff artifacts; Vuln Explorer receives metadata and explain traces.
  • CLI/Console parity for scan submission, diffing, exports, attestation verification.
  • Observability dashboards cover queue health, analyzer success rates, performance; alerts fire on SLO breaches.
  • Offline scanning (air-gapped) supported with local caches and manifest verification.

Risks & mitigations

  • Analyzer drift/determinism: golden fixtures, hash-based regression tests, deterministic sorting, strict identity rules.
  • Queue overload: adaptive backpressure, scaling workers, dead-letter review, priority lanes.
  • Storage growth: CAS dedupe, ILM policies, offline bundle pruning.
  • Attestation failures: retry with backoff, attestation health checks, Notify integration.
  • Offline divergence: packaging of analyzers/configs, manifest signatures, parity tests.

Test strategy

  • Unit: analyzer parsers, component identity, diff calculations, API validation.
  • Integration: end-to-end scan/diff/attestation flows, Export Center integration, CLI automation.
  • Performance: large images, concurrent scans, cache stress, queue throughput.
  • Determinism: repeated scans/diffs across systems, hash comparisons, property tests.
  • Security: RBAC, tenant isolation, attestation key handling, path sanitisation.
  • Offline: air-gap scanning, manifest verification, CLI offline mode.

Definition of done

  • Scanner services, analyzers, diffing, attestation pipeline, exports, and observability delivered with runbooks and Offline Kit parity.
  • Documentation (architecture, analyzer guides, CLI, offline mode, operations) updated with imposed rule statements.
  • ./TASKS.md and ../../TASKS.md updated with progress; regression fixtures maintained in repo.