11 KiB
11 KiB
CLI Developer Experience and Command UX
Version: 1.0 Date: 2025-11-29 Status: Canonical
This advisory defines the product rationale, command surface design, and implementation strategy for the Stella Ops CLI, covering developer experience, CI/CD integration, output formatting, and offline operation.
1. Executive Summary
The Stella Ops CLI is the primary interface for developers and CI/CD pipelines interacting with the platform. Key capabilities:
- Native AOT Binary - Sub-20ms startup, single binary distribution
- DPoP-Bound Authentication - Secure device-code and service principal flows
- Deterministic Outputs - JSON/table modes with stable exit codes for CI
- Buildx Integration - SBOM generation at build time
- Offline Kit Management - Air-gapped deployment support
- Shell Completions - Bash/Zsh/Fish/PowerShell auto-complete
2. Market Drivers
2.1 Target Segments
| Segment | CLI Requirements | Use Case |
|---|---|---|
| DevSecOps | CI integration, exit codes, JSON output | Pipeline gates |
| Security Engineers | Verification commands, policy testing | Audit workflows |
| Platform Operators | Offline kit, admin commands | Air-gap management |
| Developers | Scan commands, buildx integration | Local development |
2.2 Competitive Positioning
Most CLI tools in the vulnerability space are slow or lack CI ergonomics. Stella Ops differentiates with:
- Native AOT for instant startup (< 20ms vs 500ms+ for JIT)
- Deterministic exit codes (12 distinct codes for CI decision trees)
- DPoP security (no long-lived tokens on disk)
- Unified command surface (50+ commands, consistent patterns)
- Offline-first design (works without network in sealed mode)
3. Command Surface Architecture
3.1 Command Categories
| Category | Commands | Purpose |
|---|---|---|
| Auth | login, logout, status, token |
Authentication management |
| Scan | scan image, scan fs |
Vulnerability scanning |
| Export | export sbom, report final |
Artifact retrieval |
| Verify | verify attestation, verify referrers, verify image-signature |
Cryptographic verification |
| Policy | policy get, policy set, policy apply |
Policy management |
| Buildx | buildx install, buildx verify, buildx build |
Build-time SBOM |
| Runtime | runtime policy test |
Zastava integration |
| Offline | offline kit pull, offline kit import, offline kit status |
Air-gap operations |
| Decision | decision export, decision verify, decision compare |
VEX evidence management |
| AOC | sources ingest, aoc verify |
Aggregation-only guards |
| KMS | kms export, kms import |
Key management |
| Advise | advise run |
AI-powered advisory summaries |
3.2 Output Modes
Human Mode (default):
$ stella scan image nginx:latest --wait
Scanning nginx:latest...
Found 12 vulnerabilities (2 critical, 3 high, 5 medium, 2 low)
Policy verdict: FAIL
Critical:
- CVE-2025-12345 in openssl (fixed in 3.0.14)
- CVE-2025-12346 in libcurl (no fix available)
See: https://ui.internal/scans/sha256:abc123...
JSON Mode (--json):
{"event":"scan.complete","status":"fail","critical":2,"high":3,"medium":5,"low":2,"url":"https://..."}
3.3 Exit Codes
| Code | Meaning | CI Action |
|---|---|---|
| 0 | Success | Continue |
| 2 | Policy fail | Block deployment |
| 3 | Verification failed | Security alert |
| 4 | Auth error | Re-authenticate |
| 5 | Resource not found | Check inputs |
| 6 | Rate limited | Retry with backoff |
| 7 | Backend unavailable | Retry |
| 9 | Invalid arguments | Fix command |
| 11-17 | AOC guard violations | Review ingestion |
| 18 | Verification truncated | Increase limit |
| 70 | Transport failure | Check network |
| 71 | Usage error | Fix command |
4. Authentication Model
4.1 Device Code Flow (Interactive)
$ stella auth login
Opening browser for authentication...
Device code: ABCD-EFGH
Waiting for authorization...
Logged in as user@example.com (tenant: acme-corp)
4.2 Service Principal (CI/CD)
$ stella auth login --client-credentials \
--client-id $STELLA_CLIENT_ID \
--private-key $STELLA_PRIVATE_KEY
4.3 DPoP Key Management
- Ephemeral Ed25519 keypair generated on first login
- Stored in OS keychain (Keychain/DPAPI/KWallet/Gnome Keyring)
- Every request includes DPoP proof header
- Tokens refreshed proactively (30s before expiry)
4.4 Token Credential Helper
# Get one-shot token for curl/scripts
TOKEN=$(stella auth token --aud scanner)
curl -H "Authorization: Bearer $TOKEN" https://scanner.internal/api/...
5. Buildx Integration
5.1 Generator Installation
$ stella buildx install
Installing SBOM generator plugin...
Verifying signature: OK
Generator installed at ~/.docker/cli-plugins/docker-buildx-stellaops
$ stella buildx verify
Docker version: 24.0.7
Buildx version: 0.12.1
Generator: stellaops/sbom-indexer:v1.2.3@sha256:abc123...
Status: Ready
5.2 Build with SBOM
$ stella buildx build -t myapp:v1.0.0 --push --attest
Building myapp:v1.0.0...
SBOM generation: enabled (stellaops/sbom-indexer)
Provenance: enabled
Attestation: requested
Build complete!
Image: myapp:v1.0.0@sha256:def456...
SBOM: attached as referrer
Attestation: logged to Rekor (uuid: abc123)
6. Implementation Strategy
6.1 Phase 1: Core Commands (Complete)
- Auth commands with DPoP
- Scan/export commands
- JSON output mode
- Exit code standardization
- Shell completions
6.2 Phase 2: Buildx & Verification (Complete)
- Buildx plugin management
- Attestation verification
- Referrer verification
- Report commands
6.3 Phase 3: Advanced Features (In Progress)
- Decision export/verify commands
- AOC guard helpers
- KMS management
- Advisory AI integration (CLI-ADVISE-48-001)
- Filesystem scanning (CLI-SCAN-49-001)
6.4 Phase 4: Distribution (Planned)
- Homebrew formula
- Scoop/Winget manifests
- Self-update mechanism
- Cosign signature verification
7. CI/CD Integration Patterns
7.1 GitHub Actions
- name: Install Stella CLI
run: |
curl -sSL https://get.stella-ops.io | sh
echo "$HOME/.stella/bin" >> $GITHUB_PATH
- name: Authenticate
run: stella auth login --client-credentials
env:
STELLAOPS_CLIENT_ID: ${{ secrets.STELLA_CLIENT_ID }}
STELLAOPS_PRIVATE_KEY: ${{ secrets.STELLA_PRIVATE_KEY }}
- name: Scan Image
run: |
stella scan image ${{ env.IMAGE_REF }} --wait --json > scan-results.json
if [ $? -eq 2 ]; then
echo "::error::Policy failed - blocking deployment"
exit 1
fi
- name: Verify Attestation
run: stella verify attestation --artifact ${{ env.IMAGE_DIGEST }}
7.2 GitLab CI
scan:
script:
- stella auth login --client-credentials
- stella buildx install
- docker buildx build --attest=type=sbom,generator=stellaops/sbom-indexer -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
- stella scan image $CI_REGISTRY_IMAGE@$IMAGE_DIGEST --wait --json
artifacts:
reports:
container_scanning: scan-results.json
8. Configuration Model
8.1 Precedence
CLI flags > Environment variables > Config file > Defaults
8.2 Config File
# ~/.config/stellaops/config.yaml
cli:
authority: "https://authority.example.com"
backend:
scanner: "https://scanner.example.com"
attestor: "https://attestor.example.com"
auth:
deviceCode: true
audienceDefault: "scanner"
output:
json: false
color: auto
tls:
caBundle: "/etc/ssl/certs/ca-bundle.crt"
offline:
kitMirror: "s3://mirror/stellaops-kit"
8.3 Environment Variables
| Variable | Purpose |
|---|---|
STELLAOPS_AUTHORITY |
Authority URL |
STELLAOPS_SCANNER_URL |
Scanner service URL |
STELLAOPS_CLIENT_ID |
Service principal ID |
STELLAOPS_PRIVATE_KEY |
Service principal key |
STELLAOPS_TENANT |
Default tenant |
STELLAOPS_JSON |
Enable JSON output |
9. Offline Operation
9.1 Sealed Mode Detection
$ stella scan image nginx:latest
Error: Sealed mode active - external network access blocked
Remediation: Import offline kit or disable sealed mode
$ stella offline kit import latest-kit.tar.gz
Importing offline kit...
Advisories: 45,230 records
VEX documents: 12,450 records
Policy packs: 3 bundles
Import complete!
$ stella scan image nginx:latest
Scanning with offline data (2025-11-28)...
9.2 Air-Gap Guard
All HTTP flows route through StellaOps.AirGap.Policy. When sealed mode is active:
- External egress is blocked with
AIRGAP_EGRESS_BLOCKEDerror - CLI provides clear remediation guidance
- Local verification continues to work
10. Security Considerations
10.1 Credential Protection
- DPoP private keys stored in OS keychain only
- No plaintext tokens on disk
- Short-lived OpToks held in memory only
- Authorization headers redacted from verbose logs
10.2 Binary Verification
# Verify CLI binary signature
$ stella version --verify
Version: 1.2.3
Built: 2025-11-29T12:00:00Z
Signature: Valid (cosign)
Signer: release@stella-ops.io
10.3 Hard Lines
- Refuse to print token values
- Disallow
--insecurewithout explicit env var opt-in - Enforce short token TTL with proactive refresh
- Device-code cache bound to machine + user
11. Performance Targets
| Metric | Target |
|---|---|
| Startup time | < 20ms (AOT) |
| Request overhead | < 5ms |
| Large download (100MB) | > 80 MB/s |
| Buildx wrapper overhead | < 1ms |
12. Related Documentation
| Resource | Location |
|---|---|
| CLI architecture | docs/modules/cli/architecture.md |
| Policy CLI guide | docs/modules/cli/guides/policy.md |
| API/CLI reference | docs/09_API_CLI_REFERENCE.md |
| Offline operation | docs/24_OFFLINE_KIT.md |
13. Sprint Mapping
- Primary Sprint: SPRINT_0400_cli_ux.md (NEW)
- Related Sprints:
- SPRINT_210_ui_ii.md (UI integration)
- SPRINT_0187_0001_0001_evidence_locker_cli_integration.md (Evidence CLI)
Key Task IDs:
CLI-AUTH-10-001- DPoP authentication (DONE)CLI-SCAN-20-001- Scan commands (DONE)CLI-BUILDX-30-001- Buildx integration (DONE)CLI-ADVISE-48-001- Advisory AI commands (IN PROGRESS)CLI-SCAN-49-001- Filesystem scanning (TODO)
14. Success Metrics
| Metric | Target |
|---|---|
| Startup latency | < 20ms p99 |
| CI adoption | 80% of pipelines use CLI |
| Exit code coverage | 100% of failure modes |
| Shell completion coverage | 100% of commands |
| Offline operation success | Works without network |
Last updated: 2025-11-29