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

doctor enhancements, setup, enhancements, ui functionality and design consolidation and , test projects fixes , product advisory attestation/rekor and delta verfications enhancements

Browse Source
This commit is contained in:
master
2026-01-19 09:02:59 +02:00
parent 8c4bf54aed
commit 17419ba7c4
809 changed files with 170738 additions and 12244 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/README.md
View File

@@ -100,6 +100,7 @@ This documentation set is intentionally consolidated and does not maintain compa
| Security deployment hardening | `SECURITY_HARDENING_GUIDE.md` |
| VEX consensus and issuer trust | `VEX_CONSENSUS_GUIDE.md` |
| Vulnerability Explorer guide | `VULNERABILITY_EXPLORER_GUIDE.md` |
| SBOM determinism guide | `sboms/DETERMINISM.md` |
| Engineering standards (for implementers) | `code-of-conduct/CODE_OF_CONDUCT.md` |
| Testing standards (for QA/automation) | `code-of-conduct/TESTING_PRACTICES.md` |

343
docs/api/artifact-store-api.yaml Normal file
View File

@@ -0,0 +1,343 @@
openapi: 3.0.3
info:
title: Stella Ops Artifact Store API
description: |
Unified artifact storage API with bom-ref support.
Sprint: SPRINT_20260118_017_Evidence_artifact_store_unification (AS-005, AS-007)
## Overview
The Artifact Store API provides unified storage and retrieval of evidence artifacts
(SBOMs, VEX, DSSE envelopes, Rekor proofs) using a bom-ref based path convention.
## Path Convention
Artifacts are stored at: `/artifacts/{bom-ref-encoded}/{serialNumber}/{artifactId}.json`
Where:
- `bom-ref-encoded`: URL-safe base64 encoded PURL
- `serialNumber`: CycloneDX serial number (URN UUID)
- `artifactId`: Unique artifact identifier
version: 1.0.0
contact:
name: Stella Ops Team
license:
name: AGPL-3.0-or-later
servers:
- url: /api/v1
description: API v1
tags:
- name: Artifacts
description: Artifact storage and retrieval operations
- name: Evidence
description: Evidence submission operations
paths:
/evidence:
post:
operationId: submitEvidence
tags: [Evidence]
summary: Submit evidence artifact
description: |
Ingests DSSE envelopes with SBOM references and stores in unified ArtifactStore.
Extracts and validates bom_ref and cyclonedx_serial from the envelope.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EvidenceSubmissionRequest'
responses:
'201':
description: Evidence stored successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ArtifactMetadata'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: Artifact already exists
content:
application/json:
schema:
$ref: '#/components/schemas/ArtifactMetadata'
/artifacts:
get:
operationId: listArtifacts
tags: [Artifacts]
summary: List artifacts by bom-ref
description: |
Returns paginated list of artifacts for a given bom-ref.
Supports filtering by serial_number and time range.
parameters:
- name: bom_ref
in: query
required: true
description: Package URL or component reference
schema:
type: string
example: "pkg:docker/acme/api@sha256:abc123"
- name: serial_number
in: query
required: false
description: CycloneDX serial number filter
schema:
type: string
example: "urn:uuid:12345678-1234-1234-1234-123456789012"
- name: from
in: query
required: false
description: Start date filter (ISO 8601)
schema:
type: string
format: date-time
- name: to
in: query
required: false
description: End date filter (ISO 8601)
schema:
type: string
format: date-time
- name: limit
in: query
required: false
description: Maximum results per page (default 50, max 1000)
schema:
type: integer
minimum: 1
maximum: 1000
default: 50
- name: continuation_token
in: query
required: false
description: Token for pagination
schema:
type: string
responses:
'200':
description: Artifacts retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ArtifactListResponse'
/artifacts/{artifact_id}:
get:
operationId: getArtifact
tags: [Artifacts]
summary: Get artifact by ID
description: Returns artifact metadata and optionally content
parameters:
- name: artifact_id
in: path
required: true
schema:
type: string
format: uuid
- name: include_content
in: query
required: false
description: Include artifact content in response
schema:
type: boolean
default: false
responses:
'200':
description: Artifact retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/ArtifactResponse'
'404':
description: Artifact not found
delete:
operationId: deleteArtifact
tags: [Artifacts]
summary: Delete artifact (soft delete)
description: Marks artifact as deleted without removing from storage
parameters:
- name: artifact_id
in: path
required: true
schema:
type: string
format: uuid
responses:
'204':
description: Artifact deleted
'404':
description: Artifact not found
/artifacts/{artifact_id}/content:
get:
operationId: getArtifactContent
tags: [Artifacts]
summary: Get artifact content
description: Returns the raw artifact content
parameters:
- name: artifact_id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Artifact content
content:
application/octet-stream:
schema:
type: string
format: binary
application/json:
schema:
type: object
application/vnd.dsse+json:
schema:
type: object
application/vnd.cyclonedx+json:
schema:
type: object
'404':
description: Artifact not found
components:
schemas:
EvidenceSubmissionRequest:
type: object
required:
- bom_ref
properties:
bom_ref:
type: string
description: Package URL or component reference
example: "pkg:docker/acme/api@sha256:abc123def456"
cyclonedx_serial:
type: string
description: CycloneDX serial number (URN UUID)
example: "urn:uuid:12345678-1234-1234-1234-123456789012"
dsse_uri:
type: string
description: URI to DSSE envelope (s3://, file://, https://)
example: "s3://evidence-bucket/path/to/envelope.json"
rekor_uuid:
type: string
description: Rekor log entry UUID
example: "f1a2b3c4d5e6f7a8"
content:
type: string
format: byte
description: Base64-encoded artifact content (alternative to dsse_uri)
content_type:
type: string
description: MIME type of content
example: "application/vnd.dsse+json"
metadata:
type: object
additionalProperties:
type: string
description: Additional metadata key-value pairs
ArtifactMetadata:
type: object
required:
- artifact_id
- bom_ref
- storage_key
- sha256
- created_at
properties:
artifact_id:
type: string
format: uuid
description: Unique artifact identifier
bom_ref:
type: string
description: Package URL or component reference
serial_number:
type: string
nullable: true
description: CycloneDX serial number
storage_key:
type: string
description: Storage path for artifact
content_type:
type: string
description: MIME type
size_bytes:
type: integer
format: int64
description: Content size in bytes
sha256:
type: string
description: SHA-256 hash of content
created_at:
type: string
format: date-time
description: Creation timestamp
rekor_uuid:
type: string
nullable: true
description: Rekor log entry UUID if linked
metadata:
type: object
additionalProperties:
type: string
description: Additional metadata
ArtifactListResponse:
type: object
required:
- artifacts
- total
properties:
artifacts:
type: array
items:
$ref: '#/components/schemas/ArtifactMetadata'
total:
type: integer
description: Total matching artifacts
continuation_token:
type: string
nullable: true
description: Token for next page
ArtifactResponse:
allOf:
- $ref: '#/components/schemas/ArtifactMetadata'
- type: object
properties:
content:
type: string
format: byte
nullable: true
description: Base64-encoded content (if include_content=true)
ErrorResponse:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code
message:
type: string
description: Human-readable error message
details:
type: object
additionalProperties: true
description: Additional error details

280
docs/api/gates-api.yaml Normal file
View File

@@ -0,0 +1,280 @@
openapi: 3.0.3
info:
title: Stella Ops Gates API
description: |
Gate check API for unknowns queue integration.
Sprint: SPRINT_20260118_018_Unknowns_queue_enhancement (UQ-006)
## Overview
The Gates API provides endpoints to check if a component can pass through
the release gate based on its unknowns status. It implements fail-closed
semantics by default for HOT unknowns.
## Gate Decisions
- **pass**: No blocking unknowns, component may proceed
- **warn**: Non-blocking unknowns present, proceed with caution
- **block**: HOT unknowns, KEV items, or SLA breaches require resolution
version: 1.0.0
contact:
name: Stella Ops Team
license:
name: AGPL-3.0-or-later
servers:
- url: /api/v1
description: API v1
tags:
- name: Gates
description: Gate check operations for unknowns
paths:
/gates/{bom_ref}:
get:
operationId: getGateStatus
tags: [Gates]
summary: Get gate check result for a component
description: |
Returns the current unknowns state and gate decision for a BOM reference.
Results are cached for 30 seconds.
parameters:
- name: bom_ref
in: path
required: true
description: URL-encoded BOM reference (PURL)
schema:
type: string
example: pkg%3Anpm%2Flodash%404.17.21
responses:
'200':
description: Gate status retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GateStatusResponse'
'500':
description: Internal server error
/gates/{bom_ref}/check:
post:
operationId: checkGate
tags: [Gates]
summary: Perform gate check for a component
description: |
Performs a fresh gate check with optional verdict proposal.
Returns 403 if the gate is blocked.
parameters:
- name: bom_ref
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GateCheckRequest'
responses:
'200':
description: Gate passed or warning
content:
application/json:
schema:
$ref: '#/components/schemas/GateCheckResponse'
'403':
description: Gate blocked
content:
application/json:
schema:
$ref: '#/components/schemas/GateCheckResponse'
/gates/{bom_ref}/exception:
post:
operationId: requestGateException
tags: [Gates]
summary: Request an exception to bypass the gate
description: |
Requests approval to bypass blocking unknowns.
Exceptions are not auto-granted and require manual approval.
parameters:
- name: bom_ref
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionRequest'
responses:
'200':
description: Exception granted
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
'403':
description: Exception denied
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
components:
schemas:
GateStatusResponse:
type: object
required:
- bom_ref
- state
- gate_decision
- checked_at
properties:
bom_ref:
type: string
description: BOM reference (PURL)
example: "pkg:npm/lodash@4.17.21"
state:
type: string
enum: [resolved, pending, under_review, escalated, rejected]
description: Aggregate state across all unknowns
verdict_hash:
type: string
nullable: true
description: SHA-256 hash of verdict if resolved
example: "sha256:abc123..."
unknowns:
type: array
items:
$ref: '#/components/schemas/UnknownDto'
gate_decision:
type: string
enum: [pass, warn, block]
description: Gate decision
checked_at:
type: string
format: date-time
description: When the check was performed
UnknownDto:
type: object
required:
- unknown_id
- band
- state
properties:
unknown_id:
type: string
format: uuid
description: Unknown entry ID
cve_id:
type: string
nullable: true
description: CVE identifier if applicable
example: "CVE-2026-1234"
band:
type: string
enum: [hot, warm, cold]
description: Priority band based on score
sla_remaining_hours:
type: number
nullable: true
description: Hours remaining before SLA breach
state:
type: string
enum: [pending, under_review, escalated, resolved, rejected]
description: Current processing state
GateCheckRequest:
type: object
properties:
proposed_verdict:
type: string
nullable: true
description: Proposed VEX verdict (e.g., "not_affected")
example: "not_affected"
GateCheckResponse:
type: object
required:
- bom_ref
- decision
- state
- checked_at
properties:
bom_ref:
type: string
decision:
type: string
enum: [pass, warn, block]
state:
type: string
blocking_unknown_ids:
type: array
items:
type: string
format: uuid
reason:
type: string
nullable: true
description: Human-readable reason for decision
exception_granted:
type: boolean
description: Whether an exception was granted
exception_ref:
type: string
nullable: true
description: Exception reference if granted
checked_at:
type: string
format: date-time
ExceptionRequest:
type: object
required:
- justification
properties:
unknown_ids:
type: array
items:
type: string
format: uuid
description: IDs of unknowns to bypass
justification:
type: string
description: Business justification for exception
minLength: 10
ExceptionResponse:
type: object
required:
- granted
- requested_at
properties:
granted:
type: boolean
description: Whether exception was granted
exception_ref:
type: string
nullable: true
description: Exception reference for tracking
denial_reason:
type: string
nullable: true
description: Reason if not granted
expires_at:
type: string
format: date-time
nullable: true
description: When exception expires
requested_at:
type: string
format: date-time
description: When request was made

231
docs/doctor/evidence-schemas.md Normal file
View File

@@ -0,0 +1,231 @@
# Doctor Check Evidence Schemas
This document defines the standardized evidence schemas for all Doctor health checks. These schemas enable AdvisoryAI to understand field meanings, expected ranges, and root cause differentiation.
> **Sprint:** SPRINT_20260118_015_Doctor_check_quality_improvements
> **Task:** DQUAL-006 - Standardize evidence schema documentation
---
## Evidence Schema Conventions
### Field Naming
- Use `snake_case` for all field names
- Boolean fields: `is_*`, `has_*`, `*_enabled`, `*_available`
- Timestamp fields: `*_utc` suffix, ISO8601 format
- Duration fields: `*_ms` or `*_seconds` suffix
- Status fields: lowercase string enums
### Value Types
- `string`: UTF-8 text
- `int`: 64-bit signed integer
- `float`: 64-bit floating point
- `bool`: `true` or `false` (lowercase in JSON)
- `list<T>`: JSON array of type T
- `ISO8601`: timestamp string in ISO8601 format
---
## Policy Engine Checks
### check.policy.engine
**Description:** Verify policy engine compilation, evaluation, and storage health
**Evidence Fields:**
| Field | Type | Description | Expected Range |
|-------|------|-------------|----------------|
| `engine_type` | string | Policy engine type | `opa`, `rego`, `custom`, `unknown` |
| `engine_version` | string | Engine version string | Semantic version or `unknown` |
| `engine_url` | string | Policy engine base URL | Valid HTTP(S) URL |
| `compilation_status` | string | Compilation health | `OK`, `FAILED` |
| `evaluation_status` | string | Evaluation health | `OK`, `FAILED` |
| `storage_status` | string | Storage health | `OK`, `FAILED` |
| `policy_count` | int | Number of loaded policies | ≥ 0 |
| `compilation_time_ms` | int | Compilation latency | 0-10000 (typical < 100) |
| `evaluation_latency_p50_ms` | int | Median evaluation time | 0-5000 (typical < 50) |
| `cache_hit_ratio` | float | Policy cache efficiency | 0.0-1.0 |
| `last_compilation_error` | string? | Most recent compilation error | null or error message |
| `evaluation_error` | string? | Most recent evaluation error | null or error message |
| `storage_error` | string? | Most recent storage error | null or error message |
**Likely Cause Differentiation:**
| Evidence Pattern | Likely Cause |
|-----------------|--------------|
| `compilation_status=FAILED` | OPA/Rego syntax error or engine unavailable |
| `evaluation_status=FAILED` | Policy evaluation timeout or runtime error |
| `storage_status=FAILED` | PostgreSQL connection issue or disk full |
| `evaluation_latency_p50_ms > 100` | Complex policies or cold cache |
| `cache_hit_ratio < 0.5` | Cache not warmed or policies changing frequently |
---
## Authentication Checks
### check.auth.oidc
**Description:** Verify connectivity to configured OIDC provider and discovery endpoint
**Evidence Fields:**
| Field | Type | Description | Expected Range |
|-------|------|-------------|----------------|
| `issuer_url` | string | OIDC issuer URL | Valid HTTPS URL |
| `discovery_reachable` | bool | Can reach discovery endpoint | `true` or `false` |
| `discovery_response_ms` | int | Discovery fetch latency | 0-10000 (typical < 500) |
| `authorization_endpoint_present` | bool | Has authorization endpoint | `true` |
| `token_endpoint_present` | bool | Has token endpoint | `true` |
| `jwks_uri_present` | bool | Has JWKS URI | `true` |
| `jwks_key_count` | int | Number of signing keys | ≥ 1 |
| `jwks_fetch_ms` | int | JWKS fetch latency | 0-10000 (typical < 500) |
| `http_status_code` | int? | HTTP response code | null or 100-599 |
| `error_message` | string? | Error details | null or error string |
| `connection_error_type` | string? | Error classification | `ssl_error`, `dns_failure`, `refused`, `timeout`, `connection_failed` |
**Likely Cause Differentiation:**
| Evidence Pattern | Likely Cause |
|-----------------|--------------|
| `discovery_reachable=false`, `connection_error_type=dns_failure` | DNS resolution failure |
| `discovery_reachable=false`, `connection_error_type=ssl_error` | TLS certificate issue |
| `discovery_reachable=false`, `connection_error_type=refused` | OIDC provider down or firewall |
| `discovery_reachable=true`, `authorization_endpoint_present=false` | Malformed discovery document |
| `jwks_key_count=0` | JWKS endpoint error or key rotation in progress |
---
## Cryptography Checks
### check.crypto.fips
**Description:** Verify FIPS 140-2 mode is enabled when required by crypto profile
**Evidence Fields:**
| Field | Type | Description | Expected Range |
|-------|------|-------------|----------------|
| `fips_mode_enabled` | bool | System FIPS mode active | `true` or `false` |
| `platform` | string | Operating system platform | `windows`, `linux`, `macos`, `unknown` |
| `crypto_provider` | string | Cryptographic provider | `bcrypt`, `openssl`, `managed`, `unknown` |
| `openssl_fips_module_loaded` | bool | OpenSSL FIPS module status | `true` or `false` |
| `crypto_profile` | string | Configured crypto profile | Profile name from config |
| `algorithms_tested` | string | Comma-separated algorithm list | Algorithm names |
| `algorithms_available` | string | Algorithms that passed testing | Algorithm names |
| `algorithms_missing` | string | Algorithms that failed testing | Algorithm names or `none` |
| `status` | string | Overall compliance status | `compliant`, `non-compliant` |
| `test_aes_256` | string | AES-256 test result | `pass` or `fail: <error>` |
| `test_sha_256` | string | SHA-256 test result | `pass` or `fail: <error>` |
| `test_sha_384` | string | SHA-384 test result | `pass` or `fail: <error>` |
| `test_sha_512` | string | SHA-512 test result | `pass` or `fail: <error>` |
| `test_rsa_2048` | string | RSA-2048 test result | `pass` or `fail: <error>` |
| `test_ecdsa_p256` | string | ECDSA-P256 test result | `pass` or `fail: <error>` |
**Likely Cause Differentiation:**
| Evidence Pattern | Likely Cause |
|-----------------|--------------|
| `fips_mode_enabled=false`, `platform=linux` | FIPS mode not enabled via fips-mode-setup |
| `fips_mode_enabled=false`, `platform=windows` | FIPS Group Policy not configured |
| `openssl_fips_module_loaded=false` | OpenSSL FIPS provider not installed |
| `algorithms_missing` contains values | Crypto provider missing FIPS-validated algorithms |
---
## Attestation Checks
### check.attestation.clock.skew
**Description:** Verify system clock is synchronized for attestation validity
**Evidence Fields:**
| Field | Type | Description | Expected Range |
|-------|------|-------------|----------------|
| `local_time_utc` | ISO8601 | System time | Valid timestamp |
| `server_time_utc` | ISO8601 | Reference server time | Valid timestamp |
| `skew_seconds` | float | Clock difference (positive = ahead) | -300 to 300 (typical < 5) |
| `max_allowed_skew` | int | Threshold in seconds | Default: 5 |
| `ntp_daemon_running` | bool | NTP service active | `true` or `false` |
| `ntp_daemon_type` | string | NTP daemon type | `chronyd`, `ntpd`, `systemd-timesyncd`, `w32time`, `unknown` |
| `ntp_servers_configured` | string | Comma-separated NTP servers | Server hostnames |
| `last_sync_time_utc` | ISO8601? | Last successful sync | Timestamp or `null` |
| `sync_age_seconds` | int? | Seconds since last sync | ≥ 0 or `null` |
| `is_virtual_machine` | bool | Running in VM | `true` or `false` |
| `vm_type` | string | VM hypervisor type | `vmware`, `hyper-v`, `kvm`, `xen`, `container`, `none` |
| `vm_clock_sync_enabled` | bool | VM time sync tools enabled | `true` or `false` |
| `connection_error_type` | string? | Network error type | `ssl_error`, `dns_failure`, `refused`, `timeout`, `connection_failed` |
**Likely Cause Differentiation:**
| Evidence Pattern | Likely Cause |
|-----------------|--------------|
| `ntp_daemon_running=false` | NTP service not started |
| `ntp_daemon_running=true`, `sync_age_seconds > 3600` | NTP server unreachable |
| `is_virtual_machine=true`, `vm_clock_sync_enabled=false` | VM clock drift without sync |
| `skew_seconds > 0` (large positive) | System clock set to future |
| `skew_seconds < 0` (large negative) | System clock set to past |
### check.attestation.transparency.consistency
**Description:** Verify stored log checkpoints match remote transparency log
**Evidence Fields:**
| Field | Type | Description | Expected Range |
|-------|------|-------------|----------------|
| `checkpoint_path` | string | Local checkpoint file path | Filesystem path |
| `stored_tree_size` | int | Local tree size | ≥ 0 |
| `remote_tree_size` | int | Remote tree size | ≥ stored_tree_size |
| `stored_root_hash` | string | Local root hash | Hex string |
| `remote_root_hash` | string | Remote root hash | Hex string |
| `entries_behind` | int | Entries to catch up | ≥ 0 |
| `checkpoint_age` | ISO8601 | Checkpoint last update | Valid timestamp |
| `consistency_verified` | bool | Log is consistent | `true` or `false` |
**Likely Cause Differentiation:**
| Evidence Pattern | Likely Cause |
|-----------------|--------------|
| `remote_tree_size < stored_tree_size` | **CRITICAL:** Possible log rollback/tampering |
| `stored_root_hash != remote_root_hash` at same size | **CRITICAL:** Possible log modification |
| `entries_behind > 10000` | Checkpoint very stale, needs sync |
| Checkpoint file parse error | Corrupted checkpoint file |
---
## Remediation Step Properties
All remediation steps now include safety annotations:
| Property | Type | Description |
|----------|------|-------------|
| `Order` | int | Step sequence (1-based) |
| `Description` | string | Human-readable description |
| `Command` | string | Command to execute |
| `CommandType` | enum | `Shell`, `Sql`, `Api`, `Manual`, `Comment` |
| `IsDestructive` | bool | Step modifies/deletes data |
| `DryRunVariant` | string? | Safe preview command |
| `Placeholders` | dict? | User-supplied values needed |
**AdvisoryAI Integration:**
- Commands with `IsDestructive=true` must NOT be auto-executed
- Always prefer `DryRunVariant` before suggesting destructive commands
- `CommandType.Manual` requires human confirmation
---
## Adding New Check Schemas
When adding a new Doctor check:
1. Define evidence fields in the check implementation
2. Add schema documentation to this file
3. Include "Likely Cause Differentiation" table
4. Test evidence output matches schema
5. Update AdvisoryAI prompt if needed
---
*Last updated: 2026-01-18 (SPRINT_20260118_015)*

147
docs/modules/binary-index/semantic-diffing.md
View File

@@ -1,7 +1,7 @@
# Semantic Diffing Architecture
> **Status:** PLANNED
> **Version:** 1.0.0
> **Status:** PHASE 1 IMPLEMENTED (B2R2 IR Lifting)
> **Version:** 1.1.0
> **Related Sprints:**
> - `SPRINT_20260105_001_001_BINDEX_semdiff_ir_semantics.md`
> - `SPRINT_20260105_001_002_BINDEX_semdiff_corpus.md`
@@ -722,5 +722,146 @@ Delta-sig predicates are stored in the Evidence Locker and can be included in po
---
---
## 17. B2R2 Troubleshooting Guide
This section covers common issues and resolutions when using B2R2 for IR lifting.
### 17.1 Lifting Failures
**Symptom:** `B2R2LiftingException: Failed to lift function at address 0x...`
**Common Causes:**
1. **Unsupported instruction** - B2R2 may not recognize certain instructions
2. **Invalid entry point** - Function address is not a valid entry point
3. **Obfuscated code** - Heavy obfuscation defeats parsing
**Resolution:**
```csharp
// Check if architecture is supported before lifting
if (!liftingService.SupportsArchitecture(binary.Architecture))
{
// Fall back to disassembly-only mode
return await _disassemblyService.DisassembleAsync(binary, ct);
}
// Use try-lift with fallback
var result = await _liftingService.TryLiftWithFallbackAsync(
binary,
new LiftingOptions { FallbackToDisassembly = true },
ct);
```
### 17.2 Memory Issues
**Symptom:** `OutOfMemoryException` during lifting of large binaries
**Common Causes:**
1. **Pool exhaustion** - Too many concurrent lifter instances
2. **Large function** - Single function exceeds memory budget
3. **Memory leak** - Lifter instances not properly disposed
**Resolution:**
```yaml
# Adjust pool configuration in appsettings.yaml
BinaryIndex:
B2R2Pool:
MaxInstancesPerIsa: 4 # Reduce if OOM
RecycleAfterOperations: 1000 # Force recycle more often
MaxFunctionSizeBytes: 1048576 # Skip very large functions
```
### 17.3 Performance Issues
**Symptom:** Lifting takes longer than expected (>30s for small binaries)
**Common Causes:**
1. **Cold pool** - No warm lifter instances available
2. **Complex CFG** - Function has extremely complex control flow
3. **Cache misses** - IR cache not configured or full
**Resolution:**
```csharp
// Ensure pool is warmed at startup
await _lifterPool.WarmAsync(new[] { ISA.AMD64, ISA.ARM64 }, ct);
// Check cache health
var stats = await _cacheService.GetStatisticsAsync(ct);
if (stats.HitRate < 0.5)
{
_logger.LogWarning("Low cache hit rate: {HitRate:P}", stats.HitRate);
}
```
### 17.4 Determinism Issues
**Symptom:** Same binary produces different IR hashes on repeated lifts
**Common Causes:**
1. **Non-deterministic block ordering** - Blocks not sorted by address
2. **Timestamp inclusion** - IR includes lift timestamp
3. **B2R2 version mismatch** - Different versions produce different IR
**Resolution:**
- Ensure `InvariantCulture` is used for all string formatting
- Sort basic blocks by entry address before hashing
- Include B2R2 version in cache keys
- Use `DeterministicHash` utility for consistent hashing
### 17.5 Architecture Detection Issues
**Symptom:** Wrong architecture selected for multi-arch binary (fat binary)
**Common Causes:**
1. **Universal binary** - macOS fat binaries contain multiple architectures
2. **ELF with multiple ABIs** - Rare but possible
**Resolution:**
```csharp
// Explicitly specify target architecture
var liftOptions = new LiftingOptions
{
TargetArchitecture = ISA.AMD64, // Force x86-64
IgnoreOtherArchitectures = true
};
```
### 17.6 LowUIR Mapping Issues
**Symptom:** Specific B2R2 LowUIR statements not mapped correctly
**Reference: LowUIR Statement Type Mapping**
| B2R2 LowUIR | Stella IR Model | Notes |
|-------------|-----------------|-------|
| `LMark` | `IrLabel` | Block label markers |
| `Put` | `IrAssignment` | Register write |
| `Store` | `IrStore` | Memory write |
| `InterJmp` | `IrJump` | Cross-function jump |
| `IntraJmp` | `IrJump` | Intra-function jump |
| `InterCJmp` | `IrConditionalJump` | Cross-function conditional |
| `IntraCJmp` | `IrConditionalJump` | Intra-function conditional |
| `SideEffect` | `IrCall`/`IrReturn` | Function calls, returns |
| `Def`/`Use`/`Phi` | `IrPhi` | SSA form constructs |
### 17.7 Diagnostic Commands
```bash
# Check B2R2 health
stella ops binaryindex health --verbose
# Run benchmark suite
stella ops binaryindex bench --iterations 100 --binary sample.so
# View cache statistics
stella ops binaryindex cache --stats
# Dump effective configuration
stella ops binaryindex config
```
---
*Document Version: 1.1.0*
*Last Updated: 2026-01-16*
*Last Updated: 2026-01-19*

34
docs/modules/cli/AGENTS.md
View File

@@ -3,11 +3,45 @@
## Mission
The `stella` CLI is the operator-facing Swiss army knife for scans, exports, policy management, offline kit operations, and automation scripting.
## Active Work: CLI Consolidation (v2.x → v3.0)
The CLI is undergoing a major consolidation to improve discoverability and consistency. See:
- **Advisory:** `docs-archived/product/advisories/CLI_CONSOLIDATION_PROPOSAL.md`
- **Command Mapping:** `docs-archived/product/advisories/CLI_COMMAND_MAPPING.md`
- **Migration Guide:** `docs/modules/cli/guides/migration-v3.md`
### Consolidation Sprints
| Sprint | Scope | Status |
|--------|-------|--------|
| `SPRINT_20260118_010_CLI_consolidation_foundation` | Routing infrastructure, deprecation system | **DONE** |
| `SPRINT_20260118_011_CLI_settings_consolidation` | `stella config` unified settings | **DONE** |
| `SPRINT_20260118_012_CLI_verification_consolidation` | `stella verify` unified verification | **DONE** |
| `SPRINT_20260118_013_CLI_scanning_consolidation` | `stella scan` unified scanning | **DONE** |
| `SPRINT_20260118_014_CLI_evidence_remaining_consolidation` | Evidence, reachability, SBOM, crypto, etc. | TODO |
### Key Changes
- **81+ → 18 top-level commands** for discoverability
- **Unified settings under `stella config`** (notify, feeds, registry, integrations)
- **Unified verification under `stella verify`** (attestation, vex, patch, sbom)
- **Compound commands split** (`scangraph` → `scan graph`)
- **Backward compatibility** via deprecated aliases
### Implementation Priorities
1. Foundation (routing, deprecation) must complete first
2. Sprints 011-014 can run in parallel after foundation
3. All old commands kept as deprecated aliases until v3.0
4. Tests must verify both old and new paths
## Key docs
- [Module README](./README.md)
- [Architecture](./architecture.md)
- [Implementation plan](./implementation_plan.md)
- [Task board](./TASKS.md)
- [Migration Guide v3](./guides/migration-v3.md)
## How to get started
1. Open sprint file `/docs/implplan/SPRINT_*.md` and locate the stories referencing this module.

79
docs/modules/cli/architecture.md
View File

@@ -41,7 +41,72 @@ src/
**Plug-in verbs.** Non-core verbs (Excititor, runtime helpers, future integrations) ship as restart-time plug-ins under `plugins/cli/**` with manifest descriptors. The launcher loads plug-ins on startup; hot reloading is intentionally unsupported. The inaugural bundle, `StellaOps.Cli.Plugins.NonCore`, packages the Excititor, runtime, and offline-kit command groups and publishes its manifest at `plugins/cli/StellaOps.Cli.Plugins.NonCore/`.
**OS targets**: linux‑x64/arm64, windows‑x64/arm64, macOS‑x64/arm64.
**OS targets**: linuxâ€'x64/arm64, windowsâ€'x64/arm64, macOSâ€'x64/arm64.
---
## 1.1) Command Routing Infrastructure (v2.x→v3.0 Migration)
> Sprint: SPRINT_20260118_010_CLI_consolidation_foundation
The CLI includes a **command routing infrastructure** to support backward-compatible command migration. This enables consolidating 81+ top-level commands into ~18 organized command groups while maintaining backward compatibility.
### Routing Components
```
src/Cli/StellaOps.Cli/Infrastructure/
├── ICommandRouter.cs # Router interface
├── CommandRouter.cs # Route registration and lookup
├── CommandRoute.cs # Route model (old→new path mapping)
├── CommandGroupBuilder.cs # Fluent builder for command groups
├── DeprecationWarningService.cs # Warning display on stderr
├── RouteMappingConfiguration.cs # JSON config model + loader
src/Cli/StellaOps.Cli/
└── cli-routes.json # Embedded route mappings (60+ entries)
```
### How Routing Works
1. **At startup**, `CommandFactory.RegisterDeprecatedAliases()` loads `cli-routes.json` (embedded resource)
2. **For each deprecated route**, creates a hidden alias command that:
- Delegates to the canonical command
- Shows a deprecation warning on stderr (once per session)
3. **Warnings** include the old path, new path, removal version, and suppression instructions
### Route Configuration Schema
```json
{
"version": "1.0",
"mappings": [
{
"old": "scangraph",
"new": "scan graph",
"type": "deprecated",
"removeIn": "3.0",
"reason": "Consolidated under scan command"
}
]
}
```
### Deprecation Warning Format
```
WARNING: 'stella scangraph' is deprecated and will be removed in v3.0.
Use 'stella scan graph' instead.
Set STELLA_SUPPRESS_DEPRECATION_WARNINGS=1 to hide this message.
```
### Timeline
- **v2.x**: Both old and new command paths work; old paths show deprecation warnings
- **v3.0**: Old command paths removed
### Migration Guide
See [migration-v3.md](./guides/migration-v3.md) for user-facing migration instructions and command mappings.
---
@@ -174,12 +239,12 @@ Both subcommands honour offline-first expectations (no network access) and norma
* Uses `STELLAOPS_ADVISORYAI_URL` when configured; otherwise it reuses the backend base address and adds `X-StellaOps-Scopes` (`advisory:run` + task scope) per request.
* `--timeout 0` performs a single cache lookup (for CI flows that only want cached artefacts).
* `advise ask "<question>" [--evidence] [--no-action] [--conversation-id <id>] [--context <cve|scan|image>]`
* Calls advisory chat endpoints, returns a cited answer with evidence refs.
* `--no-action` disables action proposals; `--evidence` forces evidence chips in output.
### 2.12 Decision evidence (new)
* `advise ask "<question>" [--evidence] [--no-action] [--conversation-id <id>] [--context <cve|scan|image>]`
* Calls advisory chat endpoints, returns a cited answer with evidence refs.
* `--no-action` disables action proposals; `--evidence` forces evidence chips in output.
### 2.12 Decision evidence (new)
- `decision export`

350
docs/modules/cli/guides/migration-v3.md Normal file
View File

@@ -0,0 +1,350 @@
# CLI Migration Guide: v2.x to v3.0
This guide documents the CLI command consolidation that begins in v2.x (with deprecation warnings) and completes in v3.0 (old commands removed).
---
## Overview
The Stella CLI has been reorganized for better discoverability and consistency:
| Change | Reason |
|--------|--------|
| 81+ top-level commands → 18 | Easier to discover and remember |
| Scattered settings → `stella config` | Unified configuration management |
| Multiple verify commands → `stella verify` | Consistent verification interface |
| Compound names → proper hierarchy | `scangraph` → `scan graph` |
## Deprecation Timeline
- **v2.x**: Old commands work but show deprecation warnings
- **v3.0**: Old commands removed
To suppress deprecation warnings during transition:
```bash
export STELLA_SUPPRESS_DEPRECATION_WARNINGS=1
```
---
## Quick Migration Reference
### Settings & Configuration
```bash
# Before (deprecated)
stella notify channels list
stella admin feeds status
stella registry list
# After
stella config notify channels list
stella config feeds status
stella config registry list
```
### Verification
```bash
# Before (deprecated)
stella attest verify <artifact>
stella vex verify <artifact>
stella patchverify <artifact>
# After
stella verify attestation <artifact>
stella verify vex <artifact>
stella verify patch <artifact>
```
### Scanning
```bash
# Before (deprecated)
stella scangraph list
stella secrets bundle create <dir>
stella image inspect <ref>
# After
stella scan graph list
stella scan secrets bundle create <dir>
stella scan image inspect <ref>
```
### Evidence & Audit
```bash
# Before (deprecated)
stella evidenceholds list
stella audit export
stella prove --artifact <ref>
stella replay run
# After
stella evidence holds list
stella evidence audit export
stella evidence proof generate --artifact <ref>
stella evidence replay run
```
### Reachability
```bash
# Before (deprecated)
stella reachgraph list
stella slice create
stella witness show <path>
# After
stella reachability graph list
stella reachability slice create
stella reachability witness show <path>
```
### SBOM
```bash
# Before (deprecated)
stella sbomer compose
stella layersbom show <digest>
# After
stella sbom compose
stella sbom layer show <digest>
```
### Cryptography
```bash
# Before (deprecated)
stella keys list
stella issuerkeys list
stella sign image <ref>
# After
stella crypto keys list
stella crypto keys issuer list
stella crypto sign image <ref>
```
### Administration
```bash
# Before (deprecated)
stella doctor run
stella db migrate
stella admin users list
# After
stella admin doctor run
stella admin db migrate
stella auth users list
```
### CI/CD
```bash
# Before (deprecated)
stella gate evaluate
stella github upload
# After (either works)
stella release gate evaluate
stella ci gate evaluate # shortcut for CI pipelines
stella ci github upload
```
### Utilities
```bash
# Before (deprecated)
stella binary diff
stella hlc show
stella timeline query
# After
stella tools binary diff
stella tools hlc show
stella tools timeline query
```
---
## New Command Structure
### Primary Commands
```
stella scan # Scanning operations
stella release # Release management
stella verify # All verification
stella attest # Create attestations
stella evidence # Evidence management
stella policy # Policy management
stella vex # VEX operations
stella reachability # Reachability analysis
stella sbom # SBOM operations
stella crypto # Cryptography
stella config # Settings & configuration
stella auth # Authentication
stella admin # Administration
stella ci # CI/CD integration
stella setup # Initial setup
stella explain # Explain decisions
stella tools # Utility commands
```
### `stella config` - Unified Settings
All configuration is now under `stella config`:
```
stella config
├── list [--category <cat>] # List config paths
├── show <path> # Show config value
├── set <path> <value> # Set config value
├── export # Export all config
├── import <file> # Import config
├── notify/ # Notification settings
│ ├── channels list/test
│ ├── templates list/render
│ └── preferences export/import
├── feeds/ # Feed configuration
│ ├── list
│ ├── status
│ └── refresh
├── integrations/ # Integration settings
│ ├── list
│ └── test
├── registry/ # Registry settings
└── sources/ # Data sources
```
### `stella verify` - Unified Verification
All verification under one command:
```
stella verify
├── image <ref> # Image attestation
├── bundle <path> # Evidence bundle
├── offline <artifact> # Offline verification
├── attestation <artifact> # Attestation verification
├── vex <artifact> # VEX verification
├── patch <artifact> # Patch verification
└── sbom <file> # SBOM verification
```
### `stella scan` - Unified Scanning
All scanning under one command:
```
stella scan
├── run <ref> # Run a scan
├── status <id> # Check status
├── results <id> # View results
├── download # Download scanner bundle
├── workers # Configure workers
├── graph/ # Scan graph operations
├── secrets/ # Secret detection
│ └── bundle create/verify/info
└── image/ # Image analysis
├── inspect
└── layers
```
---
## CI/CD Script Updates
### GitHub Actions
```yaml
# Before
- run: stella gate evaluate --artifact ${{ env.IMAGE_SHA }}
# After (either works)
- run: stella ci gate evaluate --artifact ${{ env.IMAGE_SHA }}
# or
- run: stella release gate evaluate --artifact ${{ env.IMAGE_SHA }}
```
### GitLab CI
```yaml
# Before
script:
- stella notify channels test --channel slack-alerts
# After
script:
- stella config notify channels test --channel slack-alerts
```
### Jenkins
```groovy
// Before
sh 'stella scangraph list --format json'
// After
sh 'stella scan graph list --format json'
```
---
## Common Errors and Solutions
### "Command not found" in v3.0
If upgrading to v3.0 and a command fails:
```bash
$ stella scangraph list
Error: Unknown command 'scangraph'. Did you mean 'scan graph'?
```
Update your script to use the new path.
### "Deprecated command" warnings
```
WARNING: 'stella notify' is deprecated and will be removed in v3.0.
Use 'stella config notify' instead.
```
This is informational. The command still works but should be updated.
### Suppressing warnings in CI
```bash
export STELLA_SUPPRESS_DEPRECATION_WARNINGS=1
stella notify channels list # No warning
```
---
## Getting Help
```bash
# See all commands
stella --help
# See subcommands
stella config --help
stella verify --help
# See command details
stella config notify channels list --help
```
---
## Migration Checklist
- [ ] Update CI/CD pipelines to use new command paths
- [ ] Update documentation referencing CLI commands
- [ ] Update automation scripts
- [ ] Test with `STELLA_SUPPRESS_DEPRECATION_WARNINGS=0` to find deprecated usage
- [ ] Plan upgrade to v3.0 before end-of-support for v2.x

269
docs/modules/cli/guides/setup-guide.md Normal file
View File

@@ -0,0 +1,269 @@
# Setup Wizard Guide
This guide covers the `stella setup` command for initial configuration of Stella Ops.
## Overview
The setup wizard guides you through configuring all required and optional components. Both CLI and UI setup wizards follow the same **Infrastructure-First** order and provide identical capabilities.
## Quick Start
```bash
# Interactive setup
stella setup run
# Non-interactive with config file
stella setup run --config setup.yaml --non-interactive
# Dry-run mode (validate without applying)
stella setup run --dry-run
# Resume interrupted setup
stella setup resume
# Reconfigure a specific step
stella setup --step vault
```
## Setup Steps
Steps are organized in phases. Required steps must be completed; optional steps can be skipped.
### Phase 1: Core Infrastructure (Required)
| Step | Description |
|------|-------------|
| **database** | PostgreSQL connection for persistent storage |
| **cache** | Valkey/Redis connection for caching and distributed locks |
| **migrations** | Apply database schema migrations |
### Phase 2: Security Foundation (Required)
| Step | Description |
|------|-------------|
| **authority** | Authentication provider (Standard or LDAP) |
| **users** | Initial super user account (skipped if LDAP selected) |
| **crypto** | Cryptographic provider for signing/encryption (Default, FIPS, GOST, SM2/SM3) |
### Phase 3: Secrets Management (Optional)
| Step | Description | Configure Later |
|------|-------------|-----------------|
| **vault** | External secrets vault (HashiCorp Vault, Azure Key Vault, AWS Secrets Manager, GCP Secret Manager) | Settings > Trust & Signing, or `stella config set vault.*` |
### Phase 4: Integrations (Optional)
| Step | Description | Configure Later |
|------|-------------|-----------------|
| **registry** | Container registry for image scanning | Settings > Integrations, or `stella config set registry.*` |
| **scm** | Source control integration (GitHub, GitLab, Gitea, Bitbucket, Azure DevOps) | Settings > Integrations, or `stella config set scm.*` |
| **sources** | Advisory data sources (NVD, GHSA, OSV, distribution feeds) | Settings > Security Data, or `stella config set sources.*` |
### Phase 5: Observability (Optional)
| Step | Description | Configure Later |
|------|-------------|-----------------|
| **telemetry** | OpenTelemetry configuration for tracing, metrics, and logging | Settings > System > Telemetry, or `stella config set telemetry.*` |
| **notify** | Notification channels (Email, Slack, Teams, Webhook) | Settings > Notifications, or `stella config set notify.*` |
### Phase 6: AI Features (Optional)
| Step | Description | Configure Later |
|------|-------------|-----------------|
| **llm** | AI/LLM provider for AdvisoryAI (OpenAI, Claude, Gemini, Ollama) | Settings > Integrations > AdvisoryAI, or `stella config set llm.*` |
### Phase 7: Configuration Store (Optional)
| Step | Description | Configure Later |
|------|-------------|-----------------|
| **settingsStore** | External configuration store (Consul, etcd, Azure App Config, AWS Parameter Store) | Settings > System, or `stella config set settingsStore.*` |
### Phase 8: Release Orchestration (Optional)
| Step | Description | Configure Later |
|------|-------------|-----------------|
| **environments** | Define deployment environments (dev, staging, production) | Settings > Environments, or `stella env create` |
| **agents** | Register deployment agents for release execution | Settings > Agents, or `stella agent register` |
## Multiple Integrations
The **registry**, **scm**, and **notify** steps support configuring multiple instances. For example:
```bash
# Add multiple container registries
stella config set registry.instances.0.name "Production ECR"
stella config set registry.instances.0.provider "ecr"
stella config set registry.instances.0.isPrimary "true"
stella config set registry.instances.1.name "Docker Hub"
stella config set registry.instances.1.provider "docker"
# Add multiple SCM connections
stella config set scm.instances.0.name "GitHub Main"
stella config set scm.instances.0.provider "github"
# Add multiple notification channels
stella config set notify.instances.0.name "Ops Slack"
stella config set notify.instances.0.provider "slack"
stella config set notify.instances.1.name "Security Email"
stella config set notify.instances.1.provider "email"
```
## Skip Warnings
When skipping optional steps, the wizard displays warnings about implications:
| Skipped Step | Warning |
|--------------|---------|
| vault | Secrets stored in configuration files (less secure for production) |
| registry | Container scanning capabilities limited |
| scm | Pipeline integration and automated workflows unavailable |
| sources | CVE/VEX advisory feeds require manual updates |
| telemetry | System observability limited; tracing and metrics unavailable |
| llm | AdvisoryAI features unavailable |
| environments | Manual deployment tracking only |
| agents | Release orchestration unavailable without registered agents |
## Cryptographic Provider Selection
The **crypto** step allows selecting regional cryptographic standards:
| Provider | Standards | Use Case |
|----------|-----------|----------|
| **Default** | AES-256-GCM, SHA-256/512, Ed25519, ECDSA P-256 | General use |
| **FIPS 140-2** | AES-256-GCM (FIPS 197), SHA-256/384/512 (FIPS 180-4), ECDSA P-256/P-384 (FIPS 186-4) | US government compliance |
| **GOST R 34.10-2012** | Kuznechik/Magma, Streebog, GOST R 34.10-2012 | Russian compliance |
| **SM2/SM3** | SM4, SM3, SM2 | Chinese national standards |
FIPS mode supports HSM integration via PKCS#11, AWS CloudHSM, Azure Key Vault HSM, or GCP Cloud HSM.
## SCM Integration
The **scm** step connects Stella Ops to your source control system:
| Provider | Authentication |
|----------|----------------|
| GitHub | Personal Access Token (ghp_...) |
| GitLab | Personal Access Token (glpat-...) |
| Gitea | Access Token |
| Bitbucket | Username + App Password |
| Azure DevOps | Personal Access Token |
## Configuration File Format
For non-interactive setup, provide a YAML configuration file:
```yaml
# setup.yaml
database:
host: localhost
port: 5432
database: stellaops
user: postgres
password: ${DB_PASSWORD} # Environment variable substitution
ssl: true
cache:
host: localhost
port: 6379
password: ${CACHE_PASSWORD}
ssl: true
authority:
provider: standard # or 'ldap'
users:
superuser:
username: admin
email: admin@example.com
password: ${ADMIN_PASSWORD}
crypto:
provider: default # or 'fips', 'gost', 'sm'
vault:
provider: hashicorp
address: https://vault.example.com:8200
token: ${VAULT_TOKEN}
scm:
provider: github
url: https://github.com
token: ${GITHUB_TOKEN}
organization: my-org
sources:
enabled: nvd,ghsa,osv
nvd:
apiKey: ${NVD_API_KEY}
telemetry:
otlpEndpoint: http://localhost:4317
enableTracing: true
enableMetrics: true
notify:
provider: slack
slack:
webhookUrl: ${SLACK_WEBHOOK_URL}
llm:
provider: openai
openai:
apiKey: ${OPENAI_API_KEY}
model: gpt-4o
```
## Validation Commands
```bash
# Validate current configuration
stella setup validate
# Validate specific step
stella setup validate --step database
# Show current setup status
stella setup status
```
## Troubleshooting
### Database Connection Failed
```bash
# Test PostgreSQL connectivity
stella setup validate --step database --verbose
```
Verify:
- PostgreSQL is running and accessible
- Credentials are correct
- SSL settings match server configuration
### Cache Connection Failed
```bash
# Test Valkey/Redis connectivity
stella setup validate --step cache --verbose
```
### SCM Authentication Failed
```bash
# Test SCM connectivity
stella setup validate --step scm --verbose
```
Ensure your token has the required scopes:
- GitHub: `repo`, `workflow`
- GitLab: `api`, `read_repository`
- Azure DevOps: `Code (Read)`, `Build (Read & Execute)`
## Related Commands
- `stella config get` - View current configuration
- `stella config set` - Modify individual settings
- `stella doctor run` - Run diagnostic checks
- `stella admin db migrate` - Run database migrations

110
docs/modules/policy/gates/README.md Normal file
View File

@@ -0,0 +1,110 @@
# Policy Gates
Policy gates are automated checks that evaluate release candidates against configurable security criteria. Each gate produces a pass/fail result with detailed reasoning for policy decisions.
## CVE-Aware Gates
| Gate | ID | Description |
|------|-----|-------------|
| [EPSS Threshold](epss-threshold.md) | `epss-threshold` | Blocks CVEs above EPSS probability threshold |
| [KEV Blocker](kev-blocker.md) | `kev-blocker` | Blocks CVEs in CISA Known Exploited Vulnerabilities catalog |
| [Reachable CVE](reachable-cve.md) | `reachable-cve` | Blocks only CVEs with reachable code paths |
| [CVE Delta](cve-delta.md) | `cve-delta` | Blocks releases introducing new high-severity CVEs vs baseline |
| [Release Aggregate CVE](release-aggregate-cve.md) | `release-aggregate-cve` | Enforces aggregate CVE count limits per release |
## Gate Configuration
Gates are configured via `appsettings.json` under the `Policy:Gates` section:
```json
{
"Policy": {
"Gates": {
"EpssThreshold": {
"Enabled": true,
"Threshold": 0.6
},
"KevBlocker": {
"Enabled": true,
"AllowGracePeriod": true,
"GracePeriodDays": 14
},
"ReachableCve": {
"Enabled": true,
"SeverityThreshold": 7.0
},
"CveDelta": {
"Enabled": true,
"NewCveSeverityThreshold": 7.0,
"OnlyBlockReachable": false
},
"ReleaseAggregateCve": {
"Enabled": true,
"MaxCritical": 0,
"MaxHigh": 3,
"MaxMedium": 20
}
}
}
}
```
## Environment Overrides
Each gate supports per-environment configuration overrides:
```json
{
"Policy": {
"Gates": {
"CveDelta": {
"Enabled": true,
"NewCveSeverityThreshold": 7.0,
"Environments": {
"development": {
"Enabled": false
},
"staging": {
"NewCveSeverityThreshold": 9.0
},
"production": {
"NewCveSeverityThreshold": 7.0,
"OnlyBlockReachable": true
}
}
}
}
}
}
```
## DI Registration
Register all CVE gates:
```csharp
services.AddCvePolicyGates(configuration);
```
Or register individual gates:
```csharp
services.AddEpssThresholdGate(configuration);
services.AddKevBlockerGate(configuration);
services.AddReachableCveGate(configuration);
services.AddCveDeltaGate(configuration);
services.AddReleaseAggregateCveGate(configuration);
```
## Gate Results
All gates return a `GateResult` containing:
- `GateName`: Gate identifier
- `Passed`: Boolean pass/fail status
- `Reason`: Human-readable explanation
- `Details`: Additional metadata (warnings, counts, etc.)
---
*Last updated: 2026-01-19.*

133
docs/modules/policy/gates/cve-delta.md Normal file
View File

@@ -0,0 +1,133 @@
# CVE Delta Gate
**Gate ID:** `cve-delta`
Blocks releases that introduce new high-severity CVEs compared to a baseline. This gate prevents security regressions by tracking the CVE delta between release versions.
## How It Works
1. Retrieves CVE findings for current release candidate
2. Retrieves CVE findings from baseline (previous version or reference image)
3. Computes delta: new CVEs, fixed CVEs, unchanged CVEs
4. Blocks if new CVEs exceed severity threshold
5. Optionally tracks remediation SLA for existing CVEs
## Configuration
```json
{
"Policy": {
"Gates": {
"CveDelta": {
"Enabled": true,
"NewCveSeverityThreshold": 7.0,
"OnlyBlockReachable": false,
"RemediationSlaDays": 30,
"AllowFirstRelease": true,
"Environments": {
"development": {
"NewCveSeverityThreshold": 9.0
},
"staging": {
"NewCveSeverityThreshold": 7.0,
"OnlyBlockReachable": true
},
"production": {
"NewCveSeverityThreshold": 7.0,
"OnlyBlockReachable": true,
"RemediationSlaDays": 14
}
}
}
}
}
}
```
### Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `Enabled` | bool | `true` | Whether the gate is active |
| `NewCveSeverityThreshold` | double | `7.0` | CVSS threshold for blocking new CVEs |
| `OnlyBlockReachable` | bool | `false` | Only block new CVEs with reachable code paths |
| `RemediationSlaDays` | int? | `null` | SLA days for existing CVE remediation (null = disabled) |
| `AllowFirstRelease` | bool | `true` | Allow first release without baseline |
| `Environments` | dict | `{}` | Per-environment overrides |
## Delta Computation
The gate computes three sets:
| Set | Definition | Gate Behavior |
|-----|------------|---------------|
| **New CVEs** | In current, not in baseline | Block if ≥ threshold |
| **Fixed CVEs** | In baseline, not in current | Reported as improvement |
| **Unchanged CVEs** | In both current and baseline | Subject to SLA tracking |
## Example Gate Results
**Pass:**
```
CVE delta check passed. New: 3, Fixed: 5, Unchanged: 12 (3 new low-severity allowed)
```
**Pass (with improvement):**
```
CVE delta check passed. New: 0, Fixed: 8, Unchanged: 10. Warnings: Improvement: 3 high+ severity CVE(s) fixed
```
**Fail:**
```
Release introduces 2 new CVE(s) at or above severity 7.0: CVE-2024-1234 (CVSS: 8.1, reachable), CVE-2024-5678 (CVSS: 7.3)
```
**Fail (no baseline):**
```
CVE delta gate requires baseline reference but none provided
```
**Warning (SLA):**
```
CVE delta check passed. Warnings: 3 CVE(s) past remediation SLA: CVE-2024-0001, CVE-2024-0002, CVE-2024-0003
```
## Baseline Resolution
The baseline can be provided in multiple ways:
1. **Explicit reference**: Via `--baseline` flag or context
2. **ICveDeltaProvider**: Custom provider implementation
3. **Previous deployment**: Automatically resolved from environment history
```bash
# Explicit baseline
stella policy evaluate --gate cve-delta --image myapp:v1.2.3 --baseline myapp:v1.2.2
# Baseline from previous deployment
stella policy evaluate --gate cve-delta --image myapp:v1.2.3 --env production
```
## CLI Usage
```bash
# Basic delta evaluation
stella policy evaluate --gate cve-delta --image myapp:v1.2.3 --baseline myapp:v1.2.2
# Only block reachable new CVEs
stella policy evaluate --gate cve-delta --only-reachable --image myapp:v1.2.3
# First release (no baseline)
stella policy evaluate --gate cve-delta --allow-first-release --image myapp:v1.2.3
```
## Use Cases
1. **Prevent regressions**: Block releases that add new vulnerabilities
2. **Track improvements**: Report CVEs fixed between releases
3. **SLA enforcement**: Warn on CVEs exceeding remediation timeline
4. **Base image updates**: Evaluate security impact of base image changes
---
*Last updated: 2026-01-19.*

86
docs/modules/policy/gates/epss-threshold.md Normal file
View File

@@ -0,0 +1,86 @@
# EPSS Threshold Gate
**Gate ID:** `epss-threshold`
Blocks CVEs with Exploit Prediction Scoring System (EPSS) probability above a configurable threshold. EPSS predicts the likelihood that a CVE will be exploited in the wild within 30 days.
## How It Works
1. For each CVE finding in the release candidate, queries the EPSS score
2. Compares EPSS probability against the configured threshold
3. Blocks if any CVE exceeds threshold (or all match in "all must pass" mode)
4. Provides grace period for newly published CVEs
## Configuration
```json
{
"Policy": {
"Gates": {
"EpssThreshold": {
"Enabled": true,
"Threshold": 0.6,
"Mode": "any",
"GracePeriodDays": 7,
"RequireReachability": false,
"Environments": {
"production": {
"Threshold": 0.3
}
}
}
}
}
}
```
### Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `Enabled` | bool | `true` | Whether the gate is active |
| `Threshold` | double | `0.6` | EPSS probability threshold (0.0 - 1.0) |
| `Mode` | string | `any` | `any` = block if any CVE exceeds; `all` = block only if all exceed |
| `GracePeriodDays` | int? | `null` | Days after CVE publication before enforcing (null = no grace) |
| `RequireReachability` | bool | `false` | Only evaluate reachable CVEs |
| `Environments` | dict | `{}` | Per-environment overrides |
## EPSS Score Interpretation
| EPSS Range | Risk Level | Typical Action |
|------------|------------|----------------|
| 0.0 - 0.1 | Very Low | Monitor |
| 0.1 - 0.3 | Low | Schedule remediation |
| 0.3 - 0.6 | Medium | Prioritize remediation |
| 0.6 - 0.9 | High | Block or exception required |
| 0.9 - 1.0 | Critical | Immediate block |
## Example Gate Results
**Pass:**
```
EPSS threshold check passed. 12 CVE(s) evaluated, all below threshold 0.6
```
**Fail:**
```
EPSS threshold exceeded: CVE-2024-1234 (EPSS: 0.72), CVE-2024-5678 (EPSS: 0.85)
```
## CLI Usage
```bash
# Evaluate EPSS gate against image
stella policy evaluate --gate epss-threshold --image myapp:v1.2.3
# Override threshold for testing
stella policy evaluate --gate epss-threshold --threshold 0.9 --image myapp:v1.2.3
```
## Data Source
EPSS scores are fetched from [FIRST EPSS](https://www.first.org/epss/) via the configured `IEpssDataProvider`. Scores are cached and updated daily.
---
*Last updated: 2026-01-19.*

100
docs/modules/policy/gates/kev-blocker.md Normal file
View File

@@ -0,0 +1,100 @@
# KEV Blocker Gate
**Gate ID:** `kev-blocker`
Blocks CVEs listed in the CISA Known Exploited Vulnerabilities (KEV) catalog. KEV entries represent vulnerabilities with confirmed active exploitation in the wild.
## How It Works
1. For each CVE finding in the release candidate, checks KEV catalog membership
2. Blocks any CVE present in KEV (with optional grace period)
3. Reports KEV due dates for remediation tracking
4. Optionally respects KEV due dates as soft deadlines
## Configuration
```json
{
"Policy": {
"Gates": {
"KevBlocker": {
"Enabled": true,
"AllowGracePeriod": true,
"GracePeriodDays": 14,
"BlockPastDueDate": true,
"WarnBeforeDueDate": true,
"WarnDaysBeforeDue": 7,
"RequireReachability": false,
"Environments": {
"development": {
"Enabled": false
},
"production": {
"AllowGracePeriod": false
}
}
}
}
}
}
```
### Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `Enabled` | bool | `true` | Whether the gate is active |
| `AllowGracePeriod` | bool | `true` | Allow grace period after KEV addition |
| `GracePeriodDays` | int | `14` | Days after KEV addition before blocking |
| `BlockPastDueDate` | bool | `true` | Block CVEs past their KEV due date |
| `WarnBeforeDueDate` | bool | `true` | Emit warning as due date approaches |
| `WarnDaysBeforeDue` | int | `7` | Days before due date to start warning |
| `RequireReachability` | bool | `false` | Only evaluate reachable CVEs |
| `Environments` | dict | `{}` | Per-environment overrides |
## KEV Catalog Context
The CISA KEV catalog contains:
- CVEs with confirmed active exploitation
- Required remediation due dates (typically 2-3 weeks from addition)
- Affected vendor/product information
KEV inclusion indicates:
- Real-world exploitation is occurring
- Federal agencies must remediate by due date (BOD 22-01)
- High priority for all organizations
## Example Gate Results
**Pass:**
```
KEV blocker check passed. No KEV entries found in 15 CVE findings
```
**Fail:**
```
KEV entries found: CVE-2024-1234 (due: 2024-02-15, overdue), CVE-2024-5678 (due: 2024-02-28, 5 days remaining)
```
**Warning:**
```
KEV blocker check passed. Warnings: CVE-2024-9012 KEV due date approaching (7 days)
```
## CLI Usage
```bash
# Evaluate KEV gate against image
stella policy evaluate --gate kev-blocker --image myapp:v1.2.3
# Check with no grace period
stella policy evaluate --gate kev-blocker --no-grace-period --image myapp:v1.2.3
```
## Data Source
KEV data is fetched from [CISA KEV Catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) via the configured `IKevDataProvider`. The catalog is refreshed daily with catalog update timestamps tracked for staleness detection.
---
*Last updated: 2026-01-19.*

104
docs/modules/policy/gates/reachable-cve.md Normal file
View File

@@ -0,0 +1,104 @@
# Reachable CVE Gate
**Gate ID:** `reachable-cve`
Blocks only CVEs with confirmed reachable code paths from application entry points. This gate leverages Stella's reachability analysis to distinguish exploitable vulnerabilities from those in unreachable code.
## How It Works
1. Evaluates CVE findings against reachability analysis results
2. Filters to only reachable CVEs (code path exists from entry point to vulnerable function)
3. Applies severity threshold to reachable CVEs
4. Blocks if reachable CVEs exceed severity threshold
## Configuration
```json
{
"Policy": {
"Gates": {
"ReachableCve": {
"Enabled": true,
"SeverityThreshold": 7.0,
"RequireCompleteReachability": false,
"TreatUnknownAsReachable": false,
"BlockOnReachabilityError": false,
"Environments": {
"production": {
"SeverityThreshold": 4.0,
"TreatUnknownAsReachable": true
}
}
}
}
}
}
```
### Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `Enabled` | bool | `true` | Whether the gate is active |
| `SeverityThreshold` | double | `7.0` | CVSS score threshold for reachable CVEs |
| `RequireCompleteReachability` | bool | `false` | Require reachability analysis for all components |
| `TreatUnknownAsReachable` | bool | `false` | Treat CVEs with unknown reachability as reachable |
| `BlockOnReachabilityError` | bool | `false` | Fail gate if reachability analysis fails |
| `Environments` | dict | `{}` | Per-environment overrides |
## Reachability States
| State | Description | Default Behavior |
|-------|-------------|------------------|
| `Reachable` | Code path confirmed from entry point | Subject to severity threshold |
| `NotReachable` | No code path found | Allowed (not blocked) |
| `Unknown` | Reachability not analyzed | Depends on `TreatUnknownAsReachable` |
| `Partial` | Some paths reachable | Treated as reachable |
## Example Gate Results
**Pass:**
```
Reachable CVE check passed. 8 CVE(s) found, 2 reachable, none above threshold 7.0
```
**Pass (no reachable):**
```
Reachable CVE check passed. 15 CVE(s) found, 0 reachable (all in unreachable code)
```
**Fail:**
```
Reachable high-severity CVE(s) found: CVE-2024-1234 (CVSS: 9.1, reachable via /api/upload), CVE-2024-5678 (CVSS: 7.5, reachable via /auth/login)
```
## CLI Usage
```bash
# Evaluate reachable CVE gate
stella policy evaluate --gate reachable-cve --image myapp:v1.2.3
# With specific severity threshold
stella policy evaluate --gate reachable-cve --severity 9.0 --image myapp:v1.2.3
# Treat unknown as reachable (conservative)
stella policy evaluate --gate reachable-cve --treat-unknown-reachable --image myapp:v1.2.3
```
## Integration with Reachability Analysis
This gate requires reachability analysis results from the Stella Scanner. Ensure images are scanned with reachability enabled:
```bash
stella scan --image myapp:v1.2.3 --reachability
```
Reachability analysis examines:
- Container entry points (ENTRYPOINT, CMD)
- Exposed ports and expected protocols
- Call graphs from entry points to vulnerable functions
- Language-specific dependency loading patterns
---
*Last updated: 2026-01-19.*

137
docs/modules/policy/gates/release-aggregate-cve.md Normal file
View File

@@ -0,0 +1,137 @@
# Release Aggregate CVE Gate
**Gate ID:** `release-aggregate-cve`
Enforces aggregate CVE count limits per release by severity level. Unlike per-finding gates, this gate evaluates the total CVE profile of a release candidate.
## How It Works
1. Counts CVE findings by severity (Critical, High, Medium, Low)
2. Optionally filters by suppression status and reachability
3. Compares counts against configured limits
4. Blocks if any limit is exceeded
5. Warns when counts approach limits (80% threshold)
## Configuration
```json
{
"Policy": {
"Gates": {
"ReleaseAggregateCve": {
"Enabled": true,
"MaxCritical": 0,
"MaxHigh": 3,
"MaxMedium": 20,
"MaxLow": null,
"MaxTotal": null,
"CountSuppressed": false,
"OnlyCountReachable": false,
"Environments": {
"development": {
"Enabled": false
},
"staging": {
"MaxCritical": 1,
"MaxHigh": 10
},
"production": {
"MaxCritical": 0,
"MaxHigh": 0,
"OnlyCountReachable": true
}
}
}
}
}
}
```
### Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `Enabled` | bool | `true` | Whether the gate is active |
| `MaxCritical` | int? | `0` | Maximum critical CVEs (CVSS 9.0+); null = unlimited |
| `MaxHigh` | int? | `3` | Maximum high CVEs (CVSS 7.0-8.9); null = unlimited |
| `MaxMedium` | int? | `20` | Maximum medium CVEs (CVSS 4.0-6.9); null = unlimited |
| `MaxLow` | int? | `null` | Maximum low CVEs (CVSS 0.1-3.9); null = unlimited |
| `MaxTotal` | int? | `null` | Maximum total CVEs regardless of severity; null = unlimited |
| `CountSuppressed` | bool | `false` | Include suppressed/excepted CVEs in counts |
| `OnlyCountReachable` | bool | `false` | Only count CVEs with reachable code paths |
| `Environments` | dict | `{}` | Per-environment overrides |
## Severity Classification
| CVSS Score | Severity |
|------------|----------|
| 9.0 - 10.0 | Critical |
| 7.0 - 8.9 | High |
| 4.0 - 6.9 | Medium |
| 0.1 - 3.9 | Low |
| None/Invalid | Unknown |
## Example Gate Results
**Pass:**
```
Release CVE counts within limits. Critical: 0, High: 2, Medium: 15, Low: 8
```
**Pass (with warning):**
```
Release CVE counts within limits. Critical: 0, High: 2, Medium: 15, Low: 8. Warnings: High CVE count (2) approaching limit (3)
```
**Fail:**
```
Release CVE aggregate limits exceeded: Critical: 1/0, High: 5/3
```
**Fail (total limit):**
```
Release CVE aggregate limits exceeded: Total: 55/50
```
## CLI Usage
```bash
# Evaluate aggregate gate
stella policy evaluate --gate release-aggregate-cve --image myapp:v1.2.3
# Custom limits
stella policy evaluate --gate release-aggregate-cve \
--max-critical 0 --max-high 5 --max-medium 30 \
--image myapp:v1.2.3
# Only count reachable CVEs
stella policy evaluate --gate release-aggregate-cve --only-reachable --image myapp:v1.2.3
# Include suppressed CVEs
stella policy evaluate --gate release-aggregate-cve --count-suppressed --image myapp:v1.2.3
```
## Suppression Handling
When `CountSuppressed: false` (default):
- CVEs with valid exceptions are excluded from counts
- Expired exceptions are counted
- CVEs suppressed via VEX statements are excluded
When `CountSuppressed: true`:
- All CVEs are counted regardless of suppression status
- Useful for tracking true vulnerability exposure
## Progressive Environment Strategy
Recommended limit progression:
| Environment | Critical | High | Medium | Notes |
|-------------|----------|------|--------|-------|
| Development | Disabled | - | - | No blocking in dev |
| Staging | 1 | 10 | 50 | Lenient for testing |
| Production | 0 | 0 | 20 | Strict, reachable-only |
---
*Last updated: 2026-01-19.*

326
docs/modules/ui/architecture-rework.md Normal file
View File

@@ -0,0 +1,326 @@
# UI Rework Architecture - Release Control Plane
> **Ownership:** UI Guild, Platform Team
> **Status:** Planned
> **Related:** [Current UI Architecture](architecture.md), [Wireframes](guides/wireframes-flagship-pages.md), [Migration Map](guides/migration-map.md)
This document defines the target UI architecture for Stella Ops as an **evidence-based release control plane** with **hybrid reachability** as a first-class gate and explanation layer.
---
## 0) Vision Summary
The current UI tells users "scanner + admin console." The new UI must communicate:
1. **"What is deployed where"** (by digest, per environment/target)
2. **"What is allowed to ship next"** (promotion requests + approvals)
3. **"Why it is allowed/blocked"** (policy gates + reachability evidence)
4. **"Where the evidence is"** (one-click proof chain and export)
Everything else (vuln explorer, SBOM graph, VEX hub, feeds, ops health) is supporting detail.
---
## 1) New UX Mental Model
### 1.1 Core Objects (first-class nouns everywhere)
| Object | Description |
|--------|-------------|
| **Release** | Bundle of component-to-digest mappings (immutable identity) |
| **Environment** | Dev/QA/Staging/Prod (policies, windows, approvals) |
| **Promotion** | Request to move a Release to an Environment |
| **Deployment** | Execution instance (workflow run against targets) |
| **Evidence Packet** | Signed bundle of inputs/outputs of a decision/run |
### 1.2 Core Jobs (UI must optimize for these first)
1. **Ship a release**: create -> request promotion -> approve -> deploy
2. **Explain/justify a decision**: why allowed/blocked + evidence
3. **Operate with confidence**: drift, CVE updates, replay, audit export
---
## 2) Information Architecture
### 2.1 Current Top-Level Nav (scanner-centric)
```
HOME / ANALYZE / TRIAGE / POLICY / OPS / NOTIFY / ADMIN
```
### 2.2 New Top-Level Nav (release control plane)
```
CONTROL PLANE / RELEASES / APPROVALS / SECURITY / EVIDENCE / OPERATIONS / SETTINGS
```
### 2.3 Navigation Mapping
| New Section | Contains | Replaces |
|-------------|----------|----------|
| **Control Plane** | Pipeline overview, Action Inbox, Pending Promotions, Drift/Risk | Home dashboard |
| **Releases** | Release list, Release detail, Environment detail | Release Orchestrator (hidden) |
| **Approvals** | Approval inbox, Approval detail | Release Orchestrator approvals |
| **Security** | Overview, Findings, Vulnerabilities, SBOM Graph, VEX, Exceptions | Analyze + Triage + VEX Hub |
| **Evidence** | Packets, Proof Chains, Replay/Verify, Export, Audit Bundles | Scattered evidence views |
| **Operations** | Orchestrator, Quotas, Dead-letter, SLO, Health, Feeds, Scheduler | Ops/* + Scheduler |
| **Settings** | Integrations, Trust, Admin, Notifications, Policy Governance | Console/Admin + scattered config |
---
## 3) Shell & Layout Architecture
### 3.1 Shell Blueprint
```
+------------------------------------------------------------------------------+
| Stella Ops [Global Search: release|digest|CVE|env] [Tenant] [User] |
| Offline: OK | Feed Snapshot: 2026-01-15 | Policy: v3.1 | Evidence: ON |
+---------------+--------------------------------------------------------------+
| CONTROL PLANE | Breadcrumb: Section > Page |
| RELEASES | |
| APPROVALS | <router-outlet> |
| SECURITY | |
| EVIDENCE | |
| OPERATIONS | |
| SETTINGS | |
+---------------+--------------------------------------------------------------+
```
### 3.2 Shell Components
| Component | Responsibility |
|-----------|---------------|
| `AppShellComponent` | Top-level layout with topbar + sidebar + outlet + overlay hosts |
| `AppTopbarComponent` | Global search, tenant context, status chips, user menu |
| `AppSidebarComponent` | Left navigation rail with nav groups and items |
| `BreadcrumbComponent` | Context-aware breadcrumbs from router data |
| `GlobalSearchComponent` | Unified search across releases, digests, CVEs, environments |
| `ContextChipsRowComponent` | Offline status, feed snapshot, policy baseline, evidence mode |
---
## 4) Folder Structure (Angular 17+ Standalone)
```
src/app/
core/ # auth, api client, guards, nav config, app init
layout/ # app shell, sidebar, topbar, page scaffolding
shared/
ui/ # design system primitives (buttons, chips, tables)
domain/ # domain widgets (digest chip, gate badges, evidence link)
overlays/ # drawers/modals (evidence drawer, witness drawer)
pipes/ # formatting
util/ # helpers, comparators, trackBy fns
features/
control-plane/ # / - Control Plane Overview
releases/ # /releases, /releases/:id
approvals/ # /approvals, /approvals/:id
environments/ # /environments, /environments/:id
deployments/ # /deployments, /deployments/:id
security/ # /security/*
evidence/ # /evidence/*
reachability/ # /witness/:id
operations/ # /operations/*
settings/ # /settings/*
```
---
## 5) Shared Domain Widgets (The Moat UI)
These components encode Stella's differentiators and must be consistent everywhere.
### 5.1 Digest Identity
| Component | Inputs | Behavior |
|-----------|--------|----------|
| `DigestChipComponent` | `digest`, `label?`, `variant` | Short digest display, copy on click, full on hover |
| `BundleDigestHeaderComponent` | `releaseId`, `bundleDigest`, `createdAt`, `sourceRef` | Release identity block |
### 5.2 Gate System
| Component | Inputs | Behavior |
|-----------|--------|----------|
| `GateBadgeComponent` | `state`, `label` | PASS/WARN/BLOCK badges |
| `GateSummaryPanelComponent` | `gates[]`, `policyRef`, `snapshotRef` | Compact gate list with drill-down |
| `GateExplainDrawerComponent` | `gateRunId` | K4 lattice explanation, rule hits, evidence |
### 5.3 Evidence UX
| Component | Inputs | Behavior |
|-----------|--------|----------|
| `EvidenceLinkComponent` | `evidenceId`, `type`, `verified`, `signed` | Consistent evidence link |
| `EvidencePacketSummaryComponent` | `EvidencePacketHeaderVM` | Who/What/Why/How/When audit block |
| `ProofChainLinkComponent` | `subjectDigest` | Standard proof chain entry |
### 5.4 Reachability Witness
| Component | Inputs | Behavior |
|-----------|--------|----------|
| `ReachabilityStateChipComponent` | `state`, `confidence` | Reachable/Unreachable/Uncertain + confidence |
| `WitnessPathPreviewComponent` | `path[]`, `guards`, `deterministic` | Call path preview with drill-down |
| `WitnessViewerComponent` | `witnessId` | Full witness page with exports and replay |
---
## 6) Flagship Pages
### 6.1 Control Plane Overview (`/`)
**Goal:** Answer in one screen: what's deployed, what's pending, what changed, what needs attention.
**Components:**
- `EnvironmentPipelineWidgetComponent` - Dev -> QA -> Staging -> Prod visualization
- `ActionInboxWidgetComponent` - Pending approvals, blocked promotions, failed deployments
- `DriftRiskDeltaWidgetComponent` - CVE updates, feed staleness, config drifts
- `PendingPromotionsTableComponent` - Release promotions waiting for action
### 6.2 Release Detail (`/releases/:releaseId`)
**Goal:** One flagship screen tying promotion + gates + reachability + evidence + proof chain.
**Tabs:**
- Overview (deployment map, gate summary, security impact, latest evidence)
- Components (digest inventory)
- Gates (detailed policy evaluation)
- Promotions (promotion history)
- Deployments (deployment runs)
- Evidence (linked evidence packets)
- Proof Chain (full proof chain viewer)
### 6.3 Approval Detail (`/approvals/:approvalId`)
**Goal:** Everything needed to make a decision without navigating away.
**Panels:**
- Diff-first panel (what changed)
- Gates panel (expandable gate results)
- Decision panel (approve/reject/comment)
- Reachability Witness panel (the moat)
- Evidence quick panel
### 6.4 Evidence Packet Viewer (`/evidence/:evidenceId`)
**Goal:** Evidence as structured "who/what/why/how/when" record + bundle contents + verify.
**Sections:**
- Summary (audit-friendly header)
- Contents (SBOM, verdict, witness slice, VEX, attestations)
- Verification (signature + Rekor inclusion proofs)
---
## 7) State Management
### 7.1 Signal Store Pattern
Each major page/container has a dedicated store service:
```typescript
@Injectable()
export class ReleaseDetailStore {
private state = signal<ReleaseDetailState>({ ... });
release = computed(() => this.state().release);
gateSummary = computed(() => this.state().gateSummary);
load(releaseId: string) { /* triggers effects + sets loading/error */ }
refresh() { /* re-runs queries */ }
requestPromotion() { /* command method */ }
}
```
### 7.2 Cross-Cutting Stores
| Store | Responsibility |
|-------|---------------|
| `AppContextStore` | Tenant, user, offline mode, feed snapshot, evidence mode |
| `GlobalSearchStore` | Query -> aggregated results across types |
| `OverlayStore` | Open/close drawers (evidence, witness, gate explain) |
---
## 8) Overlays (Drawers/Modals)
Essential for "small pages, deep drill-down" requirement:
| Overlay | Purpose |
|---------|---------|
| `EvidencePacketDrawerComponent` | Opens from anywhere; condensed evidence view |
| `WitnessDrawerComponent` | Preview witness path + quick export + open full |
| `GateExplainDrawerComponent` | K4 lattice reasoning + rule hits + evidence anchors |
| `CreateReleaseModalComponent` | New release creation flow |
| `RequestPromotionModalComponent` | Promotion request flow |
| `RollbackModalComponent` | Rollback confirmation |
| `RequestExceptionModalComponent` | Exception request flow |
---
## 9) UX Contracts
### 9.1 Gate State Presentation
| State | Badge | Color |
|-------|-------|-------|
| PASS | `[PASS]` | Green |
| WARN | `[WARN]` | Amber |
| BLOCK | `[BLOCK]` | Red |
Always show with one-line reason.
### 9.2 Reachability State Presentation
| State | Display |
|-------|---------|
| Reachable | State + Confidence + Witness link |
| Unreachable | State + Confidence (0.90+) |
| Uncertain | State + Confidence + "why uncertain" + resolution hints |
### 9.3 Digest Visibility
- Show short digest everywhere (`sha256:abc...123`)
- Full digest on hover/copy
- Copy buttons for operational fields
### 9.4 Evidence Traceability
- Policy baseline version shown where decisions are made
- Feed snapshot version shown where decisions are made
- "Open Evidence" and "Open Proof Chain" always one click away
---
## 10) Implementation Priority
### Phase 1 (Highest ROI)
1. **Make `/` the Control Plane Overview** (pipeline + inbox + drift)
2. **Consolidate Settings** (stop configuration fragmentation)
3. **Make Approvals evidence-first with reachability witness** (moat on display)
### Phase 2 (Core Product)
4. Shell & navigation redesign (left rail)
5. Releases feature (list + detail flagship)
6. Evidence unification
### Phase 3 (Polish)
7. Security consolidation (merge Analyze + Triage)
8. Environments & Deployments features
9. Route migration & legacy redirect telemetry
---
## 11) Related Documentation
- [Wireframes](guides/wireframes-flagship-pages.md) - ASCII wireframes for flagship pages
- [Migration Map](guides/migration-map.md) - Route migration from current to new IA
- [Component Breakdown](guides/component-breakdown.md) - Detailed Angular component inventory
- [Current Architecture](architecture.md) - Existing UI architecture reference
---
*Last updated: 2026-01-18*

50
docs/modules/ui/components/README.md
View File

@@ -46,6 +46,56 @@ Findings can have special flags indicating evidence quality:
| `anchored` | [A] | Violet | Score anchored with DSSE/Rekor attestation |
| `hard-fail` | [!] | Red | Policy hard-fail triggered |
## Witness Visualization Components
> **Sprint:** SPRINT_20260118_020_FE_witness_visualization
The witness visualization component suite provides UI for runtime witness display, static vs runtime path comparison, and witness gate results in release promotion flows.
### Components
| Component | Purpose | Location |
|-----------|---------|----------|
| [WitnessStatusChip](./witness-visualization.md#witness-status-chip) | Status badge showing witness state (witnessed/unwitnessed/stale/failed) | `shared/domain/witness-status-chip/` |
| [WitnessComparison](./witness-visualization.md#witness-comparison-component) | Side-by-side static vs runtime path comparison | `shared/components/witness-comparison/` |
| [UnwitnessedAdvisory](./witness-visualization.md#unwitnessed-advisory-component) | Advisory panel for paths without witnesses | `shared/components/unwitnessed-advisory/` |
| [GateSummaryPanel](./witness-visualization.md#gate-summary-panel-extended) | Extended gate summary with witness metrics | `shared/domain/gate-summary-panel/` |
### Witness States
| State | Badge Color | Description |
|-------|-------------|-------------|
| `witnessed` | Green | Path confirmed by runtime observation |
| `unwitnessed` | Yellow | Path not yet observed at runtime |
| `stale` | Orange | Witness data is outdated |
| `failed` | Red | Witness verification failed |
### Usage
```typescript
import {
WitnessStatusChipComponent,
WitnessComparisonComponent,
UnwitnessedAdvisoryComponent,
GateSummaryPanelComponent,
} from '@app/shared/domain';
```
```html
<!-- Witness Status Chip -->
<app-witness-status-chip [status]="'witnessed'" [showCount]="true" />
<!-- Witness Comparison -->
<app-witness-comparison [data]="comparisonData" (stepClick)="onStepClick($event)" />
<!-- Unwitnessed Advisory -->
<app-unwitnessed-advisory [data]="advisoryData" (createTestTask)="onCreateTask($event)" />
```
See [witness-visualization.md](./witness-visualization.md) for full documentation.
---
## Grey Queue Components
> **Sprint:** SPRINT_20260112_011_FE_policy_unknowns_queue_integration

352
docs/modules/ui/components/witness-visualization.md Normal file
View File

@@ -0,0 +1,352 @@
# Witness Visualization Components
> **Sprint:** SPRINT_20260118_020_FE_witness_visualization
The witness visualization component suite provides UI for displaying runtime witness data, comparing static analysis paths with runtime observations, and managing witness gate results in release promotion flows.
## Overview
Runtime witnesses confirm that static analysis reachability paths are actually exercised during application execution. These components visualize:
- **Witness Status**: Whether a path has been witnessed at runtime
- **Static vs Runtime Comparison**: Side-by-side or overlay views comparing predicted and observed paths
- **Gate Results**: Witness gate outcomes for release promotion decisions
- **Unwitnessed Advisories**: Paths requiring runtime exercise before promotion
## Components
### Core Components
| Component | Purpose | Location |
|-----------|---------|----------|
| `WitnessStatusChipComponent` | Status badge showing witness state | `shared/domain/witness-status-chip/` |
| `WitnessComparisonComponent` | Static vs runtime path comparison | `shared/components/witness-comparison/` |
| `UnwitnessedAdvisoryComponent` | Advisory panel for unwitnessed paths | `shared/components/unwitnessed-advisory/` |
| `GateSummaryPanelComponent` | Gate results with witness metrics | `shared/domain/gate-summary-panel/` |
### Witness Status Chip
Displays the witness status of a reachability path with color-coded badges.
```typescript
import { WitnessStatusChipComponent, WitnessStatus } from '@app/shared/domain/witness-status-chip';
```
#### States
| State | Color | Icon | Description |
|-------|-------|------|-------------|
| `witnessed` | Green | ✓ | Path confirmed by runtime observation |
| `unwitnessed` | Yellow | ○ | Path not yet observed at runtime |
| `stale` | Orange | ⏱ | Witness data is outdated |
| `failed` | Red | ✗ | Witness verification failed |
#### Usage
```html
<!-- Basic usage -->
<app-witness-status-chip [status]="'witnessed'" />
<!-- With details for tooltip -->
<app-witness-status-chip
[status]="'witnessed'"
[details]="{
status: 'witnessed',
lastObserved: '2026-01-15T10:30:00Z',
observationCount: 42,
rekorLogIndex: 12345
}"
[showCount]="true"
(chipClick)="onChipClick()"
/>
```
#### Input Properties
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `status` | `WitnessStatus` | required | Witness status to display |
| `details` | `WitnessStatusDetails` | `null` | Optional metadata for tooltip |
| `showCount` | `boolean` | `true` | Whether to show observation count |
---
### Witness Comparison Component
Side-by-side or overlay view comparing static analysis paths with runtime observations. The main visualization for understanding witness coverage.
```typescript
import {
WitnessComparisonComponent,
WitnessComparisonData,
ComparisonPathStep,
ComparisonMetrics,
} from '@app/shared/components/witness-comparison';
```
#### Features
- **View Modes**: List view (vertical) or overlay view (side-by-side columns)
- **Color Coding**: Green (confirmed), yellow (static only), orange (runtime only/unexpected)
- **Filtering**: Filter by confirmation status
- **Metrics Summary**: Totals and confirmation rate display
- **Step Drill-down**: Click steps for detailed information
#### Usage
```html
<app-witness-comparison
[data]="comparisonData"
(stepClick)="onStepClick($event)"
(refresh)="onRefresh()"
/>
```
#### Input Properties
| Property | Type | Description |
|----------|------|-------------|
| `data` | `WitnessComparisonData` | Comparison data with paths and metrics |
#### Output Events
| Event | Type | Description |
|-------|------|-------------|
| `stepClick` | `ComparisonPathStep` | Emitted when user clicks a step |
| `refresh` | `void` | Emitted when user requests data refresh |
#### Data Models
```typescript
interface ComparisonPathStep {
nodeId: string;
symbol: string;
file?: string;
line?: number;
package?: string;
inStatic: boolean; // Found in static analysis
inRuntime: boolean; // Observed at runtime
runtimeInvocations?: number;
lastObserved?: string;
}
interface ComparisonMetrics {
totalSteps: number;
confirmedSteps: number; // Both static and runtime
staticOnlySteps: number; // Static only (unwitnessed)
runtimeOnlySteps: number; // Runtime only (unexpected)
confirmationRate: number; // Percentage confirmed
}
interface WitnessComparisonData {
claimId: string;
cveId?: string;
packageName: string;
packageVersion?: string;
pathSteps: ComparisonPathStep[];
metrics: ComparisonMetrics;
generatedAt: string;
}
```
---
### Unwitnessed Advisory Component
Advisory panel displayed when release promotion encounters paths without runtime witnesses. Used in the gate flow to inform operators about witness coverage gaps.
```typescript
import {
UnwitnessedAdvisoryComponent,
UnwitnessedAdvisoryData,
UnwitnessedPath,
} from '@app/shared/components/unwitnessed-advisory';
```
#### Features
- **Severity Summary**: Visual breakdown by vulnerability severity
- **Path List**: Sortable list of unwitnessed paths
- **Blocking/Advisory Mode**: Different styling based on gate configuration
- **Action Buttons**: Create test tasks for individual paths or all at once
#### Usage
```html
<app-unwitnessed-advisory
[data]="advisoryData"
(createTestTask)="onCreateTestTask($event)"
(createAllTestTasks)="onCreateAllTestTasks()"
(viewComparison)="onViewComparison()"
/>
```
#### Input Properties
| Property | Type | Description |
|----------|------|-------------|
| `data` | `UnwitnessedAdvisoryData` | Advisory data with paths and configuration |
#### Output Events
| Event | Type | Description |
|-------|------|-------------|
| `createTestTask` | `UnwitnessedPath` | Create test task for specific path |
| `createAllTestTasks` | `void` | Create test tasks for all paths |
| `viewComparison` | `void` | Open full comparison view |
#### Data Models
```typescript
interface UnwitnessedPath {
pathId: string;
cveId?: string;
vulnId: string;
packageName: string;
packageVersion?: string;
entrypoint: string;
sink: string;
severity: 'critical' | 'high' | 'medium' | 'low' | 'unknown';
confidence: number;
lastAnalyzed?: string;
}
interface UnwitnessedAdvisoryData {
totalUnwitnessed: number;
paths: UnwitnessedPath[];
targetEnvironment?: string;
isBlocking: boolean;
}
```
---
### Gate Summary Panel (Extended)
Extended to support witness gate display with metrics, expandable details, and comparison links.
```typescript
import {
GateSummaryPanelComponent,
GateResult,
WitnessGateMetrics,
WitnessPathSummary,
} from '@app/shared/domain/gate-summary-panel';
```
#### Witness Gate Support
The `GateResult` interface now supports witness-specific properties:
```typescript
interface GateResult {
id: string;
name: string;
state: 'PASS' | 'WARN' | 'BLOCK' | 'SKIP';
reason?: string;
ruleHits?: number;
gateType?: 'standard' | 'witness' | 'cve' | 'sbom';
witnessMetrics?: WitnessGateMetrics;
}
interface WitnessGateMetrics {
totalPaths: number;
witnessedPaths: number;
unwitnessedPaths: number;
stalePaths?: number;
unwitnessedPathDetails?: WitnessPathSummary[];
}
interface WitnessPathSummary {
pathId: string;
entrypoint: string;
sink: string;
severity?: 'critical' | 'high' | 'medium' | 'low' | 'unknown';
vulnId?: string;
}
```
#### Usage
```html
<app-gate-summary-panel
[gates]="gates"
[policyRef]="policyReference"
[snapshotRef]="snapshotReference"
(openExplain)="onOpenExplain($event)"
(openEvidence)="onOpenEvidence()"
(openComparison)="onOpenComparison($event)"
/>
```
#### Witness Gate Features
- **Metrics Display**: Shows X/Y witnessed paths, unwitnessed count, stale count
- **Advisory Styling**: Yellow border and background for WARN state witness gates
- **Expandable Details**: Click "Details" to see unwitnessed path list
- **Compare Button**: Opens full comparison view
---
## Color Coding Reference
### Comparison States
| State | Color | CSS Variable | Meaning |
|-------|-------|--------------|---------|
| Confirmed | Green | `--green-500` | Path in both static and runtime |
| Static Only | Yellow | `--yellow-500` | Path predicted but not observed |
| Runtime Only | Orange | `--orange-500` | Unexpected path observed |
### Severity Colors
| Severity | Color | CSS Variable |
|----------|-------|--------------|
| Critical | Red | `--red-500` |
| High | Orange | `--orange-500` |
| Medium | Yellow | `--yellow-500` |
| Low | Blue | `--blue-500` |
| Unknown | Gray | `--gray-400` |
---
## Integration with Existing Components
The witness visualization components integrate with several existing UI elements:
| Existing Component | Integration |
|--------------------|-------------|
| `WitnessDrawerComponent` | Can embed comparison view |
| `WitnessPageComponent` | Full reachability analysis page |
| `TimelineListComponent` | Display witness observation timeline |
| `GateExplainDrawerComponent` | Show witness gate explanation |
---
## Accessibility
All witness visualization components follow WCAG 2.1 AA guidelines:
- ARIA labels for all interactive elements
- Keyboard navigation support
- Focus management for expandable sections
- Color + icon combinations (not color alone)
- Screen reader announcements for status changes
---
## Testing
Unit tests are located alongside components:
- `witness-status-chip.component.spec.ts`
- `witness-comparison.component.spec.ts`
- `unwitnessed-advisory.component.spec.ts`
- `gate-summary-panel.component.spec.ts`
Run tests:
```bash
cd src/Web/StellaOps.Web
npm test -- --include="**/*witness*" --include="**/*gate-summary*"
```

209
docs/modules/ui/guides/setup-guide.md Normal file
View File

@@ -0,0 +1,209 @@
# UI Setup Wizard Guide
This guide covers the web-based Setup Wizard for initial configuration of Stella Ops.
## Overview
The Setup Wizard guides you through configuring all required and optional components. Both CLI and UI setup wizards follow the same **Infrastructure-First** order and provide identical capabilities.
## Accessing the Setup Wizard
Navigate to `/setup` in your browser to access the Setup Wizard. The wizard is available when:
- First-time installation (no configuration exists)
- Explicitly navigating to `/setup` as an administrator
- Using reconfiguration mode to modify existing settings
## Setup Steps
Steps are organized in phases. Required steps must be completed; optional steps can be skipped.
### Phase 1: Core Infrastructure (Required)
| Step | Description |
|------|-------------|
| **Database** | PostgreSQL connection for persistent storage |
| **Cache** | Valkey/Redis connection for caching and distributed locks |
| **Migrations** | Apply database schema migrations |
### Phase 2: Security Foundation (Required)
| Step | Description |
|------|-------------|
| **Authority** | Authentication provider (Standard or LDAP) |
| **Users** | Initial super user account (skipped if LDAP selected) |
| **Crypto** | Cryptographic provider for signing/encryption |
### Phase 3: Secrets Management (Optional)
| Step | Description | Configure Later |
|------|-------------|-----------------|
| **Vault** | External secrets vault (HashiCorp Vault, Azure Key Vault, AWS Secrets Manager, GCP Secret Manager) | Settings > Trust & Signing |
### Phase 4: Integrations (Optional)
| Step | Description | Configure Later |
|------|-------------|-----------------|
| **Registry** | Container registries for image scanning (supports multiple) | Settings > Integrations |
| **SCM** | Source control connections (supports multiple) | Settings > Integrations |
| **Sources** | Advisory data sources (NVD, GHSA, OSV, VEX feeds, custom mirrors) | Settings > Security Data |
### Phase 5: Observability (Optional)
| Step | Description | Configure Later |
|------|-------------|-----------------|
| **Telemetry** | OpenTelemetry configuration | Settings > System > Telemetry |
| **Notify** | Notification channels (supports multiple) | Settings > Notifications |
### Phase 6: AI Features (Optional)
| Step | Description | Configure Later |
|------|-------------|-----------------|
| **LLM** | AI/LLM provider for AdvisoryAI (OpenAI, Claude, Gemini, Ollama) | Settings > Integrations > AdvisoryAI |
### Phase 7: Configuration Store (Optional)
| Step | Description | Configure Later |
|------|-------------|-----------------|
| **Settings Store** | External configuration store (Consul, etcd, Azure App Config, AWS) | Settings > System |
### Phase 8: Release Orchestration (Optional)
| Step | Description | Configure Later |
|------|-------------|-----------------|
| **Environments** | Define deployment environments (dev, staging, production) | Settings > Environments |
| **Agents** | Register deployment agents | Settings > Agents |
## Multiple Integrations
The **Registry**, **SCM**, and **Notify** steps support configuring multiple instances:
### Container Registries
Add multiple registries for different purposes:
- Production registry (e.g., ECR, GCR)
- Development registry (e.g., Harbor)
- Third-party images (e.g., Docker Hub)
One registry can be marked as **Primary** for default operations.
### Source Control Connections
Add connections to multiple SCM providers:
- Main organization GitHub
- Internal GitLab instance
- Partner organization Bitbucket
One connection can be marked as **Primary** for default operations.
### Notification Channels
Add multiple notification destinations:
- Operations team Slack channel
- Security team email distribution
- Custom webhook for SIEM integration
All channels can receive notifications based on event rules.
## Wizard Navigation
### Progress Indicator
The left sidebar shows:
- Completed steps (green checkmark)
- Current step (highlighted)
- Pending steps (gray)
- Skipped steps (dash)
### Step Actions
Each step provides:
- **Test Connection**: Validate configuration without applying
- **Apply Configuration**: Save and validate the step
- **Skip this step**: Available for optional steps
### Skip Warnings
When skipping optional steps, warnings explain the implications:
| Skipped Step | Warning |
|--------------|---------|
| Vault | Secrets stored in configuration files (less secure) |
| Registry | Container scanning capabilities limited |
| SCM | Pipeline integration unavailable |
| Sources | Advisory feeds require manual updates |
| Telemetry | System observability limited |
| LLM | AdvisoryAI features unavailable |
| Environments | Manual deployment tracking only |
| Agents | Release orchestration unavailable |
## Cryptographic Provider Selection
The **Crypto** step allows selecting regional cryptographic standards:
| Provider | Standards | Use Case |
|----------|-----------|----------|
| **Default** | AES-256-GCM, SHA-256/512, Ed25519, ECDSA P-256 | General use |
| **FIPS 140-2** | FIPS-compliant algorithms with optional HSM | US government compliance |
| **GOST R 34.10-2012** | Kuznechik/Magma, Streebog, GOST signatures | Russian compliance |
| **SM2/SM3** | SM4, SM3, SM2 | Chinese national standards |
## Advisory Data Sources
The **Sources** step supports multiple feed types:
### CVE/Vulnerability Feeds
- NVD (NIST National Vulnerability Database)
- GHSA (GitHub Security Advisories)
- OSV (Open Source Vulnerabilities)
- Distribution feeds (Red Hat, Ubuntu, Debian, Alpine, Wolfi)
### VEX Sources
- CSAF VEX feeds from vendors
- OpenVEX format feeds
- CycloneDX BOM with embedded VEX
### Custom Mirrors
- Self-hosted advisory mirrors for air-gapped environments
- Supports Basic Auth, Bearer Token, or mTLS authentication
- Configurable sync intervals
## Environment Patterns
The **Environments** step provides quick-start patterns:
| Pattern | Environments | Description |
|---------|--------------|-------------|
| **Standard** | Dev > Staging > Production | Common three-tier pipeline |
| **Simple** | Staging > Production | Minimal two-tier setup |
| **Extended** | Dev > QA > Staging > Pre-Prod > Production | Enterprise pipeline |
| **Custom** | User-defined | Flexible custom configuration |
## Resuming Setup
If setup is interrupted:
1. Return to `/setup` to resume where you left off
2. Session state is preserved automatically
3. Completed steps remain configured
## Reconfiguration Mode
To modify existing configuration:
1. Navigate to `/setup?mode=reconfigure`
2. Previously configured steps show current values
3. Modify and re-apply any step as needed
## Keyboard Navigation
| Key | Action |
|-----|--------|
| Tab | Move between form fields |
| Enter | Submit current form / Activate button |
| Escape | Cancel current operation |
## Accessibility
The Setup Wizard follows WCAG 2.1 AA guidelines:
- All form fields have associated labels
- Error messages are announced to screen readers
- Focus is managed through step transitions
- Color is not the only indicator of status
## Related Documentation
- [CLI Setup Guide](../../cli/guides/setup-guide.md) - Command-line setup
- [Settings Architecture](../architecture.md) - Settings page structure
- [API Strategy](../api-strategy.md) - Backend API contracts

119
docs/modules/unknowns/grey-queue-state-machine.md Normal file
View File

@@ -0,0 +1,119 @@
# Grey Queue State Machine
Sprint: SPRINT_20260118_018_Unknowns_queue_enhancement (UQ-005)
## State Diagram
```mermaid
stateDiagram-v2
[*] --> Pending: Entry created
Pending --> Processing: Start processing
Pending --> UnderReview: Assign to reviewer
Pending --> Expired: TTL exceeded
Pending --> Dismissed: Manual dismissal
Processing --> Retrying: Processing failed (retry)
Processing --> UnderReview: Needs human review
Processing --> Resolved: Successfully resolved
Processing --> Failed: Max attempts exhausted
Retrying --> Processing: Retry attempt
Retrying --> Failed: Max attempts exhausted
Retrying --> Expired: TTL exceeded
UnderReview --> Escalated: Escalate to security
UnderReview --> Resolved: Reviewer resolves
UnderReview --> Rejected: Reviewer rejects
UnderReview --> Pending: Unassign (reset)
Escalated --> Resolved: Security resolves
Escalated --> Rejected: Security rejects
Escalated --> UnderReview: De-escalate
Rejected --> Pending: Reopen
Failed --> Pending: Reset for retry
Dismissed --> Pending: Reopen
Resolved --> [*]
Expired --> [*]
```
## States
| State | Description | Entry Criteria | Exit Criteria |
|-------|-------------|----------------|---------------|
| **Pending** | Awaiting initial processing | Entry created | Processing started, assigned, expired, or dismissed |
| **Processing** | Actively being processed by automation | Processing started | Retry, human review, resolved, or failed |
| **Retrying** | Waiting for retry after failed attempt | Processing failed | Retry attempt, max attempts, or TTL |
| **UnderReview** | Assigned to human reviewer | Needs human decision | Escalated, resolved, rejected, or unassigned |
| **Escalated** | Promoted to security team | Reviewer escalates | Security team decision |
| **Resolved** | Evidence now sufficient (terminal) | Automated or manual resolution | N/A |
| **Rejected** | Invalid or not actionable | Reviewer/security rejects | Can be reopened |
| **Failed** | Exhausted all retries (terminal-ish) | Max attempts exceeded | Can be reset |
| **Expired** | TTL exceeded (terminal) | Time limit reached | N/A |
| **Dismissed** | Manually dismissed (terminal-ish) | Operator dismissal | Can be reopened |
## State Requirements
### UnderReview
- **Requires**: `assignee` field must be set
- **Triggers**: Assignment notification to reviewer
- **Validation**: Cannot transition without assignee
### Escalated
- **Requires**: `escalation_reason` field
- **Triggers**: Notification to security team
- **Sets**: `escalated_at` timestamp
### Rejected
- **Records**: Reason and who rejected
- **Allows**: Reopening back to Pending
## Valid Transitions
```
Pending → [Processing, UnderReview, Expired, Dismissed]
Processing → [Retrying, UnderReview, Resolved, Failed]
Retrying → [Processing, Failed, Expired]
UnderReview → [Escalated, Resolved, Rejected, Pending]
Escalated → [Resolved, Rejected, UnderReview]
Resolved → [] (terminal)
Rejected → [Pending]
Failed → [Pending]
Expired → [] (terminal)
Dismissed → [Pending]
```
## Transition Audit
All transitions are recorded in `grey_queue_state_transitions` table:
| Column | Description |
|--------|-------------|
| `entry_id` | Grey queue entry reference |
| `from_state` | Previous state |
| `to_state` | New state |
| `transitioned_by` | User who triggered transition |
| `reason` | Optional reason for transition |
| `transitioned_at` | Timestamp |
| `metadata` | Additional context (JSONB) |
## API Endpoints
| Endpoint | Transition |
|----------|------------|
| `POST /api/grey-queue/{id}/assign` | → UnderReview |
| `POST /api/grey-queue/{id}/escalate` | → Escalated |
| `POST /api/grey-queue/{id}/reject` | → Rejected |
| `POST /api/grey-queue/{id}/reopen` | → Pending |
| `POST /api/grey-queue/{id}/resolve` | → Resolved |
| `POST /api/grey-queue/{id}/dismiss` | → Dismissed |
| `GET /api/grey-queue/{id}/transitions` | Get valid next states |
## Code Reference
- State enum: `src/Unknowns/__Libraries/StellaOps.Unknowns.Core/Models/GreyQueueEntry.cs`
- State machine: `GreyQueueStateMachine` class in same file
- Endpoints: `src/Unknowns/StellaOps.Unknowns.WebService/Endpoints/GreyQueueEndpoints.cs`
- Migration: `devops/database/migrations/V20260119_001__Add_UnderReview_Escalated_Rejected_States.sql`

212
docs/operations/artifact-migration-runbook.md Normal file
View File

@@ -0,0 +1,212 @@
# Artifact Store Migration Runbook
Sprint: SPRINT_20260118_017_Evidence_artifact_store_unification (AS-006)
## Overview
This runbook covers the migration of existing evidence from legacy artifact stores to the unified ArtifactStore.
## Migration Sources
| Source | Legacy Path | Description |
|--------|-------------|-------------|
| EvidenceLocker | `tenants/{tenantId}/bundles/{bundleId}/{sha256}-{name}` | Evidence bundles |
| Attestor | `attest/dsse/{bundleSha256}.json` | DSSE envelopes |
| Vex | `{prefix}/{format}/{digest}.{ext}` | VEX documents |
## Target Path Convention
All artifacts are migrated to: `/artifacts/{bom-ref-encoded}/{serialNumber}/{artifactId}.json`
## Pre-Migration Checklist
- [ ] Backup existing S3 buckets
- [ ] Verify PostgreSQL backup is current
- [ ] Ensure sufficient storage for duplicated data
- [ ] Review migration in dry-run mode first
- [ ] Notify stakeholders of potential service impact
## Running the Migration
### Dry Run (Recommended First Step)
```bash
stella artifacts migrate --source all --dry-run --output migration-preview.json
```
### Full Migration
```bash
# Migrate all sources with default settings
stella artifacts migrate --source all
# Migrate with increased parallelism
stella artifacts migrate --source all --parallelism 8 --batch-size 200
# Migrate specific source
stella artifacts migrate --source evidence --output migration-report.json
# Migrate specific tenant
stella artifacts migrate --source all --tenant <tenant-uuid>
```
### Resuming Failed Migration
```bash
# Use checkpoint ID from previous run
stella artifacts migrate --source all --resume-from <checkpoint-id>
```
## Progress Monitoring
The CLI displays real-time progress:
```
Progress: 1500/10000 (15.0%) - Success: 1495, Failed: 3, Skipped: 2
```
## Rollback Procedure
### When to Rollback
- Migration corrupted data
- Performance degradation after migration
- Business-critical bug discovered
### Rollback Steps
#### 1. Stop New Writes to Unified Store
```bash
# Disable unified store in configuration
kubectl set env deployment/evidence-locker ARTIFACT_STORE_UNIFIED_ENABLED=false
kubectl set env deployment/attestor ARTIFACT_STORE_UNIFIED_ENABLED=false
```
#### 2. Revert Application Configuration
```yaml
# etc/appsettings.yaml
artifactStore:
useUnifiedStore: false
legacyMode: true
```
#### 3. Clear Unified Store Index
```sql
-- Clear PostgreSQL index (preserves S3 data)
TRUNCATE TABLE artifact_store.artifacts;
```
#### 4. (Optional) Remove Migrated S3 Objects
```bash
# Only if disk space is critical and you're certain about rollback
# WARNING: This is destructive!
aws s3 rm s3://artifacts-bucket/artifacts/ --recursive
```
#### 5. Restart Services
```bash
kubectl rollout restart deployment/evidence-locker
kubectl rollout restart deployment/attestor
```
#### 6. Verify Legacy Stores Work
```bash
# Test evidence retrieval
stella evidence get --bundle-id <test-bundle>
# Test attestation retrieval
stella attestor get --digest <test-digest>
```
## Post-Migration Validation
### Verify Artifact Counts
```sql
-- Count migrated artifacts by source
SELECT
CASE
WHEN storage_key LIKE '%evidence%' THEN 'evidence'
WHEN storage_key LIKE '%dsse%' THEN 'attestor'
WHEN storage_key LIKE '%vex%' THEN 'vex'
ELSE 'unknown'
END as source,
COUNT(*) as count
FROM artifact_store.artifacts
GROUP BY 1;
```
### Verify bom-ref Extraction
```sql
-- Check for artifacts with synthetic bom-refs (extraction failed)
SELECT COUNT(*) as synthetic_count
FROM artifact_store.artifacts
WHERE bom_ref LIKE 'sha256:%';
```
### Test Retrieval
```bash
# Query by bom-ref
curl "https://api.example.com/api/v1/artifacts?bom_ref=pkg:docker/acme/api@sha256:abc123"
# Verify content matches original
stella artifacts compare \
--original tenants/xxx/bundles/yyy/sha256-sbom.json \
--migrated /artifacts/encoded-ref/serial/artifact.json
```
## Troubleshooting
### Migration Stuck
```bash
# Check for stuck workers
ps aux | grep migrate
# Check migration checkpoints
cat /var/lib/stella/migration-checkpoint.json
```
### High Failure Rate
1. Check migration report for common errors
2. Verify source store connectivity
3. Check for corrupted source artifacts
4. Increase batch size for memory issues
### Slow Migration
1. Increase parallelism (up to CPU count)
2. Run during off-peak hours
3. Consider migrating by tenant in parallel
4. Verify network bandwidth to S3
## Representative Dataset Testing
Before production migration, test with representative dataset:
```bash
# Export sample from each source
stella evidence list --limit 100 --output sample-evidence.json
stella attestor list --limit 100 --output sample-attestor.json
# Create test environment with samples
stella artifacts migrate --source all --tenant test-tenant --output test-report.json
# Verify counts and content
diff <(cat sample-evidence.json | jq '.total') <(cat test-report.json | jq '.succeeded')
```
## Related Documentation
- [Artifact Store API](../api/artifact-store-api.yaml)
- [IArtifactStore Interface](../../src/__Libraries/StellaOps.Artifact.Core/IArtifactStore.cs)
- [PostgreSQL Index Schema](../../src/__Libraries/StellaOps.Artifact.Infrastructure/Migrations/001_artifact_index_schema.sql)

177
docs/operations/unknowns-queue-runbook.md
View File

@@ -494,71 +494,142 @@ stella unknowns resolve unk-... \
## 7. Monitoring & Alerting
> **Updated**: Sprint SPRINT_20260118_018_Unknowns_queue_enhancement (UQ-007)
### 7.1 Key Metrics
| Metric | Description | Alert Threshold |
|--------|-------------|-----------------|
| `unknowns_total` | Total unknowns in queue | > 500 |
| `unknowns_hot_count` | HOT band count | > 20 |
| `unknowns_sla_breached` | SLA breaches | > 0 |
| `unknowns_resolution_rate` | Daily resolutions | < 5 |
| `unknowns_escalation_failures` | Failed escalations | > 0 |
| `unknowns_avg_age_hours` | Average unknown age | > 168 (1 week) |
| `unknowns_queue_depth_hot` | HOT band queue depth | > 5 critical, > 0 for 1h warning |
| `unknowns_queue_depth_warm` | WARM band queue depth | > 25 warning |
| `unknowns_queue_depth_cold` | COLD band queue depth | > 100 warning |
| `unknowns_sla_compliance` | SLA compliance rate (0-1) | < 0.80 critical, < 0.95 warning |
| `unknowns_sla_breach_total` | Total SLA breaches (counter) | increase > 0 |
| `unknowns_escalated_total` | Escalations (counter) | rate > 10/hour |
| `unknowns_demoted_total` | Demotions (counter) | - |
| `unknowns_expired_total` | Expirations (counter) | - |
| `unknowns_processing_time_seconds` | Processing time histogram | p95 > 30s |
| `unknowns_resolution_time_hours` | Resolution time by band | p95 > SLA |
| `unknowns_state_transitions_total` | State transitions (by from/to) | - |
| `greyqueue_stuck_total` | Stuck processing entries | > 0 |
| `greyqueue_timeout_total` | Processing timeouts | > 5/hour |
| `greyqueue_processing_count` | Currently processing | > 10 for 30m |
### 7.2 Grafana Dashboard
```
Dashboard: Unknowns Queue Health
Panels:
- Queue size by band (HOT/WARM/COLD)
- SLA compliance rate
- Unknowns by reason code
- Resolution velocity
- Escalation success rate
- Queue age distribution
- KEV item tracking
```
Import dashboard from: `devops/observability/grafana/dashboards/unknowns-queue-dashboard.json`
**Dashboard Panels:**
| Panel | Description |
|-------|-------------|
| Total Queue Depth | Stat showing total across all bands |
| HOT/WARM/COLD Unknowns | Individual band stats with thresholds |
| SLA Compliance | Gauge showing compliance percentage |
| Queue Depth Over Time | Time series by band |
| SLA Compliance Over Time | Trending compliance |
| State Transitions | Rate of state changes |
| Processing Time (p95) | Performance histogram |
| Escalations & Failures | Lifecycle events |
| Resolution Time by Band | Time-to-resolution |
| Stuck & Timeout Events | Watchdog metrics |
| SLA Breaches Today | 24h breach counter |
### 7.3 Alerting Rules
```yaml
groups:
- name: unknowns-queue
rules:
- alert: UnknownsHotBandHigh
expr: unknowns_hot_count > 20
for: 5m
labels:
severity: warning
annotations:
summary: "HOT unknowns queue is high ({{ $value }} items)"
- alert: UnknownsSLABreach
expr: unknowns_sla_breached > 0
for: 1m
labels:
severity: critical
annotations:
summary: "{{ $value }} unknowns have breached SLA"
- alert: UnknownsQueueGrowing
expr: rate(unknowns_total[1h]) > 10
for: 30m
labels:
severity: warning
annotations:
summary: "Unknowns queue is growing rapidly"
- alert: UnknownsKEVPending
expr: unknowns_kev_count > 0 and unknowns_kev_unresolved_age_hours > 24
for: 5m
labels:
severity: critical
annotations:
summary: "KEV unknown pending for over 24 hours"
Alert rules deployed from: `devops/observability/prometheus/rules/unknowns-queue-alerts.yaml`
**Critical Alerts:**
| Alert | Condition | Response |
|-------|-----------|----------|
| `UnknownsSlaBreachCritical` | compliance < 80% | Immediate escalation to security team |
| `UnknownsHotQueueHigh` | HOT > 5 for 10m | Prioritize resolution |
| `UnknownsProcessingFailures` | Failed entries in 1h | Manual intervention required |
| `UnknownsSlaMonitorDown` | No metrics for 5m | Check service health |
| `UnknownsHealthCheckUnhealthy` | Health check failing | Check SLA breaches |
**Warning Alerts:**
| Alert | Condition | Response |
|-------|-----------|----------|
| `UnknownsSlaBreachWarning` | 80% ≤ compliance < 95% | Review queue health |
| `UnknownsHotQueuePresent` | HOT > 0 for 1h | Check progress |
| `UnknownsQueueBacklog` | Total > 100 for 30m | Scale processing |
| `UnknownsStuckProcessing` | Processing > 10 for 30m | Check bottlenecks |
| `UnknownsProcessingTimeout` | Timeouts > 5/hour | Review automation |
| `UnknownsEscalationRate` | Escalations > 10/hour | Review criteria |
### 7.4 Metric-Based Troubleshooting
#### SLA Breach Investigation
```bash
# 1. Check current breach status
curl -s "http://prometheus:9090/api/v1/query?query=unknowns_sla_compliance" | jq
# 2. Identify breached entries
curl -s "$UNKNOWNS_API/grey-queue?status=pending" | \
jq '.items[] | select(.sla_breached == true)'
# 3. Check SLA health endpoint
curl -s "$UNKNOWNS_API/health/sla" | jq
# 4. Review breach timeline
# In Grafana: SLA Compliance Over Time panel, last 24h
```
### 7.4 Daily Report
#### Stuck Processing Investigation
```bash
# 1. Check processing count
curl -s "http://prometheus:9090/api/v1/query?query=greyqueue_processing_count" | jq
# 2. List stuck entries
curl -s "$UNKNOWNS_API/grey-queue?status=Processing" | \
jq '.items[] | select((.last_processed_at | fromdateiso8601) < (now - 3600))'
# 3. Check watchdog metrics
curl -s "http://prometheus:9090/api/v1/query?query=rate(greyqueue_stuck_total[1h])" | jq
# 4. Force retry if needed
curl -X POST "$UNKNOWNS_API/grey-queue/{id}/retry"
```
#### High Escalation Rate
```bash
# 1. Check escalation rate
curl -s "http://prometheus:9090/api/v1/query?query=rate(unknowns_escalated_total[1h])" | jq
# 2. Review escalation reasons
curl -s "$UNKNOWNS_API/grey-queue?status=Escalated" | \
jq 'group_by(.escalation_reason) | map({reason: .[0].escalation_reason, count: length})'
# 3. Check for EPSS/KEV spikes
# Events triggering escalations:
# - epss.updated with score increase
# - kev.added events
# - deployment.created with affected components
```
#### Queue Growth Analysis
```bash
# 1. Check inflow rate
curl -s "http://prometheus:9090/api/v1/query?query=rate(unknowns_enqueued_total[1h])" | jq
# 2. Check resolution rate
curl -s "http://prometheus:9090/api/v1/query?query=rate(unknowns_resolved_total[1h])" | jq
# 3. Calculate net growth
# growth_rate = inflow_rate - resolution_rate
# 4. Review reasons for new unknowns
curl -s "$UNKNOWNS_API/grey-queue/summary" | jq '.by_reason'
```
### 7.5 Daily Report
```bash
# Generate daily report

371
docs/sboms/DETERMINISM.md Normal file
View File

@@ -0,0 +1,371 @@
# SBOM Determinism Guide
> **Sprint**: SPRINT_20260118_025_ReleaseOrchestrator_sbom_release_association
> **Task**: TASK-025-005
> **Status**: Living Document
This document consolidates all determinism requirements for Stella Ops SBOMs. Deterministic SBOMs are critical for reproducible builds, verifiable release gates, and trust chain integrity.
---
## 1. Why Determinism Matters
### 1.1 Reproducibility
Deterministic SBOMs ensure that scanning the same artifact multiple times produces identical output. This is essential for:
- **CI/CD Reliability**: Re-running a pipeline should produce the same SBOM hash
- **Audit Trails**: Evidence submitted to compliance frameworks must be reproducible
- **Caching**: Content-addressed storage can deduplicate identical SBOMs
- **Debugging**: Engineers can reproduce exact SBOM state from artifact digest
### 1.2 Verifiable Gates
Policy gates rely on SBOM hashes for trust verification:
```plaintext
Artifact Digest → SBOM Generation → Canonical Hash → DSSE Signature → Policy Evaluation
```
If SBOM generation is non-deterministic, the same artifact could produce different hashes, breaking:
- Signature verification (hash mismatch)
- Gate decisions (different vulnerability sets)
- Attestation chains (broken proof lineage)
### 1.3 Trust Chaining
Evidence chains require stable identifiers. A release component's `SbomDigest` must match the SBOM retrieved later for verification. Non-determinism breaks this chain:
```plaintext
Release Finalization: SbomDigest = sha256:abc123...
Later Verification: sha256(regenerated-sbom) = sha256:xyz789... ← BROKEN
```
---
## 2. Canonicalization Rules
Stella Ops uses [RFC 8785 JSON Canonicalization Scheme (JCS)](https://tools.ietf.org/html/rfc8785) for deterministic JSON serialization.
### 2.1 Core JCS Rules
1. **No Whitespace**: Output has no formatting, newlines, or indentation
2. **Sorted Keys**: Object keys are sorted lexicographically (Unicode code point order)
3. **Normalized Numbers**: No leading zeros, no trailing decimal zeros, no positive exponent sign
4. **UTF-8 Encoding**: All strings encoded as UTF-8 without BOM
5. **No Duplicate Keys**: Object keys must be unique
### 2.2 Implementation
```csharp
// Using StellaOps.Canonical.Json
using StellaOps.Canonical.Json;
// Canonicalize raw JSON bytes
byte[] canonical = CanonJson.CanonicalizeParsedJson(jsonBytes);
// Compute SHA-256 of canonical form
string digest = CanonJson.Sha256Hex(canonical);
```
### 2.3 SBOM-Specific Ordering
Beyond JCS, Stella Ops applies additional ordering for SBOM elements:
| Element | Ordering Strategy |
|---------|-------------------|
| `components` | Sorted by `bom-ref` (Ordinal) |
| `dependencies` | Sorted by `ref` (Ordinal) |
| `hashes` | Sorted by `alg` (Ordinal) |
| `licenses` | Sorted by license ID (Ordinal) |
| `dependsOn` | Sorted lexicographically |
This ensures component order doesn't affect the canonical hash.
---
## 3. Identity Field Derivation
### 3.1 serialNumber (CycloneDX)
**Rule**: Use `urn:sha256:<artifact-digest>` format for deterministic identification.
```json
{
"bomFormat": "CycloneDX",
"specVersion": "1.6",
"serialNumber": "urn:sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}
```
**Benefits**:
- Directly ties SBOM identity to the artifact it describes
- Enables verification: `serialNumber == urn:sha256:$(sha256sum artifact)`
- Content-addressed: identical artifacts produce identical serialNumbers
**Fallback**: If artifact digest is unavailable, UUIDv5 derived from sorted components is used for backwards compatibility. This produces a warning during validation.
### 3.2 bom-ref
**Rule**: Use deterministic derivation based on purl or component identity.
```plaintext
bom-ref = sha256(purl || name || version)[:12] // truncated hash
```
Or use the package URL directly if available:
```json
{
"bom-ref": "pkg:npm/lodash@4.17.21",
"name": "lodash",
"version": "4.17.21",
"purl": "pkg:npm/lodash@4.17.21"
}
```
**Anti-pattern**: Random UUIDs or incrementing counters as bom-ref.
### 3.3 SPDX Document Namespace
**Rule**: Use artifact-derived namespace for SPDX documents.
```plaintext
DocumentNamespace: https://stella-ops.org/spdx/sha256/<artifact-digest>
```
---
## 4. Ephemeral Data Policy
Certain SBOM fields are inherently non-deterministic and should be handled carefully.
### 4.1 Prunable Fields
These fields should be omitted or normalized before hashing:
| Field | Treatment |
|-------|-----------|
| `metadata.timestamp` | Use fixed epoch or artifact build time |
| `metadata.tools[].version` | Optional: pin tool versions |
| File paths (absolute) | Convert to relative paths |
| Environment variables | Exclude from SBOM |
### 4.2 Timestamp Strategy
Option 1: **Fixed Epoch** (Recommended)
```json
"timestamp": "1970-01-01T00:00:00Z"
```
Option 2: **Artifact Build Time**
```json
"timestamp": "<artifact-created-at>"
```
Option 3: **Omit Field**
```json
// No timestamp field - allowed by CycloneDX
```
### 4.3 Tool Metadata
Tool information aids debugging but affects hashes:
```json
"tools": [
{
"vendor": "Stella Ops",
"name": "stella-scanner",
"version": "1.0.0" // Pin this version
}
]
```
**Recommendation**: Pin tool versions in CI configuration to ensure reproducibility.
---
## 5. Verification Workflow
### 5.1 CLI Commands
**Verify Canonical Form**:
```bash
stella sbom verify input.json --canonical
# Exit 0: Input is canonical
# Exit 1: Input is not canonical (outputs SHA-256 of canonical form)
```
**Canonicalize and Output**:
```bash
stella sbom verify input.json --canonical --output bom.canonical.json
# Writes: bom.canonical.json (canonical SBOM)
# Writes: bom.canonical.json.sha256 (digest sidecar)
```
**Verbose Output**:
```bash
stella sbom verify input.json --canonical --verbose
# SHA-256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
# Canonical: yes
# Input size: 15234 bytes
# Canonical size: 12456 bytes
```
### 5.2 CI Gate Integration
```yaml
# .gitea/workflows/sbom-gate.yaml
steps:
- name: Generate SBOM
run: stella sbom generate --artifact ${{ artifact }} --output bom.json
- name: Verify Canonical
run: |
stella sbom verify bom.json --canonical --output bom.canonical.json
if [ $? -ne 0 ]; then
echo "SBOM is not in canonical form"
exit 1
fi
- name: Sign SBOM
run: stella sbom sign bom.canonical.json --key ${{ signing_key }}
- name: Store Digest
run: |
DIGEST=$(cat bom.canonical.json.sha256)
echo "SBOM_DIGEST=$DIGEST" >> $GITHUB_ENV
```
### 5.3 Release Finalization
At release finalization, the SBOM digest is captured:
```plaintext
1. Lookup SBOM for artifact: ISbomService.GetByDigestAsync(artifact.Digest)
2. Extract canonical digest: sbom.SbomSha256
3. Store on ReleaseComponent: component.SbomDigest = sbom.SbomSha256
4. Include in release manifest hash computation
```
---
## 6. KPIs and Monitoring
### 6.1 Byte-Identical Rate
**Metric**: Percentage of SBOM regenerations that produce identical bytes.
**Target**: 100% for same artifact + same scanner version
**Alert**: < 99.9% indicates non-determinism bug
### 6.2 Stable-Field Coverage
**Metric**: Percentage of SBOM fields that are deterministic.
| Field Type | Target |
|------------|--------|
| Component identifiers | 100% |
| Hashes | 100% |
| Dependencies | 100% |
| Metadata timestamps | 95%+ (fixed epoch) |
| Tool versions | 90%+ (pinned) |
### 6.3 Gate False Positives
**Metric**: Signature verification failures due to hash mismatch.
**Target**: 0% for valid artifacts
**Investigation**: Any mismatch indicates canonicalization or regeneration issue.
---
## 7. Troubleshooting
### 7.1 Hash Mismatch on Regeneration
**Symptom**: Same artifact produces different SBOM hashes.
**Causes**:
1. **Timestamp drift**: Check if `metadata.timestamp` varies
2. **Tool version change**: Check scanner/tool versions
3. **Ordering instability**: Check component/dependency ordering
4. **Unicode normalization**: Check for composed vs decomposed characters
**Debug**:
```bash
# Compare two SBOMs
stella sbom diff bom1.json bom2.json
# Check canonical form
stella sbom verify bom1.json --canonical --verbose
stella sbom verify bom2.json --canonical --verbose
```
### 7.2 serialNumber Warning
**Symptom**: Warning `CDX_SERIAL_NON_DETERMINISTIC` during validation.
**Cause**: SBOM uses `urn:uuid:` format instead of `urn:sha256:`.
**Fix**: Ensure `ArtifactDigest` is provided when generating SBOM:
```csharp
var document = new SbomDocument
{
Name = "my-app",
ArtifactDigest = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
// ...
};
```
### 7.3 Canonical vs Pretty-Printed
**Symptom**: SBOM appears valid but fails canonical verification.
**Cause**: SBOM was saved with indentation/formatting.
**Fix**:
```bash
# Convert to canonical form
stella sbom verify input.json --canonical --output output.json
# Use output.json for signing and storage
```
### 7.4 Platform-Specific Differences
**Symptom**: Same code produces different SBOMs on Windows vs Linux.
**Causes**:
1. **Line endings**: CR+LF vs LF in embedded content
2. **Path separators**: `\` vs `/` in file paths
3. **Locale differences**: Number formatting, date formatting
**Prevention**:
- Normalize line endings in CI
- Use forward slashes for paths
- Use invariant culture for formatting
---
## References
- [RFC 8785: JSON Canonicalization Scheme](https://tools.ietf.org/html/rfc8785)
- [CycloneDX 1.6 Specification](https://cyclonedx.org/docs/1.6/json/)
- [SPDX 2.3 Specification](https://spdx.github.io/spdx-spec/v2.3/)
- `docs/modules/scanner/signed-sbom-archive-spec.md` - Archive format
- `docs/modules/scanner/deterministic-sbom-compose.md` - Composition rules
- `src/Attestor/__Libraries/StellaOps.Attestor.StandardPredicates/Writers/CycloneDxWriter.cs` - Implementation
- `src/__Libraries/StellaOps.Canonical.Json/CanonJson.cs` - Canonicalization library
---
## Changelog
| Date | Change |
|------|--------|
| 2026-01-19 | Initial creation (TASK-025-005) |

147
docs/schemas/binary-index/delta-sig-v1.schema.json Normal file
View File

@@ -0,0 +1,147 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://stella.dev/schemas/binary-index/delta-sig-v1.schema.json",
"title": "Stella Ops Delta Signature Predicate v1",
"description": "JSON Schema for delta-sig predicate used in binary patch verification. Enables offline CI gate validation per advisory requirements.",
"type": "object",
"required": [
"predicateType",
"subject",
"original_hash",
"patched_hash",
"diff_method",
"similarity_score",
"confidence",
"call_ngram_hash",
"bom_ref",
"architecture",
"lifter",
"computed_at"
],
"properties": {
"predicateType": {
"type": "string",
"const": "stella.dev/delta-sig/v1",
"description": "Predicate type URI identifying this as a Stella delta signature"
},
"subject": {
"type": "object",
"description": "Subject function identification",
"required": ["func_id"],
"properties": {
"func_id": {
"$ref": "#/$defs/func_id",
"description": "Function identifier in format: module:bom-ref:offset:canonical-IR-hash"
},
"name": {
"type": "string",
"description": "Human-readable function name (optional)"
},
"demangled": {
"type": "string",
"description": "Demangled C++/Rust symbol name (optional)"
}
}
},
"original_hash": {
"$ref": "#/$defs/hash_value",
"description": "Hash of the original (unpatched) function's canonical IR with algorithm prefix"
},
"patched_hash": {
"$ref": "#/$defs/hash_value",
"description": "Hash of the patched function's canonical IR with algorithm prefix"
},
"diff_method": {
"type": "string",
"description": "Method used to compute the semantic diff",
"enum": [
"semantic-ir",
"cfg-structural",
"call-ngram",
"instruction-sequence",
"composite"
]
},
"proof_ref": {
"type": "string",
"description": "Reference to the full diff proof (rekor entry ID, sha256, or blake3 digest)",
"pattern": "^(rekor|sha256|blake3):[a-fA-F0-9]{64,128}$"
},
"similarity_score": {
"type": "number",
"description": "Similarity score between original and patched functions [0.0, 1.0]",
"minimum": 0,
"maximum": 1
},
"confidence": {
"type": "number",
"description": "Match confidence score [0.0, 1.0]",
"minimum": 0,
"maximum": 1
},
"call_ngram_hash": {
"$ref": "#/$defs/hash_value",
"description": "Call-ngram fingerprint for cross-compiler resilience"
},
"bom_ref": {
"type": "string",
"description": "CycloneDX/SPDX bom-ref linking to SBOM component"
},
"architecture": {
"type": "string",
"description": "Target architecture",
"examples": ["x86-64", "arm64", "arm32", "riscv64", "mips64"]
},
"lifter": {
"type": "string",
"description": "IR lifter used for binary analysis",
"examples": ["B2R2", "Ghidra", "BinaryNinja", "Iced", "Capstone", "angr"]
},
"ir_version": {
"type": "string",
"description": "IR representation version for cache invalidation",
"default": "v1.0.0",
"pattern": "^v[0-9]+\\.[0-9]+\\.[0-9]+$"
},
"computed_at": {
"type": "string",
"description": "ISO 8601 timestamp when signature was computed",
"format": "date-time"
}
},
"additionalProperties": false,
"$defs": {
"func_id": {
"type": "string",
"description": "Function identifier in format: module:bom-ref:offset:canonical-IR-hash",
"pattern": "^[^:]+:[^:]+:0x[a-fA-F0-9]+:[a-f0-9]{64}$"
},
"hash_value": {
"type": "string",
"description": "Hash value with algorithm prefix",
"pattern": "^(sha256|sha384|sha512|blake3):[a-f0-9]{64,128}$"
}
},
"examples": [
{
"predicateType": "stella.dev/delta-sig/v1",
"subject": {
"func_id": "libssl.so.3:pkg:deb/openssl@3.0.2:0x12345:abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234",
"name": "SSL_read",
"demangled": "SSL_read"
},
"original_hash": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
"patched_hash": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
"diff_method": "semantic-ir",
"proof_ref": "rekor:3333333333333333333333333333333333333333333333333333333333333333",
"similarity_score": 0.95,
"confidence": 0.98,
"call_ngram_hash": "blake3:4444444444444444444444444444444444444444444444444444444444444444",
"bom_ref": "pkg:deb/debian/openssl@3.0.2-0ubuntu1.10",
"architecture": "x86-64",
"lifter": "B2R2",
"ir_version": "v1.0.0",
"computed_at": "2026-01-18T12:00:00Z"
}
]
}

17
docs/technical/adr/0044-binary-delta-signatures.md
View File

@@ -54,18 +54,21 @@ Vulnerability scanners today rely on version string comparison to determine if a
### Disassembly Engine Selection
**Chosen: Plugin-based architecture with Iced (primary) + B2R2 (fallback)**
**Chosen: Plugin-based architecture with Iced (primary for disassembly) + B2R2 (primary for IR lifting)**
| Engine | Strengths | Weaknesses |
|--------|-----------|------------|
| **Iced** | Fastest x86/x86-64, MIT license, pure C# | x86 only |
| **B2R2** | Multi-arch (ARM, MIPS, RISC-V), IR lifting, MIT license | F# (requires wrapper) |
| Engine | Strengths | Weaknesses | Use Case |
|--------|-----------|------------|----------|
| **Iced** | Fastest x86/x86-64, MIT license, pure C# | x86 only | Fast disassembly for delta-sig normalization |
| **B2R2** | Multi-arch (ARM, MIPS, RISC-V), IR lifting, MIT license | F# (requires wrapper) | Semantic IR analysis, multi-arch |
**Rationale:**
- Iced for performance-critical x86/x86-64 path (90%+ of scanned binaries)
- B2R2 for ARM64, MIPS, RISC-V when needed
- Iced for performance-critical x86/x86-64 delta-sig path (90%+ of scanned binaries)
- B2R2 for ARM64, MIPS, RISC-V when needed for delta-sigs
- **B2R2 as primary backend for semantic IR lifting** (see `SPRINT_20260118_027_BinaryIndex_b2r2_full_integration.md`)
- Plugin architecture allows adding engines without core changes
**Update (2026-01-19):** B2R2 is now the primary backend for semantic IR lifting via `B2R2LowUirLiftingService`. This enables high-fidelity semantic analysis across x86, ARM64, MIPS, RISC-V, PowerPC, and SPARC architectures. See `docs/modules/binary-index/semantic-diffing.md` for details.
### Normalization Strategy
To compare binaries compiled by different toolchains/versions, we normalize:

237
docs/technical/architecture/runtime-agents-architecture.md
View File

@@ -714,9 +714,246 @@ This document describes the runtime observation layer in StellaOps, including eB
---
## Tetragon Integration
```
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ TETRAGON eBPF INTEGRATION │
├─────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Tetragon provides kernel-level security observability via eBPF TracingPolicies. │
│ StellaOps integrates Tetragon as a complementary runtime observation source. │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────────┐ │
│ │ ARCHITECTURE │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Tetragon Daemon (DaemonSet) │ │ │
│ │ │ │ │ │
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │
│ │ │ │ kprobe │ │ tracepoint │ │ uprobe │ │ │ │
│ │ │ │ (syscalls) │ │ (scheduler) │ │ (userspace) │ │ │ │
│ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ └─────────────────┼─────────────────┘ │ │ │
│ │ │ │ │ │ │
│ │ │ ┌─────────▼─────────┐ │ │ │
│ │ │ │ TracingPolicy │ │ │ │
│ │ │ │ CRD Enforcement │ │ │ │
│ │ │ └─────────┬─────────┘ │ │ │
│ │ │ │ │ │ │
│ │ │ ┌─────────▼─────────┐ │ │ │
│ │ │ │ Export API │ │ │ │
│ │ │ │ (gRPC/HTTP) │ │ │ │
│ │ │ └─────────┬─────────┘ │ │ │
│ │ │ │ │ │ │
│ │ └────────────────────────────┼────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ┌─────────▼─────────┐ │ │
│ │ │ StellaOps Agent │ │ │
│ │ │ (Tetragon) │ │ │
│ │ └─────────┬─────────┘ │ │
│ │ │ │ │
│ │ ┌────────────────────────────┼───────────────────────────────────────┐ │ │
│ │ │ │ │ │ │
│ │ │ ┌─────────────┐ ┌───────▼───────┐ ┌─────────────┐ │ │ │
│ │ │ │ Privacy │ │ Event │ │ Frame │ │ │ │
│ │ │ │ Filter │──│ Adapter │──│ Canonicalizer │ │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ │ └─────────────┘ └───────────────┘ └──────┬──────┘ │ │ │
│ │ │ │ │ │ │
│ │ │ ┌───────────────────────────────────────────┼────────────────┐ │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ │ ┌─────────────────┐ ┌───────────────▼────────────┐ │ │ │ │
│ │ │ │ │ Hot Symbol │ │ Witness │ │ │ │ │
│ │ │ │ │ Bridge │ │ Bridge │ │ │ │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ │ │ └────────┬────────┘ └──────────────┬─────────────┘ │ │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ └───────────┼─────────────────────────────┼──────────────────┘ │ │ │
│ │ │ │ │ │ │ │
│ │ └───────────────┼─────────────────────────────┼─────────────────────┘ │ │
│ │ │ │ │ │
│ │ ┌─────────▼─────────┐ ┌─────────────▼───────────┐ │ │
│ │ │ signals.hot_symbols│ │ RuntimeWitnessGenerator │ │ │
│ │ │ (PostgreSQL) │ │ (Signing Pipeline) │ │ │
│ │ └────────────────────┘ └─────────────────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────────┐ │
│ │ TRACINGPOLICY CONFIGURATION │ │
│ │ │ │
│ │ The StellaOps TracingPolicy captures: │ │
│ │ │ │
│ │ • Process execution (execve) with full arguments │ │
│ │ • Network connections (connect, socket) │ │
│ │ • File operations (open, read, write) │ │
│ │ • Kernel and user-space stack traces │ │
│ │ │ │
│ │ Namespace selectors: stella-ops-*, application namespaces │ │
│ │ Pod selectors: Via labels (stellaops.io/observe=true) │ │
│ │ │ │
│ │ Policy file: devops/manifests/tetragon/stella-ops-tracing-policy.yaml │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────────┐ │
│ │ COMPONENT RESPONSIBILITIES │ │
│ │ │ │
│ │ TetragonAgentCapability: │ │
│ │ • Connects to Tetragon Export API (gRPC) │ │
│ │ • Implements IAgentCapability interface │ │
│ │ • Supports start/stop collection, status, flush tasks │ │
│ │ • Health checks via Tetragon health endpoint │ │
│ │ │ │
│ │ TetragonEventAdapter: │ │
│ │ • Converts TetragonEvent to RuntimeCallEvent format │ │
│ │ • Maps stack frames to canonical symbols │ │
│ │ • Extracts process/container context │ │
│ │ │ │
│ │ TetragonFrameCanonicalizer: │ │
│ │ • Resolves Build-ID for binaries │ │
│ │ • Demangles C++, Rust, Go symbol names │ │
│ │ • Computes function IDs matching static analysis │ │
│ │ • Format: buildid:function+offset │ │
│ │ │ │
│ │ TetragonHotSymbolBridge: │ │
│ │ • Records observations to hot_symbols index │ │
│ │ • Time-window aggregation (1-minute windows) │ │
│ │ • Confidence scoring (0.20-1.00 range) │ │
│ │ │ │
│ │ TetragonWitnessBridge: │ │
│ │ • Buffers observations by claim_id │ │
│ │ • Emits to RuntimeWitnessGenerator │ │
│ │ • Implements backpressure via SemaphoreSlim │ │
│ │ │ │
│ │ TetragonPrivacyFilter: │ │
│ │ • Argument redaction (passwords, tokens, PII) │ │
│ │ • Symbol-ID-only mode for privacy-sensitive envs │ │
│ │ • Namespace allowlisting │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────────┐ │
│ │ TETRAGON vs SIGNALS COMPARISON │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Aspect │ Signals (Native) │ Tetragon Integration │ │ │
│ │ │ ─────────────────┼──────────────────────┼────────────────────────│ │ │
│ │ │ Deployment │ Custom eBPF agent │ Standard Tetragon │ │ │
│ │ │ Configuration │ Code-level │ TracingPolicy CRD │ │ │
│ │ │ Policy management │ Recompile │ K8s-native (kubectl) │ │ │
│ │ │ Stack capture │ Custom unwinding │ Built-in │ │ │
│ │ │ Ecosystem │ StellaOps only │ CNCF, broad adoption │ │ │
│ │ │ Use case │ Deep integration │ Standard compliance │ │ │
│ │ └──────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Recommendation: Use Tetragon for Kubernetes environments with compliance │ │
│ │ requirements. Use native Signals for maximum control and non-K8s estates. │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────────┐ │
│ │ PERFORMANCE TARGETS │ │
│ │ │ │
│ │ Target KPIs for Tetragon integration: │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Metric │ Target │ Measurement │ │ │
│ │ │ ─────────────────────────┼──────────────────┼──────────────────────│ │ │
│ │ │ CPU overhead │ <5% │ Per monitored pod │ │ │
│ │ │ Memory overhead (agent) │ <100MB │ Agent container │ │ │
│ │ │ Capture latency (P95) │ <100ms │ Event to hot_symbols │ │ │
│ │ │ Throughput │ >10,000 events/s │ Per agent instance │ │ │
│ │ │ Privacy filter overhead │ <10% │ Compared to baseline │ │ │
│ │ │ Frame canonicalization │ <10ms per frame │ With symbol resolve │ │ │
│ │ │ Function ID computation │ <0.1ms per call │ Hash + format │ │ │
│ │ │ Demangling throughput │ >100,000 sym/s │ Mixed C++/Rust/Go │ │ │
│ │ └──────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Benchmarks: src/RuntimeInstrumentation/StellaOps.RuntimeInstrumentation. │ │
│ │ Tetragon.Tests/Benchmarks/TetragonPerformanceBenchmarks.cs │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────────┘
```
---
## Tetragon Deployment Guide
### Prerequisites
1. **Kubernetes cluster** with Linux nodes (kernel 5.8+)
2. **Tetragon installed** via Helm or operator
3. **StellaOps control plane** deployed
### Installation Steps
```bash
# 1. Install Tetragon (if not already installed)
helm repo add cilium https://helm.cilium.io
helm install tetragon cilium/tetragon -n kube-system
# 2. Apply StellaOps TracingPolicy
kubectl apply -f devops/manifests/tetragon/stella-ops-tracing-policy.yaml
# 3. Deploy StellaOps Tetragon Agent
kubectl apply -f devops/manifests/tetragon/stella-ops-tetragon-agent-daemonset.yaml
# 4. Verify deployment
kubectl get pods -n stella-ops -l app=stella-ops-tetragon-agent
kubectl logs -n stella-ops -l app=stella-ops-tetragon-agent --tail=50
```
### Configuration
The Tetragon agent is configured via ConfigMap:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: stella-ops-tetragon-config
namespace: stella-ops
data:
config.yaml: |
tetragon:
address: "tetragon.kube-system.svc:54321"
connectionTimeout: 30s
hotSymbols:
aggregationWindowSeconds: 60
minConfidenceThreshold: 0.2
flushIntervalSeconds: 30
privacy:
redactArguments: true
useDefaultRedactionPatterns: true
symbolIdOnlyMode: false
allowedNamespaces:
- stella-ops-workloads
- default
```
### Monitoring
The agent exposes Prometheus metrics at `:8080/metrics`:
- `tetragon_events_total` - Total events received
- `tetragon_events_filtered` - Events dropped by privacy filter
- `tetragon_hotsymbols_flushed` - Hot symbols written to DB
- `tetragon_witness_generated` - Runtime witnesses generated
- `tetragon_latency_seconds` - Event processing latency histogram
---
## Related Documentation
- [Policy Engine Data Pipeline](policy-engine-data-pipeline.md) - How runtime feeds policy
- [Reachability Drift Alert Flow](../../flows/19-reachability-drift-alert-flow.md) - Runtime-triggered alerts
- [Signals Module Architecture](../../modules/signals/architecture.md) - Signals module dossier
- [Zastava Architecture](../../modules/zastava/architecture.md) - Container observer dossier
- [Tetragon Integration Sprint](../../implplan/SPRINT_20260118_019_Infra_tetragon_integration.md) - Implementation details

216
docs/ui-analysis/01_SHELL_AND_NAVIGATION.md Normal file
View File

@@ -0,0 +1,216 @@
# Stella Ops UI Structure - Part 1: Shell & Navigation
## Technology Stack
- **Framework**: Angular 17+ (standalone components, signals)
- **Routing**: Angular Router with lazy-loaded modules
- **Styling**: SCSS
- **Architecture**: Feature-based module organization under `src/app/features/`
- **Location**: `src/Web/StellaOps.Web/`
---
## 1. MAIN SHELL & HEADER
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ [QUICKSTART BANNER - visible only in demo/offline mode] │
├─────────────────────────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────────────────────────────────┐ ┌────────────────┐ │
│ │ StellaOps │ │ HOME│ANALYZE│TRIAGE│POLICY│OPS│NOTIFY│ │ Fresh Auth │ │
│ │ Dashboard │ │ │ADMIN │ │ Tenant: xxx │ │
│ │ (brand) │ │ │ │ [User Menu ▼] │ │
│ └─────────────┘ └─────────────────────────────────────────┘ └────────────────┘ │
├─────────────────────────────────────────────────────────────────────────────────┤
│ [BREADCRUMB: Dashboard > Section > Subsection] │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────┐ │
│ │ <router-outlet /> │ │
│ │ (Page Content) │ │
│ └─────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
│
┌─────────────────────┼─────────────────────┐
▼ ▼ ▼
[Command Palette] [Toast Container] [Keyboard Shortcuts]
```
### Shell Components (from app.component.html)
- `app-navigation-menu` - Main navigation
- `app-user-menu` - User dropdown
- `app-breadcrumb` - Breadcrumb navigation
- `app-command-palette` - Command palette (keyboard shortcut access)
- `app-toast-container` - Toast notifications
- `app-keyboard-shortcuts` - Keyboard shortcut handler
---
## 2. NAVIGATION MENU STRUCTURE
Source: `src/app/core/navigation/navigation.config.ts`
```
┌──────────────────────────────────────────────────────────────────────────────┐
│ MAIN NAVIGATION │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ HOME │ │ ANALYZE │ │ TRIAGE │ │ POLICY │ │ OPS │ │
│ │ [icon] │ │ [icon] ▼ │ │ [icon] ▼ │ │ [icon] ▼ │ │ [icon] ▼ │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │ │ │
│ ┌────▼─────┐ ┌────▼───────────────────┐ ┌────▼──────────┐ ┌─▼────────────┐│
│ │Dashboard │ │ • Scans & Findings │ │ • Artifacts │ │• SBOM Sources││
│ └──────────┘ │ • Vulnerabilities │ │ • Exceptions │ │• Quotas ││
│ │ • SBOM Graph │ │ • Audit │ │ └→ Overview ││
│ │ • Lineage │ │ Bundles │ │ └→ Tenants ││
│ │ • Reachability │ │ • Risk │ │ └→ Throttle ││
│ │ • VEX Hub │ │ Profiles │ │ └→ Forecast ││
│ │ • Unknowns │ └───────────────┘ │ └→ Alerts ││
│ │ • Patch Map │ │ └→ Reports ││
│ └────────────────────────┘ │• Dead-Letter ││
│ │ └→ Dashboard││
│ ┌──────────┐ ┌───────────────────────────────────────────▲│ └→ Queue ││
│ │ NOTIFY │ │ ADMIN (scoped) ││• SLO Monitor ││
│ │ [icon] │ │ ││ └→ Dashboard││
│ └────┬─────┘ └────┬──────────────────────────────────────┘│ └→ Alerts ││
│ │ │ │ └→ Defs ││
│ ┌────▼─────┐ ┌────▼───────────────────────────────────┐ │• Platform ││
│ │Notific. │ │ • Tenants • OAuth Clients │ │ Health ││
│ │Panel │ │ • Users • Tokens │ │• Feed Mirror ││
│ └──────────┘ │ • Roles • Unified Audit Log │ │ └→ Dashboard││
│ │ • Branding • Notification Admin │ │ └→ AirGap ││
│ │ • Platform • Trust Management │ │• Offline Kit ││
│ │ Status • Policy Governance │ │• AOC Compli. ││
│ │ • Trivy DB • Policy Simulation │ │• Scheduler ││
│ │ • Registry • Issuer Directory │ │• Doctor Diag ││
│ │ Tokens • Scanner Ops │ │ ││
│ └────────────────────────────────────────┘ └──────────────┘│
└──────────────────────────────────────────────────────────────────────────────┘
```
---
## 3. NAVIGATION GROUPS DETAIL
### 3.1 HOME Group
| ID | Label | Route | Icon | Scopes |
|---|---|---|---|---|
| dashboard | Dashboard | `/` | dashboard | - |
### 3.2 ANALYZE Group
| ID | Label | Route | Icon | Scopes |
|---|---|---|---|---|
| findings | Scans & Findings | `/findings` | scan | - |
| vulnerabilities | Vulnerabilities | `/vulnerabilities` | bug | - |
| graph | SBOM Graph | `/graph` | graph | graph:read |
| lineage | Lineage | `/lineage` | git-branch | - |
| reachability | Reachability | `/reachability` | network | - |
| vex-hub | VEX Hub | `/admin/vex-hub` | shield-check | - |
| unknowns | Unknowns | `/analyze/unknowns` | help-circle | - |
| patch-map | Patch Map | `/analyze/patch-map` | grid | - |
### 3.3 TRIAGE Group
| ID | Label | Route | Icon | Scopes |
|---|---|---|---|---|
| artifacts | Artifact Workspace | `/triage/artifacts` | package | - |
| exceptions | Exception Queue | `/exceptions` | exception | - |
| audit-bundles | Audit Bundles | `/triage/audit-bundles` | archive | - |
| risk | Risk Profiles | `/risk` | shield | - |
### 3.4 POLICY Group
| ID | Label | Route | Icon | Scopes |
|---|---|---|---|---|
| policy-studio | Policy Studio | - | edit | - |
| ├─ policy-editor | Editor | `/policy-studio/packs` | - | policy:author |
| ├─ policy-simulate | Simulate | `/policy-studio/simulate` | - | policy:simulate |
| ├─ policy-approvals | Approvals | `/policy-studio/approvals` | - | policy:review OR policy:approve |
| └─ policy-dashboard | Dashboard | `/policy-studio/dashboard` | - | policy:read |
| orchestrator | Jobs & Orchestration | `/orchestrator` | workflow | - |
### 3.5 OPS Group
| ID | Label | Route | Icon | Children |
|---|---|---|---|---|
| sbom-sources | SBOM Sources | `/sbom-sources` | database | - |
| quotas | Quota Dashboard | `/ops/quotas` | gauge | Overview, Tenant Usage, Throttle Events, Forecast, Alert Config, Reports |
| dead-letter | Dead-Letter Queue | `/ops/orchestrator/dead-letter` | alert-triangle | Dashboard, Queue Browser |
| slo-monitoring | SLO Monitoring | `/ops/orchestrator/slo` | activity | Dashboard, Alerts, Definitions |
| platform-health | Platform Health | `/ops/health` | heart-pulse | Dashboard, Incidents |
| feed-mirror | Feed Mirror & AirGap | `/ops/feeds` | mirror | Dashboard, Import Bundle, Export Bundle, Version Locks |
| offline-kit | Offline Kit | `/ops/offline-kit` | offline | Dashboard, Bundles, Verification, JWKS |
| aoc-compliance | AOC Compliance | `/ops/aoc` | shield-check | Dashboard, Guard Violations, Ingestion Flow, Provenance Validator, Compliance Report |
### 3.6 NOTIFY Group
| ID | Label | Route | Icon | Scopes |
|---|---|---|---|---|
| notifications | Notifications | `/notify` | notification | - |
### 3.7 ADMIN Group (requires ui.admin scope)
| ID | Label | Route | Icon | Notes |
|---|---|---|---|---|
| tenants | Tenants | `/console/admin/tenants` | building | - |
| users | Users | `/console/admin/users` | users | - |
| roles | Roles & Scopes | `/console/admin/roles` | key | - |
| clients | OAuth Clients | `/console/admin/clients` | app | - |
| tokens | Tokens | `/console/admin/tokens` | token | - |
| audit | Unified Audit Log | `/admin/audit` | log | Has children: Dashboard, All Events, Policy Audit, Authority Audit, VEX Audit, Integration Audit, Export |
| branding | Branding | `/console/admin/branding` | palette | - |
| platform-status | Platform Status | `/console/status` | monitor | - |
| trivy-db | Trivy DB Settings | `/concelier/trivy-db-settings` | database | - |
| admin-notifications | Notification Admin | `/admin/notifications` | bell-config | - |
| admin-trust | Trust Management | `/admin/trust` | certificate | - |
| policy-governance | Policy Governance | `/admin/policy/governance` | policy-config | - |
| policy-simulation | Policy Simulation | `/admin/policy/simulation` | test-tube | - |
| registry-admin | Registry Tokens | `/admin/registries` | container | - |
| issuer-trust | Issuer Directory | `/admin/issuers` | shield-check | - |
| scanner-ops | Scanner Ops | `/ops/scanner` | scan | - |
---
## 4. USER MENU ITEMS
| ID | Label | Route | Icon |
|---|---|---|---|
| profile | Profile | `/console/profile` | user |
| settings | Settings | `/settings` | settings |
---
## 5. FEATURE MODULES COUNT
Total feature directories under `src/app/features/`: **77 modules**
```
admin-notifications/ evidence-export/ policy-governance/ setup-wizard/
advisory-ai/ evidence-pack/ policy-simulation/ slo-monitoring/
ai-runs/ evidence-thread/ policy-studio/ snapshot/
aoc/ exceptions/ proof/ sources/
aoc-compliance/ feed-mirror/ proof-chain/ timeline/
audit-log/ findings/ proof-studio/ triage/
auth/ graph/ proofs/ triage-inbox/
binary-index/ home/ quota-dashboard/ trivy-db-settings/
change-trace/ integration-hub/ reachability/ trust-admin/
compare/ integrations/ registry-admin/ unknowns/
configuration-pane/ issuer-trust/ release-orchestrator/ unknowns-tracking/
console/ lineage/ releases/ verdicts/
console-admin/ notify/ risk/ vex-hub/
cvss/ offline-kit/ runs/ vex-studio/
dashboard/ opsmemory/ sbom/ vuln-explorer/
deadletter/ orchestrator/ sbom-sources/ vulnerabilities/
doctor/ platform-health/ scanner-ops/ welcome/
evidence/ policy/ scans/
policy-gates/ scheduler-ops/
scores/
secret-detection/
settings/
```

379
docs/ui-analysis/02_HOME_AND_ANALYZE_SCREENS.md Normal file
View File

@@ -0,0 +1,379 @@
# Stella Ops UI Structure - Part 2: Home & Analyze Screens
---
## 1. HOME DASHBOARD
**Route:** `/`
**Component:** `HomeDashboardComponent`
**Location:** `src/app/features/home/home-dashboard.component.ts`
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ SECURITY DASHBOARD │
│ [Last updated] [Refresh]│
├────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────┐ ┌─────────────────────────┐ ┌─────────────────┐│
│ │ VULNERABILITIES │ │ RISK OVERVIEW │ │ REACHABILITY ││
│ │ [View all →] │ │ [View details →] │ │ [Explore →] ││
│ ├─────────────────────────┤ ├─────────────────────────┤ ├─────────────────┤│
│ │ Critical ████████ 245 │ │ ┌───────────┐ │ │ ┌───────┐ ││
│ │ High ██████ 89 │ │ / 72 \ │ │ / 75% \ ││
│ │ Medium ███████ 156 │ │ │ SCORE │ │ │ │ REACH. │ ││
│ │ Low ████ 42 │ │ \ ↑ 5% / │ │ \ / ││
│ │ │ │ └───────────┘ │ │ └───────┘ ││
│ │ Total Findings: 532 │ │ │ │ ││
│ │ │ │ [Crit] [High] [Medium] │ │ ● Reachable ││
│ │ │ │ 12 34 89 │ │ ● Unreachable ││
│ └─────────────────────────┘ └─────────────────────────┘ │ ● Uncertain ││
│ └─────────────────┘│
│ │
│ ┌─────────────────────────┐ ┌─────────────────────────┐ ┌─────────────────┐│
│ │ COMPLIANCE STATUS │ │ ACTIVE POLICIES │ │ RECENT SCANS ││
│ ├─────────────────────────┤ ├─────────────────────────┤ ├─────────────────┤│
│ │ [Compliance metrics] │ │ [Policy status list] │ │ [Scan history] ││
│ └─────────────────────────┘ └─────────────────────────┘ └─────────────────┘│
└────────────────────────────────────────────────────────────────────────────────┘
```
### Dashboard Cards:
- Vulnerabilities Summary (by severity with progress bars)
- Risk Overview (circular score with trend indicator)
- Reachability (donut chart with legend)
- Compliance Status
- Active Policies
- Recent Scans
---
## 2. WELCOME PAGE
**Route:** `/welcome`
**Component:** `WelcomePageComponent`
**Location:** `src/app/features/welcome/welcome-page.component.ts`
---
## 3. ANALYZE SECTION
### 3.1 Scans & Findings
**Route:** `/findings`
**Component:** `FindingsContainerComponent`
**Location:** `src/app/features/findings/container/findings-container.component.ts`
**Additional Route:** `/findings/:scanId`
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ SCANS & FINDINGS │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ [Search/Filter Bar] [Severity ▼] [Source ▼] [Date Range] [Bulk Actions]│ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ [View Toggle: Diff-First | List | Timeline] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ ☐ │ Sev │ CVE ID │ Package │ Status │ Reach. │ Actions │ │
│ ├───┼─────┼───────────────┼────────────────┼──────────┼────────┼───────────┤ │
│ │ ☐ │ 🔴 │ CVE-2024-1234 │ log4j 2.14.1 │ Open │ ✓ Yes │ [...] [→] │ │
│ │ ☐ │ 🟠 │ CVE-2024-5678 │ spring 5.2.1 │ Triaged │ ✗ No │ [...] [→] │ │
│ │ ☐ │ 🟡 │ CVE-2024-9012 │ commons-io 2.4 │ Open │ ? TBD │ [...] [→] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│ │
│ [Pagination: < 1 2 3 ... 45 >] │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ BULK TRIAGE PANEL ──────────────────────────────────────────────────────┐ │
│ │ Selected: 3 items [Accept Risk] [Create Exception] [Export] [Dismiss] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
```
#### Related Components:
- `FindingsListComponent` - List view
- `BulkTriageViewComponent` - Bulk operations
- `AiChipRowComponent` - AI-enhanced findings
---
### 3.2 Vulnerabilities
**Route:** `/vulnerabilities`
**Component:** `VulnerabilityExplorerComponent`
**Location:** `src/app/features/vulnerabilities/vulnerability-explorer.component.ts`
**Detail Route:** `/vulnerabilities/:vulnId`
**Component:** `VulnerabilityDetailComponent`
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ VULNERABILITY EXPLORER │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ 🔍 Search CVE/Package... [Severity ▼] [CVSS ▼] [Exploited ▼] [Year ▼] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌────────────────────────────────────────────────────────────────────────────┐│
│ │ CVE ID │ CVSS │ Severity │ Description │ Exploited │ VEX ││
│ ├───────────────┼──────┼──────────┼───────────────────────┼───────────┼──────┤│
│ │ CVE-2024-... │ 9.8 │ Critical │ Remote code exec... │ 🔴 Yes │ ⚑ ││
│ │ CVE-2024-... │ 7.5 │ High │ SQL injection in... │ ⚪ No │ ││
│ │ CVE-2024-... │ 5.0 │ Medium │ Information disc... │ ⚪ No │ ⚑ ││
│ └────────────────────────────────────────────────────────────────────────────┘│
│ │
│ ┌─ VULNERABILITY DETAIL (slide-out) ───────────────────────────────────────┐ │
│ │ CVE-2024-1234 [Open in new tab] │ │
│ │ ─────────────────────────────────────────────────────────────────────── │ │
│ │ CVSS: 9.8 Critical │ │
│ │ Description: Remote code execution vulnerability in... │ │
│ │ Affected: [package@version list] │ │
│ │ VEX Statements: [consensus status] │ │
│ │ Reachability: [analysis results] │ │
│ │ Fix Available: ✓ Yes - Upgrade to version X.X.X │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 3.3 SBOM Graph
**Route:** `/graph`
**Component:** `GraphExplorerComponent`
**Location:** `src/app/features/graph/graph-explorer.component.ts`
**Required Scope:** `graph:read`
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ SBOM GRAPH EXPLORER │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ [Search node...] [Filter by type ▼] [Depth: ▼] [Layout: ▼] [Zoom: ─●─] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌─────────┐ │ │
│ │ ┌────────┤ app-svc ├────────┐ │ │
│ │ │ └────┬────┘ │ │ │
│ │ ▼ │ ▼ │ │
│ │ ┌─────────┐ │ ┌─────────┐ │ │
│ │ │ log4j │◄────────┼──────►│ spring │ │ │
│ │ │ 🔴 vuln │ │ │ 🟠 vuln │ │ │
│ │ └─────────┘ │ └────┬────┘ │ │
│ │ │ │ │ │ │
│ │ ▼ │ ▼ │ │
│ │ ┌─────────┐ ┌────┴───┐ ┌─────────┐ │ │
│ │ │ jackson │ │commons │ │ netty │ │ │
│ │ └─────────┘ └────────┘ └─────────┘ │ │
│ │ │ │
│ │ [Legend: ● Package 🔴 Critical 🟠 High 🟡 Medium ⚫ Low] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├─ NODE DETAILS ─────────────────────────────────────────────────────────────────┤
│ │ Selected: log4j@2.14.1 │ │
│ │ Type: Library │ License: Apache-2.0 │ Dependencies: 12 │ Dependents: 45 │ │
│ │ Vulnerabilities: 3 Critical, 1 High │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 3.4 Lineage
**Route:** `/lineage`
**Component:** `LineageGraphContainerComponent`
**Location:** `src/app/features/lineage/components/lineage-graph-container/lineage-graph-container.component.ts`
**Sub-routes:**
- `/lineage/:artifact/compare` - Compare with artifact context
- `/lineage/compare` - Legacy compare route
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ SBOM LINEAGE GRAPH │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ [Artifact selector ▼] [Version A ▼] ⟷ [Version B ▼] [Compare] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────────┤
│ │
│ v1.0.0 v1.1.0 v1.2.0 v1.3.0 │
│ ●─────────────●─────────────●─────────────● (lineage timeline) │
│ │ │ │ │ │
│ │ │ ┌──────┴──────┐ │ │
│ │ │ ▼ ▼ │ │
│ │ │ hotfix-a hotfix-b │ │
│ │ │ │ │ │ │
│ │ │ └──────┬──────┘ │ │
│ │ │ ▼ │ │
│ │ │ v1.2.1 │ │
│ │ │ │ │ │
│ └─────────────┴─────────────┴─────────────┘ │
│ │
├─ SMART DIFF ───────────────────────────────────────────────────────────────────┤
│ │ Comparing: v1.2.0 ⟷ v1.3.0 │ │
│ ├──────────────────────────────────────────────────────────────────────────┤ │
│ │ + Added: 3 packages 🔴 New CVEs: 2 │ │
│ │ - Removed: 1 package ✓ Fixed CVEs: 5 │ │
│ │ ↻ Changed: 7 packages ⚠ Degraded: 1 │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 3.5 Reachability Center
**Route:** `/reachability`
**Component:** `ReachabilityCenterComponent`
**Location:** `src/app/features/reachability/reachability-center.component.ts`
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ REACHABILITY CENTER │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ COVERAGE SUMMARY ───────────────────────────────────────────────────────┐ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
│ │ │ Total CVEs │ │ Reachable │ │ Unreachable│ │ Uncertain │ │ │
│ │ │ 1,234 │ │ 456 │ │ 678 │ │ 100 │ │ │
│ │ │ │ │ (37%) │ │ (55%) │ │ (8%) │ │ │
│ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ REACHABILITY BY ARTIFACT ───────────────────────────────────────────────┐ │
│ │ │ │
│ │ Artifact │ Total │ Reachable │ Unreachable │ Coverage │ │
│ │ ─────────────────────┼───────┼───────────┼─────────────┼─────────────│ │
│ │ app-backend:latest │ 45 │ 12 │ 28 │ ████░░ 62% │ │
│ │ api-gateway:v2.3 │ 32 │ 8 │ 20 │ ███░░░ 50% │ │
│ │ worker-svc:1.0.0 │ 78 │ 45 │ 25 │ ██████ 89% │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├─ CALL PATH VISUALIZATION ──────────────────────────────────────────────────────┤
│ │ Selected: CVE-2024-1234 in log4j │ │
│ │ │ │
│ │ main() → processRequest() → Logger.log() → vulnerable_function() │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 3.6 VEX Hub
**Route:** `/admin/vex-hub`
**Location:** `src/app/features/vex-hub/`
**Sub-routes:**
| Path | Component |
|---|---|
| `/admin/vex-hub` | `VexHubDashboardComponent` |
| `/admin/vex-hub/search` | `VexStatementSearchComponent` |
| `/admin/vex-hub/search/detail/:id` | `VexStatementDetailComponent` |
| `/admin/vex-hub/stats` | `VexHubStatsComponent` |
| `/admin/vex-hub/consensus` | `VexConsensusComponent` |
| `/admin/vex-hub/explorer` | `VexHubComponent` |
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ VEX HUB │
├──────────────────┬─────────────────────────────────────────────────────────────┤
│ NAVIGATION │ │
│ ───────────── │ │
│ [Dashboard] │ VEX DASHBOARD │
│ [Search] │ ───────────────────────────────────────────────────────── │
│ [Stats] │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ [Consensus] │ │ Statements │ │ Conflicts │ │ Consensus │ │
│ [Explorer] │ │ 1,234 │ │ 12 │ │ Reached: 89%│ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ AI FEATURES │ ┌─ RECENT VEX STATEMENTS ────────────────────────────────┐ │
│ ───────────── │ │ CVE ID │ Product │ Status │ Issuer │ │
│ [AI Explain] │ │ CVE-2024-... │ app-svc │ Not Affected │ Vendor A │ │
│ [AI Justify] │ │ CVE-2024-... │ api-gw │ Fixed │ Vendor B │ │
│ [AI Remediate] │ │ CVE-2024-... │ worker │ Under Invest. │ Internal │ │
│ │ └────────────────────────────────────────────────────────┘ │
│ │ │
│ │ ┌─ CONFLICT RESOLUTION ──────────────────────────────────┐ │
│ │ │ 12 conflicts pending review → [Resolve] │ │
│ │ └────────────────────────────────────────────────────────┘ │
└──────────────────┴─────────────────────────────────────────────────────────────┘
```
#### VEX Hub Components:
- `VexHubDashboardComponent`
- `VexStatementSearchComponent`
- `VexStatementDetailComponent`
- `VexStatementDetailPanelComponent`
- `VexHubStatsComponent`
- `VexConsensusComponent`
- `VexConflictResolutionComponent`
- `VexCreateWorkflowComponent`
- `AiConsentGateComponent`
- `AiExplainPanelComponent`
- `AiJustifyPanelComponent`
- `AiRemediatePanelComponent`
---
### 3.7 Unknowns Tracking
**Route:** `/analyze/unknowns`
**Location:** `src/app/features/unknowns-tracking/`
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ UNKNOWNS TRACKING │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ SUMMARY ────────────────────────────────────────────────────────────────┐ │
│ │ Unknown Components: 234 │ Unresolved PURLs: 45 │ Missing SBOMs: 12 │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────────┤
│ [Search...] [Type ▼] [Status ▼] [Source ▼] │
├────────────────────────────────────────────────────────────────────────────────┤
│ │ Component Name │ Type │ First Seen │ Status │ Actions │ │
│ ├───────────────────┼───────────┼─────────────┼───────────┼───────────────┤ │
│ │ unknown-lib-1.0 │ Library │ 2024-01-15 │ Pending │ [Match] [Ign] │ │
│ │ mystery-pkg │ Package │ 2024-01-14 │ Reviewing │ [Match] [Ign] │ │
│ │ vendor-binary.dll │ Binary │ 2024-01-13 │ Matched │ [View] │ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 3.8 Patch Map
**Route:** `/analyze/patch-map`
**Component:** `PatchMapComponent`
**Location:** `src/app/features/binary-index/patch-map.component.ts`
Fleet-wide binary patch coverage heatmap visualization.
---
### 3.9 Scan Detail
**Route:** `/scans/:scanId`
**Component:** `ScanDetailPageComponent`
**Location:** `src/app/features/scans/scan-detail-page.component.ts`
---
### 3.10 CVSS Receipt
**Route:** `/cvss/receipts/:receiptId`
**Component:** `CvssReceiptComponent`
**Location:** `src/app/features/cvss/cvss-receipt.component.ts`
---
### 3.11 Compare View
**Route:** `/compare/:currentId`
**Component:** `CompareViewComponent`
**Location:** `src/app/features/compare/components/compare-view/compare-view.component.ts`

668
docs/ui-analysis/03_TRIAGE_POLICY_OPS_SCREENS.md Normal file
View File

@@ -0,0 +1,668 @@
# Stella Ops UI Structure - Part 3: Triage, Policy & Ops Screens
---
## 1. TRIAGE SECTION
### 1.1 Artifact Workspace
**Route:** `/triage/artifacts`
**Component:** `TriageArtifactsComponent`
**Location:** `src/app/features/triage/triage-artifacts.component.ts`
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ ARTIFACT WORKSPACE │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ [Search artifacts...] [Registry ▼] [Status ▼] [Risk Level ▼] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ ARTIFACTS LIST ─────────────────────────────────────────────────────────┐ │
│ │ Image Name │ Tag │ Risk │ Findings │ VEX │ Actions │ │
│ ├────────────────────────┼──────────┼───────┼──────────┼────────┼─────────┤ │
│ │ registry/app-svc │ v1.2.3 │ 🔴 │ 45 │ 3 │ [→] │ │
│ │ registry/api-gateway │ latest │ 🟠 │ 23 │ 1 │ [→] │ │
│ │ registry/worker │ 2.0.0 │ 🟢 │ 5 │ 5 │ [→] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 1.2 Artifact Detail / Triage Workspace
**Route:** `/triage/artifacts/:artifactId`
**Component:** `TriageWorkspaceComponent`
**Location:** `src/app/features/triage/triage-workspace.component.ts`
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ TRIAGE WORKSPACE: registry/app-svc:v1.2.3 │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ [Findings] [Components] [VEX Decisions] [Attestations] [Evidence] [History]││
│ └─────────────────────────────────────────────────────────────────────────────┘│
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ ARTIFACT INFO ─────────────────────────────────────────────────────────────┐│
│ │ Digest: sha256:abc123... │ Created: 2024-01-15 │ Size: 245MB ││
│ │ Risk Score: 78 (High) │ Total CVEs: 45 │ Exceptions: 3 ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ TRIAGE ACTIONS ─────────────────────────────────────────────────────────┐ │
│ │ Selected: 5 findings │ │
│ │ [Create VEX] [Add Exception] [Request Review] [Export Evidence] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ FINDINGS LIST ──────────────────────────────────────────────────────────┐ │
│ │ ☐ │ Sev │ CVE │ Component │ Status │ VEX │ Except │ │
│ ├───┼─────┼───────────────┼────────────────┼───────────┼─────────┼────────┤ │
│ │ ☑ │ 🔴 │ CVE-2024-1234 │ log4j@2.14.1 │ Open │ │ │ │
│ │ ☑ │ 🔴 │ CVE-2024-5678 │ spring@5.2.1 │ Triaged │ ⚑ │ │ │
│ │ ☐ │ 🟠 │ CVE-2024-9012 │ jackson@2.9 │ Excepted │ │ ✓ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
```
#### Related Components:
- `TriageAttestationDetailModalComponent`
- `VexDecisionModalComponent`
- Components in `src/app/features/triage/components/`
---
### 1.3 Exception Queue
**Route:** `/exceptions`
**Component:** `TriageArtifactsComponent` (reused)
**Location:** `src/app/features/triage/triage-artifacts.component.ts`
---
### 1.4 Audit Bundles
**Route:** `/triage/audit-bundles`
**Component:** `TriageAuditBundlesComponent`
**Location:** `src/app/features/triage/triage-audit-bundles.component.ts`
**Create Route:** `/triage/audit-bundles/new`
**Component:** `TriageAuditBundleNewComponent`
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ AUDIT BUNDLES │
├────────────────────────────────────────────────────────────────────────────────┤
│ [Search bundles...] [Status ▼] [Date Range] [+ New Bundle] │
├────────────────────────────────────────────────────────────────────────────────┤
│ │ Bundle ID │ Created │ Artifacts │ Status │ Signed │ Actions │ │
│ ├────────────────┼──────────────┼───────────┼───────────┼─────────┼─────────┤ │
│ │ AUDIT-2024-001 │ 2024-01-15 │ 12 │ Complete │ ✓ │ [↓] [→] │ │
│ │ AUDIT-2024-002 │ 2024-01-14 │ 8 │ Pending │ │ [→] │ │
│ │ AUDIT-2024-003 │ 2024-01-13 │ 25 │ Complete │ ✓ │ [↓] [→] │ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 1.5 Risk Dashboard
**Route:** `/risk`
**Component:** `RiskDashboardComponent`
**Location:** `src/app/features/risk/risk-dashboard.component.ts`
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ RISK PROFILES │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ RISK OVERVIEW ──────────────────────────────────────────────────────────┐ │
│ │ ┌───────────────┐ │ │
│ │ / 72 \ Overall Risk Score │ │
│ │ │ ↓ 3% from │ ────────────────────────────────────────────────│ │
│ │ \ last week / • Critical Findings: 12 │ │
│ │ └───────────────┘ • High Findings: 45 │ │
│ │ • Active Exceptions: 23 │ │
│ │ • Compliance Gaps: 5 │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ RISK BY ARTIFACT ───────────────────────────────────────────────────────┐ │
│ │ Artifact │ Score │ Trend │ Critical │ High │ Exceptions │ │
│ ├──────────────────┼───────┼────────┼──────────┼──────┼───────────────────┤ │
│ │ app-svc │ 85 │ ↑ +5 │ 5 │ 12 │ 3 │ │
│ │ api-gateway │ 62 │ ↓ -8 │ 2 │ 8 │ 2 │ │
│ │ worker │ 35 │ = 0 │ 0 │ 3 │ 1 │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├─ RISK DRIFT ───────────────────────────────────────────────────────────────────┤
│ │ [Time-series chart showing risk score changes over time] │ │
│ │ 100 ┤ │ │
│ │ 75 ┤ ╭──╮ ╭───── │ │
│ │ 50 ┤ ╭───╯ ╰────╯ │ │
│ │ 25 ┤──╯ │ │
│ │ 0 └──────────────────────────────────────────────────────────── │ │
│ │ Jan Feb Mar Apr May Jun │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
## 2. POLICY SECTION
### 2.1 Policy Studio - Workspace
**Route:** `/policy-studio/packs`
**Component:** `PolicyWorkspaceComponent`
**Location:** `src/app/features/policy-studio/workspace/policy-workspace.component.ts`
**Required Scope:** `policy:read`
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ POLICY STUDIO │
├────────────────────────────────────────────────────────────────────────────────┤
│ [+ New Pack] [Search packs...] [Status ▼] [Environment ▼] │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ POLICY PACKS ───────────────────────────────────────────────────────────┐ │
│ │ Pack Name │ Version │ Status │ Envs │ Rules │ Actions │ │
│ ├────────────────────┼─────────┼───────────┼───────────┼───────┼──────────┤ │
│ │ security-baseline │ v2.3.0 │ Active │ Prod,Stg │ 45 │ [Edit] │ │
│ │ compliance-pci │ v1.0.0 │ Draft │ - │ 23 │ [Edit] │ │
│ │ internal-standards │ v3.1.0 │ Pending │ Dev │ 67 │ [Review] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 2.2 Policy Editor
**Route:** `/policy-studio/packs/:packId/editor`
**Component:** `PolicyEditorComponent`
**Location:** `src/app/features/policy-studio/editor/policy-editor.component.ts`
**Required Scope:** `policy:author`
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ POLICY EDITOR: security-baseline v2.3.0 │
├────────────────────────────────────────────────────────────────────────────────┤
│ [Editor] [YAML] [Simulate] [Approvals] [Rules] [Dashboard] │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────┬────────────────────────────────────────────┐ │
│ │ RULES TREE │ RULE DETAILS │ │
│ │ ───────────── │ ───────────────────────────────────────── │ │
│ │ ▼ vulnerability-gates │ Rule: block-critical-cves │ │
│ │ ├── block-critical-cves │ ────────────────────────────────────────── │ │
│ │ ├── warn-high-cves │ Description: │ │
│ │ └── require-fix-path │ Block artifacts with critical CVEs │ │
│ │ ▼ compliance-checks │ │ │
│ │ ├── require-sbom │ Condition: │ │
│ │ ├── verify-signatures │ cvss_score >= 9.0 AND status == "open" │ │
│ │ └── check-licenses │ │ │
│ │ ▼ quality-gates │ Action: BLOCK │ │
│ │ ├── test-coverage │ Message: "Critical CVE detected..." │ │
│ │ └── code-review │ │ │
│ │ │ [Edit Rule] [Test Rule] [Delete] │ │
│ └─────────────────────────────┴────────────────────────────────────────────┘ │
├─ ACTIONS ──────────────────────────────────────────────────────────────────────┤
│ [Save Draft] [Validate] [Submit for Review] [History] │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 2.3 Policy YAML Editor
**Route:** `/policy-studio/packs/:packId/yaml`
**Component:** `PolicyYamlEditorComponent`
**Location:** `src/app/features/policy-studio/yaml/policy-yaml-editor.component.ts`
**Required Scope:** `policy:author`
---
### 2.4 Policy Simulation
**Route:** `/policy-studio/packs/:packId/simulate`
**Component:** `PolicySimulationComponent`
**Location:** `src/app/features/policy-studio/simulation/policy-simulation.component.ts`
**Required Scope:** `policy:simulate`
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ POLICY SIMULATION: security-baseline v2.3.0 │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ INPUT ──────────────────────────────────────────────────────────────────┐ │
│ │ Artifact: [Select artifact... ▼] Environment: [Staging ▼] │ │
│ │ [Run Simulation] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ SIMULATION RESULTS ─────────────────────────────────────────────────────┐ │
│ │ Overall Verdict: 🔴 BLOCKED │ │
│ │ ─────────────────────────────────────────────────────────────────────── │ │
│ │ Rule │ Result │ Details │ │
│ │ ────────────────────────┼──────────┼────────────────────────────────────│ │
│ │ block-critical-cves │ 🔴 BLOCK │ 3 critical CVEs found │ │
│ │ warn-high-cves │ 🟡 WARN │ 12 high CVEs found │ │
│ │ require-sbom │ 🟢 PASS │ SBOM present and valid │ │
│ │ verify-signatures │ 🟢 PASS │ Valid signature from trusted key │ │
│ │ check-licenses │ 🟡 WARN │ GPL-3.0 detected in 2 components │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├─ EXPLAIN ──────────────────────────────────────────────────────────────────────┤
│ │ [AI-powered explanation of simulation results] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 2.5 Policy Approvals
**Route:** `/policy-studio/packs/:packId/approvals`
**Component:** `PolicyApprovalsComponent`
**Location:** `src/app/features/policy-studio/approvals/policy-approvals.component.ts`
**Required Scope:** `policy:review` OR `policy:approve`
---
### 2.6 Policy Rule Builder
**Route:** `/policy-studio/packs/:packId/rules`
**Component:** `PolicyRuleBuilderComponent`
**Location:** `src/app/features/policy-studio/rule-builder/policy-rule-builder.component.ts`
**Required Scope:** `policy:author`
---
### 2.7 Policy Explain
**Route:** `/policy-studio/packs/:packId/explain/:runId`
**Component:** `PolicyExplainComponent`
**Location:** `src/app/features/policy-studio/explain/policy-explain.component.ts`
**Required Scope:** `policy:read`
---
### 2.8 Policy Dashboard
**Route:** `/policy-studio/packs/:packId/dashboard`
**Component:** `PolicyDashboardComponent`
**Location:** `src/app/features/policy-studio/dashboard/policy-dashboard.component.ts`
**Required Scope:** `policy:read`
---
### 2.9 Orchestrator Dashboard
**Route:** `/orchestrator`
**Component:** `OrchestratorDashboardComponent`
**Location:** `src/app/features/orchestrator/orchestrator-dashboard.component.ts`
**Required Scope:** `orch:read`
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ ORCHESTRATOR DASHBOARD │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ SUMMARY ────────────────────────────────────────────────────────────────┐ │
│ │ Running: 5 │ Queued: 12 │ Completed: 1,234 │ Failed: 23 │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────────┤
│ [Search jobs...] [Type ▼] [Status ▼] [Date Range] │
├────────────────────────────────────────────────────────────────────────────────┤
│ │ Job ID │ Type │ Artifact │ Status │ Started │ Action│ │
│ ├─────────────┼─────────────┼────────────────┼──────────┼───────────┼───────┤ │
│ │ JOB-12345 │ Scan │ app-svc:v1.2.3 │ Running │ 2m ago │ [→] │ │
│ │ JOB-12344 │ Policy │ api-gw:latest │ Complete │ 5m ago │ [→] │ │
│ │ JOB-12343 │ Reachability│ worker:2.0.0 │ Failed │ 10m ago │ [↻] │ │
│ │ JOB-12342 │ Export │ bundle-001 │ Complete │ 15m ago │ [↓] │ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 2.10 Orchestrator Jobs
**Route:** `/orchestrator/jobs`
**Component:** `OrchestratorJobsComponent`
**Location:** `src/app/features/orchestrator/orchestrator-jobs.component.ts`
**Required Scope:** `orch:read`
---
### 2.11 Orchestrator Job Detail
**Route:** `/orchestrator/jobs/:jobId`
**Component:** `OrchestratorJobDetailComponent`
**Location:** `src/app/features/orchestrator/orchestrator-job-detail.component.ts`
**Required Scope:** `orch:read`
---
### 2.12 Orchestrator Quotas
**Route:** `/orchestrator/quotas`
**Component:** `OrchestratorQuotasComponent`
**Location:** `src/app/features/orchestrator/orchestrator-quotas.component.ts`
**Required Scope:** `orch:operator`
---
## 3. OPS SECTION
### 3.1 SBOM Sources
**Route:** `/sbom-sources`
**Location:** `src/app/features/sbom-sources/`
**Sub-routes:**
| Path | Component | Title |
|---|---|---|
| `/sbom-sources` | `SourcesListComponent` | SBOM Sources |
| `/sbom-sources/new` | `SourceWizardComponent` | Create SBOM Source |
| `/sbom-sources/:id` | `SourceDetailComponent` | Source Details |
| `/sbom-sources/:id/edit` | `SourceWizardComponent` | Edit Source |
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ SBOM SOURCES │
├────────────────────────────────────────────────────────────────────────────────┤
│ [+ New Source] [Search sources...] [Type ▼] [Status ▼] │
├────────────────────────────────────────────────────────────────────────────────┤
│ │ Source Name │ Type │ URL │ Status │ Last Sync │ │
│ ├─────────────────┼───────────┼──────────────────────┼─────────┼────────────┤ │
│ │ docker-hub │ Registry │ registry.docker.io │ 🟢 OK │ 2m ago │ │
│ │ github-actions │ CI │ github.com/org │ 🟢 OK │ 5m ago │ │
│ │ gitlab-ci │ CI │ gitlab.company.com │ 🟡 Warn │ 1h ago │ │
│ │ local-registry │ Registry │ registry.local:5000 │ 🔴 Error│ 2d ago │ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 3.2 Quota Dashboard
**Route:** `/ops/quotas`
**Location:** `src/app/features/quota-dashboard/`
**Sub-routes:**
| Path | Component |
|---|---|
| `/ops/quotas` | `QuotaDashboardComponent` |
| `/ops/quotas/tenants` | `TenantQuotaTableComponent` |
| `/ops/quotas/tenants/:tenantId` | `TenantQuotaDetailComponent` |
| `/ops/quotas/throttle` | `ThrottleContextComponent` |
| `/ops/quotas/alerts` | `QuotaAlertConfigComponent` |
| `/ops/quotas/forecast` | `QuotaForecastComponent` |
| `/ops/quotas/reports` | `QuotaReportExportComponent` |
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ QUOTA DASHBOARD │
├──────────────────┬─────────────────────────────────────────────────────────────┤
│ NAVIGATION │ QUOTA OVERVIEW │
│ ───────────── │ ───────────────────────────────────────────────────────── │
│ [Overview] │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ [Tenant Usage] │ │ Scan Quota │ │ API Calls │ │ Storage │ │
│ [Throttle] │ │ 67% used │ │ 45% used │ │ 82% used │ │
│ [Forecast] │ │ ████░░ │ │ ███░░░ │ │ █████░ │ │
│ [Alert Config] │ └────────────┘ └────────────┘ └────────────┘ │
│ [Reports] │ │
│ │ ┌─ QUOTA TRENDS ─────────────────────────────────────────┐│
│ │ │ [Time-series chart] ││
│ │ └─────────────────────────────────────────────────────────┘│
│ │ │
│ │ ┌─ ALERTS ────────────────────────────────────────────────┐│
│ │ │ ⚠ Storage quota at 82% - forecast exhaustion in 14 days││
│ │ │ ⚠ Tenant "prod-team" exceeded scan rate limit ││
│ │ └─────────────────────────────────────────────────────────┘│
└──────────────────┴─────────────────────────────────────────────────────────────┘
```
---
### 3.3 Dead-Letter Queue
**Route:** `/ops/orchestrator/dead-letter`
**Location:** `src/app/features/deadletter/`
**Sub-routes:**
| Path | Component |
|---|---|
| `/ops/orchestrator/dead-letter` | Dashboard |
| `/ops/orchestrator/dead-letter/queue` | Queue Browser |
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ DEAD-LETTER QUEUE │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ QUEUE STATS ────────────────────────────────────────────────────────────┐ │
│ │ Total: 23 │ Retryable: 18 │ Permanent: 5 │ Oldest: 2 days │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────────┤
│ [Search...] [Error Type ▼] [Job Type ▼] [Retry All] [Purge Permanent] │
├────────────────────────────────────────────────────────────────────────────────┤
│ │ Job ID │ Type │ Error │ Retries │ Actions │ │
│ ├─────────────┼───────────┼──────────────────────┼─────────┼───────────────┤ │
│ │ JOB-ERR-001 │ Scan │ Timeout connecting...│ 3/5 │ [↻] [🗑] [→] │ │
│ │ JOB-ERR-002 │ Export │ Out of memory │ 5/5 │ [🗑] [→] │ │
│ │ JOB-ERR-003 │ Policy │ Invalid policy pack │ 2/5 │ [↻] [🗑] [→] │ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 3.4 SLO Monitoring
**Route:** `/ops/orchestrator/slo`
**Location:** `src/app/features/slo-monitoring/`
**Sub-routes:**
| Path | Component |
|---|---|
| `/ops/orchestrator/slo` | Dashboard |
| `/ops/orchestrator/slo/alerts` | Alerts |
| `/ops/orchestrator/slo/definitions` | Definitions |
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ SLO MONITORING │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ SLO STATUS ─────────────────────────────────────────────────────────────┐ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │
│ │ │ Scan Latency │ │ API Availability│ │ Policy Eval │ │ │
│ │ │ Target: < 30s │ │ Target: 99.9% │ │ Target: < 100ms │ │ │
│ │ │ Current: 28s │ │ Current: 99.95% │ │ Current: 85ms │ │ │
│ │ │ 🟢 HEALTHY │ │ 🟢 HEALTHY │ │ 🟢 HEALTHY │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ BURN RATE ──────────────────────────────────────────────────────────────┐ │
│ │ SLO Name │ Budget │ Burned │ Rate │ Status │ TTL │ │
│ │ ─────────────────┼────────┼────────┼─────────┼──────────┼──────────────│ │
│ │ Scan Latency │ 0.1% │ 0.02% │ 0.5x │ 🟢 Safe │ 45 days │ │
│ │ API Availability │ 0.1% │ 0.05% │ 1.2x │ 🟡 Watch │ 18 days │ │
│ │ Policy Eval │ 0.1% │ 0.01% │ 0.2x │ 🟢 Safe │ 90+ days │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 3.5 Platform Health
**Route:** `/ops/health`
**Location:** `src/app/features/platform-health/`
**Sub-routes:**
| Path | Component |
|---|---|
| `/ops/health` | `PlatformHealthDashboardComponent` |
| `/ops/health/services/:serviceName` | `ServiceDetailComponent` |
| `/ops/health/incidents` | `IncidentTimelineComponent` |
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ PLATFORM HEALTH DASHBOARD │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ SERVICE STATUS ─────────────────────────────────────────────────────────┐ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Scanner │ │ Policy │ │ Authority│ │ VEX Hub │ │ Evidence │ │ │
│ │ │ 🟢 OK │ │ 🟢 OK │ │ 🟢 OK │ │ 🟡 Warn │ │ 🟢 OK │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Scheduler│ │ Graph │ │ Integrat.│ │ Notifier │ │ Telemetry│ │ │
│ │ │ 🟢 OK │ │ 🟢 OK │ │ 🔴 Error │ │ 🟢 OK │ │ 🟢 OK │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ DEPENDENCIES ───────────────────────────────────────────────────────────┐ │
│ │ PostgreSQL: 🟢 │ Redis: 🟢 │ RabbitMQ: 🟢 │ S3: 🟢 │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ RECENT INCIDENTS ───────────────────────────────────────────────────────┐ │
│ │ Time │ Service │ Severity │ Status │ Duration │ │
│ │ 10:23 UTC │ Integrations │ 🔴 High │ Active │ 15m (ongoing) │ │
│ │ 09:45 UTC │ VEX Hub │ 🟡 Medium │ Resolved │ 8m │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 3.6 Feed Mirror & AirGap
**Route:** `/ops/feeds`
**Location:** `src/app/features/feed-mirror/`
**Sub-routes:**
| Path | Component |
|---|---|
| `/ops/feeds` | `FeedMirrorDashboardComponent` |
| `/ops/feeds/mirror/:mirrorId` | `MirrorDetailComponent` |
| `/ops/feeds/airgap/import` | `AirgapImportComponent` |
| `/ops/feeds/airgap/export` | `AirgapExportComponent` |
| `/ops/feeds/version-locks` | `VersionLockComponent` |
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ FEED MIRROR & AIRGAP OPERATIONS │
├────────────────────────────────────────────────────────────────────────────────┤
│ [Dashboard] [Import Bundle] [Export Bundle] [Version Locks] │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ FEED STATUS ────────────────────────────────────────────────────────────┐ │
│ │ Feed Name │ Version │ Last Sync │ Status │ Size │ │
│ │ ────────────────────┼────────────┼────────────┼─────────┼─────────────│ │
│ │ NVD │ 2024-01-15 │ 2h ago │ 🟢 OK │ 2.3 GB │ │
│ │ Trivy │ 2024-01-15 │ 1h ago │ 🟢 OK │ 856 MB │ │
│ │ OSV │ 2024-01-14 │ 1d ago │ 🟡 Stale│ 1.2 GB │ │
│ │ GitHub Advisories │ 2024-01-15 │ 30m ago │ 🟢 OK │ 245 MB │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ AIRGAP BUNDLES ─────────────────────────────────────────────────────────┐ │
│ │ Bundle ID │ Created │ Size │ Signed │ Status │ Action │ │
│ │ ───────────────┼──────────────┼─────────┼─────────┼───────────┼────────│ │
│ │ AIRGAP-2024-01 │ 2024-01-15 │ 4.5 GB │ ✓ │ Ready │ [↓] │ │
│ │ AIRGAP-2024-02 │ 2024-01-10 │ 4.2 GB │ ✓ │ Imported │ [→] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 3.7 Offline Kit
**Route:** `/ops/offline-kit`
**Location:** `src/app/features/offline-kit/`
**Sub-routes:**
| Path | Component |
|---|---|
| `/ops/offline-kit` | `OfflineKitComponent` (shell) |
| `/ops/offline-kit/dashboard` | `OfflineDashboardComponent` |
| `/ops/offline-kit/bundles` | `BundleManagementComponent` |
| `/ops/offline-kit/verify` | `VerificationCenterComponent` |
| `/ops/offline-kit/jwks` | `JwksManagementComponent` |
---
### 3.8 AOC Compliance
**Route:** `/ops/aoc`
**Location:** `src/app/features/aoc-compliance/`
**Sub-routes:**
| Path | Component |
|---|---|
| `/ops/aoc` | `AocComplianceDashboardComponent` |
| `/ops/aoc/violations` | `GuardViolationsListComponent` |
| `/ops/aoc/ingestion` | `IngestionFlowComponent` |
| `/ops/aoc/provenance` | `ProvenanceValidatorComponent` |
| `/ops/aoc/report` | `ComplianceReportComponent` |
---
### 3.9 Scheduler Operations
**Route:** `/scheduler`
**Location:** `src/app/features/scheduler-ops/`
**Sub-routes:**
| Path | Component |
|---|---|
| `/scheduler/runs` | `SchedulerRunsComponent` |
| `/scheduler/schedules` | `ScheduleManagementComponent` |
| `/scheduler/workers` | `WorkerFleetComponent` |
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ SCHEDULER OPERATIONS │
├────────────────────────────────────────────────────────────────────────────────┤
│ [Runs] [Schedules] [Workers] │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ SCHEDULED JOBS ─────────────────────────────────────────────────────────┐ │
│ │ Schedule Name │ Cron │ Next Run │ Last Run │ Status │ │
│ │ ────────────────┼──────────────┼───────────────┼────────────┼───────────│ │
│ │ daily-scan │ 0 0 * * * │ in 4h 23m │ 19h ago │ 🟢 Active │ │
│ │ hourly-sync │ 0 * * * * │ in 23m │ 37m ago │ 🟢 Active │ │
│ │ weekly-report │ 0 0 * * 0 │ in 3d 4h │ 3d ago │ 🟢 Active │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ WORKER FLEET ───────────────────────────────────────────────────────────┐ │
│ │ Worker ID │ Status │ Current Job │ Queue │ Uptime │ CPU │ │
│ │ ─────────────┼──────────┼──────────────┼──────────┼──────────┼─────────│ │
│ │ worker-01 │ 🟢 Busy │ JOB-12345 │ scan │ 5d 4h │ 45% │ │
│ │ worker-02 │ 🟢 Idle │ - │ scan │ 5d 4h │ 12% │ │
│ │ worker-03 │ 🔴 Down │ - │ export │ - │ - │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 3.10 Doctor Diagnostics
**Route:** `/ops/doctor`
**Component:** `DoctorDashboardComponent`
**Location:** `src/app/features/doctor/doctor-dashboard.component.ts`
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ DOCTOR DIAGNOSTICS │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ SYSTEM HEALTH CHECK ────────────────────────────────────────────────────┐ │
│ │ [Run Full Diagnostics] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ DIAGNOSTIC RESULTS ─────────────────────────────────────────────────────┐ │
│ │ Check │ Status │ Details │ Action │ │
│ │ ────────────────────────┼──────────┼──────────────────────────┼─────────│ │
│ │ Database connectivity │ 🟢 Pass │ 5ms latency │ │ │
│ │ Redis connectivity │ 🟢 Pass │ 2ms latency │ │ │
│ │ Certificate validity │ 🟡 Warn │ Expires in 14 days │ [Fix] │ │
│ │ Feed freshness │ 🟢 Pass │ All feeds < 24h old │ │ │
│ │ Storage capacity │ 🟡 Warn │ 82% used │ [→] │ │
│ │ Worker health │ 🔴 Fail │ 1 of 3 workers down │ [Fix] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├─ RECOMMENDATIONS ──────────────────────────────────────────────────────────────┤
│ │ 1. Renew TLS certificate before expiration │ │
│ │ 2. Consider expanding storage or enabling cleanup policies │ │
│ │ 3. Investigate worker-03 failure and restart if necessary │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
```

645
docs/ui-analysis/04_ADMIN_CONFIG_RELEASE_EVIDENCE_SCREENS.md Normal file
View File

@@ -0,0 +1,645 @@
# Stella Ops UI Structure - Part 4: Admin, Configuration, Release & Evidence Screens
---
## 1. ADMIN SECTION
### 1.1 Console Admin
**Route:** `/console/admin`
**Location:** `src/app/features/console-admin/`
**Required Scope:** `ui.admin`
**Sub-routes:**
| Path | Component | Required Scope |
|---|---|---|
| `/console/admin/tenants` | `TenantsListComponent` | authority:tenants:read |
| `/console/admin/users` | `UsersListComponent` | authority:users:read |
| `/console/admin/roles` | `RolesListComponent` | authority:roles:read |
| `/console/admin/clients` | `ClientsListComponent` | authority:clients:read |
| `/console/admin/tokens` | `TokensListComponent` | authority:tokens:read |
| `/console/admin/audit` | `AuditLogComponent` | authority:audit:read |
| `/console/admin/branding` | `BrandingEditorComponent` | authority:branding:read |
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ CONSOLE ADMIN │
├──────────────────┬─────────────────────────────────────────────────────────────┤
│ ADMIN MENU │ │
│ ───────────── │ │
│ [Tenants] │ Current View: TENANTS │
│ [Users] │ ───────────────────────────────────────────────────────── │
│ [Roles & Scopes] │ [+ New Tenant] [Search tenants...] │
│ [OAuth Clients] │ │
│ [Tokens] │ │ Tenant Name │ ID │ Users │ Status │ Actions │ │
│ [Audit Log] │ ├───────────────┼───────────┼───────┼─────────┼──────────┤ │
│ [Branding] │ │ Production │ prod-001 │ 45 │ 🟢 Active│ [Edit] │ │
│ │ │ Staging │ stg-001 │ 12 │ 🟢 Active│ [Edit] │ │
│ │ │ Development │ dev-001 │ 8 │ 🟢 Active│ [Edit] │ │
│ │ │ Partner Org │ part-001 │ 5 │ 🟡 Trial │ [Edit] │ │
└──────────────────┴─────────────────────────────────────────────────────────────┘
```
---
### 1.2 Unified Audit Log
**Route:** `/admin/audit`
**Location:** `src/app/features/audit-log/`
**Sub-routes:**
| Path | Component |
|---|---|
| `/admin/audit` | `AuditLogDashboardComponent` |
| `/admin/audit/events` | `AuditLogTableComponent` |
| `/admin/audit/events/:eventId` | `AuditEventDetailComponent` |
| `/admin/audit/timeline` | `AuditTimelineSearchComponent` |
| `/admin/audit/correlations` | `AuditCorrelationsComponent` |
| `/admin/audit/anomalies` | `AuditAnomaliesComponent` |
| `/admin/audit/export` | `AuditExportComponent` |
| `/admin/audit/policy` | `AuditPolicyComponent` |
| `/admin/audit/authority` | `AuditAuthorityComponent` |
| `/admin/audit/vex` | `AuditVexComponent` |
| `/admin/audit/integrations` | `AuditIntegrationsComponent` |
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ UNIFIED AUDIT LOG │
├────────────────────────────────────────────────────────────────────────────────┤
│ [Dashboard] [All Events] [Timeline] [Correlations] [Anomalies] [Export] │
│ [Policy Audit] [Authority Audit] [VEX Audit] [Integration Audit] │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ FILTERS ────────────────────────────────────────────────────────────────┐ │
│ │ [Search...] [Module ▼] [Action ▼] [User ▼] [Date Range] [Severity ▼] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────────┤
│ │ Timestamp │ Module │ Action │ User │ Details │ │
│ ├──────────────────┼───────────┼─────────────┼────────────┼───────────────┤ │
│ │ 2024-01-15 10:23 │ Policy │ Approved │ admin@... │ Pack v2.3.0 │ │
│ │ 2024-01-15 10:22 │ Authority │ Token Issue │ system │ OAuth grant │ │
│ │ 2024-01-15 10:21 │ VEX │ Statement │ user1@... │ CVE-2024-1234 │ │
│ │ 2024-01-15 10:20 │ Scanner │ Scan Start │ scheduler │ app-svc:v1.2 │ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 1.3 Trust Management
**Route:** `/admin/trust`
**Location:** `src/app/features/trust-admin/`
**Required Scope:** `signer:read`
**Sub-routes:**
| Path | Component |
|---|---|
| `/admin/trust` | `TrustAdminComponent` (shell) |
| `/admin/trust/keys` | `SigningKeyDashboardComponent` |
| `/admin/trust/issuers` | `IssuerTrustListComponent` |
| `/admin/trust/certificates` | `CertificateInventoryComponent` |
| `/admin/trust/audit` | `TrustAuditLogComponent` |
| `/admin/trust/airgap` | `AirgapAuditComponent` |
| `/admin/trust/incidents` | `IncidentAuditComponent` |
| `/admin/trust/analytics` | `TrustAnalyticsComponent` |
| `/admin/trust/score-config` | `TrustScoreConfigComponent` |
#### Additional Components:
- `KeyDetailPanelComponent`
- `KeyExpiryWarningComponent`
- `KeyRotationWizardComponent`
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ TRUST MANAGEMENT │
├──────────────────┬─────────────────────────────────────────────────────────────┤
│ TRUST MENU │ │
│ ───────────── │ SIGNING KEYS │
│ [Signing Keys] │ ───────────────────────────────────────────────────────── │
│ [Issuers] │ [+ Generate Key] [Import Key] │
│ [Certificates] │ │
│ [Audit Log] │ │ Key ID │ Algorithm │ Created │ Expires │ Status│ │
│ [AirGap Audit] │ ├────────────┼───────────┼────────────┼──────────┼───────┤ │
│ [Incidents] │ │ key-prod-1 │ ECDSA-256 │ 2024-01-01 │ 2025-01 │ 🟢 Act│ │
│ [Score Config] │ │ key-prod-2 │ RSA-4096 │ 2023-06-01 │ 2024-06 │ 🟡 Exp│ │
│ [Analytics] │ │ key-stg-1 │ ECDSA-256 │ 2024-01-01 │ 2025-01 │ 🟢 Act│ │
│ │ │
│ │ ┌─ KEY ROTATION WIZARD ─────────────────────────────────┐ │
│ │ │ Recommended: Rotate key-prod-2 before expiration │ │
│ │ │ [Start Rotation Wizard] │ │
│ │ └───────────────────────────────────────────────────────┘ │
└──────────────────┴─────────────────────────────────────────────────────────────┘
```
---
### 1.4 Registry Admin
**Route:** `/admin/registries`
**Location:** `src/app/features/registry-admin/`
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ REGISTRY TOKEN SERVICE │
├────────────────────────────────────────────────────────────────────────────────┤
│ [+ New Registry] [Search registries...] │
├────────────────────────────────────────────────────────────────────────────────┤
│ │ Registry Name │ URL │ Auth Type │ Status │ Actions │ │
│ ├─────────────────┼────────────────────────┼────────────┼─────────┼─────────┤ │
│ │ Docker Hub │ registry.docker.io │ Token │ 🟢 OK │ [Edit] │ │
│ │ GitHub CR │ ghcr.io │ PAT │ 🟢 OK │ [Edit] │ │
│ │ ECR Prod │ 123.dkr.ecr.aws │ IAM Role │ 🟢 OK │ [Edit] │ │
│ │ Private │ registry.internal:5000 │ Basic │ 🟡 Exp │ [Edit] │ │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ TOKEN PLANS ────────────────────────────────────────────────────────────┐ │
│ │ Plan Name │ Registries │ Expiry │ Permissions │ Actions │ │
│ │ ──────────────┼────────────┼───────────┼────────────────────┼───────────│ │
│ │ ci-readonly │ 3 │ 24h │ pull │ [Edit] │ │
│ │ deploy-prod │ 2 │ 1h │ pull, push │ [Edit] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 1.5 Issuer Trust / Issuer Directory
**Route:** `/admin/issuers`
**Location:** `src/app/features/issuer-trust/`
---
### 1.6 Scanner Ops
**Route:** `/ops/scanner`
**Location:** `src/app/features/scanner-ops/`
**Sub-routes:**
| Path | Component |
|---|---|
| `/ops/scanner` | `ScannerOpsComponent` (shell) |
| `/ops/scanner/offline-kits` | `OfflineKitListComponent` |
| `/ops/scanner/baselines` | `BaselineListComponent` |
| `/ops/scanner/settings` | `DeterminismSettingsComponent` |
| `/ops/scanner/analyzers` | `AnalyzerHealthComponent` |
| `/ops/scanner/performance` | `PerformanceBaselineComponent` |
---
### 1.7 Notification Admin
**Route:** `/admin/notifications`
**Location:** `src/app/features/admin-notifications/`
---
### 1.8 Policy Governance
**Route:** `/admin/policy/governance`
**Location:** `src/app/features/policy-governance/`
---
### 1.9 Policy Simulation (Admin)
**Route:** `/admin/policy/simulation`
**Location:** `src/app/features/policy-simulation/`
---
### 1.10 Trivy DB Settings
**Route:** `/concelier/trivy-db-settings`
**Component:** `TrivyDbSettingsPageComponent`
**Location:** `src/app/features/trivy-db-settings/trivy-db-settings-page.component.ts`
---
### 1.11 Console Profile
**Route:** `/console/profile`
**Component:** `ConsoleProfileComponent`
**Location:** `src/app/features/console/console-profile.component.ts`
---
### 1.12 Console Status
**Route:** `/console/status`
**Component:** `ConsoleStatusComponent`
**Location:** `src/app/features/console/console-status.component.ts`
---
## 2. CONFIGURATION SECTION
### 2.1 Setup Wizard
**Route:** `/setup`
**Location:** `src/app/features/setup-wizard/`
**Sub-routes:**
| Path | Component |
|---|---|
| `/setup` | `SetupWizardComponent` |
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ STELLAOPS SETUP WIZARD │
├────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ● ─────── ○ ─────── ○ ─────── ○ ─────── ○ │ │
│ │ Welcome Database Auth Integr. Complete │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ STEP 1: WELCOME ───────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Welcome to StellaOps! │ │
│ │ │ │
│ │ This wizard will guide you through initial configuration: │ │
│ │ │ │
│ │ • Database connection │ │
│ │ • Authentication providers (OIDC/OAuth) │ │
│ │ • Registry integrations │ │
│ │ • Initial admin user │ │
│ │ │ │
│ │ Estimated time: 10-15 minutes │ │
│ │ │ │
│ │ [Skip] [Get Started →] │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 2.2 Configuration Pane
**Route:** `/console/configuration`
**Location:** `src/app/features/configuration-pane/`
**Sub-routes:**
| Path | Component |
|---|---|
| `/console/configuration` | `ConfigurationPaneComponent` |
#### Related Components:
- `IntegrationSectionComponent`
- `IntegrationDetailComponent`
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ SYSTEM CONFIGURATION │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ INTEGRATION SECTIONS ───────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │
│ │ │ 📦 REGISTRIES │ │ 🔗 SCM │ │ ⚙️ CI/CD │ │ │
│ │ │ 3 configured │ │ 2 configured │ │ 1 configured │ │ │
│ │ │ [Configure →] │ │ [Configure →] │ │ [Configure →] │ │ │
│ │ └────────────────┘ └────────────────┘ └────────────────┘ │ │
│ │ │ │
│ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │
│ │ │ 🔔 NOTIFY │ │ 📊 FEEDS │ │ 🔐 SECRETS │ │ │
│ │ │ 2 channels │ │ 4 sources │ │ 1 vault │ │ │
│ │ │ [Configure →] │ │ [Configure →] │ │ [Configure →] │ │ │
│ │ └────────────────┘ └────────────────┘ └────────────────┘ │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ INTEGRATION DETAIL (expanded) ──────────────────────────────────────────┐ │
│ │ REGISTRIES │ │
│ │ ─────────────────────────────────────────────────────────────────────── │ │
│ │ ☑ Docker Hub registry.docker.io [Edit] [Test] [Delete] │ │
│ │ ☑ GitHub CR ghcr.io [Edit] [Test] [Delete] │ │
│ │ ☑ AWS ECR 123.dkr.ecr.aws [Edit] [Test] [Delete] │ │
│ │ │ │
│ │ [+ Add Registry] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 2.3 Integration Hub
**Route:** `/integrations`
**Location:** `src/app/features/integration-hub/`
**Sub-routes:**
| Path | Component |
|---|---|
| `/integrations` | `IntegrationHubComponent` |
| `/integrations/registries` | `IntegrationListComponent` (type: Registry) |
| `/integrations/scm` | `IntegrationListComponent` (type: Scm) |
| `/integrations/ci` | `IntegrationListComponent` (type: Ci) |
| `/integrations/hosts` | `IntegrationListComponent` (type: Host) |
| `/integrations/feeds` | `IntegrationListComponent` (type: Feed) |
| `/integrations/activity` | `IntegrationActivityComponent` |
| `/integrations/:integrationId` | `IntegrationDetailComponent` |
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ INTEGRATION HUB │
├────────────────────────────────────────────────────────────────────────────────┤
│ [All] [Registries] [SCM] [CI] [Hosts] [Feeds] [Activity] │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ INTEGRATION CATALOG ────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ REGISTRIES SCM CI/CD │ │
│ │ ──────────── ──────────── ──────────── │ │
│ │ [Docker Hub] [GitHub] [GitHub Actions] │ │
│ │ [AWS ECR] [GitLab] [GitLab CI] │ │
│ │ [Google GCR] [Bitbucket] [Jenkins] │ │
│ │ [Azure ACR] [Gitea] [Azure DevOps] │ │
│ │ [Harbor] [Azure DevOps] [CircleCI] │ │
│ │ │ │
│ │ NOTIFICATION SECRETS FEEDS │ │
│ │ ──────────── ──────────── ──────────── │ │
│ │ [Slack] [HashiCorp Vault] [NVD] │ │
│ │ [Teams] [AWS Secrets] [OSV] │ │
│ │ [Email] [Azure Key Vault] [GitHub Advisories] │ │
│ │ [Webhook] [GCP Secret Mgr] [Trivy] │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
## 3. RELEASE ORCHESTRATOR SECTION
**Route:** `/release-orchestrator`
**Location:** `src/app/features/release-orchestrator/`
### 3.1 Release Dashboard
**Route:** `/release-orchestrator`
**Component:** `ReleaseDashboardComponent`
**Location:** `src/app/features/release-orchestrator/dashboard/dashboard.component.ts`
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ RELEASE ORCHESTRATOR │
├────────────────────────────────────────────────────────────────────────────────┤
│ [Dashboard] [Environments] [Releases] [Workflows] [Approvals] [Deployments] │
│ [Evidence] │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ ENVIRONMENT PIPELINE ───────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ DEV │ →→ │ QA │ →→ │ STAGING │ →→ │ PROD │ │ │
│ │ │ v1.3.0 │ │ v1.2.5 │ │ v1.2.4 │ │ v1.2.3 │ │ │
│ │ │ 🟢 OK │ │ 🟢 OK │ │ 🟡 Pend │ │ 🟢 OK │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ PENDING RELEASES ───────────────────────────────────────────────────────┐ │
│ │ Release │ From │ To │ Status │ Actions │ │
│ │ ─────────────┼──────────┼──────────┼─────────────────┼─────────────────│ │
│ │ v1.2.5 │ QA │ Staging │ ⏳ Policy Check │ [View] │ │
│ │ v1.2.6 │ Dev │ QA │ ✅ Approved │ [Deploy] [View] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ RECENT DEPLOYMENTS ─────────────────────────────────────────────────────┐ │
│ │ Deployment │ Environment │ Version │ Time │ Status │ Evidence│ │
│ │ ─────────────┼─────────────┼─────────┼────────────┼──────────┼─────────│ │
│ │ DEP-2024-045 │ Production │ v1.2.3 │ 2h ago │ 🟢 OK │ [↓] │ │
│ │ DEP-2024-044 │ Staging │ v1.2.4 │ 6h ago │ 🟢 OK │ [↓] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 3.2 Environments
**Route:** `/release-orchestrator/environments`
**Location:** `src/app/features/release-orchestrator/environments/`
---
### 3.3 Releases
**Route:** `/release-orchestrator/releases`
**Location:** `src/app/features/release-orchestrator/releases/`
---
### 3.4 Workflows
**Route:** `/release-orchestrator/workflows`
**Location:** `src/app/features/release-orchestrator/workflows/`
---
### 3.5 Approvals
**Route:** `/release-orchestrator/approvals`
**Location:** `src/app/features/release-orchestrator/approvals/`
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ RELEASE APPROVALS │
├────────────────────────────────────────────────────────────────────────────────┤
│ [Pending (3)] [Approved] [Rejected] [All] │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ PENDING APPROVALS ──────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Release: app-svc v1.2.5 → Staging │ │ │
│ │ │ Requested by: deploy-bot │ Time: 2h ago │ │ │
│ │ │ ──────────────────────────────────────────────────────────────────│ │ │
│ │ │ Policy Gates: │ │ │
│ │ │ ✅ No critical CVEs │ │ │
│ │ │ ✅ Valid SBOM and signatures │ │ │
│ │ │ ⚠️ 3 high CVEs (with VEX statements) │ │ │
│ │ │ ✅ All tests passed │ │ │
│ │ │ ──────────────────────────────────────────────────────────────────│ │ │
│ │ │ [View Evidence] [View Diff] [✓ Approve] [✗ Reject] [💬 Comment]│ │ │
│ │ └────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 3.6 Deployments
**Route:** `/release-orchestrator/deployments`
**Location:** `src/app/features/release-orchestrator/deployments/`
---
### 3.7 Evidence (Release Orchestrator)
**Route:** `/release-orchestrator/evidence`
**Location:** `src/app/features/release-orchestrator/evidence/`
---
## 4. EVIDENCE SECTION
### 4.1 Evidence Center
**Route:** `/evidence`
**Location:** `src/app/features/evidence-export/`
**Sub-routes:**
| Path | Component |
|---|---|
| `/evidence` | redirects to `/evidence/bundles` |
| `/evidence/bundles` | `EvidenceBundlesComponent` |
| `/evidence/export` | `ExportCenterComponent` |
| `/evidence/replay` | `ReplayControlsComponent` |
| `/evidence/provenance` | `ProvenanceVisualizationComponent` |
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ EVIDENCE CENTER │
├────────────────────────────────────────────────────────────────────────────────┤
│ [Bundles] [Export Center] [Verdict Replay] [Provenance] │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ EVIDENCE BUNDLES ───────────────────────────────────────────────────────┐ │
│ │ [Search bundles...] [Type ▼] [Date Range] [+ Create Bundle] │ │
│ │ │ │
│ │ │ Bundle ID │ Type │ Artifacts │ Created │ Signed │ Actions││ │
│ │ ├────────────────┼──────────┼───────────┼────────────┼────────┼────────┤│ │
│ │ │ EVD-2024-0045 │ Release │ 5 │ 2h ago │ ✓ │ [↓][→] ││ │
│ │ │ EVD-2024-0044 │ Audit │ 12 │ 1d ago │ ✓ │ [↓][→] ││ │
│ │ │ EVD-2024-0043 │ Scan │ 1 │ 2d ago │ ✓ │ [↓][→] ││ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ BUNDLE CONTENTS (expanded) ─────────────────────────────────────────────┐ │
│ │ EVD-2024-0045: Release Evidence for app-svc v1.2.5 │ │
│ │ ─────────────────────────────────────────────────────────────────────── │ │
│ │ • SBOM (CycloneDX) sha256:abc123... [View] [Download] │ │
│ │ • Scan Results sha256:def456... [View] [Download] │ │
│ │ • Policy Verdict sha256:789abc... [View] [Download] │ │
│ │ • VEX Statements (3) sha256:xyz789... [View] [Download] │ │
│ │ • Attestations (SLSA) sha256:slsa12... [View] [Download] │ │
│ │ │ │
│ │ [Download All] [Verify Signatures] [Export to Rekor] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
### 4.2 Evidence Pack List
**Route:** `/evidence-packs`
**Component:** `EvidencePackListComponent`
**Location:** `src/app/features/evidence-pack/evidence-pack-list.component.ts`
---
### 4.3 Evidence Pack Viewer
**Route:** `/evidence-packs/:packId`
**Component:** `EvidencePackViewerComponent`
**Location:** `src/app/features/evidence-pack/evidence-pack-viewer.component.ts`
---
### 4.4 Proof Chain Viewer
**Route:** `/proofs/:subjectDigest`
**Component:** `ProofChainComponent`
**Location:** `src/app/features/proof-chain/proof-chain.component.ts`
```
┌────────────────────────────────────────────────────────────────────────────────┐
│ PROOF CHAIN VIEWER │
├────────────────────────────────────────────────────────────────────────────────┤
│ Subject: sha256:abc123... │
├────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ PROOF CHAIN ────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌─────────────┐ │ │
│ │ │ Build │ ← Source attestation (GitHub Actions) │ │
│ │ │ 2024-01-15 │ │ │
│ │ └──────┬──────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌─────────────┐ │ │
│ │ │ Scan │ ← SBOM + Vulnerability scan │ │
│ │ │ 2024-01-15 │ │ │
│ │ └──────┬──────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌─────────────┐ │ │
│ │ │ Policy │ ← Policy evaluation verdict │ │
│ │ │ 2024-01-15 │ │ │
│ │ └──────┬──────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌─────────────┐ │ │
│ │ │ Approval │ ← Human approval attestation │ │
│ │ │ 2024-01-15 │ │ │
│ │ └──────┬──────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌─────────────┐ │ │
│ │ │ Deploy │ ← Deployment attestation │ │
│ │ │ 2024-01-15 │ │ │
│ │ └─────────────┘ │ │
│ │ │ │
│ │ [Verify Chain] [Export] [View in Rekor] │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────┘
```
---
## 5. OTHER SCREENS
### 5.1 AI Runs
**Route:** `/ai-runs`
**Component:** `AiRunsListComponent`
**Location:** `src/app/features/ai-runs/ai-runs-list.component.ts`
**Detail Route:** `/ai-runs/:runId`
**Component:** `AiRunViewerComponent`
---
### 5.2 Change Trace
**Route:** `/change-trace`
**Location:** `src/app/features/change-trace/`
---
### 5.3 Notifications Panel
**Route:** `/notify`
**Component:** `NotifyPanelComponent`
**Location:** `src/app/features/notify/notify-panel.component.ts`
---
### 5.4 Sources Dashboard
**Route:** `/dashboard/sources`
**Component:** `SourcesDashboardComponent`
**Location:** `src/app/features/dashboard/sources-dashboard.component.ts`
---
### 5.5 Timeline
**Route:** `/timeline`
**Location:** `src/app/features/timeline/`
---
### 5.6 Auth Callback
**Route:** `/auth/callback`
**Component:** `AuthCallbackComponent`
**Location:** `src/app/features/auth/auth-callback.component.ts`

373
docs/ui-analysis/05_ROUTE_SUMMARY_AND_OBSERVATIONS.md Normal file
View File

@@ -0,0 +1,373 @@
# Stella Ops UI Structure - Part 5: Route Summary & Observations
---
## 1. COMPLETE ROUTE TABLE
### 1.1 Home & Dashboard Routes
| Route | Component | Location | Guards |
|---|---|---|---|
| `/` | `HomeDashboardComponent` | features/home/ | requireAuthGuard |
| `/welcome` | `WelcomePageComponent` | features/welcome/ | - |
| `/dashboard/sources` | `SourcesDashboardComponent` | features/dashboard/ | - |
### 1.2 Analyze Routes
| Route | Component | Location | Guards |
|---|---|---|---|
| `/findings` | `FindingsContainerComponent` | features/findings/container/ | requireAuthGuard |
| `/findings/:scanId` | `FindingsContainerComponent` | features/findings/container/ | requireAuthGuard |
| `/vulnerabilities` | `VulnerabilityExplorerComponent` | features/vulnerabilities/ | requireAuthGuard |
| `/vulnerabilities/:vulnId` | `VulnerabilityDetailComponent` | features/vulnerabilities/ | requireAuthGuard |
| `/graph` | `GraphExplorerComponent` | features/graph/ | requireAuthGuard |
| `/lineage` | `LineageGraphContainerComponent` | features/lineage/components/ | requireAuthGuard |
| `/lineage/:artifact/compare` | `LineageCompareComponent` | features/lineage/components/ | requireAuthGuard |
| `/lineage/compare` | `LineageCompareComponent` | features/lineage/components/ | requireAuthGuard |
| `/reachability` | `ReachabilityCenterComponent` | features/reachability/ | requireAuthGuard |
| `/admin/vex-hub` | `VexHubDashboardComponent` | features/vex-hub/ | requireAuthGuard |
| `/admin/vex-hub/search` | `VexStatementSearchComponent` | features/vex-hub/ | requireAuthGuard |
| `/admin/vex-hub/search/detail/:id` | `VexStatementDetailComponent` | features/vex-hub/ | requireAuthGuard |
| `/admin/vex-hub/stats` | `VexHubStatsComponent` | features/vex-hub/ | requireAuthGuard |
| `/admin/vex-hub/consensus` | `VexConsensusComponent` | features/vex-hub/ | requireAuthGuard |
| `/admin/vex-hub/explorer` | `VexHubComponent` | features/vex-hub/ | requireAuthGuard |
| `/analyze/unknowns` | unknownsRoutes | features/unknowns-tracking/ | requireAuthGuard |
| `/analyze/patch-map` | `PatchMapComponent` | features/binary-index/ | requireAuthGuard |
| `/scans/:scanId` | `ScanDetailPageComponent` | features/scans/ | - |
| `/compare/:currentId` | `CompareViewComponent` | features/compare/components/ | requireAuthGuard |
| `/cvss/receipts/:receiptId` | `CvssReceiptComponent` | features/cvss/ | requireAuthGuard |
### 1.3 Triage Routes
| Route | Component | Location | Guards |
|---|---|---|---|
| `/triage/artifacts` | `TriageArtifactsComponent` | features/triage/ | requireAuthGuard |
| `/triage/artifacts/:artifactId` | `TriageWorkspaceComponent` | features/triage/ | requireAuthGuard |
| `/triage/audit-bundles` | `TriageAuditBundlesComponent` | features/triage/ | requireAuthGuard |
| `/triage/audit-bundles/new` | `TriageAuditBundleNewComponent` | features/triage/ | requireAuthGuard |
| `/exceptions` | `TriageArtifactsComponent` | features/triage/ | requireAuthGuard |
| `/risk` | `RiskDashboardComponent` | features/risk/ | requireAuthGuard |
### 1.4 Policy Routes
| Route | Component | Location | Guards |
|---|---|---|---|
| `/policy-studio/packs` | `PolicyWorkspaceComponent` | features/policy-studio/workspace/ | requirePolicyViewerGuard |
| `/policy-studio/packs/:packId/editor` | `PolicyEditorComponent` | features/policy-studio/editor/ | requirePolicyAuthorGuard |
| `/policy-studio/packs/:packId/yaml` | `PolicyYamlEditorComponent` | features/policy-studio/yaml/ | requirePolicyAuthorGuard |
| `/policy-studio/packs/:packId/simulate` | `PolicySimulationComponent` | features/policy-studio/simulation/ | requirePolicySimulatorGuard |
| `/policy-studio/packs/:packId/approvals` | `PolicyApprovalsComponent` | features/policy-studio/approvals/ | requirePolicyReviewOrApproveGuard |
| `/policy-studio/packs/:packId/rules` | `PolicyRuleBuilderComponent` | features/policy-studio/rule-builder/ | requirePolicyAuthorGuard |
| `/policy-studio/packs/:packId/explain/:runId` | `PolicyExplainComponent` | features/policy-studio/explain/ | requirePolicyViewerGuard |
| `/policy-studio/packs/:packId/dashboard` | `PolicyDashboardComponent` | features/policy-studio/dashboard/ | requirePolicyViewerGuard |
| `/orchestrator` | `OrchestratorDashboardComponent` | features/orchestrator/ | requireOrchViewerGuard |
| `/orchestrator/jobs` | `OrchestratorJobsComponent` | features/orchestrator/ | requireOrchViewerGuard |
| `/orchestrator/jobs/:jobId` | `OrchestratorJobDetailComponent` | features/orchestrator/ | requireOrchViewerGuard |
| `/orchestrator/quotas` | `OrchestratorQuotasComponent` | features/orchestrator/ | requireOrchOperatorGuard |
### 1.5 Ops Routes
| Route | Component | Location | Guards |
|---|---|---|---|
| `/sbom-sources` | `SourcesListComponent` | features/sbom-sources/components/ | requireAuthGuard |
| `/sbom-sources/new` | `SourceWizardComponent` | features/sbom-sources/components/ | requireAuthGuard |
| `/sbom-sources/:id` | `SourceDetailComponent` | features/sbom-sources/components/ | requireAuthGuard |
| `/sbom-sources/:id/edit` | `SourceWizardComponent` | features/sbom-sources/components/ | requireAuthGuard |
| `/ops/quotas` | quotaRoutes | features/quota-dashboard/ | requireAuthGuard |
| `/ops/quotas/tenants` | `TenantQuotaTableComponent` | features/quota-dashboard/ | requireAuthGuard |
| `/ops/quotas/tenants/:tenantId` | `TenantQuotaDetailComponent` | features/quota-dashboard/ | requireAuthGuard |
| `/ops/quotas/throttle` | `ThrottleContextComponent` | features/quota-dashboard/ | requireAuthGuard |
| `/ops/quotas/alerts` | `QuotaAlertConfigComponent` | features/quota-dashboard/ | requireAuthGuard |
| `/ops/quotas/forecast` | `QuotaForecastComponent` | features/quota-dashboard/ | requireAuthGuard |
| `/ops/quotas/reports` | `QuotaReportExportComponent` | features/quota-dashboard/ | requireAuthGuard |
| `/ops/orchestrator/dead-letter` | deadletterRoutes | features/deadletter/ | requireAuthGuard |
| `/ops/orchestrator/slo` | sloRoutes | features/slo-monitoring/ | requireAuthGuard |
| `/ops/health` | platformHealthRoutes | features/platform-health/ | requireAuthGuard |
| `/ops/feeds` | feedMirrorRoutes | features/feed-mirror/ | requireAuthGuard |
| `/ops/feeds/mirror/:mirrorId` | `MirrorDetailComponent` | features/feed-mirror/ | requireAuthGuard |
| `/ops/feeds/airgap/import` | `AirgapImportComponent` | features/feed-mirror/ | requireAuthGuard |
| `/ops/feeds/airgap/export` | `AirgapExportComponent` | features/feed-mirror/ | requireAuthGuard |
| `/ops/feeds/version-locks` | `VersionLockComponent` | features/feed-mirror/ | requireAuthGuard |
| `/ops/offline-kit` | offlineKitRoutes | features/offline-kit/ | requireAuthGuard |
| `/ops/aoc` | AOC_COMPLIANCE_ROUTES | features/aoc-compliance/ | requireAuthGuard |
| `/ops/doctor` | DOCTOR_ROUTES | features/doctor/ | requireAuthGuard |
| `/scheduler` | schedulerOpsRoutes | features/scheduler-ops/ | requireAuthGuard |
| `/scheduler/runs` | `SchedulerRunsComponent` | features/scheduler-ops/ | requireAuthGuard |
| `/scheduler/schedules` | `ScheduleManagementComponent` | features/scheduler-ops/ | requireAuthGuard |
| `/scheduler/workers` | `WorkerFleetComponent` | features/scheduler-ops/ | requireAuthGuard |
### 1.6 Notify Routes
| Route | Component | Location | Guards |
|---|---|---|---|
| `/notify` | `NotifyPanelComponent` | features/notify/ | - |
### 1.7 Admin Routes
| Route | Component | Location | Guards |
|---|---|---|---|
| `/console/admin` | consoleAdminRoutes | features/console-admin/ | requireAuthGuard + ui.admin |
| `/console/admin/tenants` | `TenantsListComponent` | features/console-admin/tenants/ | authority:tenants:read |
| `/console/admin/users` | `UsersListComponent` | features/console-admin/users/ | authority:users:read |
| `/console/admin/roles` | `RolesListComponent` | features/console-admin/roles/ | authority:roles:read |
| `/console/admin/clients` | `ClientsListComponent` | features/console-admin/clients/ | authority:clients:read |
| `/console/admin/tokens` | `TokensListComponent` | features/console-admin/tokens/ | authority:tokens:read |
| `/console/admin/audit` | `AuditLogComponent` | features/console-admin/audit/ | authority:audit:read |
| `/console/admin/branding` | `BrandingEditorComponent` | features/console-admin/branding/ | authority:branding:read |
| `/admin/audit` | auditLogRoutes | features/audit-log/ | requireAuthGuard |
| `/admin/notifications` | adminNotificationsRoutes | features/admin-notifications/ | requireAuthGuard |
| `/admin/trust` | trustAdminRoutes | features/trust-admin/ | requireAuthGuard + signer:read |
| `/admin/policy/governance` | policyGovernanceRoutes | features/policy-governance/ | requireAuthGuard |
| `/admin/policy/simulation` | policySimulationRoutes | features/policy-simulation/ | requireAuthGuard |
| `/admin/registries` | registryAdminRoutes | features/registry-admin/ | requireAuthGuard |
| `/admin/issuers` | issuerTrustRoutes | features/issuer-trust/ | requireAuthGuard |
| `/ops/scanner` | scannerOpsRoutes | features/scanner-ops/ | requireAuthGuard |
| `/concelier/trivy-db-settings` | `TrivyDbSettingsPageComponent` | features/trivy-db-settings/ | - |
### 1.8 Console Routes
| Route | Component | Location | Guards |
|---|---|---|---|
| `/console/profile` | `ConsoleProfileComponent` | features/console/ | - |
| `/console/status` | `ConsoleStatusComponent` | features/console/ | - |
| `/console/configuration` | CONFIGURATION_PANE_ROUTES | features/configuration-pane/ | requireAuthGuard |
### 1.9 Release Orchestrator Routes
| Route | Component | Location | Guards |
|---|---|---|---|
| `/release-orchestrator` | DASHBOARD_ROUTES | features/release-orchestrator/dashboard/ | requireAuthGuard |
| `/release-orchestrator/environments` | ENVIRONMENT_ROUTES | features/release-orchestrator/environments/ | requireAuthGuard |
| `/release-orchestrator/releases` | RELEASE_ROUTES | features/release-orchestrator/releases/ | requireAuthGuard |
| `/release-orchestrator/workflows` | WORKFLOW_ROUTES | features/release-orchestrator/workflows/ | requireAuthGuard |
| `/release-orchestrator/approvals` | APPROVAL_ROUTES | features/release-orchestrator/approvals/ | requireAuthGuard |
| `/release-orchestrator/deployments` | DEPLOYMENT_ROUTES | features/release-orchestrator/deployments/ | requireAuthGuard |
| `/release-orchestrator/evidence` | EVIDENCE_ROUTES | features/release-orchestrator/evidence/ | requireAuthGuard |
### 1.10 Evidence Routes
| Route | Component | Location | Guards |
|---|---|---|---|
| `/evidence` | evidenceExportRoutes | features/evidence-export/ | requireAuthGuard |
| `/evidence/bundles` | `EvidenceBundlesComponent` | features/evidence-export/ | requireAuthGuard |
| `/evidence/export` | `ExportCenterComponent` | features/evidence-export/ | requireAuthGuard |
| `/evidence/replay` | `ReplayControlsComponent` | features/evidence-export/ | requireAuthGuard |
| `/evidence/provenance` | `ProvenanceVisualizationComponent` | features/evidence-export/ | requireAuthGuard |
| `/evidence-packs` | `EvidencePackListComponent` | features/evidence-pack/ | requireAuthGuard |
| `/evidence-packs/:packId` | `EvidencePackViewerComponent` | features/evidence-pack/ | requireAuthGuard |
| `/proofs/:subjectDigest` | `ProofChainComponent` | features/proof-chain/ | requireAuthGuard |
### 1.11 Integration Routes
| Route | Component | Location | Guards |
|---|---|---|---|
| `/integrations` | integrationHubRoutes | features/integration-hub/ | requireAuthGuard |
| `/integrations/registries` | `IntegrationListComponent` | features/integration-hub/ | requireAuthGuard |
| `/integrations/scm` | `IntegrationListComponent` | features/integration-hub/ | requireAuthGuard |
| `/integrations/ci` | `IntegrationListComponent` | features/integration-hub/ | requireAuthGuard |
| `/integrations/hosts` | `IntegrationListComponent` | features/integration-hub/ | requireAuthGuard |
| `/integrations/feeds` | `IntegrationListComponent` | features/integration-hub/ | requireAuthGuard |
| `/integrations/activity` | `IntegrationActivityComponent` | features/integration-hub/ | requireAuthGuard |
| `/integrations/:integrationId` | `IntegrationDetailComponent` | features/integration-hub/ | requireAuthGuard |
### 1.12 Other Routes
| Route | Component | Location | Guards |
|---|---|---|---|
| `/ai-runs` | `AiRunsListComponent` | features/ai-runs/ | requireAuthGuard |
| `/ai-runs/:runId` | `AiRunViewerComponent` | features/ai-runs/ | requireAuthGuard |
| `/change-trace` | changeTraceRoutes | features/change-trace/ | requireAuthGuard |
| `/setup` | setupWizardRoutes | features/setup-wizard/ | - |
| `/auth/callback` | `AuthCallbackComponent` | features/auth/ | - |
| `**` | redirectTo: '' | - | - |
---
## 2. ROUTE COUNT SUMMARY
| Category | Route Count |
|---|---|
| Home & Dashboard | 3 |
| Analyze | 20 |
| Triage | 6 |
| Policy | 12 |
| Ops | 30+ |
| Notify | 1 |
| Admin | 17+ |
| Console | 3 |
| Release Orchestrator | 7 |
| Evidence | 8 |
| Integrations | 8 |
| Other | 5 |
| **TOTAL** | **~120+ routes** |
---
## 3. OBSERVATIONS
### 3.1 Navigation Structure Observations
1. **7 top-level navigation groups** defined in `navigation.config.ts`:
- HOME, ANALYZE, TRIAGE, POLICY, OPS, NOTIFY, ADMIN
2. **Deep nesting in OPS section**: The Ops navigation group contains sub-items with their own children (e.g., Quotas has 6 sub-routes, SLO Monitoring has 3 sub-routes)
3. **Admin section size**: Admin group contains 17+ items in the navigation configuration
4. **Inconsistent route prefixes**:
- VEX Hub is at `/admin/vex-hub` but shown in Analyze menu
- Scanner Ops is at `/ops/scanner` but listed under Admin menu
- Some scheduler routes are at `/scheduler` (not `/ops/scheduler`)
### 3.2 Feature Module Observations
1. **77 feature directories** under `src/app/features/`
2. **Duplicate/similar named modules**:
- `evidence/` and `evidence-export/` and `evidence-pack/` and `evidence-thread/`
- `proof/` and `proof-chain/` and `proof-studio/` and `proofs/`
- `unknowns/` and `unknowns-tracking/`
- `integrations/` and `integration-hub/`
- `vex-hub/` and `vex-studio/`
- `triage/` and `triage-inbox/`
- `policy/` and `policy-gates/` and `policy-governance/` and `policy-simulation/` and `policy-studio/`
3. **Orphaned/unused modules** (exist as directories but not in main routes):
- `advisory-ai/`
- `aoc/` (vs `aoc-compliance/`)
- `evidence/` (vs `evidence-export/`)
- `exceptions/` (route uses triage component)
- `integrations/` (vs `integration-hub/`)
- `opsmemory/`
- `policy/` (vs `policy-studio/`)
- `proof/` (vs `proof-chain/`)
- `proofs/` (vs `proof-chain/`)
- `releases/` (vs release-orchestrator)
- `runs/`
- `sbom/`
- `scores/`
- `secret-detection/`
- `settings/`
- `snapshot/`
- `sources/`
- `triage-inbox/`
- `unknowns/` (vs `unknowns-tracking/`)
- `verdicts/`
- `vex-studio/`
- `vuln-explorer/` (vs `vulnerabilities/`)
### 3.3 Route Path Observations
1. **Mixed path conventions**:
- Some use `/admin/` prefix: `/admin/vex-hub`, `/admin/trust`, `/admin/audit`
- Some use `/console/admin/`: `/console/admin/tenants`, `/console/admin/users`
- Some use `/ops/`: `/ops/quotas`, `/ops/health`, `/ops/feeds`
- Some use root: `/scheduler`, `/evidence`, `/integrations`
2. **Inconsistent pluralization**:
- `/vulnerabilities` (plural) vs `/risk` (singular)
- `/findings` (plural) vs `/graph` (singular)
- `/integrations` (plural) vs `/scheduler` (singular)
3. **Deep routes**:
- `/policy-studio/packs/:packId/explain/:runId` - 5 segments
- `/admin/vex-hub/search/detail/:id` - 5 segments
- `/ops/orchestrator/dead-letter/queue` - 4 segments
### 3.4 Guard/Scope Observations
1. **Different guard patterns used**:
- `requireAuthGuard` - basic authentication
- `requireOrchViewerGuard` - orchestrator read access
- `requireOrchOperatorGuard` - orchestrator operator access
- `requirePolicyViewerGuard` - policy read
- `requirePolicyAuthorGuard` - policy authoring
- `requirePolicySimulatorGuard` - policy simulation
- `requirePolicyReviewerGuard` - policy review
- `requirePolicyApproverGuard` - policy approval
- `requirePolicyReviewOrApproveGuard` - either review or approve
2. **Scope-based access defined in navigation config**:
- `graph:read` for SBOM Graph
- `policy:author`, `policy:simulate`, `policy:review`, `policy:approve`, `policy:read`
- `ui.admin` for Admin section
3. **Some routes have no guards**: `/welcome`, `/notify`, `/scans/:scanId`, `/concelier/trivy-db-settings`
### 3.5 Dashboard Screen Observations
Multiple dashboard screens exist across the application:
1. **Home Dashboard** (`/`) - Security overview
2. **Orchestrator Dashboard** (`/orchestrator`) - Job management
3. **Policy Dashboard** (`/policy-studio/packs/:packId/dashboard`) - Per-pack metrics
4. **Quota Dashboard** (`/ops/quotas`) - License/quota metrics
5. **Platform Health Dashboard** (`/ops/health`) - Service health
6. **Feed Mirror Dashboard** (`/ops/feeds`) - Feed sync status
7. **Offline Dashboard** (`/ops/offline-kit/dashboard`) - Offline mode
8. **AOC Compliance Dashboard** (`/ops/aoc`) - Compliance metrics
9. **Release Dashboard** (`/release-orchestrator`) - Release pipeline
10. **VEX Hub Dashboard** (`/admin/vex-hub`) - VEX statements
11. **Doctor Dashboard** (`/ops/doctor`) - Diagnostics
12. **SLO Dashboard** (`/ops/orchestrator/slo`) - SLO health
13. **Dead-Letter Dashboard** (`/ops/orchestrator/dead-letter`) - Failed jobs
14. **Audit Dashboard** (`/admin/audit`) - Audit overview
15. **Trust Dashboard** (`/admin/trust/keys`) - Signing keys
16. **Sources Dashboard** (`/dashboard/sources`) - SBOM sources
### 3.6 Configuration/Settings Screen Observations
Multiple locations for configuration:
1. **Setup Wizard** (`/setup`) - Initial setup
2. **Configuration Pane** (`/console/configuration`) - Integration config
3. **Integration Hub** (`/integrations`) - Integration catalog
4. **Console Admin** (`/console/admin/*`) - User/tenant/role management
5. **Trust Admin** (`/admin/trust`) - Keys/certificates
6. **Registry Admin** (`/admin/registries`) - Registry tokens
7. **Notification Admin** (`/admin/notifications`) - Notification rules
8. **Policy Governance** (`/admin/policy/governance`) - Policy config
9. **Scanner Ops** (`/ops/scanner/settings`) - Scanner settings
10. **Quota Alert Config** (`/ops/quotas/alerts`) - Alert thresholds
11. **SLO Definitions** (`/ops/orchestrator/slo/definitions`) - SLO config
12. **Trivy DB Settings** (`/concelier/trivy-db-settings`) - Trivy config
### 3.7 Evidence/Proof Screen Observations
Multiple locations for evidence-related functionality:
1. **Evidence Center** (`/evidence`) - Bundles, export, replay, provenance
2. **Evidence Packs** (`/evidence-packs`) - Pack list/viewer
3. **Proof Chain** (`/proofs/:subjectDigest`) - Proof visualization
4. **Audit Bundles** (`/triage/audit-bundles`) - Audit evidence
5. **Release Evidence** (`/release-orchestrator/evidence`) - Release evidence
### 3.8 Shared Component Observations
Large number of shared components in `src/app/shared/components/`:
- 100+ shared components
- Mix of UI primitives (button, card, modal) and domain-specific (finding-detail, vex-status-chip)
- Some components are highly specific (e.g., `dsse-envelope-viewer`, `lattice-diagram`)
### 3.9 Feature Overlap Observations
1. **Findings vs Triage**: Both handle vulnerability findings with different workflows
2. **VEX Hub vs Triage VEX**: VEX decisions can be made in both places
3. **Evidence in multiple places**: Evidence features spread across 5 different feature modules
4. **Policy in multiple places**: Policy features spread across 5 different feature modules
5. **Audit logs in multiple places**: Console admin audit, unified audit log, trust audit, etc.
### 3.10 UI Pattern Observations
1. **Consistent patterns used**:
- Tab navigation within features
- Slide-out detail panels
- Data tables with filters and pagination
- Status badges with color coding (🟢🟡🔴)
- Skeleton loading states
2. **Dashboard card pattern**: Used on home dashboard and several other dashboards
3. **Wizard pattern**: Used in setup wizard, source wizard, key rotation wizard
4. **Split-pane pattern**: Used in policy editor, triage workspace