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
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
|
||||
Reference in New Issue
Block a user