git.stella-ops.org/docs/UI_GUIDE.md

# 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/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/VULNERABILITY_EXPLORER_GUIDE.md` for the conceptual model and determinism requirements.

### AI Remediation and Pull Requests

> **Sprint:** SPRINT_20260112_012_FE_remediation_pr_ui_wiring

The AI Remediate panel provides automated remediation guidance and can create pull requests to fix vulnerabilities.

**Opening the AI Remediate Panel:**

1. From a finding detail view, click **AI Remediate**.
2. The panel generates remediation recommendations (upgrade, patch, mitigate, workaround).
3. Review recommendations sorted by priority and effort level.

**Creating a Remediation PR:**

When SCM connections are configured:

1. Select an SCM connection from the dropdown.
2. Click **Open PR** to create a pull request with the recommended fix.
3. Monitor progress with the loading indicator.
4. On success, view the PR link, branch name, and CI status.

**PR Status Display:**

| Status | Badge | Description |
|--------|-------|-------------|
| Draft | Gray | PR created as draft |
| Open | Green | PR open for review |
| Review Requested | Green | Review explicitly requested |
| Approved | Blue | PR approved |
| Changes Requested | Yellow | Changes requested by reviewer |
| Merged | Purple | PR merged |
| Closed | Red | PR closed without merge |

**CI Status Indicators:**

| Status | Color | Description |
|--------|-------|-------------|
| Pending | Yellow | CI checks queued |
| Running | Yellow | CI checks in progress |
| Success | Green | All CI checks passed |
| Failure | Red | One or more CI checks failed |
| Skipped | Gray | CI checks skipped |

**When SCM Not Configured:**

If no SCM connections are available, the panel shows a link to the Integrations Hub to configure GitHub, GitLab, or other SCM providers.

**Error Handling:**

| Error | Description | Action |
|-------|-------------|--------|
| No SCM connection | No provider configured | Configure in Integrations Hub |
| SCM auth failed | Authentication expired | Re-authenticate provider |
| Repository not found | Repo no longer accessible | Verify repository access |
| Branch conflict | Branch already exists | Use existing PR or delete branch |
| Rate limited | API rate limit exceeded | Wait and retry |
| PR already exists | Duplicate PR | View existing PR |

**Remediation PR Settings:**

> **Sprint:** SPRINT_20260112_012_FE_remediation_pr_ui_wiring (REMPR-FE-004)

Configure remediation PR behavior in **Settings > AI > Remediation Pull Requests**:

| Setting | Default | Description |
|---------|---------|-------------|
| Enable Remediation PRs | On | Allow creating pull requests from AI suggestions |
| Attach Evidence Card | On | Include evidence card reference in PR description |
| Add AI Summary Comment | On | Post AI-generated summary comment on the PR |
| Auto-assign Reviewers | Off | Automatically assign default reviewers |
| Apply Default Labels | On | Add configured labels to created PRs |

**Organization-Level Settings:**

Some settings are controlled at the organization level:

- **Enabled:** If disabled at org level, all PR creation is blocked
- **Require Approval:** When enabled, PRs require approval before merge
- **Default Labels:** Labels added automatically to all remediation PRs
- **Default Reviewers:** Reviewers assigned automatically when enabled

**Storage Key:** `stellaops.remediation-pr.preferences`

### 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/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/OFFLINE_KIT.md` for packaging and offline verification workflows.

### Export Evidence Cards (v1.1)

Evidence Cards are single-file exports containing SBOM excerpt, DSSE envelope, and optional Rekor receipt for offline verification.

**To export an Evidence Card:**

1. Open an evidence pack from **Findings** or **Runs** workspace.
2. Click the **Export** dropdown in the pack viewer header.
3. Select **Evidence Card** for full export or **Evidence Card (Compact)** for a smaller file without full SBOM.
4. The browser downloads a `.evidence-card.json` file.

**Evidence Card contents:**

- `cardId`: Unique card identifier
- `version`: Schema version (e.g., "1.0.0")
- `packId`: Source evidence pack ID
- `subject`: Finding/CVE/component metadata
- `envelope`: DSSE signature envelope (when signed)
- `sbomExcerpt`: Relevant SBOM component data (full export only)
- `rekorReceipt`: Sigstore Rekor transparency log receipt (when available)
- `contentDigest`: SHA-256 digest for verification

**Content types:**

- Full: `application/vnd.stellaops.evidence-card+json`
- Compact: `application/vnd.stellaops.evidence-card-compact+json`

See `docs/api/evidence-decision-api.openapi.yaml` for the complete schema.

### Grey Queue and Unknowns Triage

> **Sprint:** SPRINT_20260112_009_FE_unknowns_queue_ui

