docs re-org, audit fixes, build fixes
This commit is contained in:
StellaOps Bot
107
docs/UI_GUIDE.md
Executable file
107
docs/UI_GUIDE.md
Executable file
@@ -0,0 +1,107 @@
|
||||
# Console (Web UI) Guide
|
||||
|
||||
The StellaOps Console is the operator-facing web UI. It is built for fast triage and auditability: decisions link back to concrete evidence, and workflows continue to work in air-gapped deployments via Offline Kit snapshots.
|
||||
|
||||
This is a usage guide (what the Console does and how to operate it). For UI implementation architecture, see `docs/modules/ui/architecture.md`.
|
||||
|
||||
## Scope
|
||||
|
||||
- Console workspaces and what each is for
|
||||
- Common operator workflows (triage, evidence review, exports)
|
||||
- Offline/air-gap posture and what to expect in the UI
|
||||
- Links to deeper module documentation
|
||||
|
||||
Out of scope: API shapes, schema details, and UI component implementation.
|
||||
|
||||
## Core Concepts
|
||||
|
||||
- **Tenant context:** most views are tenant-scoped; switching tenants changes what evidence you see and what actions you can take.
|
||||
- **Evidence-linked decisions:** verdicts (ship/block/needs-exception) should link to the SBOM facts, advisory/VEX observations, reachability proofs, and policy explanations that justify them.
|
||||
- **Effective VEX:** the platform computes an effective status using issuer trust and policy rules, without rewriting upstream VEX (see `docs/16_VEX_CONSENSUS_GUIDE.md`).
|
||||
- **Snapshots and staleness:** offline sites operate on snapshots; the Console should surface snapshot identity and freshness rather than hide it.
|
||||
|
||||
## Workspaces (Navigation)
|
||||
|
||||
The Console is organized into workspaces. Names vary slightly by build, but the intent is stable:
|
||||
|
||||
- **Dashboard:** fleet status, feed/VEX age, queue depth, and policy posture.
|
||||
- **Scans / SBOM:** scan history and scan detail; SBOM viewing and export.
|
||||
- **Findings / Triage:** the vulnerability triage surface (case view + evidence rail).
|
||||
- **Advisories & VEX:** provider status, conflicts, provenance, and issuer trust.
|
||||
- **Policies:** policy packs, previews, promotion workflow, and waiver/exception flows.
|
||||
- **Runs / Scheduler:** background jobs, re-evaluation, and reachability/delta work.
|
||||
- **Downloads / Offline:** Offline Kit and signed artifact distribution and mirroring.
|
||||
- **Admin:** tenants, roles/scopes, clients, quotas, and operational settings.
|
||||
|
||||
## Common Operator Workflows
|
||||
|
||||
### Triage a Finding
|
||||
|
||||
1. Open **Findings** and filter to the tenant/environment you care about.
|
||||
2. Open a finding to review:
|
||||
- Verdict + "why" summary
|
||||
- Effective VEX status and issuer provenance
|
||||
- Reachability/impact signals (when available)
|
||||
- Policy explanation trace and the gate that produced the verdict
|
||||
3. Record a triage action (assign/comment/ack/mute/exception request) with justification.
|
||||
4. Export an evidence bundle when review, escalation, or offline verification is required.
|
||||
|
||||
See `docs/20_VULNERABILITY_EXPLORER_GUIDE.md` for the conceptual model and determinism requirements.
|
||||
|
||||
### Review VEX Conflicts and Issuer Trust
|
||||
|
||||
- Use **Advisories & VEX** to see which providers contributed statements, whether signatures verified, and where conflicts exist.
|
||||
- The Console should not silently hide conflicts; it should show what disagrees and why, and how policy resolved it.
|
||||
|
||||
See `docs/16_VEX_CONSENSUS_GUIDE.md` for the underlying concepts.
|
||||
|
||||
### Export and Verify Evidence Bundles
|
||||
|
||||
- Exports are intended to be portable and verifiable (audits, incident response, air-gap review).
|
||||
- Expect deterministic ordering, UTC timestamps, and hash manifests.
|
||||
|
||||
See `docs/24_OFFLINE_KIT.md` for packaging and offline verification workflows.
|
||||
|
||||
## Offline / Air-Gap Expectations
|
||||
|
||||
- The Console must operate against Offline Kit snapshots (no external lookups required).
|
||||
- The UI should surface snapshot identity and staleness budgets (feeds, VEX, policy versions).
|
||||
- Upload/import workflows for Offline Kit bundles should be auditable (who imported what, when).
|
||||
|
||||
## Security and Access
|
||||
|
||||
- Authentication is typically OIDC/OAuth2 via Authority; scopes/roles govern write actions.
|
||||
- Treat tokens as sensitive; avoid copying secrets into notes/tickets.
|
||||
- For CSP, scopes, and DPoP posture, see `docs/security/console-security.md`.
|
||||
|
||||
## Observability and Accessibility
|
||||
|
||||
- UI telemetry and metrics guidance: `docs/observability/ui-telemetry.md`.
|
||||
- Accessibility baseline and keyboard model: `docs/accessibility.md`.
|
||||
|
||||
## Deploy and Install References
|
||||
|
||||
- Deployment configuration and health checks: `docs/deploy/console.md`.
|
||||
- Container install recipes: `docs/operations/console-docker-install.md`.
|
||||
|
||||
## Detailed References
|
||||
|
||||
Operator-facing deep dives (Console):
|
||||
|
||||
- `docs/console/airgap.md`
|
||||
- `docs/console/admin-tenants.md`
|
||||
- `docs/console/forensics.md`
|
||||
- `docs/console/observability.md`
|
||||
|
||||
UX and interaction contracts:
|
||||
|
||||
- `docs/ux/TRIAGE_UX_GUIDE.md`
|
||||
|
||||
## Related Docs
|
||||
|
||||
- `docs/16_VEX_CONSENSUS_GUIDE.md`
|
||||
- `docs/20_VULNERABILITY_EXPLORER_GUIDE.md`
|
||||
- `docs/24_OFFLINE_KIT.md`
|
||||
- `docs/cli-vs-ui-parity.md`
|
||||
- `docs/architecture/console-admin-rbac.md`
|
||||
- `docs/architecture/console-branding.md`
|
||||
Reference in New Issue
Block a user