stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
579236bfce197db61f9f31bd9645665ba620726a
git.stella-ops.org/docs/vuln/explorer-overview.md
StellaOps Bot 579236bfce
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Details
Add MongoDB storage library and update acceptance tests with deterministic stubs 
- Created StellaOps.Notify.Storage.Mongo project with initial configuration.
- Added expected output files for acceptance tests (at1.txt to at10.txt).
- Added fixture input files for acceptance tests (at1 to at10).
- Created input and signature files for test cases fc1 to fc5.
2025-12-05 22:56:01 +02:00

4.4 KiB
Raw Blame History

Vuln Explorer Overview (Md.XI draft)

Status: DRAFT (awaiting GRAP0101 contract; finalize after domain model freeze).

Scope

  • Summarize Vuln Explorer domain model and identities involved in triage/remediation.
  • Capture AOC (attestations of control) guarantees supplied by Findings Ledger and Explorer API.
  • Provide a concise workflow walkthrough from ingestion to console/CLI/API use.
  • Reflect VEX-first triage posture (per module architecture) and offline/export requirements.

Inputs & Dependencies

Input Status Notes
GRAP0101 domain model contract pending Required for final entity/relationship names and invariants.
Console/CLI assets (screens, payloads, samples) requested Needed for workflow illustrations and hash manifests.
Findings Ledger schema + replay/Merkle notes available See docs/modules/findings-ledger/schema.md and docs/modules/findings-ledger/merkle-anchor-policy.md.

Domain Model (to be finalized)

  • Entities (from current architecture): finding_records (canonical enriched findings), finding_history (append-only state transitions), triage_actions (operator actions), remediation_plans, reports (saved templates/exports). Final names/fields subject to GRAP0101 freeze.
  • Relationships: findings link to advisories, VEX, SBOM component IDs, policyVersion, explain bundle refs; history and actions reference findingId with tenant + artifact scope; remediation plans and reports reference findings. (Clarify cardinality once GRAP0101 arrives.)
  • Key identifiers: tenant, artifactId, findingKey, policyVersion, sourceRunId; attachment/download tokens validated via Authority (see Identity section).

Identities & Roles

  • Operators: console users with scopes vuln:view, vuln:investigate, vuln:operate, vuln:audit; legacy vuln:read honored but deprecated. ABAC filters (vuln_env, vuln_owner, vuln_business_tier) enforced on tokens and permalinks.
  • Automation/agents: service accounts carrying the same scopes + ABAC filters; attachment tokens short-lived and validated against ledger hashes.
  • External inputs: advisories, SBOMs, reachability signals, VEX decisions; map to findings via advisoryRawIds, vexRawIds, sbomComponentId (see GRAP0101 for final field names).

AOC Guarantees

  • Ledger anchoring and replay: reference docs/modules/findings-ledger/merkle-anchor-policy.md and replay-harness.md for deterministic replays and Merkle roots.
  • Provenance chain: DSSE + in-toto/attestations (link to docs/modules/findings-ledger/dsse-policy-linkage.md); audit exports include signed manifests.
  • Data integrity: append-only history plus Authority-issued attachment tokens checked against ledger hashes; GRAP0101 will confirm checksum fields.

Workflow Summary (happy path)

  1. Ingest findings/advisories → normalize → enrich with policy/VEX/reachability/AI → persist to finding_records.
  2. Apply ABAC + scopes → store history/action entries → trigger notifications.
  3. Expose via API/Console/CLI with cached reachability/VEX context and policy explain bundles (VEX-first, reachability second, policy gates third per architecture).
  4. Export reports/offline bundles; verify with ledger hashes and DSSE attestations.

Triage States (architecture; finalize with GRAP0101)

  • new → triaged → in_progress → awaiting_verification → remediated
  • new → closed_false_positive
  • new → accepted_risk
  • Each transition requires justification; accepted risk requires multi-approver workflow (Policy Studio) and ABAC enforcement.

Offline / Export Expectations

  • Offline bundle structure: manifest.json, findings.jsonl, history.jsonl, actions.jsonl, reports/, signatures/ (DSSE envelopes); deterministic ordering and hashes.
  • Bundles are consumed by Export Center mirror profiles; include Merkle roots and hash manifests for verification.

Offline/Determinism Notes

  • Hash captures for screenshots/payloads recorded in docs/assets/vuln-explorer/SHA256SUMS (empty until assets arrive).
  • Use fixed fixture sets and ordered outputs when adding examples.

Open Items before publish

  • Replace all [[pending:…]] placeholders with GRAP0101 contract details.
  • Insert deterministic examples (console, API, CLI) once assets drop.
  • Add summary diagram if provided by Vuln Explorer Guild.
  • Mirror any architecture updates from docs/modules/vuln-explorer/architecture.md into this overview when GRAP0101 finalizes.

Last updated: 2025-12-05 (UTC)