git.stella-ops.org/docs/modules/vuln-explorer/architecture.md

Vulnerability Explorer architecture

Based on Epic 6 – Vulnerability Explorer; this specification summarises the ledger model, triage workflows, APIs, and export requirements.

1) Ledger data model

• See ../findings-ledger/schema.md for the canonical SQL schema, hashing strategy, and fixtures underpinning these collections.

• Collections / tables

  • finding_records – canonical, policy-derived findings enriched with advisory, VEX, SBOM, runtime context. Includes policyVersion, advisoryRawIds, vexRawIds, sbomComponentId, policyRationale (array of explain bundle URIs or remediation notes returned by /api/policy/eval/batch), and explainBundleRef.
  • finding_history – append-only state transitions (new, triaged, accepted_risk, remediated, false_positive, etc.) with timestamps, actor, and justification.
  • triage_actions – discrete operator actions (comment, assignment, remediation note, ticket link) with immutable provenance.
  • remediation_plans – structured remediation steps (affected assets, deadlines, recommended fixes, auto-generated from SRM/AI hints).
  • reports – saved report definitions, export manifests, and signatures.

• Immutability & provenance – All updates are append-only; previous state is recoverable. Records capture tenant, artifactId, findingKey, policyVersion, sourceRunId, sr mDigest.

2) Triage workflow

1. Ingest effective findings from Policy Engine (stream policy.finding.delta) and on-demand batch evaluations. Projection workers call /api/policy/eval/batch with ledger event payloads to receive status/severity/label/rationale updates before writing finding_records. Each delta updates finding_records, generates history entries, and triggers notification rules.
2. Prioritisation uses contextual heuristics: runtime exposure, VEX status, policy severity, AI hints. Stored as priorityScore with provenance from Zastava/AI modules.
3. Assignment & collaboration – Operators claim findings, add comments, attach evidence, and link tickets. Assignment uses Authority identities and RBAC.
4. Remediation tracking – Link remediation plans, record progress, and integrate with Scheduler for follow-up scans once fixes deploy.
5. Closure – When Policy or rescans mark finding resolved, system logs closure with explain trace and updates audit ledger.

State machine summary:

new -> (triage) triaged -> (remediate) in_progress -> (verify) awaiting_verification -> (scan) remediated
new -> (false_positive) closed_false_positive
new -> (risk_accept) accepted_risk

All transitions require justification; certain transitions (accepted risk) require multi-approver workflow defined by Policy Studio.

3) APIs

• GET /v1/findings — filtered listing with pagination, search (artifact, advisory, priority, status, assignee).
• GET /v1/findings/{id} — detail view (policy context, explain trace, evidence timeline).
• POST /v1/findings/{id}/actions — create triage action (assign, comment, status change, remediation, ticket link) with DSSE signature support.
• POST /v1/reports — generate report artifact (JSON, CSV, PDF) defined by saved templates; records manifest + signature.
• GET /v1/exports/offline — stream deterministic bundle for Offline Kit (findings JSON, history, attachments, manifest).

CLI mirrors these endpoints (stella findings list|view|update|export). Console UI consumes the same APIs via typed clients.

4) AI/automation integration

• Advisory AI contributes remediation hints and conflict explanations stored alongside findings (aiInsights).
• Scheduler integration triggers follow-up scans or policy re-evaluation when remediation plan reaches checkpoint.
• Zastava (Differential SBOM) feeds runtime exposure signals to reprioritise findings automatically.

5) Observability & compliance

• Metrics: findings_open_total{severity,tenant}, findings_mttr_seconds, triage_actions_total{type}, report_generation_seconds.
• Logs: structured with findingId, artifactId, advisory, policyVersion, actor, actionType.
• Audit exports: audit_log.jsonl appended whenever state changes; offline bundles include signed audit log and manifest.
• Compliance: accepted risk requires dual approval and stores justification plus expiry reminders (raised through Notify).

6) Identity & access integration

• Scopes – vuln:view, vuln:investigate, vuln:operate, vuln:audit map to read-only, triage, workflow, and audit experiences respectively. The deprecated vuln:read scope is still honoured for legacy tokens but is no longer advertised.
• Attribute filters (ABAC) – Authority enforces per-service-account filters via the client-credential parameters vuln_env, vuln_owner, and vuln_business_tier. Service accounts define the allowed values in authority.yaml (attributes block). Tokens include the resolved filters as claims (stellaops:vuln_env, stellaops:vuln_owner, stellaops:vuln_business_tier), and tokens persisted to Mongo retain the same values for audit and revocation.
• Audit trail – Every token issuance emits authority.vuln_attr.* audit properties that mirror the resolved filter set, along with delegation.service_account and ordered delegation.actor[n] entries so Vuln Explorer can correlate access decisions.
• Permalinks – Signed permalinks inherit the caller’s ABAC filters; consuming services must enforce the embedded claims in addition to scope checks when resolving permalinks.
• Attachment tokens – Authority mints short-lived tokens (POST /vuln/attachments/tokens/issue) to gate evidence downloads. Verification (POST /vuln/attachments/tokens/verify) enforces tenant, scope, and ABAC metadata, and emits vuln.attachment.token.* audit records.
• Ledger verification – Offline workflows validate attachments by comparing the Authority-issued token, the Vuln Explorer ledger hash, and the downloaded artefact hash before distribution.

7) Offline bundle requirements

• Bundle structure:
  • manifest.json (hashes, counts, policy version, generation timestamp).
  • findings.jsonl (current open findings).
  • history.jsonl (state changes).
  • actions.jsonl (comments, assignments, tickets).
  • reports/ (generated PDFs/CSVs).
  • signatures/ (DSSE envelopes).
• Bundles produced deterministically; Export Center consumes them for mirror profiles.