151 lines
5.0 KiB
Markdown
151 lines
5.0 KiB
Markdown
# stella CLI — Configuration
|
|
|
|
## Precedence (highest → lowest)
|
|
1. Command-line flags (e.g., `--output json`, `--offline`)
|
|
2. Environment variables
|
|
3. Config file (`config.yaml`/`config.json`) loaded from the first existing path:
|
|
- `$STELLA_CONFIG` (explicit override)
|
|
- `$XDG_CONFIG_HOME/stella/config.yaml` (or `%APPDATA%\\Stella\\config.yaml` on Windows)
|
|
- `$HOME/.config/stella/config.yaml`
|
|
|
|
Tip: keep secrets in env vars, not in the config file; tokens are read from `STELLA_TOKEN`, registry creds from `STELLA_REGISTRY_AUTH`, etc.
|
|
|
|
## Common settings (YAML example)
|
|
```yaml
|
|
output: json # json|ndjson|table
|
|
offline: true # force no-network mode
|
|
api:
|
|
baseUrl: https://console.stella.local
|
|
token: ${STELLA_TOKEN} # prefer env substitution
|
|
policy:
|
|
tenant: demo-tenant
|
|
rationale: true
|
|
airgap:
|
|
bundlesPath: /var/stella/bundles
|
|
trustRoots: /var/stella/trust/roots.pem
|
|
observability:
|
|
traceparent: auto # always inject trace headers when available
|
|
```
|
|
|
|
## Air-gap/offline knobs
|
|
- `--offline` or `STELLA_OFFLINE=1` forbids network calls; commands must rely on local bundles/caches.
|
|
- `airgap.bundlesPath` controls where imports/exports read/write sealed bundles.
|
|
- Mirror/import/export commands respect `STELLA_TRUST_ROOTS` for DSSE/TUF verification.
|
|
|
|
## Logging & telemetry
|
|
- `STELLA_LOG_LEVEL=debug` for verbose logs; `trace` adds wire dumps (still deterministic).
|
|
- Tracing headers: CLI injects `traceparent` when provided by the environment (CI runners, gateways); never emits PII.
|
|
|
|
## Profiles (planned)
|
|
- Profiles will live under `profiles/<name>.yaml` and can be selected with `--profile <name>`; until shipped, stick to the single default config file.
|
|
|
|
---
|
|
|
|
## Config Inspection Commands
|
|
|
|
> **Sprint:** SPRINT_20260112_014_CLI_config_viewer
|
|
|
|
The CLI provides unified config inspection across all StellaOps modules.
|
|
|
|
### List All Config Paths
|
|
|
|
```bash
|
|
# List all supported config paths
|
|
stella config list
|
|
|
|
# Output:
|
|
# Path Alias Module
|
|
# ────────────────────────────────────────────────────────────────────────
|
|
# policy.determinization policy:determinization Policy
|
|
# policy.confidenceweights policy:weights Policy
|
|
# scanner scanner Scanner
|
|
# scanner.reachability.prgate scanner:prgate Scanner
|
|
# attestor.rekor attestor:rekor Attestor
|
|
# signals.evidenceweightedscore signals:ews Signals
|
|
# ...
|
|
|
|
# Filter by module
|
|
stella config list --module policy
|
|
|
|
# Output as JSON
|
|
stella config list --output json
|
|
```
|
|
|
|
### Show Effective Config
|
|
|
|
```bash
|
|
# Show effective config for a path
|
|
stella config policy.determinization show
|
|
|
|
# Output:
|
|
# Effective Determinization Config
|
|
# ─────────────────────────────────
|
|
# Source: Service (api/v1/policy/config/determinization)
|
|
#
|
|
# Reanalysis Triggers:
|
|
# epssDeltaThreshold: 0.2
|
|
# triggerOnThresholdCrossing: true
|
|
# triggerOnRekorEntry: true
|
|
# triggerOnVexStatusChange: true
|
|
# triggerOnRuntimeTelemetryChange: true
|
|
# triggerOnPatchProofAdded: true
|
|
# triggerOnDsseValidationChange: true
|
|
# triggerOnToolVersionChange: false
|
|
#
|
|
# Conflict Handling:
|
|
# vexReachabilityContradiction: RequireManualReview
|
|
# ...
|
|
|
|
# Use path alias
|
|
stella config policy:determinization show
|
|
|
|
# Output as JSON
|
|
stella config policy.determinization show --output json
|
|
|
|
# Show from config file (bypass service)
|
|
stella config policy.determinization show --config /etc/stella/config.yaml
|
|
```
|
|
|
|
### Config Path Normalization
|
|
|
|
Path matching is case-insensitive with flexible separators:
|
|
|
|
| Input | Normalized | Valid |
|
|
|-------|------------|-------|
|
|
| `policy.determinization` | `policy.determinization` | ✓ |
|
|
| `Policy:Determinization` | `policy.determinization` | ✓ |
|
|
| `POLICY.DETERMINIZATION` | `policy.determinization` | ✓ |
|
|
| `policy:determinization` | `policy.determinization` | ✓ |
|
|
|
|
### Secret Redaction
|
|
|
|
Secrets are automatically redacted in config output:
|
|
|
|
```bash
|
|
stella config database show
|
|
|
|
# Output:
|
|
# database:
|
|
# host: pg.stella.local
|
|
# port: 5432
|
|
# database: stella
|
|
# username: stella_app
|
|
# password: ******** # Redacted
|
|
# connectionString: ******** # Redacted
|
|
```
|
|
|
|
### Popular Config Paths
|
|
|
|
| Path | Description |
|
|
|------|-------------|
|
|
| `policy.determinization` | Determinization triggers and thresholds |
|
|
| `policy.confidenceweights` | Evidence confidence weight values |
|
|
| `scanner` | Core scanner settings |
|
|
| `attestor.rekor` | Rekor transparency log settings |
|
|
| `signals.evidenceweightedscore` | EWS calculation settings |
|
|
| `excititor.mirror` | VEX mirror configuration |
|
|
| `airgap.bundlesigning` | Offline kit bundle signing |
|
|
| `signer.keyless` | Sigstore keyless signing |
|
|
|
|
See the full config inventory in `docs/implplan/SPRINT_20260112_014_CLI_config_viewer.md`.
|