579236bfce
- 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.
60 lines
4.4 KiB
Markdown
60 lines
4.4 KiB
Markdown
# 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)_
|