stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 Releases Wiki Activity

sprints completion. new product advisories prepared

Browse Source
This commit is contained in:
master
2026-01-16 16:30:03 +02:00
parent a927d924e3
commit 4ca3ce8fb4
255 changed files with 42434 additions and 1020 deletions
Download Patch File Download Diff File Expand all files Collapse all files

395
docs/UI_GUIDE.md
View File

@@ -48,6 +48,89 @@ The Console is organized into workspaces. Names vary slightly by build, but the
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.
@@ -91,6 +174,276 @@ Evidence Cards are single-file exports containing SBOM excerpt, DSSE envelope, a
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).
@@ -132,6 +485,48 @@ The wizard guides operators through these configuration areas:
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: