# 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)_