The Grey Queue surfaces observations with uncertain status requiring operator attention or additional evidence. This is distinct from the standard triage queue.

**Grey Queue Panel Features:**

- **Band indicator:** Shows priority band (HOT, WARM, COLD, GREY) with color coding
- **Observation state badge:** Displays current state (PendingDeterminization, Disputed, GuardedPass)
- **Fingerprint section:** Shows deterministic reanalysis fingerprint for reproducibility
- **Triggers list:** Sorted by `receivedAt` (descending), shows what events caused reanalysis
- **Conflicts section:** Highlights conflicting evidence with severity coloring
- **Next actions:** Badges showing suggested resolution paths (await_vex, run_reachability, manual_review)
- **Triage actions:** Buttons for resolve, escalate, and defer actions

**Observation States:**

| State | Badge Color | Description |
|-------|-------------|-------------|
| `PendingDeterminization` | Yellow | Evidence incomplete; monitoring active |
| `Disputed` | Orange | Conflicting evidence; manual adjudication required |
| `GuardedPass` | Blue | Allowed with runtime guardrails |
| `Resolved` | Green | Operator has made a determination |

**Accessing the Grey Queue:**

1. Navigate to **Findings > Grey Queue** tab.
2. Filter by observation state, priority band, or trigger type.
3. Click an item to open the Grey Queue Panel with full details.
4. Review conflicts and suggested next actions.
5. Take a triage action (resolve, escalate, or defer) with justification.

**Conflict Display:**

Conflicts show the source disagreements:
- **Status mismatch:** Different providers report conflicting vulnerability status
- **VEX/reachability contradiction:** VEX says not_affected but reachability proves otherwise
- **Trust tie:** Equal trust scores with opposite conclusions

See `docs/VEX_CONSENSUS_GUIDE.md` for conflict detection semantics.

### Risk Line Display

> **Sprint:** SPRINT_20260112_004_FE_risk_line_runtime_trace_ui

The Risk Line is an always-visible summary bar in finding detail views showing reachability evidence at a glance.

**Risk Line Sections:**

| Section | Display | Description |
|---------|---------|-------------|
| **Reachability** | Score (0-100%) with progress bar | Likelihood that vulnerable code is reachable from application entry points |
| **Runtime** | Badge (Confirmed/Not Observed/Unknown/Pending) | Whether runtime monitoring has observed the vulnerable code path executing |
| **Evidence** | Rekor link with log index | Transparency log entry for verifiable evidence timestamp |
| **Method** | Badge (Hybrid/Runtime/Static/None) | Analysis method used to determine reachability |

**Reachability Score Levels:**

| Level | Score Range | Color | Meaning |
|-------|-------------|-------|---------|
| High | >= 70% | Red | Strong evidence of reachability; prioritize remediation |
| Medium | 30-69% | Amber | Moderate evidence; may warrant investigation |
| Low | < 30% | Green | Low likelihood of reachability |
| Unknown | -- | Gray | No reachability analysis available |

**Runtime Status Badges:**

| Status | Icon | Color | Description |
|--------|------|-------|-------------|
| Confirmed | [+] | Green | Runtime traces observed execution through vulnerable path |
| Not Observed | [-] | Yellow | Monitoring active but path not observed in window |
| Pending | [?] | Blue | Analysis in progress |
| Unknown | [--] | Gray | No runtime monitoring data available |

**Evidence Link:**

When evidence is anchored to a Rekor transparency log:
- Click the **Log #NNNNNN** link to view the entry in Rekor
- A **[OK]** badge indicates the log entry has been verified
- The timestamp shows when evidence was recorded

**Graceful Fallbacks:**

- If reachability data is unavailable, the score displays "--" with "(no data)" hint
- If runtime status is unknown, the UI clearly shows "Unknown" rather than implying "Not Observed"
- Missing Rekor entries display "No Rekor entry" message

### Trace Export

> **Sprint:** SPRINT_20260112_004_FE_risk_line_runtime_trace_ui

Export reachability call graphs for offline analysis or integration with other tools.

**Export Formats:**

| Format | Extension | Use Case |
|--------|-----------|----------|
| GraphSON | `.graphson.json` | Graph databases (TinkerPop, JanusGraph) |
| JSON | `.trace.json` | General purpose, human-readable |
| SARIF | `.sarif` | IDE integration, GitHub Code Scanning |

**To Export a Trace:**

1. Open a finding with reachability evidence.
2. In the reachability panel, click **Export**.
3. Select the desired format.
4. The file downloads with a deterministic filename: `{artifactDigest}_{findingId}.{format}`

**Export Contents:**

- **Nodes:** Functions/methods in the call path with file:line locations
- **Edges:** Call relationships with type (direct/indirect/virtual/async)
- **Runtime confirmation:** Which edges were observed in runtime traces
- **Metadata:** Analysis timestamp, analyzer version, confidence scores

**Determinism Guarantee:**

Exports use deterministic ordering:
- Nodes sorted by canonical ID
- Edges sorted by (from, to) tuple
- Timestamps in ISO-8601 UTC format

### AI Code Guard Badge

> **Sprint:** SPRINT_20260112_010_FE_ai_code_guard_console

The AI Code Guard Badge displays scan results for AI-generated code in scan and PR views.

**Badge States:**

| State | Icon | Color | Description |
|-------|------|-------|-------------|
| Pass | Check | Green | No findings or all findings are low severity |
| Review | Warning | Amber | Warnings requiring human review |
| Block | X | Red | Critical or high severity findings blocking release |
| Error | Dash | Gray | Scan encountered an error |
| Pending | Search | Blue | Scan in progress |

**Count Badge:**

When findings exist, a count badge shows the total with severity-based coloring:
- Critical count > 0: Red background
- High count > 0: Red background (lighter)
- Medium count > 0: Amber background
- Low count > 0: Gray background

**Accessibility:**

The badge includes proper ARIA attributes:
- `role="status"` for screen reader announcements
- `aria-label` with verdict and count (e.g., "AI Code Guard: Block, 3 findings")

**Usage:**

The badge appears in:
- Scan summary views
- PR/MR check status
- Finding detail headers
- Policy gate results

### Binary Diff Explain Panel

> **Sprint:** SPRINT_20260112_010_FE_binary_diff_explain_panel

The Binary Diff Explain Panel shows binary artifact comparison evidence in the evidence panel tabs.

**Panel Sections:**

| Section | Description |
|---------|-------------|
| Summary | Hash comparison, size delta, modification stats, confidence score |
| Sections | Binary sections with offset, size, type, and modification status |
| Symbol Changes | Added/removed/modified symbols with addresses and size changes |
| Footer | Analysis timestamp and export button |

**Section Status:**

| Status | Border Color | Description |
|--------|--------------|-------------|
| Identical | None | Section unchanged between versions |
| Modified | Amber | Section contents differ |
| Added | Green | Section exists only in head |
| Removed | Red | Section exists only in base |

**Segment Types:**

| Type | Badge Color | Description |
|------|-------------|-------------|
| code | Blue | Executable code section (.text) |
| data | Purple | Writable data section (.data) |
| rodata | Amber | Read-only data section (.rodata) |
| header | Gray | File headers |
| symbol | Green | Symbol tables |

**Symbol Change Types:**

| Type | Description |
|------|-------------|
| function | Function/method symbol |
| variable | Data variable symbol |
| import | Imported symbol from external library |
| export | Exported public symbol |

**Confidence Levels:**

| Level | Score Range | Badge |
|-------|-------------|-------|
| High | >= 90% | Green "High (95%)" |
| Medium | 70-89% | Amber "Medium (78%)" |
| Low | < 70% | Red "Low (45%)" |

**Export:**

Click **Export** to download the full binary diff analysis as JSON for offline review or integration with other tools.

**Show More:**

When sections or symbols exceed 5 items, a "Show More" button expands the full list. Click "Show Less" to collapse.

### Runtime-Confirmed Call Graph

The reachability call graph highlights runtime-confirmed paths:

**Legend:**

| Key | Icon | Color | Description |
|-----|------|-------|-------------|
| Runtime Confirmed | [+] | Green | Edge observed in runtime execution traces |
| Static Analysis | [~] | Indigo | Edge inferred from static code analysis |
| Unknown | [?] | Gray | Edge status not determined |
| Entry Point | [>] | Blue | Application entry point or public API |
| Vulnerable | [!] | Red | Location of vulnerable code |

**User Settings:**

Runtime overlays and trace export can be toggled in **Settings > Display Preferences**:

- **Show Runtime Overlays:** Highlight runtime-confirmed edges (default: on)
- **Enable Trace Export:** Show export actions in reachability panel (default: on)

### Display Preferences

> **Sprint:** SPRINT_20260112_004_FE_risk_line_runtime_trace_ui (FE-RISK-006)

The Display Preferences panel allows users to customize triage and finding views. Settings are persisted to browser localStorage and apply immediately.

**Access:** Navigate to **Settings > Display > Triage Display Preferences**

**Available Settings:**

| Setting | Default | Description |
|---------|---------|-------------|
| Show Runtime Overlays | On | Highlight runtime-confirmed edges in call graphs |
| Enable Trace Export | On | Show GraphSON/JSON/SARIF export buttons in reachability panel |
| Show Risk Line | On | Display the risk line summary bar in finding detail views |
| Show Signed Override Indicators | On | Display DSSE badge and Rekor link for signed VEX overrides |
| Expand Runtime Evidence | Off | Expand runtime evidence section by default |

