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

up
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
AOC Guard CI / aoc-guard (push) Has been cancelled
Details
AOC Guard CI / aoc-verify (push) Has been cancelled
Details

Browse Source
This commit is contained in:
StellaOps Bot
2025-11-29 11:08:08 +02:00
parent 7e7be4d2fd
commit 3488b22c0c
102 changed files with 18487 additions and 969 deletions
Download Patch File Download Diff File Expand all files Collapse all files

402
docs/product-advisories/29-Nov-2025 - CLI Developer Experience and Command UX.md Normal file
View File

@@ -0,0 +1,402 @@
# 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`):**
```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)
```bash
$ 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)
```bash
$ 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
```bash
# 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
```bash
$ 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
```bash
$ 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)
- [x] Auth commands with DPoP
- [x] Scan/export commands
- [x] JSON output mode
- [x] Exit code standardization
- [x] Shell completions
### 6.2 Phase 2: Buildx & Verification (Complete)
- [x] Buildx plugin management
- [x] Attestation verification
- [x] Referrer verification
- [x] Report commands
### 6.3 Phase 3: Advanced Features (In Progress)
- [x] Decision export/verify commands
- [x] AOC guard helpers
- [x] 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
```yaml
- 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
```yaml
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
```yaml
# ~/.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
```bash
$ 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_BLOCKED` error
- 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
```bash
# 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 `--insecure` without 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*