5590a99a1a
- Created `StellaOps.TestKit.Tests` project for unit tests related to determinism. - Implemented `DeterminismManifestTests` to validate deterministic output for canonical bytes and strings, file read/write operations, and error handling for invalid schema versions. - Added `SbomDeterminismTests` to ensure identical inputs produce consistent SBOMs across SPDX 3.0.1 and CycloneDX 1.6/1.7 formats, including parallel execution tests. - Updated project references in `StellaOps.Integration.Determinism` to include the new determinism testing library.
104 lines
4.8 KiB
Markdown
Executable File
104 lines
4.8 KiB
Markdown
Executable File
# 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/install/docker.md`.
|
|
|
|
## Legacy Pages
|
|
|
|
Several older, topic-specific pages were consolidated into this guide and related canonical docs. The previous locations remain as short "archived" stubs for compatibility:
|
|
|
|
- `docs/ui/*.md`
|
|
- `docs/console/*.md`
|
|
- `docs/ux/*.md`
|
|
- `docs/vuln/*.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`
|