**Graph Settings:**

| Setting | Default | Range | Description |
|---------|---------|-------|-------------|
| Max Graph Nodes | 50 | 10-200 | Maximum nodes to render in call graph visualizations |
| Runtime Highlight Style | Both | Bold/Color/Both | How runtime-confirmed edges are highlighted |

**Storage Key:** `stellaops.display.preferences`

**Reset:** Click **Reset to Defaults** to restore all settings to their default values.

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

## Setup Wizard

The Setup Wizard provides a guided interface for initial platform configuration and reconfiguration. It communicates with the Platform backend via `/api/v1/setup/*` endpoints.

### Wizard Features

- **Session-based workflow:** Sessions track progress across steps, enabling resume after interruption.
- **Step validation:** Each step includes Doctor checks that validate configuration before proceeding.
- **Dry-run mode:** Preview configuration changes before applying them.
- **Error handling:** Problem+JSON errors are mapped to user-friendly messages with suggested fixes.
- **Data freshness:** Stale data banners show when cached information may be outdated.
- **Retry support:** Failed operations can be retried with backoff and attempt tracking.

### Wizard Steps

The wizard guides operators through these configuration areas:

| Step | Category | Required | Description |
|------|----------|----------|-------------|
| Database | Infrastructure | Yes | PostgreSQL connection and migrations |
| Cache | Infrastructure | Yes | Valkey/Redis connection |
| Vault | Security | No | HashiCorp Vault, Azure Key Vault, or AWS Secrets Manager |
| Settings Store | Configuration | No | Consul, etcd, or PostgreSQL-backed configuration |
| Registry | Integration | No | Container registry connections |
| Telemetry | Observability | No | OTLP endpoint configuration |

### Using the Wizard

1. Access the Setup Wizard from **Admin > Configuration Wizard** or during first-run.
2. Complete required steps (Database, Cache) before optional integrations.
3. Use **Test Connection** to validate credentials before applying.
4. Review validation checks (Doctor diagnostics) for each step.
5. Use dry-run mode to preview changes before committing.
6. After completion, restart services to apply the configuration.

### Determinization Configuration Pane

> **Sprint:** SPRINT_20260112_013_FE_determinization_config_pane

The Determinization Config Pane allows policy admins to view and edit grey queue settings.

**Accessing the Configuration Pane:**

1. Navigate to **Admin > Policy Configuration**.
2. Select the **Determinization** tab.
3. Non-admins see read-only view; admins see an **Edit** button.

**Configuration Sections:**

| Section | Description |
|---------|-------------|
| Reanalysis Triggers | Toggle events that trigger grey queue reanalysis |
| Conflict Handling | Set actions for different conflict types |
| Environment Thresholds | Configure per-environment (dev/staging/prod) thresholds |

**Editing Configuration:**

1. Click **Edit** to enter edit mode.
2. Modify trigger toggles, conflict actions, or thresholds.
3. Server-side validation errors appear inline.
4. Provide a change reason (required for audit trail).
5. Click **Save** to apply changes.
6. View change history in the **Audit Log** section.

**Environment Threshold Presets:**

| Environment | MinConfidence | MaxEntropy | EPSS Threshold |
|-------------|---------------|------------|----------------|
| Development | 0.40 | 0.7 | 0.6 |
| Staging | 0.60 | 0.5 | 0.4 |
| Production | 0.75 | 0.3 | 0.3 |

**Notes:**
- Configuration changes require `policy-admin` scope.
- Changes are audited with timestamp, user, and reason.
- In offline deployments, config is read from Offline Kit bundles.

### Reconfiguration

To modify existing configuration:
- Use `stella setup --reconfigure` (CLI) or **Admin > Configuration Wizard** (UI).
- Individual steps can be reconfigured without re-running the entire wizard.

See `docs/setup/setup-wizard-ux.md` for detailed UX specifications and CLI parity.

## 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/modules/telemetry/guides/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/modules/ui/operations/airgap-console.md`
- `docs/modules/ui/operations/admin-tenants.md`
- `docs/modules/ui/operations/forensics.md`
- `docs/modules/ui/operations/observability-guide.md`

UX and interaction contracts:

- `docs/modules/ui/guides/ux/TRIAGE_UX_GUIDE.md`

## Related Docs

- `docs/VEX_CONSENSUS_GUIDE.md`
- `docs/VULNERABILITY_EXPLORER_GUIDE.md`
- `docs/OFFLINE_KIT.md`
- `docs/cli-vs-ui-parity.md`
- `docs/technical/architecture/console-admin-rbac.md`
- `docs/technical/architecture/console-branding.md`