# 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.