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

docs consolidation work

Browse Source
This commit is contained in:
StellaOps Bot
2025-12-25 18:48:11 +02:00
parent 2a06f780cf
commit 82a49f6743
102 changed files with 3550 additions and 1679 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
docs/modules/vuln-explorer/README.md
View File

@@ -1,16 +1,16 @@
# StellaOps Vulnerability Explorer
Vulnerability Explorer delivers policy-aware triage, investigation, and reporting surfaces for effective findings.
## Latest updates (2025-11-30)
- Documentation refresh aligned to sprint 0334: added observability/runbook snapshot and cross-links to OpenAPI draft (`./api.md`) and schemas in `architecture.md`.
- New offline-friendly observability runbook at `runbooks/observability.md` plus stub Grafana JSON in `runbooks/dashboards/`.
- Retained 2025-11-03 access-control changes; verify Authority scopes before enabling attachment uploads (`docs/updates/2025-11-03-vuln-explorer-access-controls.md`).
## Responsibilities
- Present policy-evaluated findings with advisory, VEX, SBOM, and runtime context.
- Capture triage workflow in an immutable findings ledger with role-based access.
- Provide pivots, exports, and reports for auditors and operations teams.
Vulnerability Explorer delivers policy-aware triage, investigation, and reporting surfaces for effective findings.
## Latest updates (2025-11-30)
- Documentation refresh aligned to sprint 0334: added observability/runbook snapshot and cross-links to OpenAPI draft (`./api.md`) and schemas in `architecture.md`.
- New offline-friendly observability runbook at `runbooks/observability.md` plus stub Grafana JSON in `runbooks/dashboards/`.
- Retained 2025-11-03 access-control changes; verify Authority scopes before enabling attachment uploads (`docs/updates/2025-11-03-vuln-explorer-access-controls.md`).
## Responsibilities
- Present policy-evaluated findings with advisory, VEX, SBOM, and runtime context.
- Capture triage workflow in an immutable findings ledger with role-based access.
- Provide pivots, exports, and reports for auditors and operations teams.
- Integrate explain traces, remediation notes, and offline bundles.
## Key components
@@ -24,11 +24,71 @@ Vulnerability Explorer delivers policy-aware triage, investigation, and reportin
- Scheduler for remediation/verification jobs.
- Notify for triage notifications.
## Operational notes
- Audit logging per Epic 6 requirements.
- Offline-ready CSV/PDF exports with deterministic hashes.
- Dashboards for MTTR and triage throughput.
- Observability runbook and dashboard stub: see `runbooks/observability.md` and `runbooks/dashboards/vuln-explorer-observability.json` (import locally).
## Operational notes
- Audit logging per Epic 6 requirements.
- Offline-ready CSV/PDF exports with deterministic hashes.
- Dashboards for MTTR and triage throughput.
- Observability runbook and dashboard stub: see `runbooks/observability.md` and `runbooks/dashboards/vuln-explorer-observability.json` (import locally).
## Implementation Status
### Phase 1 – Findings Ledger & resolver (In Progress)
- Append-only ledger with Merkle root anchoring
- Projector to finding_records and finding_history tables
- Ecosystem resolvers: npm/Maven/PyPI/Go/RPM/DEB with canonical advisory keys
- Provenance hashing and time-travel snapshots
- Idempotent event processing
### Phase 2 – API & simulation (Planned)
- REST endpoints: /v1/findings (list/detail/grouping/simulation)
- Batch evaluation with Policy Engine rationales
- Export orchestrator for JSON/CSV/PDF
- Simulation endpoint returning diffs without state mutation
### Phase 3 – Console & CLI workflows (Planned)
- Triage UI: assignments, comments, remediation plans, simulation bar
- Detail tabs: policy, evidence, paths, remediation
- Keyboard accessibility, virtualization for large result sets
- CLI commands: stella vuln list/show/simulate/assign/accept-risk/verify-fix/export
### Phase 4 – Automation & integrations (Planned)
- Advisory AI hints integration
- Zastava runtime exposure correlation
- Notify rules for SLA breaches and deadlines
- Scheduler follow-up scans and Graph Explorer deep links
### Phase 5 – Exports & offline parity (Planned)
- Deterministic bundles: JSON, CSV, PDF formats
- Offline Kit manifests with signed reports
- Audit logs and compliance exports
- Evidence bundle viewer
### Phase 6 – Observability & hardening (Planned)
- Dashboards: projection lag, MTTR, accepted-risk cadence
- Alerts: projector backlog, API 5xx, export failures, expiring accepted-risk
- Performance tuning for 5M findings/tenant
- Security/RBAC validation and attachment encryption
### Key Acceptance Criteria
- Ledger/event sourcing reproduces historical states byte-for-byte with Merkle verification
- Resolver respects ecosystem semantics, scope, runtime context
- Triage workflows enforce justification/approval with audit records
- Simulation returns policy diffs without mutating state; CLI/UI parity achieved
- Exports reproducible with signed manifests and provenance
- RBAC/ABAC validated; attachments encrypted; tenant isolation guaranteed
### Technical Decisions & Risks
- 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
### Operational Assets (Sprint 0334 · 2025-11-30)
- Observability runbook: runbooks/observability.md
- Dashboard stub: runbooks/dashboards/vuln-explorer-observability.json
- OpenAPI draft: api.md and openapi/vuln-explorer.v1.yaml
- Access controls: docs/updates/2025-11-03-vuln-explorer-access-controls.md
## Epic alignment
- Epic 6: Vulnerability Explorer.