197 lines
10 KiB
Markdown
197 lines
10 KiB
Markdown
# 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`](../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.
|
||
|
||
## 8) VEX-First Triage UX
|
||
|
||
> Reference: Product advisory `28-Nov-2025 - Vulnerability Triage UX & VEX-First Decisioning.md`
|
||
|
||
### 8.1 Evidence-First Finding Cards
|
||
|
||
Each vulnerability finding is displayed as an evidence-first card showing:
|
||
- CVE/vulnerability identifier with severity badge
|
||
- Package name, version, ecosystem
|
||
- Location (file path, container layer, function, call path)
|
||
- Scanner and database date
|
||
- Status badges: `New`, `VEX: Not affected`, `Policy: blocked`
|
||
|
||
Primary actions per card:
|
||
- **VEX: Set status** - Opens VEX decision modal
|
||
- **Fix PR / View Fix** - When available from connected scanners (Snyk/GitLab)
|
||
- **Attach Evidence** - Link PRs, tickets, docs, commits
|
||
- **Copy audit reference** - findingId + attestation digest
|
||
|
||
### 8.2 VEX Decision Model
|
||
|
||
VEX decisions follow the `VexDecision` schema (`docs/schemas/vex-decision.schema.json`):
|
||
|
||
**Status values:**
|
||
- `NOT_AFFECTED` - Vulnerability does not apply to this artifact
|
||
- `AFFECTED_MITIGATED` - Vulnerable but mitigations in place
|
||
- `AFFECTED_UNMITIGATED` - Vulnerable without mitigations
|
||
- `FIXED` - Vulnerability has been remediated
|
||
|
||
**Justification types (CSAF/VEX aligned):**
|
||
- `CODE_NOT_PRESENT`
|
||
- `CODE_NOT_REACHABLE`
|
||
- `VULNERABLE_CODE_NOT_IN_EXECUTE_PATH`
|
||
- `CONFIGURATION_NOT_AFFECTED`
|
||
- `OS_NOT_AFFECTED`
|
||
- `RUNTIME_MITIGATION_PRESENT`
|
||
- `COMPENSATING_CONTROLS`
|
||
- `ACCEPTED_BUSINESS_RISK`
|
||
- `OTHER`
|
||
|
||
**Scope and validity:**
|
||
- Decisions can be scoped to specific environments and projects
|
||
- Validity windows with `notBefore` and `notAfter` timestamps
|
||
- Expired decisions are surfaced with warnings
|
||
|
||
### 8.3 Explainability Panel
|
||
|
||
Right-side panel with tabs for each finding:
|
||
|
||
**Overview tab:**
|
||
- Title, severity, package/version
|
||
- Scanner + DB date
|
||
- Finding history timeline
|
||
- Current VEX decision summary
|
||
|
||
**Reachability tab:**
|
||
- Call path visualization
|
||
- Module dependency list
|
||
- Runtime usage indicators (when available)
|
||
|
||
**Policy tab:**
|
||
- Policy evaluation result (PASS/WARN/FAIL)
|
||
- Gate details with "this gate failed because..." explanations
|
||
- Links to gate definitions
|
||
|
||
**Attestations tab:**
|
||
- Attestations mentioning this artifact/vulnerability/scan
|
||
- Type, subject, predicate, signer, verified status
|
||
- "Signed evidence" pill linking to attestation detail
|
||
|
||
### 8.4 VEX Decision APIs
|
||
|
||
New endpoints for VEX decisions:
|
||
|
||
- `POST /v1/vex-decisions` - Create new VEX decision with optional attestation
|
||
- `PATCH /v1/vex-decisions/{id}` - Update existing decision (creates superseding record)
|
||
- `GET /v1/vex-decisions` - List decisions with filters
|
||
- `GET /v1/vex-decisions/{id}` - Get decision detail
|
||
|
||
Request/response follows `VexDecisionDto` per schema.
|
||
|
||
### 8.5 Audit Bundle Export
|
||
|
||
Immutable audit bundles follow the `AuditBundleIndex` schema (`docs/schemas/audit-bundle-index.schema.json`):
|
||
|
||
**Bundle contents:**
|
||
- Vulnerability reports (scanner outputs)
|
||
- SBOM (CycloneDX/SPDX)
|
||
- VEX decisions
|
||
- Policy evaluations
|
||
- Raw attestations (DSSE envelopes)
|
||
- `audit-bundle-index.json` manifest with integrity hashes
|
||
|
||
**APIs:**
|
||
- `POST /v1/audit-bundles` - Create new bundle (async generation)
|
||
- `GET /v1/audit-bundles/{bundleId}` - Download bundle (ZIP or OCI)
|
||
- `GET /v1/audit-bundles` - List previously created bundles
|
||
|
||
### 8.6 Industry Pattern Alignment
|
||
|
||
The triage UX aligns with industry patterns from:
|
||
|
||
| Tool | Pattern Adopted |
|
||
|------|-----------------|
|
||
| **Snyk** | PR checks, Fix PRs, ignore with reasons |
|
||
| **GitLab SCA** | Vulnerability Report, status workflow, activity log |
|
||
| **Harbor/Trivy** | Artifact-centric navigation, attestation accessories |
|
||
| **Anchore** | Policy gates with trigger explanations, allowlists |
|
||
|
||
## 9) Schemas
|
||
|
||
The following JSON schemas define the data contracts for VEX and audit functionality:
|
||
|
||
- `docs/schemas/vex-decision.schema.json` - VEX decision form and persistence
|
||
- `docs/schemas/attestation-vuln-scan.schema.json` - Vulnerability scan attestation predicate
|
||
- `docs/schemas/audit-bundle-index.schema.json` - Audit bundle manifest
|
||
|
||
These schemas are referenced by both backend DTOs and frontend TypeScript interfaces.
|