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/vuln-explorer/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 — Vulnerability Explorer

Delivery phases

  • Phase 1 – Findings Ledger & resolver
    Create append-only ledger, projector, ecosystem resolvers (npm/Maven/PyPI/Go/RPM/DEB), canonical advisory keys, and provenance hashing.
  • Phase 2 – API & simulation
    Ship Vuln Explorer API (list/detail/grouping/simulation), batch evaluation with Policy Engine rationales, and export orchestrator.
  • Phase 3 – Console & CLI workflows
    Deliver triage UI (assignments, comments, remediation plans, simulation bar), keyboard accessibility, and CLI commands (stella vuln ...) with JSON/CSV output.
  • Phase 4 – Automation & integrations
    Integrate Advisory AI hints, Zastava runtime exposure, Notify rules, Scheduler follow-up scans, and Graph Explorer deep links.
  • Phase 5 – Exports & offline parity
    Generate deterministic bundles (JSON, CSV, PDF, Offline Kit manifests), audit logs, and signed reports.
  • Phase 6 – Observability & hardening
    Complete dashboards (projection lag, MTTR, accepted-risk cadence), alerts, runbooks, performance tuning (5M findings/tenant), and security/RBAC validation.

Work breakdown

  • Findings Ledger
    • Define event schema, Merkle root anchoring, append-only storage, history tables.
    • Projector to finding_records and finding_history, idempotent event processing, time travel snapshots.
    • Resolver pipelines referencing SBOM inventory deltas, policy outputs, VEX consensus, runtime signals.
  • API & exports
    • REST endpoints (/v1/findings, /v1/findings/{id}, /actions, /reports, /exports) with ABAC filters.
    • Simulation endpoint returning diffs, integration with Policy Engine batch evaluation.
    • Export jobs for JSON/CSV/PDF plus Offline Kit bundle assembly and signing.
  • Console
    • Feature module vuln-explorer with grid, filters, saved views, deep links, detail tabs (policy, evidence, paths, remediation).
    • Simulation drawer, delta chips, accepted-risk approvals, evidence bundle viewer.
    • Accessibility (keyboard navigation, ARIA), virtualization for large result sets.
  • CLI
    • Commands stella vuln list|show|simulate|assign|accept-risk|verify-fix|export.
    • Stable schemas for automation; piping support; tests for exit codes.
  • Integrations
    • Conseiller/Excitator: normalized advisory keys, linksets, evidence retrieval.
    • SBOM Service: inventory deltas with scope/runtime flags, safe version hints.
    • Notify: events for SLA breaches, accepted-risk expiries, remediation deadlines.
    • Scheduler: trigger rescans when remediation plan milestones complete.
  • Observability & ops
    • Metrics (open findings, MTTR, projection lag, export duration, SLA burn), logs/traces with correlation IDs.
    • Alerting on projector backlog, API 5xx spikes, export failures, accepted-risk nearing expiry.
    • Runbooks covering recompute storms, mapping errors, report issues.

Acceptance criteria

  • Ledger/event sourcing reproduces historical states byte-for-byte; Merkle hashes verify integrity.
  • Resolver respects ecosystem semantics, scope, and runtime context; path evidence presented in UI/CLI.
  • Triage workflows (assignment, comments, accepted-risk) enforce justification and approval requirements with audit records.
  • Simulation returns policy diffs without mutating state; CLI/UI parity achieved for simulation and exports.
  • Exports and Offline Kit bundles reproducible with signed manifests and provenance; reports available in JSON/CSV/PDF.
  • Observability dashboards show green SLOs, alerts fire for projection lag or SLA burns, and runbooks documented.
  • RBAC/ABAC validated; attachments encrypted; tenant isolation guaranteed.

Risks & mitigations

  • Advisory identity collisions: strict canonicalization, linkset references, raw evidence access.
  • Resolver inaccuracies: property-based tests, path verification, manual override workflows.
  • Projection lag/backlog: autoscaling, queue backpressure, alerting, pause controls.
  • Export size/performance: streaming NDJSON, size estimators, chunked downloads.
  • User confusion on suppression: rationale tab, explicit badges, explain traces.

Test strategy

  • Unit: resolver algorithms, state machine transitions, policy mapping, export builders.
  • Integration: ingestion → ledger → projector → API flow, simulation, Notify notifications.
  • E2E: Console triage scenarios, CLI flows, accessibility tests.
  • Performance: 5M findings/tenant, projection rebuild, export generation.
  • Security: RBAC/ABAC matrix, CSRF, attachment encryption, signed URL expiry.
  • Determinism: time-travel snapshots, export manifest hashing, Offline Kit replay.

Definition of done

  • Services, UI/CLI, integrations, exports, and observability deployed with runbooks and Offline Kit parity.
  • Documentation suite (overview, using-console, API, CLI, findings ledger, policy mapping, VEX/SBOM integration, telemetry, security, runbooks, install) updated with imposed rule statement.
  • ./TASKS.md and ../../TASKS.md reflect active progress; compliance checklists appended where required.