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
442
docs-archived/product/advisories/CLI_COMMAND_MAPPING.md
Normal file
442
docs-archived/product/advisories/CLI_COMMAND_MAPPING.md
Normal file
@@ -0,0 +1,442 @@
|
||||
# CLI Command Mapping: Old to New
|
||||
|
||||
**Companion to:** CLI_CONSOLIDATION_PROPOSAL.md
|
||||
|
||||
This document provides the complete mapping from current commands to proposed new paths.
|
||||
|
||||
---
|
||||
|
||||
## Legend
|
||||
|
||||
- `->` : Maps to new location
|
||||
- `(alias)` : Old path kept as alias
|
||||
- `(deprecated)` : Will show deprecation warning
|
||||
- `(removed)` : Removed in v3.0
|
||||
|
||||
---
|
||||
|
||||
## Settings & Configuration
|
||||
|
||||
### Current → Proposed
|
||||
|
||||
```
|
||||
stella config list -> stella config list
|
||||
stella config show <path> -> stella config show <path>
|
||||
stella config <path> -> stella config show <path>
|
||||
|
||||
stella notify -> stella config notify (deprecated)
|
||||
stella notify channels list -> stella config notify channels list
|
||||
stella notify channels test -> stella config notify channels test
|
||||
stella notify templates list -> stella config notify templates list
|
||||
stella notify templates render -> stella config notify templates render
|
||||
stella notify preferences export -> stella config notify preferences export
|
||||
stella notify preferences import -> stella config notify preferences import
|
||||
|
||||
stella integrations list -> stella config integrations list
|
||||
stella integrations test -> stella config integrations test
|
||||
|
||||
stella admin feeds list -> stella config feeds list
|
||||
stella admin feeds status -> stella config feeds status
|
||||
stella admin feeds refresh -> stella config feeds refresh
|
||||
stella admin feeds history -> stella config feeds history
|
||||
|
||||
stella feeds list -> stella config feeds list (alias)
|
||||
stella feeds status -> stella config feeds status (alias)
|
||||
|
||||
stella registry list -> stella config registry list
|
||||
stella registry configure -> stella config registry configure
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Authentication & Access Control
|
||||
|
||||
```
|
||||
stella auth -> stella auth (unchanged)
|
||||
stella auth clients list -> stella auth clients list
|
||||
stella auth clients create -> stella auth clients create
|
||||
stella auth clients delete -> stella auth clients delete
|
||||
stella auth roles list -> stella auth roles list
|
||||
stella auth roles assign -> stella auth roles assign
|
||||
stella auth scopes list -> stella auth scopes list
|
||||
stella auth token inspect -> stella auth token inspect
|
||||
stella auth api-keys list -> stella auth api-keys list
|
||||
stella auth api-keys create -> stella auth api-keys create
|
||||
stella auth api-keys revoke -> stella auth api-keys revoke
|
||||
|
||||
stella admin users list -> stella auth users list (moved)
|
||||
stella admin users add -> stella auth users add (moved)
|
||||
stella admin users revoke -> stella auth users revoke (moved)
|
||||
stella admin users update -> stella auth users update (moved)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Scanning Operations
|
||||
|
||||
```
|
||||
stella scan -> stella scan run (default action)
|
||||
stella scanner download -> stella scan download
|
||||
stella scanner workers -> stella scan workers
|
||||
|
||||
stella scangraph -> stella scan graph (deprecated alias)
|
||||
stella scan graph list -> stella scan graph list
|
||||
stella scan graph show -> stella scan graph show
|
||||
|
||||
stella secrets -> stella scan secrets (deprecated alias)
|
||||
stella secrets bundle create -> stella scan secrets bundle create
|
||||
stella secrets bundle verify -> stella scan secrets bundle verify
|
||||
stella secrets bundle info -> stella scan secrets bundle info
|
||||
|
||||
stella image -> stella scan image (deprecated alias)
|
||||
stella image inspect -> stella scan image inspect
|
||||
stella image layers -> stella scan image layers
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Release Management
|
||||
|
||||
```
|
||||
stella release -> stella release (unchanged)
|
||||
stella release list -> stella release list
|
||||
stella release show -> stella release show
|
||||
stella release create -> stella release create
|
||||
|
||||
stella gate -> stella release gate (deprecated alias)
|
||||
stella gate evaluate -> stella release gate evaluate
|
||||
stella gate status -> stella release gate status
|
||||
|
||||
stella promotion -> stella release promote (deprecated alias)
|
||||
|
||||
stella exception -> stella release exception
|
||||
stella exception list -> stella release exception list
|
||||
stella exception approve -> stella release exception approve
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verification (Consolidated)
|
||||
|
||||
```
|
||||
stella verify -> stella verify (unchanged)
|
||||
stella verify offline -> stella verify offline
|
||||
stella verify image -> stella verify image
|
||||
stella verify bundle -> stella verify bundle
|
||||
|
||||
stella attest verify -> stella verify attestation (deprecated alias)
|
||||
stella vex verify -> stella verify vex (deprecated alias)
|
||||
stella patchverify -> stella verify patch (deprecated alias)
|
||||
|
||||
# New unified verify help
|
||||
stella verify --help
|
||||
attestation Verify attestation
|
||||
bundle Verify evidence bundle
|
||||
image Verify image attestation
|
||||
offline Offline verification
|
||||
patch Patch verification
|
||||
vex Verify VEX statement
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Attestation Operations
|
||||
|
||||
```
|
||||
stella attest -> stella attest (unchanged)
|
||||
stella attest build -> stella attest build
|
||||
stella attest attach -> stella attest attach
|
||||
stella attest list -> stella attest list
|
||||
stella attest fetch -> stella attest fetch
|
||||
|
||||
stella patchattest -> stella attest patch (deprecated alias)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Evidence Management
|
||||
|
||||
```
|
||||
stella evidence -> stella evidence (unchanged)
|
||||
stella evidence list -> stella evidence list
|
||||
stella evidence show -> stella evidence show
|
||||
stella evidence export -> stella evidence export
|
||||
|
||||
stella evidenceholds -> stella evidence holds (deprecated alias)
|
||||
stella evidenceholds list -> stella evidence holds list
|
||||
stella evidenceholds create -> stella evidence holds create
|
||||
stella evidenceholds release -> stella evidence holds release
|
||||
|
||||
stella audit -> stella evidence audit (deprecated alias)
|
||||
stella audit list -> stella evidence audit list
|
||||
stella audit export -> stella evidence audit export
|
||||
|
||||
stella replay -> stella evidence replay (deprecated alias)
|
||||
stella scorereplay -> stella evidence replay score (deprecated alias)
|
||||
|
||||
stella prove -> stella evidence proof generate (deprecated alias)
|
||||
stella proof -> stella evidence proof (deprecated alias)
|
||||
stella proof anchor -> stella evidence proof anchor
|
||||
stella proof receipt -> stella evidence proof receipt
|
||||
|
||||
stella provenance -> stella evidence provenance (deprecated alias)
|
||||
stella prov -> stella evidence provenance (deprecated alias)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Policy Management
|
||||
|
||||
```
|
||||
stella policy -> stella policy (unchanged)
|
||||
stella policy validate -> stella policy validate
|
||||
stella policy install -> stella policy install
|
||||
stella policy list-packs -> stella policy list-packs
|
||||
stella policy simulate -> stella policy simulate
|
||||
|
||||
stella admin policy export -> stella policy export (moved)
|
||||
stella admin policy import -> stella policy import (moved)
|
||||
stella admin policy validate -> stella policy validate (alias)
|
||||
stella admin policy list -> stella policy list (moved)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## VEX Operations
|
||||
|
||||
```
|
||||
stella vex -> stella vex (unchanged)
|
||||
stella vex list -> stella vex list
|
||||
stella vex check -> stella vex check
|
||||
stella vex auto-downgrade -> stella vex auto-downgrade
|
||||
stella vex not-reachable -> stella vex not-reachable
|
||||
stella vex observation -> stella vex observation
|
||||
stella vex rekor -> stella vex rekor
|
||||
|
||||
stella vexgatescan -> stella vex gate-scan (deprecated alias)
|
||||
stella verdict -> stella vex verdict (deprecated alias)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Reachability Analysis
|
||||
|
||||
```
|
||||
stella reachability -> stella reachability (unchanged)
|
||||
stella reachability analyze -> stella reachability analyze
|
||||
|
||||
stella reachgraph -> stella reachability graph (deprecated alias)
|
||||
stella reachgraph list -> stella reachability graph list
|
||||
stella reachgraph show -> stella reachability graph show
|
||||
|
||||
stella slice -> stella reachability slice (deprecated alias)
|
||||
stella slice create -> stella reachability slice create
|
||||
stella slice show -> stella reachability slice show
|
||||
|
||||
stella witness -> stella reachability witness (deprecated alias)
|
||||
stella witness list -> stella reachability witness list
|
||||
stella witness show -> stella reachability witness show
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## SBOM Operations
|
||||
|
||||
```
|
||||
stella sbom -> stella sbom (unchanged)
|
||||
stella sbom generate -> stella sbom generate
|
||||
stella sbom show -> stella sbom show
|
||||
stella sbom verify -> stella sbom verify
|
||||
|
||||
stella sbomer -> stella sbom compose (deprecated alias)
|
||||
|
||||
stella layersbom -> stella sbom layer (deprecated alias)
|
||||
stella layersbom show -> stella sbom layer show
|
||||
stella layersbom generate -> stella sbom layer generate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cryptography & Keys
|
||||
|
||||
```
|
||||
stella crypto -> stella crypto (unchanged)
|
||||
|
||||
stella keys -> stella crypto keys (deprecated alias)
|
||||
stella keys list -> stella crypto keys list
|
||||
stella keys create -> stella crypto keys create
|
||||
stella keys rotate -> stella crypto keys rotate
|
||||
|
||||
stella issuerkeys -> stella crypto keys issuer (deprecated alias)
|
||||
stella issuerkeys list -> stella crypto keys issuer list
|
||||
|
||||
stella sign -> stella crypto sign (deprecated alias)
|
||||
stella sign image -> stella crypto sign image
|
||||
|
||||
stella kms -> stella crypto kms (deprecated alias)
|
||||
stella kms status -> stella crypto kms status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Administration
|
||||
|
||||
```
|
||||
stella admin -> stella admin (unchanged, but slimmed)
|
||||
|
||||
stella admin system status -> stella admin system status
|
||||
stella admin system info -> stella admin system info
|
||||
|
||||
stella system migrations-run -> stella admin system migrations run
|
||||
stella system migrations-status -> stella admin system migrations status
|
||||
stella system migrations-verify -> stella admin system migrations verify
|
||||
|
||||
stella doctor -> stella admin doctor (deprecated alias)
|
||||
stella doctor run -> stella admin doctor run
|
||||
stella doctor report -> stella admin doctor report
|
||||
|
||||
stella db -> stella admin db (deprecated alias)
|
||||
stella db migrate -> stella admin db migrate
|
||||
stella db status -> stella admin db status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
```
|
||||
stella ci -> stella ci (unchanged)
|
||||
stella ci template -> stella ci template
|
||||
|
||||
stella gate -> stella ci gate (shortcut, deprecated for main path)
|
||||
stella gate evaluate -> stella ci gate evaluate
|
||||
|
||||
stella github -> stella ci github (deprecated alias)
|
||||
stella github upload -> stella ci github upload
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tools & Utilities
|
||||
|
||||
```
|
||||
stella tools -> stella tools (unchanged)
|
||||
|
||||
stella binary -> stella tools binary (deprecated alias)
|
||||
stella binary diff -> stella tools binary diff
|
||||
stella binary indexops -> stella tools binary indexops
|
||||
stella binary deltasig -> stella tools binary deltasig
|
||||
|
||||
stella delta -> stella tools delta (deprecated alias)
|
||||
stella deltasig -> stella tools deltasig (deprecated alias)
|
||||
|
||||
stella hlc -> stella tools hlc (deprecated alias)
|
||||
stella hlc show -> stella tools hlc show
|
||||
|
||||
stella timeline -> stella tools timeline (deprecated alias)
|
||||
stella timeline query -> stella tools timeline query
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Specialized/Advanced Commands
|
||||
|
||||
```
|
||||
stella airgap -> stella airgap (unchanged, specialized)
|
||||
stella federation -> stella federation (unchanged)
|
||||
stella mirror -> stella mirror (unchanged)
|
||||
stella fixchain -> stella fixchain (unchanged)
|
||||
stella chainlinking -> stella chainlinking (unchanged)
|
||||
stella goldenset -> stella goldenset (unchanged)
|
||||
|
||||
stella drift -> stella tools drift (deprecated alias)
|
||||
stella seal -> stella evidence seal (deprecated alias)
|
||||
stella changetrace -> stella tools changetrace (deprecated alias)
|
||||
stella unknowns -> stella vex unknowns (deprecated alias)
|
||||
stella risk -> stella policy risk (deprecated alias)
|
||||
stella riskbudget -> stella policy risk budget (deprecated alias)
|
||||
stella guard -> stella release guard (deprecated alias)
|
||||
|
||||
stella model -> stella tools model (deprecated alias)
|
||||
stella signals -> stella config signals (deprecated alias)
|
||||
stella sources -> stella config sources (deprecated alias)
|
||||
stella incidents -> stella admin incidents (deprecated alias)
|
||||
stella taskrunner -> stella admin taskrunner (deprecated alias)
|
||||
stella observability -> stella admin observability (deprecated alias)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Setup & Onboarding
|
||||
|
||||
```
|
||||
stella setup -> stella setup (unchanged)
|
||||
stella setup run -> stella setup run
|
||||
stella setup resume -> stella setup resume
|
||||
stella setup status -> stella setup status
|
||||
stella setup reset -> stella setup reset
|
||||
stella setup validate -> stella setup validate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Commands to Remove (v3.0)
|
||||
|
||||
These compound-word commands will be removed after deprecation period:
|
||||
|
||||
```
|
||||
scangraph -> scan graph
|
||||
reachgraph -> reachability graph
|
||||
layersbom -> sbom layer
|
||||
vexgatescan -> vex gate-scan
|
||||
scorereplay -> evidence replay score
|
||||
evidenceholds -> evidence holds
|
||||
patchattest -> attest patch
|
||||
patchverify -> verify patch
|
||||
issuerkeys -> crypto keys issuer
|
||||
deltasig -> tools deltasig
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Card
|
||||
|
||||
### Before (Confusing)
|
||||
```bash
|
||||
stella notify # Channel management, not settings
|
||||
stella secrets # Secret detection rules, not secrets
|
||||
stella gate # Release gating
|
||||
stella scangraph # Scan graph
|
||||
stella prove # Generate proof
|
||||
stella prov # Provenance tracking
|
||||
```
|
||||
|
||||
### After (Clear)
|
||||
```bash
|
||||
stella config notify # Notification configuration
|
||||
stella scan secrets # Secret detection scanning
|
||||
stella release gate # Release gating (or stella ci gate)
|
||||
stella scan graph # Scan graph operations
|
||||
stella evidence proof generate # Generate proof
|
||||
stella evidence provenance # Provenance tracking
|
||||
```
|
||||
|
||||
### Common Tasks
|
||||
```bash
|
||||
# See all settings paths
|
||||
stella config list
|
||||
|
||||
# Configure notifications
|
||||
stella config notify channels list
|
||||
stella config notify preferences export
|
||||
|
||||
# Run a scan
|
||||
stella scan run --image sha256:abc123
|
||||
|
||||
# Verify an image
|
||||
stella verify image sha256:abc123
|
||||
|
||||
# Check release gate
|
||||
stella release gate evaluate --release rel-123
|
||||
stella ci gate # shortcut for CI pipelines
|
||||
```
|
||||
445
docs-archived/product/advisories/CLI_CONSOLIDATION_PROPOSAL.md
Normal file
445
docs-archived/product/advisories/CLI_CONSOLIDATION_PROPOSAL.md
Normal file
@@ -0,0 +1,445 @@
|
||||
# CLI Consolidation Proposal
|
||||
|
||||
**Date:** 2026-01-18
|
||||
**Status:** Draft Advisory
|
||||
**Author:** Engineering
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
The Stella CLI has grown to **81+ top-level command groups**, creating usability issues:
|
||||
- Commands are hard to discover and remember
|
||||
- Similar functionality exists under different names
|
||||
- Settings/configuration is scattered across multiple commands
|
||||
- Naming conventions are inconsistent (verb-first vs noun-first)
|
||||
|
||||
This proposal recommends consolidating the CLI into a cleaner, more intuitive hierarchy.
|
||||
|
||||
---
|
||||
|
||||
## Current Problems
|
||||
|
||||
### 1. Command Explosion (81+ root commands)
|
||||
|
||||
Users must memorize dozens of top-level commands:
|
||||
```
|
||||
stella verify, attest, policy, gate, evidence, audit, scan, scanner,
|
||||
scangraph, image, reachability, reachgraph, slice, witness, crypto,
|
||||
keys, issuerkeys, sign, secrets, proof, prove, provenance, delta,
|
||||
deltasig, vex, vexgatescan, verdict, feeds, sources, signals, sbom,
|
||||
sbomer, layersbom, doctor, admin, notify, incidents, config, setup,
|
||||
auth, db, registry, tools, system, binary, ci, github, seal, drift...
|
||||
```
|
||||
|
||||
### 2. Duplicate/Overlapping Commands
|
||||
|
||||
| Command A | Command B | Overlap |
|
||||
|-----------|-----------|---------|
|
||||
| `admin policy` | `policy` | Both manage policies |
|
||||
| `admin feeds` | `feeds` | Both manage feeds |
|
||||
| `admin users` | `auth roles` | Both manage user access |
|
||||
| `admin system` | `system` | Both have system commands |
|
||||
| `config` | `setup`, `admin` | Configuration scattered |
|
||||
|
||||
### 3. Confusing Names
|
||||
|
||||
| Command | What user might expect | What it actually does |
|
||||
|---------|------------------------|----------------------|
|
||||
| `notify` | Change notification settings | Manage notification channels/templates |
|
||||
| `secrets` | Manage secrets (like Vault) | Secret detection rule bundles |
|
||||
| `prove` | Prove something? | Generate replay proofs |
|
||||
| `proof` | Same as prove? | Different - proof operations |
|
||||
| `prov` | Provenance? | Something else |
|
||||
|
||||
### 4. Inconsistent Naming Patterns
|
||||
|
||||
- **Verb-first:** `verify`, `scan`, `prove`, `explain`, `seal`
|
||||
- **Noun-first:** `evidence`, `policy`, `feeds`, `secrets`
|
||||
- **Hybrid:** `vexgatescan`, `scangraph`, `layersbom`
|
||||
|
||||
### 5. No Unified Settings Management
|
||||
|
||||
Settings are scattered:
|
||||
```
|
||||
stella config show <path> # View configuration
|
||||
stella notify preferences export # Notification preferences
|
||||
stella setup run # Initial setup
|
||||
stella admin system status # System status
|
||||
stella auth ... # Auth settings
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Proposed Structure
|
||||
|
||||
### Design Principles
|
||||
|
||||
1. **Resource-oriented hierarchy** (like `kubectl`, `gh`, `docker`)
|
||||
2. **Consistent verb patterns**: `list`, `show`, `create`, `delete`, `verify`, `test`
|
||||
3. **Grouped by domain**: scanning, release, security, admin
|
||||
4. **Unified settings under `stella config`**
|
||||
5. **Max 15-20 top-level commands** for discoverability
|
||||
|
||||
### New Command Hierarchy
|
||||
|
||||
```
|
||||
stella
|
||||
├── scan # All scanning operations
|
||||
│ ├── run # Run a scan
|
||||
│ ├── status # Check scan status
|
||||
│ ├── results # View scan results
|
||||
│ ├── graph # Scan graph operations (was: scangraph)
|
||||
│ └── secrets # Secret detection (was: secrets bundle)
|
||||
│
|
||||
├── release # Release management
|
||||
│ ├── list # List releases
|
||||
│ ├── show # Show release details
|
||||
│ ├── create # Create release
|
||||
│ ├── approve # Approve release
|
||||
│ ├── gate # Gate evaluation (was: gate)
|
||||
│ └── promote # Promote to environment
|
||||
│
|
||||
├── verify # All verification commands (consolidated)
|
||||
│ ├── image # Verify image attestation
|
||||
│ ├── bundle # Verify evidence bundle
|
||||
│ ├── attestation # Verify attestation (was: attest verify)
|
||||
│ ├── vex # Verify VEX (was: vex verify)
|
||||
│ ├── offline # Offline verification
|
||||
│ └── patch # Patch verification (was: patchverify)
|
||||
│
|
||||
├── attest # Create attestations
|
||||
│ ├── build # Build attestation
|
||||
│ ├── attach # Attach to artifact
|
||||
│ ├── list # List attestations
|
||||
│ └── patch # Patch attestation (was: patchattest)
|
||||
│
|
||||
├── evidence # Evidence management
|
||||
│ ├── list # List evidence
|
||||
│ ├── show # Show evidence details
|
||||
│ ├── export # Export evidence
|
||||
│ ├── holds # Evidence retention (was: evidenceholds)
|
||||
│ ├── replay # Replay operations (was: replay, scorereplay)
|
||||
│ └── proof # Proof generation (was: prove, proof)
|
||||
│
|
||||
├── policy # Policy management (consolidated)
|
||||
│ ├── list # List policies
|
||||
│ ├── show # Show policy
|
||||
│ ├── validate # Validate policy
|
||||
│ ├── install # Install policy pack
|
||||
│ ├── export # Export policy (was: admin policy export)
|
||||
│ ├── import # Import policy (was: admin policy import)
|
||||
│ └── simulate # Simulate policy
|
||||
│
|
||||
├── vex # VEX operations (consolidated)
|
||||
│ ├── list # List VEX observations
|
||||
│ ├── create # Create VEX statement
|
||||
│ ├── check # Check vulnerabilities
|
||||
│ ├── auto-downgrade # Auto-downgrade
|
||||
│ └── not-reachable # Mark unreachable
|
||||
│
|
||||
├── reachability # Reachability analysis (consolidated)
|
||||
│ ├── analyze # Run reachability analysis
|
||||
│ ├── graph # Graph operations (was: reachgraph)
|
||||
│ ├── slice # Slice operations (was: slice)
|
||||
│ └── witness # Witness paths (was: witness)
|
||||
│
|
||||
├── sbom # SBOM operations (consolidated)
|
||||
│ ├── generate # Generate SBOM
|
||||
│ ├── verify # Verify SBOM
|
||||
│ ├── show # Show SBOM
|
||||
│ └── layer # Layer SBOM (was: layersbom)
|
||||
│
|
||||
├── crypto # Cryptography (consolidated)
|
||||
│ ├── keys # Key management (was: keys)
|
||||
│ │ ├── list
|
||||
│ │ ├── create
|
||||
│ │ ├── rotate
|
||||
│ │ └── issuer # Issuer keys (was: issuerkeys)
|
||||
│ ├── sign # Signing operations (was: sign)
|
||||
│ └── kms # KMS operations (was: kms)
|
||||
│
|
||||
├── config # UNIFIED SETTINGS (NEW)
|
||||
│ ├── show # Show config value
|
||||
│ ├── set # Set config value
|
||||
│ ├── list # List all config paths
|
||||
│ ├── export # Export configuration
|
||||
│ ├── import # Import configuration
|
||||
│ │
|
||||
│ ├── notify # Notification settings (was: notify)
|
||||
│ │ ├── channels list
|
||||
│ │ ├── channels test
|
||||
│ │ ├── templates list
|
||||
│ │ └── preferences export/import
|
||||
│ │
|
||||
│ ├── integrations # Integration settings
|
||||
│ │ ├── list
|
||||
│ │ ├── test
|
||||
│ │ └── configure
|
||||
│ │
|
||||
│ ├── feeds # Feed configuration (was: admin feeds, feeds)
|
||||
│ │ ├── list
|
||||
│ │ ├── status
|
||||
│ │ └── refresh
|
||||
│ │
|
||||
│ └── registry # Registry settings (was: registry)
|
||||
│ ├── list
|
||||
│ └── configure
|
||||
│
|
||||
├── auth # Authentication (unchanged structure)
|
||||
│ ├── clients # OAuth clients
|
||||
│ ├── roles # Role management
|
||||
│ ├── scopes # Scope information
|
||||
│ ├── token # Token inspection
|
||||
│ ├── api-keys # API key management
|
||||
│ └── users # User management (was: admin users)
|
||||
│
|
||||
├── admin # Administrative operations (slimmed down)
|
||||
│ ├── system # System management
|
||||
│ │ ├── status
|
||||
│ │ ├── info
|
||||
│ │ └── migrations
|
||||
│ ├── audit # Audit operations (was: audit)
|
||||
│ └── doctor # Diagnostics (was: doctor)
|
||||
│
|
||||
├── ci # CI/CD integration (consolidated)
|
||||
│ ├── gate # CI gate command (shortcut to release gate)
|
||||
│ ├── template # Generate CI templates
|
||||
│ └── github # GitHub-specific (was: github)
|
||||
│
|
||||
├── setup # Initial setup wizard (unchanged)
|
||||
│ ├── run
|
||||
│ ├── resume
|
||||
│ ├── status
|
||||
│ └── validate
|
||||
│
|
||||
├── explain # Explain decisions (unchanged)
|
||||
│
|
||||
└── tools # Utility tools (unchanged)
|
||||
├── binary # Binary analysis (was: binary)
|
||||
├── delta # Delta/diff (was: delta, deltasig)
|
||||
├── hlc # Hybrid logical clock (was: hlc)
|
||||
└── timeline # Timeline operations (was: timeline)
|
||||
```
|
||||
|
||||
### Command Count Comparison
|
||||
|
||||
| Category | Before | After |
|
||||
|----------|--------|-------|
|
||||
| Top-level commands | 81+ | 18 |
|
||||
| Max depth | 4 | 4 |
|
||||
| Discoverability | Poor | Good |
|
||||
|
||||
---
|
||||
|
||||
## Migration Path
|
||||
|
||||
### Phase 1: Add Aliases (Non-Breaking)
|
||||
|
||||
Create new command structure as aliases to existing commands:
|
||||
|
||||
```csharp
|
||||
// Old command still works
|
||||
stella gate evaluate ...
|
||||
|
||||
// New command added as alias
|
||||
stella release gate evaluate ...
|
||||
// or
|
||||
stella ci gate ...
|
||||
```
|
||||
|
||||
**Files to modify:**
|
||||
- `CommandFactory.cs` - Add routing for new paths
|
||||
- Add deprecation warnings to old paths
|
||||
|
||||
### Phase 2: Consolidate Settings
|
||||
|
||||
Move scattered settings into `stella config`:
|
||||
|
||||
| Old Command | New Command |
|
||||
|-------------|-------------|
|
||||
| `stella notify channels list` | `stella config notify channels list` |
|
||||
| `stella notify preferences export` | `stella config notify preferences export` |
|
||||
| `stella admin feeds list` | `stella config feeds list` |
|
||||
| `stella registry list` | `stella config registry list` |
|
||||
|
||||
### Phase 3: Deprecate Old Paths
|
||||
|
||||
Add warnings when using old command paths:
|
||||
```
|
||||
WARNING: 'stella gate evaluate' is deprecated.
|
||||
Use 'stella release gate evaluate' or 'stella ci gate' instead.
|
||||
This command will be removed in v3.0.
|
||||
```
|
||||
|
||||
### Phase 4: Remove Old Paths (Major Version)
|
||||
|
||||
In a major version release (v3.0), remove deprecated command paths.
|
||||
|
||||
---
|
||||
|
||||
## Specific Recommendations
|
||||
|
||||
### 1. Unified Settings Pattern
|
||||
|
||||
**Current mess:**
|
||||
```bash
|
||||
stella notify preferences export --user alice # Notification prefs
|
||||
stella config show policy.determinization # Policy config
|
||||
stella admin feeds status # Feed settings
|
||||
```
|
||||
|
||||
**Proposed pattern:**
|
||||
```bash
|
||||
stella config show <path> # View any config
|
||||
stella config set <path> <value> # Set any config
|
||||
stella config list --category notify # List notification paths
|
||||
stella config notify preferences export # Notification-specific
|
||||
stella config feeds status # Feed-specific
|
||||
```
|
||||
|
||||
### 2. Consolidate Verify Commands
|
||||
|
||||
**Current:**
|
||||
```bash
|
||||
stella verify offline ...
|
||||
stella verify image ...
|
||||
stella attest verify ...
|
||||
stella vex verify ...
|
||||
stella patchverify ...
|
||||
```
|
||||
|
||||
**Proposed:**
|
||||
```bash
|
||||
stella verify offline ...
|
||||
stella verify image ...
|
||||
stella verify attestation ... # was: attest verify
|
||||
stella verify vex ... # was: vex verify
|
||||
stella verify patch ... # was: patchverify
|
||||
```
|
||||
|
||||
### 3. Rename Confusing Commands
|
||||
|
||||
| Old Name | New Name | Reason |
|
||||
|----------|----------|--------|
|
||||
| `secrets` | `scan secrets` | It's about secret detection, not secret management |
|
||||
| `prove` | `evidence proof generate` | Clarify it generates proofs |
|
||||
| `prov` | `evidence provenance` | Consistent naming |
|
||||
| `scangraph` | `scan graph` | Split compound word |
|
||||
| `reachgraph` | `reachability graph` | Split compound word |
|
||||
| `layersbom` | `sbom layer` | Consistent with other sbom commands |
|
||||
|
||||
### 4. Common Verb Patterns
|
||||
|
||||
All resource-oriented commands should support:
|
||||
- `list` - List resources
|
||||
- `show <id>` - Show details
|
||||
- `create` - Create new
|
||||
- `delete` - Delete
|
||||
- `verify` - Verify integrity
|
||||
- `export` - Export data
|
||||
|
||||
---
|
||||
|
||||
## Examples of Improved UX
|
||||
|
||||
### Before (Confusing)
|
||||
```bash
|
||||
# User wants to check notification settings
|
||||
stella notify # Manages channels, not settings
|
||||
stella config show ... # Doesn't know the path
|
||||
stella admin ... # Maybe here?
|
||||
|
||||
# User wants to verify something
|
||||
stella verify ... # Some verify commands
|
||||
stella attest verify ... # Also verify
|
||||
stella vex verify ... # Also verify
|
||||
```
|
||||
|
||||
### After (Intuitive)
|
||||
```bash
|
||||
# All settings under config
|
||||
stella config list # See all paths
|
||||
stella config notify channels list # Notification channels
|
||||
stella config notify preferences export # My preferences
|
||||
|
||||
# All verification under verify
|
||||
stella verify --help # See all verify options
|
||||
stella verify image sha256:abc123
|
||||
stella verify attestation sha256:abc123
|
||||
stella verify vex CVE-2025-1234
|
||||
```
|
||||
|
||||
### Discoverability
|
||||
```bash
|
||||
# User types "stella" and sees clear categories
|
||||
$ stella --help
|
||||
|
||||
COMMANDS:
|
||||
scan Scan images and artifacts for vulnerabilities
|
||||
release Manage releases and promotions
|
||||
verify Verify attestations, images, and evidence
|
||||
evidence Manage evidence bundles and proofs
|
||||
policy Manage security policies
|
||||
config Configure Stella settings and integrations
|
||||
auth Authentication and access control
|
||||
admin Administrative operations
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Tasks
|
||||
|
||||
### Sprint 1: Foundation
|
||||
- [ ] Create command routing infrastructure for aliases
|
||||
- [ ] Implement deprecation warning system
|
||||
- [ ] Add `stella config` unified settings command
|
||||
|
||||
### Sprint 2: Settings Consolidation
|
||||
- [ ] Move `notify` under `config notify`
|
||||
- [ ] Move `feeds` under `config feeds`
|
||||
- [ ] Move `registry` under `config registry`
|
||||
- [ ] Add backward-compatible aliases
|
||||
|
||||
### Sprint 3: Verification Consolidation
|
||||
- [ ] Create `stella verify` umbrella command
|
||||
- [ ] Route `attest verify` -> `verify attestation`
|
||||
- [ ] Route `vex verify` -> `verify vex`
|
||||
- [ ] Route `patchverify` -> `verify patch`
|
||||
|
||||
### Sprint 4: Scanning Consolidation
|
||||
- [ ] Create `stella scan` umbrella command
|
||||
- [ ] Route `secrets bundle` -> `scan secrets bundle`
|
||||
- [ ] Route `scangraph` -> `scan graph`
|
||||
|
||||
### Sprint 5: Documentation & Polish
|
||||
- [ ] Update all CLI documentation
|
||||
- [ ] Add migration guide
|
||||
- [ ] Update CI templates with new commands
|
||||
|
||||
---
|
||||
|
||||
## Risks & Mitigations
|
||||
|
||||
| Risk | Impact | Mitigation |
|
||||
|------|--------|------------|
|
||||
| Breaking existing CI pipelines | High | Keep old commands as aliases for 2 major versions |
|
||||
| User confusion during transition | Medium | Clear deprecation warnings with suggested alternatives |
|
||||
| Documentation drift | Medium | Generate docs from command metadata |
|
||||
| Plugin compatibility | Medium | Plugin interface remains stable; only routing changes |
|
||||
|
||||
---
|
||||
|
||||
## Decision Required
|
||||
|
||||
1. **Approve general direction?** (Resource-oriented consolidation)
|
||||
2. **Phase 1 start date?** (Add aliases)
|
||||
3. **Deprecation timeline?** (How many versions before removal?)
|
||||
4. **Naming conventions?** (Approve proposed verb patterns)
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Full Command Mapping
|
||||
|
||||
See [CLI_COMMAND_MAPPING.md](./CLI_COMMAND_MAPPING.md) for complete old->new mapping.
|
||||
Reference in New Issue
Block a user