stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity

feat(docs): Add comprehensive documentation for Vexer, Vulnerability Explorer, and Zastava modules

Browse Source 
- 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.
This commit is contained in:
master
2025-10-30 00:09:39 +02:00
parent 86f606a115
commit e8537460a3
503 changed files with 16136 additions and 54638 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
docs/modules/scanner/implementation_plan.md Normal file
View File

@@ -0,0 +1,64 @@
# 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.