doctor enhancements, setup, enhancements, ui functionality and design consolidation and , test projects fixes , product advisory attestation/rekor and delta verfications enhancements
This commit is contained in:
master
@@ -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*
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
350
docs/modules/cli/guides/migration-v3.md
Normal 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
269
docs/modules/cli/guides/setup-guide.md
Normal 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
110
docs/modules/policy/gates/README.md
Normal 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
133
docs/modules/policy/gates/cve-delta.md
Normal 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
86
docs/modules/policy/gates/epss-threshold.md
Normal 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
100
docs/modules/policy/gates/kev-blocker.md
Normal 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
104
docs/modules/policy/gates/reachable-cve.md
Normal 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
137
docs/modules/policy/gates/release-aggregate-cve.md
Normal 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
326
docs/modules/ui/architecture-rework.md
Normal 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*
|
||||
@@ -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
352
docs/modules/ui/components/witness-visualization.md
Normal 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
209
docs/modules/ui/guides/setup-guide.md
Normal 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
119
docs/modules/unknowns/grey-queue-state-machine.md
Normal 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`
|
||||
Reference in New Issue
Block a user