feat: add PolicyPackSelectorComponent with tests and integration
- Implemented PolicyPackSelectorComponent for selecting policy packs. - Added unit tests for component behavior, including API success and error handling. - Introduced monaco-workers type declarations for editor workers. - Created acceptance tests for guardrails with stubs for AT1–AT10. - Established SCA Failure Catalogue Fixtures for regression testing. - Developed plugin determinism harness with stubs for PL1–PL10. - Added scripts for evidence upload and verification processes.
This commit is contained in:
StellaOps Bot
50
docs/vuln/explorer-api.md
Normal file
50
docs/vuln/explorer-api.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# Vuln Explorer API (Md.XI draft)
|
||||
|
||||
> Status: DRAFT — depends on GRAP0101 contract and console/CLI payload samples. Publish only after schemas freeze and hashes recorded.
|
||||
|
||||
## Scope
|
||||
- Describe public Explorer API endpoints, query schema, grouping, errors, and rate limits.
|
||||
- Include deterministic examples with hashed request/response payloads.
|
||||
|
||||
## Prerequisites
|
||||
- GRAP0101 contract (final field names, query params).
|
||||
- Payload samples from console/CLI asset drop (due 2025-12-09).
|
||||
- Current architecture reference: `docs/modules/vuln-explorer/architecture.md`.
|
||||
|
||||
## Endpoints (to finalize)
|
||||
- `GET /v1/findings` — list with filters (tenant, advisory, status, reachability, VEX, priority, owner); pagination & sorting.
|
||||
- `GET /v1/findings/{id}` — detail (policy context, explain trace, attachments, history).
|
||||
- `POST /v1/findings/{id}/actions` — create action (assign, comment, status change, remediation, ticket link) with DSSE optional.
|
||||
- `POST /v1/reports` — create report; returns manifest + location.
|
||||
- `GET /v1/reports/{id}` — fetch report metadata/download.
|
||||
- `GET /v1/exports/offline` — download deterministic bundle (JSONL + manifests + signatures).
|
||||
- `POST /v1/vex-decisions` / `PATCH /v1/vex-decisions/{id}` / `GET /v1/vex-decisions` — decision lifecycle (aligns with `vex-decision.schema.json`).
|
||||
|
||||
## Query Schema (draft)
|
||||
- Filters: `tenant`, `advisoryId`, `vexStatus`, `reachability`, `priority`, `status`, `owner`, `artifactId`, `sbomComponentId`.
|
||||
- Pagination: `page`, `pageSize` (cap tbd per GRAP0101).
|
||||
- Sorting: `sort` (supports multi-field, stable order; default `priority desc, updatedAt desc`).
|
||||
- Projection: `fields` allowlist to shrink payloads; defaults tbd.
|
||||
- ETag/If-None-Match for cache-aware clients (confirm in GRAP0101).
|
||||
|
||||
## Errors & Rate Limits
|
||||
- Standard error envelope (status, code, message, correlationId); attach `hint` when policy gate blocks action.
|
||||
- Rate limits: per-tenant and per-service-account quotas; retry after header; offline bundles exempt.
|
||||
|
||||
## Determinism & Offline
|
||||
- All example payloads must be fixed fixtures; record hashes in `docs/assets/vuln-explorer/SHA256SUMS`.
|
||||
- Use canonical ordering for list responses; include sample `ETag` and manifest hash where relevant.
|
||||
|
||||
### Fixtures to Capture (when assets drop)
|
||||
- `assets/vuln-explorer/api-findings-list.json` (filtered list response)
|
||||
- `assets/vuln-explorer/api-finding-detail.json` (detail with history/actions)
|
||||
- `assets/vuln-explorer/api-action-post.json` (action request/response)
|
||||
- `assets/vuln-explorer/api-report-create.json` (report creation + manifest)
|
||||
- `assets/vuln-explorer/api-vex-decision.json` (create/list payloads)
|
||||
|
||||
## Open Items
|
||||
- Fill in finalized parameter names, limits, and error codes from GRAP0101.
|
||||
- Add example requests/responses once asset drop is delivered; include hashes.
|
||||
- Confirm DSSE optional flag shape for `actions` endpoint.
|
||||
|
||||
_Last updated: 2025-12-05 (UTC)_
|
||||
39
docs/vuln/explorer-cli.md
Normal file
39
docs/vuln/explorer-cli.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# Vuln Explorer CLI (Md.XI draft)
|
||||
|
||||
> Status: DRAFT — depends on explorer API/console assets and GRAP0101 schema. Do not publish until samples are hashed and prerequisites land.
|
||||
|
||||
## Scope
|
||||
- Command reference for Explorer-related CLI verbs (list/view/actions/reports/exports/VEX decisions).
|
||||
- Examples must be deterministic and offline-friendly (fixed fixtures, no live endpoints).
|
||||
|
||||
## Prerequisites
|
||||
- GRAP0101 contract for finalized field names and filters.
|
||||
- CLI sample payloads (requested with console assets; due 2025-12-09).
|
||||
- API schema from `docs/vuln/explorer-api.md` once finalized.
|
||||
|
||||
## Commands (outline)
|
||||
- `stella findings list` — filters, pagination, sorting, `--fields`, `--reachability`, `--vex-status`.
|
||||
- `stella findings view <id>` — includes history, actions, explain bundle refs.
|
||||
- `stella findings action <id> --assign/--comment/--status/--remediate/--ticket` — DSSE signing optional.
|
||||
- `stella findings report create` — outputs manifest path and DSSE envelope.
|
||||
- `stella findings export offline` — deterministic bundle with hashes (aligns with Offline Kit).
|
||||
- `stella vex decisions` — create/update/list VEX decisions.
|
||||
|
||||
## Determinism & Offline
|
||||
- Record all sample command outputs (stdout/stderr) with hashes in `docs/assets/vuln-explorer/SHA256SUMS`.
|
||||
- Use fixed fixture IDs, ordered output, and `--format json` where applicable.
|
||||
|
||||
### Fixtures to Capture (once CLI samples arrive)
|
||||
- `assets/vuln-explorer/cli-findings-list.json` (list with filters)
|
||||
- `assets/vuln-explorer/cli-findings-view.json` (detail view)
|
||||
- `assets/vuln-explorer/cli-action.json` (assign/comment/status change)
|
||||
- `assets/vuln-explorer/cli-report-create.json` (report creation output)
|
||||
- `assets/vuln-explorer/cli-export-offline.json` (bundle manifest snippet)
|
||||
- `assets/vuln-explorer/cli-vex-decision.json` (decision create/list)
|
||||
|
||||
## Open Items
|
||||
- Insert real examples and exit codes once assets arrive.
|
||||
- Confirm DSSE flag names and default signing key selection.
|
||||
- Add CI snippets for GitLab/GitHub once policy overlays provided.
|
||||
|
||||
_Last updated: 2025-12-05 (UTC)_
|
||||
49
docs/vuln/explorer-overview.md
Normal file
49
docs/vuln/explorer-overview.md
Normal file
@@ -0,0 +1,49 @@
|
||||
# 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.
|
||||
|
||||
## 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)_
|
||||
37
docs/vuln/explorer-using-console.md
Normal file
37
docs/vuln/explorer-using-console.md
Normal file
@@ -0,0 +1,37 @@
|
||||
# Vuln Explorer — Using the Console (Md.XI draft)
|
||||
|
||||
> Status: DRAFT (awaiting GRAP0101 domain model + console asset drop). Do not publish until hashes captured.
|
||||
|
||||
## Scope
|
||||
- Walk through primary console workflows: search/filter, saved views, keyboard shortcuts, drill-down, evidence export.
|
||||
- Highlight identity/ABAC enforcement and tenant scoping in UI.
|
||||
- Keep all examples deterministic; attach payload/screenshot hashes to `docs/assets/vuln-explorer/SHA256SUMS`.
|
||||
|
||||
## Prerequisites
|
||||
- Domain model from GRAP0101 (entities, identifiers) — needed for labels and field names.
|
||||
- UI/CLI asset drop (screenshots, payload samples) — requested, due 2025-12-09.
|
||||
- Ledger/observability context from `docs/modules/vuln-explorer/architecture.md` and Findings Ledger docs.
|
||||
|
||||
## Workflows (to be filled with assets)
|
||||
1) Discover & filter findings (search, severity, reachability/VEX toggles).
|
||||
2) Keyboard shortcuts for navigation (list, detail, actions) — pending asset table.
|
||||
3) Saved views & deep links (shareable, ABAC-aware permalinks) — include hash-verified examples.
|
||||
4) Drill-down: finding detail → history → actions → attachments (token validation flow).
|
||||
5) Export: reports and offline bundles; note hash verification step.
|
||||
|
||||
## Determinism & Offline Notes
|
||||
- All screenshots/payloads must be hashed; record in `docs/assets/vuln-explorer/SHA256SUMS`.
|
||||
- Use fixed fixture IDs and ordered outputs; avoid live endpoints.
|
||||
|
||||
### Hash Capture Checklist (fill once assets arrive)
|
||||
- `assets/vuln-explorer/console-list.png` (list view with filters applied)
|
||||
- `assets/vuln-explorer/console-detail.png` (finding detail + history/actions panes)
|
||||
- `assets/vuln-explorer/console-shortcuts.md` (shortcut matrix payload)
|
||||
- `assets/vuln-explorer/console-saved-view.json` (saved view export)
|
||||
|
||||
## Open Items before publish
|
||||
- Replace placeholders with GRAP0101-backed field names and identity labels.
|
||||
- Insert screenshot tables and payload snippets once assets arrive.
|
||||
- Add keyboard shortcut matrix and deep-link examples with hashes.
|
||||
|
||||
_Last updated: 2025-12-05 (UTC)_
|
||||
49
docs/vuln/findings-ledger.md
Normal file
49
docs/vuln/findings-ledger.md
Normal file
@@ -0,0 +1,49 @@
|
||||
# Findings Ledger (Vuln Explorer) — Event Model & Replay (Md.XI draft)
|
||||
|
||||
> Status: DRAFT — depends on GRAP0101 alignment and security review. Do not publish until hashes and schema cross-checks are complete.
|
||||
|
||||
## Scope
|
||||
- Explain event schema, hashing strategy, Merkle roots, and replay tooling as consumed by Vuln Explorer.
|
||||
- Align with canonical ledger docs: `docs/modules/findings-ledger/schema.md`, `merkle-anchor-policy.md`, `replay-harness.md`.
|
||||
- Provide deterministic examples and hash manifests (record in `docs/assets/vuln-explorer/SHA256SUMS`).
|
||||
|
||||
## Dependencies
|
||||
| Input | Status | Notes |
|
||||
| --- | --- | --- |
|
||||
| GRAP0101 contract | pending | Confirm field names/identifiers to keep Explorer/ledger in sync. |
|
||||
| Security review (hashing/attachments) | pending | Required before publication. |
|
||||
| Replay fixtures | available | See `docs/modules/findings-ledger/replay-harness.md` and `golden-checksums.json`. |
|
||||
|
||||
## Event Schema (summary)
|
||||
- `finding_records` (canonical): includes advisory/VEX/SBOM refs, `policyVersion`, `sourceRunId`, `explainBundleRef`, tenant, artifact identifiers.
|
||||
- `finding_history`: append-only transitions with actor, scope, justification, timestamps (UTC, ISO-8601), hash-chained.
|
||||
- `triage_actions`: discrete operator actions (comment, assign, remediation, ticket link) with immutable provenance.
|
||||
- `remediation_plans`: planned fixes linked to findings; optional due dates and checkpoints.
|
||||
|
||||
> See `docs/modules/findings-ledger/schema.md` for authoritative field names; update this section when GRAP0101 finalizes.
|
||||
|
||||
## Hashing & Merkle Roots
|
||||
- Per-event SHA-256 digests; history and actions chained by previous hash to ensure tamper evidence.
|
||||
- Periodic Merkle roots anchored per tenant + artifact namespace; policy version included in leaf payloads.
|
||||
- Export bundles carry `manifest.json` + `audit_log.jsonl` with hashes; verify against Merkle roots.
|
||||
|
||||
## Replay & Verification
|
||||
- Replay harness (`replay-harness.md`) replays `finding_history` + `triage_actions` to reconstruct `finding_records` and compare hashes.
|
||||
- Use `golden-checksums.json` to validate deterministic output; include hash of replay output in `SHA256SUMS` once fixtures copied here.
|
||||
|
||||
## Offline/Determinism Notes
|
||||
- All sample logs/responses added to this doc must have hashes recorded in `docs/assets/vuln-explorer/SHA256SUMS`.
|
||||
- Use fixed fixture IDs; avoid live timestamps; maintain sorted outputs.
|
||||
|
||||
### Hash Capture Checklist (when fixtures are pulled)
|
||||
- `assets/vuln-explorer/ledger-history.jsonl` (sample history entries)
|
||||
- `assets/vuln-explorer/ledger-actions.jsonl` (triage actions snippet)
|
||||
- `assets/vuln-explorer/ledger-replay-output.json` (replay harness output)
|
||||
- `assets/vuln-explorer/ledger-manifest.json` (export manifest sample)
|
||||
|
||||
## Open Items
|
||||
- Replace schema placeholders once GRAP0101 and security review land.
|
||||
- Add sample history/action entries and replay verification commands with hashes.
|
||||
- Document attachment token validation path when security review provides final wording.
|
||||
|
||||
_Last updated: 2025-12-05 (UTC)_
|
||||
Reference in New Issue
Block a user