master
7b5bdcf4d3
- 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.
65 lines
4.3 KiB
Markdown
65 lines
4.3 KiB
Markdown
# 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.
|