Files
git.stella-ops.org/docs/modules/cli/guides/commands/reference.md
2026-01-24 00:12:43 +02:00

54 KiB

stella CLI - Complete Command Reference

Sprint: SPRINT_4100_0006_0006 - CLI Documentation Overhaul

Command Overview

The stella CLI provides 50+ commands organized into functional groups:

graph TD
    CLI[stella CLI] --> SCAN[Scanning & Analysis]
    CLI --> CRYPTO[Cryptography]
    CLI --> ADMIN[Administration]
    CLI --> AUTH[Authentication]
    CLI --> POLICY[Policy Management]
    CLI --> EXPLAIN[Explainability]
    CLI --> VEX[VEX & Decisioning]
    CLI --> SBOM[SBOM Operations]
    CLI --> ANALYTICS[Analytics & Insights]
    CLI --> REPORT[Reporting & Export]
    CLI --> OFFLINE[Offline Operations]
    CLI --> SYSTEM[System & Config]

Global Options

Available for all commands:

Option Alias Description
--verbose -v Enable verbose logging output
--tenant <id> -t Tenant context for the operation
--help -h Show command help
--version Show version information

Scanning & Analysis Commands

stella scan

Scan container images for vulnerabilities and generate SBOMs.

Usage:

stella scan <image> [options]

Arguments:

  • <image> - Container image reference (e.g., docker://nginx:latest, tar://image.tar)

Options:

Option Description Default
--output <path> Output file path stdout
--sbom-format <format> SBOM format: spdx, cyclonedx spdx
--sbom-only Generate SBOM only (skip vuln scan) false
--attestation Generate in-toto attestation false
--vex-mode <mode> VEX mode: strict, permissive, disabled strict
--policy <path> Policy file to apply None
--fail-on-policy-violations Exit with error if policy violations false

Examples:

# Basic scan
stella scan docker://nginx:latest --output scan-result.json

# Generate SPDX SBOM only
stella scan docker://nginx:latest --sbom-only --sbom-format spdx --output nginx.spdx.json

# Scan with attestation and policy enforcement
stella scan docker://nginx:latest \
  --attestation \
  --policy company-policy.yaml \
  --fail-on-policy-violations \
  --output results/

# Scan local tar archive
stella scan tar://image.tar --output scan.json

Exit Codes:

  • 0 - Success
  • 1 - Scan error
  • 2 - Policy violations (with --fail-on-policy-violations)

stella aoc

Generate Attestation of Compliance (AoC) documents.

Usage:

stella aoc [options]

Options:

Option Description
--scan <path> Scan result file
--sbom <path> SBOM file
--output <path> Output attestation file
--sign Sign attestation with crypto provider
--provider <name> Crypto provider (for signing)

Example:

stella aoc \
  --scan scan-result.json \
  --sbom sbom.spdx.json \
  --sign \
  --provider gost \
  --output attestation.jsonl

stella symbols

Extract and index debug symbols from containers.

Usage:

stella symbols <command> [options]

Subcommands:

  • extract - Extract debug symbols
  • index - Index symbols for lookup
  • query - Query symbol database

Example:

# Extract symbols
stella symbols extract docker://myapp:v1.2.3 --output symbols/

# Index symbols
stella symbols index symbols/ --output symbols.db

# Query symbols
stella symbols query --db symbols.db --address 0x12345678

Cryptography Commands

stella crypto providers

List available cryptographic providers.

Usage:

stella crypto providers [--json] [--verbose]

Output (International):

Available Crypto Providers:
- default (.NET Crypto, BouncyCastle)
  Algorithms: ECDSA-P256, ECDSA-P384, EdDSA, RSA-2048, RSA-4096

Output (Russia):

Available Crypto Providers:
- default (.NET Crypto, BouncyCastle)
  Algorithms: ECDSA-P256, ECDSA-P384, EdDSA, RSA-2048, RSA-4096
- gost (GOST R 34.10-2012, GOST R 34.11-2012)
  Algorithms: GOST12-256, GOST12-512, GOST2001

Distribution Availability: All


stella crypto sign

Sign files with cryptographic algorithms.

Usage:

stella crypto sign [options]

Options:

Option Description Required
--provider <name> Crypto provider Yes
--algorithm <alg> Algorithm (e.g., GOST12-256) Yes
--key-id <id> Key identifier Yes
--file <path> File to sign Yes
--output <path> Signature output file Yes
--detached Create detached signature No (default: true)

Examples:

# Sign with default provider (ECDSA)
stella crypto sign \
  --provider default \
  --algorithm ECDSA-P256 \
  --key-id prod-key \
  --file document.pdf \
  --output document.pdf.sig

# Sign with GOST (Russia distribution)
stella crypto sign \
  --provider gost \
  --algorithm GOST12-256 \
  --key-id gost-key-2024 \
  --file document.pdf \
  --output document.pdf.sig

# Sign with eIDAS QES (EU distribution)
stella crypto sign \
  --provider eidas \
  --algorithm ECDSA-P256-QES \
  --key-id eidas-qes-key \
  --file contract.pdf \
  --output contract.pdf.sig

Distribution Availability:

  • Default provider: All
  • GOST provider: Russia
  • eIDAS provider: EU
  • SM provider: China

stella crypto verify

Verify cryptographic signatures.

Usage:

stella crypto verify [options]

Options:

Option Description Required
--provider <name> Crypto provider Yes
--algorithm <alg> Algorithm Yes
--key-id <id> Key identifier Yes
--file <path> Original file Yes
--signature <path> Signature file Yes

Example:

stella crypto verify \
  --provider gost \
  --algorithm GOST12-256 \
  --key-id gost-key-2024 \
  --file document.pdf \
  --signature document.pdf.sig

Output:

✅ Signature valid
Provider: gost
Algorithm: GOST12-256
Signer: CN=Company GOST Key 2024

Exit Codes:

  • 0 - Signature valid
  • 1 - Signature invalid or verification error

stella crypto profiles

Manage crypto profiles for easy provider/key switching.

Usage:

stella crypto profiles [command]

Subcommands:

  • list - List crypto profiles
  • create - Create new profile
  • use - Set active profile
  • delete - Delete profile

Examples:

# List profiles
stella crypto profiles list

# Create GOST profile
stella crypto profiles create gost-prod \
  --provider gost \
  --algorithm GOST12-256 \
  --key-id gost-key-2024

# Use profile
stella crypto profiles use gost-prod

# Sign using active profile
stella crypto sign --file document.pdf --output document.pdf.sig

Administration Commands

stella admin policy

Manage platform policies.

Usage:

stella admin policy <command> [options]

Subcommands:

stella admin policy export

Export active policy snapshot.

stella admin policy export [--output <path>] [--verbose]

Example:

stella admin policy export --output policy-backup-$(date +%F).yaml

stella admin policy import

Import policy from file.

stella admin policy import --file <path> [--validate-only] [--verbose]

Example:

# Validate before importing
stella admin policy import --file new-policy.yaml --validate-only

# Import after validation
stella admin policy import --file new-policy.yaml

stella admin policy validate

Validate policy file without importing.

stella admin policy validate --file <path> [--verbose]

stella admin policy list

List all policy revisions.

stella admin policy list [--format table|json] [--verbose]

Required Scope: admin.policy

See Also: Admin Reference


stella admin users

User management commands.

Usage:

stella admin users <command> [options]

Subcommands:

stella admin users list

List platform users.

stella admin users list [--role <role>] [--format table|json] [--verbose]

stella admin users add

Add new user.

stella admin users add <email> --role <role> [--tenant <id>] [--verbose]

Roles:

  • admin - Full platform access
  • security-engineer - Security operations
  • developer - Development access
  • viewer - Read-only access

Example:

stella admin users add alice@example.com --role security-engineer --tenant acme-corp

stella admin users revoke

Revoke user access (destructive - requires confirmation).

stella admin users revoke <email> --confirm [--verbose]

Example:

stella admin users revoke bob@example.com --confirm

stella admin users update

Update user role.

stella admin users update <email> --role <role> [--verbose]

Required Scope: admin.users


stella admin feeds

Advisory feed management.

Usage:

stella admin feeds <command> [options]

Subcommands:

stella admin feeds list

List configured advisory feeds.

stella admin feeds list [--format table|json] [--verbose]

stella admin feeds status

Show feed synchronization status.

stella admin feeds status [--source <id>] [--verbose]

stella admin feeds refresh

Trigger feed refresh.

stella admin feeds refresh [--source <id>] [--force] [--verbose]

Example:

# Refresh all feeds
stella admin feeds refresh

# Force refresh NVD (ignore cache)
stella admin feeds refresh --source nvd --force

stella admin feeds history

Show feed synchronization history.

stella admin feeds history --source <id> [--limit <n>] [--verbose]

Required Scope: admin.feeds


stella admin system

System management commands.

Usage:

stella admin system <command> [options]

Subcommands:

stella admin system status

Show system health status.

stella admin system status [--format table|json] [--verbose]

Output:

System Health Status:
Component        Status    Uptime    Version
─────────────────────────────────────────────
Scanner          ✅ UP     5d 3h     2.1.0
Concelier        ✅ UP     5d 3h     2.1.0
Authority        ✅ UP     5d 3h     2.1.0
PostgreSQL       ✅ UP     10d 2h    16.2

stella admin system info

Show system version, build, and configuration.

stella admin system info [--verbose]

Required Scope: admin.platform


Authentication Commands

stella auth login

Authenticate with platform (interactive).

Usage:

stella auth login [--authority <url>] [--verbose]

Example:

# Interactive login (opens browser)
stella auth login

# Specify Authority URL
stella auth login --authority https://auth.stellaops.example.com

Output:

Opening browser for authentication...
✅ Logged in as alice@example.com
Token saved to ~/.stellaops/tokens.json

stella auth logout

Log out from platform.

Usage:

stella auth logout [--verbose]

stella auth whoami

Show current authentication status.

Usage:

stella auth whoami [--verbose]

Output:

Authenticated as: alice@example.com
Tenant: acme-corp
Scopes: scan.read, scan.write, admin.policy
Token expires: 2025-12-24T10:30:00Z

Score Commands

stella score compute

Compute a unified trust score from signal values.

Usage:

stella score compute [OPTIONS]

Options:

Option Description
--finding-id <ID> CVE@PURL finding identifier
--cvss <score> CVSS base score (0-10)
--epss <score> EPSS probability (0-1)
--reachability <value> Reachability signal (0-1)
--runtime <value> Runtime observation signal (0-1)
--exploit <value> Exploit maturity signal (0-1)
--backport <value> Backport availability signal (0-1)
--source <value> Source confidence signal (0-1)
--mitigation <value> Mitigation strength signal (0-1)
--weights-version <ver> Pin specific weight manifest version
--show-unknowns Include U metric and band in output
--show-deltas Include delta-if-present calculations
--format <fmt> Output format: table, json, markdown
--offline Use bundled weights (no server required)

Examples:

# Basic score computation
stella score compute --finding-id CVE-2024-1234@pkg:npm/lodash@4.17.0 \
    --cvss 7.5 --epss 0.15 --reachability 0.9

# Full output with deltas
stella score compute --finding-id CVE-2024-1234@pkg:npm/lodash@4.17.0 \
    --cvss 7.5 --reachability 0.9 --runtime 0.7 \
    --show-unknowns --show-deltas --format json

stella score explain

Display detailed breakdown of a score computation.

Usage:

stella score explain <FINDING-ID> [OPTIONS]

Examples:

stella score explain CVE-2024-1234@pkg:npm/lodash@4.17.0
stella score explain CVE-2024-1234@pkg:npm/lodash@4.17.0 --format markdown

stella score replay

Fetch the signed replay proof for a previously computed score.

Usage:

stella score replay <SCORE-ID> [OPTIONS]

Options:

Option Description
--format <fmt> Output format: table, json, markdown
--verify-rekor Also verify Rekor inclusion proof

Examples:

stella score replay score_a1b2c3d4e5f67890
stella score replay score_a1b2c3d4e5f67890 --format json --verify-rekor

stella score verify

Re-execute a score computation and verify it matches the original.

Usage:

stella score verify <SCORE-ID> [OPTIONS]

Options:

Option Description
--format <fmt> Output format: table, json, markdown
--verify-rekor Also verify Rekor inclusion proof

Examples:

stella score verify score_a1b2c3d4e5f67890

stella gate score evaluate

Compute unified score as part of a gate evaluation (enhanced with unknowns support).

Usage:

stella gate score evaluate [OPTIONS]

Additional Options (new):

Option Description
--show-unknowns Include U metric and unknowns band
--show-deltas Include delta-if-present for missing signals
--weights-version <ver> Pin specific weight manifest version

stella gate score weights

Manage EWS weight manifests.

Usage:

stella gate score weights <SUBCOMMAND>

Subcommands:

Subcommand Description
list List available weight manifest versions
show <version> Display manifest details
diff <v1> <v2> Compare two manifests

Examples:

stella gate score weights list
stella gate score weights show v2026-01-22
stella gate score weights diff v2026-01-22 v2026-02-01

Policy Commands

stella policy test

Test policy against scan results.

Usage:

stella policy test --policy <path> --scan <path> [--verbose]

Example:

stella policy test \
  --policy company-policy.yaml \
  --scan scan-result.json

Output:

Policy Test Results:
✅ PASS: No critical vulnerabilities
✅ PASS: SBOM completeness >= 95%
❌ FAIL: Found 3 GPL-licensed dependencies (policy: copyleft-disallowed)

Policy Status: FAILED (1/3 checks failed)

stella policy validate

Validate policy syntax and logic.

Usage:

stella policy validate --file <path> [--verbose]

VEX & Decisioning Commands

stella vex generate

Generate VEX document from scan results.

Usage:

stella vex generate --scan <path> [--output <path>] [--verbose]

Example:

stella vex generate \
  --scan scan-result.json \
  --output vex-doc.json

stella vex merge

Merge multiple VEX documents.

Usage:

stella vex merge --vex <path1> --vex <path2> [--output <path>] [--verbose]

stella decision

Manage vulnerability decisions (VEX workflow).

Usage:

stella decision <command> [options]

Subcommands:

  • create - Create new decision
  • list - List decisions
  • update - Update decision
  • export - Export decisions to VEX

Example:

# Mark CVE as not_affected
stella decision create \
  --cve CVE-2024-12345 \
  --status not_affected \
  --justification vulnerable_code_not_in_execute_path \
  --impact-statement "Vulnerable function not called in our application"

SBOM Operations

stella sbom generate

Generate SBOM from source code or container.

Usage:

stella sbom generate <target> [options]

Options:

Option Description
--format <format> SBOM format: spdx, cyclonedx
--output <path> Output file path
--include-dev-dependencies Include dev dependencies

Example:

# Generate SPDX SBOM from source
stella sbom generate . --format spdx --output sbom.spdx.json

# Generate CycloneDX SBOM from container
stella sbom generate docker://myapp:v1 --format cyclonedx --output sbom.cdx.json

stella sbom validate

Validate SBOM against schema.

Usage:

stella sbom validate --file <path> [--verbose]

stella sbom merge

Merge multiple SBOMs.

Usage:

stella sbom merge --sbom <path1> --sbom <path2> [--output <path>] [--verbose]

Analytics Commands

stella analytics sbom-lake

Query SBOM lake analytics views (suppliers, licenses, vulnerabilities, backlog, attestation coverage, trends).

Usage:

stella analytics sbom-lake <subcommand> [options]

Subcommands:

  • suppliers - Supplier concentration
  • licenses - License distribution
  • vulnerabilities - CVE exposure (VEX-adjusted)
  • backlog - Fixable vulnerability backlog
  • attestation-coverage - Provenance/SLSA coverage
  • trends - Time-series trends (vulnerabilities/components)

Common options:

Option Description
--environment <env> Filter to a specific environment
--min-severity <level> Minimum severity (critical, high, medium, low)
--days <n> Lookback window in days (trends only)
--series <name> Trend series (vulnerabilities, components, all)
--limit <n> Maximum number of rows
--format <fmt> Output format: table, json, csv
--output <path> Output file path

Example:

stella analytics sbom-lake vulnerabilities --environment prod --min-severity high --format csv --output vuln.csv

Function Map Commands

stella function-map generate

Generate a function map predicate from an SBOM and optional static analysis.

Usage:

stella function-map generate [OPTIONS]

Options:

Option Alias Description
--sbom <path> -s Path to SBOM file (required)
--service <name> Service name (required)
--subject <purl> Subject artifact PURL (derived from SBOM if omitted)
--static-analysis <path> Path to static analysis results
--hot-functions <glob> -H Glob patterns for functions of interest (repeatable)
--min-rate <value> Minimum observation rate 0.0-1.0 (default 0.95)
--window <seconds> Observation window in seconds (default 1800)
--fail-on-unexpected Fail verification on unexpected symbols
--output <path> -o Output file path
--format <fmt> -f Output format: json, yaml (default json)
--build-id <id> Build ID for provenance correlation

Examples:

# Basic generation from SBOM
stella function-map generate --sbom app.cdx.json --service my-backend

# With hot function filtering and custom thresholds
stella function-map generate \
  --sbom app.cdx.json \
  --service my-backend \
  --hot-functions "crypto/*" --hot-functions "auth/*" \
  --min-rate 0.90 --window 3600 \
  --output function-map.json

stella function-map verify

Verify runtime observations against a function map predicate.

Usage:

stella function-map verify [OPTIONS]

Options:

Option Alias Description
--function-map <path> -m Path or OCI reference to predicate (required)
--container <id> -c Filter to specific container ID
--from <timestamp> ISO 8601 start time (default: 30 min ago)
--to <timestamp> ISO 8601 end time (default: now)
--output <path> -o Output verification report path
--format <fmt> -f Output format: json, table, md (default table)
--strict Fail on any unexpected symbols
--offline Use bundled observations file
--observations <path> Path to observations file (NDJSON)

Examples:

# Online verification against live observations
stella function-map verify \
  --function-map function-map.json \
  --from "2026-01-23T00:00:00Z" --to "2026-01-23T01:00:00Z"

# Offline verification with bundled observations
stella function-map verify \
  --function-map function-map.json \
  --offline --observations obs.ndjson \
  --format json --output report.json

Observations Commands

stella observations query

Query runtime observations from the observation store.

Usage:

stella observations query [OPTIONS]

Options:

Option Alias Description
--symbol <glob> -s Glob pattern for symbol name
--node-hash <hash> -n Exact node hash filter
--container <id> -c Container ID filter
--pod <name> -p Pod name filter
--namespace <ns> -N Kubernetes namespace filter
--probe-type <type> Probe type filter
--from <timestamp> ISO 8601 start time (default: 1 hour ago)
--to <timestamp> ISO 8601 end time (default: now)
--limit <n> -l Maximum results (default 100)
--offset <n> Pagination offset (default 0)
--format <fmt> -f Output format: json, table, csv (default table)
--summary Show statistics instead of individual records
--output <path> -o Output file path
--offline Use local observations file
--observations-file <path> Path to observations file for offline mode

Examples:

# Query all crypto-related observations
stella observations query --symbol "crypto_*" --from "2026-01-23T00:00:00Z"

# Summary for a specific container
stella observations query --container abc123 --summary

# Export as CSV for analysis
stella observations query --pod my-service-pod --format csv --output obs.csv

Ground-Truth Corpus Commands

stella groundtruth

Manage ground-truth corpus for patch-paired binary verification. The corpus supports precision validation of security advisories by maintaining symbol and binary pairs from upstream sources.

Sprint: SPRINT_20260121_035_BinaryIndex_golden_corpus_connectors_cli

Usage:

stella groundtruth <subcommand> [options]

Subcommands:

  • sources - Manage symbol source connectors
  • symbols - Query and search symbols in the corpus
  • pairs - Manage security pairs (vuln/patch binary pairs)
  • validate - Run validation and view metrics

stella groundtruth sources

Manage upstream symbol source connectors.

Usage:

stella groundtruth sources <command> [options]

Subcommands:

stella groundtruth sources list

List available symbol source connectors.

stella groundtruth sources list [--output-format table|json] [--verbose]

Output:

ID                        Display Name              Status       Last Sync
------------------------------------------------------------------------------------------
debuginfod-fedora         Fedora Debuginfod         Enabled      2026-01-22T10:00:00Z
debuginfod-ubuntu         Ubuntu Debuginfod         Enabled      2026-01-22T10:00:00Z
ddeb-ubuntu               Ubuntu ddebs              Enabled      2026-01-22T09:30:00Z
buildinfo-debian          Debian Buildinfo          Enabled      2026-01-22T08:00:00Z
secdb-alpine              Alpine SecDB              Enabled      2026-01-22T06:00:00Z

stella groundtruth sources enable

Enable a symbol source connector.

stella groundtruth sources enable <source> [--verbose]

Arguments:

  • <source> - Source connector ID (e.g., debuginfod-fedora)

Example:

stella groundtruth sources enable debuginfod-fedora

stella groundtruth sources disable

Disable a symbol source connector.

stella groundtruth sources disable <source> [--verbose]

stella groundtruth sources sync

Synchronize symbol sources from upstream.

stella groundtruth sources sync [--source <id>] [--full] [--verbose]

Options:

Option Description
--source <id> Source connector ID (all if not specified)
--full Perform a full sync instead of incremental

Example:

# Incremental sync of all sources
stella groundtruth sources sync

# Full sync of Debian buildinfo
stella groundtruth sources sync --source buildinfo-debian --full

stella groundtruth symbols

Query and search symbols in the corpus.

Usage:

stella groundtruth symbols <command> [options]

stella groundtruth symbols lookup

Lookup symbols by debug ID (build-id).

stella groundtruth symbols lookup --debug-id <id> [--output-format table|json] [--verbose]

Options:

Option Alias Description Required
--debug-id -d Debug ID (build-id) to lookup Yes
--output-format -O Output format: table, json No

Example:

stella groundtruth symbols lookup --debug-id 7f8a9b2c4d5e6f1a --output-format json

Output (table):

Binary: libcrypto.so.3
Architecture: x86_64
Distribution: debian-bookworm
Package: openssl@3.0.11-1
Symbol Count: 4523
Sources: debuginfod-fedora, buildinfo-debian

Search symbols by package or distribution.

stella groundtruth symbols search [--package <name>] [--distro <distro>] [--limit <n>] [--output-format table|json] [--verbose]

Options:

Option Alias Description Default
--package -p Package name to search for -
--distro Distribution filter (debian, ubuntu, alpine) -
--limit -l Maximum results 20

Example:

stella groundtruth symbols search --package openssl --distro debian --limit 50

stella groundtruth pairs

Manage security pairs (vulnerable/patched binary pairs) in the corpus.

Usage:

stella groundtruth pairs <command> [options]

stella groundtruth pairs create

Create a new security pair.

stella groundtruth pairs create --cve <cve-id> --vuln-pkg <pkg=ver> --patch-pkg <pkg=ver> [--distro <distro>] [--verbose]

Options:

Option Description Required
--cve CVE identifier Yes
--vuln-pkg Vulnerable package (name=version) Yes
--patch-pkg Patched package (name=version) Yes
--distro Distribution (e.g., debian-bookworm) No

Example:

stella groundtruth pairs create \
  --cve CVE-2024-1234 \
  --vuln-pkg openssl=3.0.10-1 \
  --patch-pkg openssl=3.0.11-1 \
  --distro debian-bookworm

stella groundtruth pairs list

List security pairs in the corpus.

stella groundtruth pairs list [--cve <pattern>] [--package <name>] [--limit <n>] [--output-format table|json] [--verbose]

Options:

Option Alias Description Default
--cve Filter by CVE (supports wildcards: CVE-2024-*) -
--package -p Filter by package name -
--limit -l Maximum results 50

Example:

stella groundtruth pairs list --cve CVE-2024-* --package openssl --limit 100

Output:

Pair ID      CVE                Package      Vuln Version    Patch Version
-------------------------------------------------------------------------------
pair-001     CVE-2024-1234      openssl      3.0.10-1        3.0.11-1
pair-002     CVE-2024-5678      curl         8.4.0-1         8.5.0-1

stella groundtruth pairs delete

Delete a security pair from the corpus.

stella groundtruth pairs delete <pair-id> [--force] [--verbose]

Options:

Option Alias Description
--force -f Skip confirmation prompt

stella groundtruth validate

Run validation harness against security pairs.

Usage:

stella groundtruth validate <command> [options]

stella groundtruth validate run

Run validation on security pairs.

stella groundtruth validate run [--pairs <pattern>] [--matcher <type>] [--output <path>] [--parallel <n>] [--verbose]

Options:

Option Alias Description Default
--pairs -p Pair filter pattern (e.g., openssl:CVE-2024-*) all
--matcher -m Matcher type: semantic-diffing, hash-based, hybrid semantic-diffing
--output -o Output file for validation report -
--parallel Maximum parallel validations 4

Example:

stella groundtruth validate run \
  --pairs "openssl:CVE-2024-*" \
  --matcher semantic-diffing \
  --parallel 8 \
  --output validation-report.md

Output:

Validating pairs: 10/10
Validation complete. Run ID: vr-20260122100532
  Function Match Rate: 94.2%
  False-Negative Rate: 2.1%
  SBOM Hash Stability: 3/3
Report written to: validation-report.md

stella groundtruth validate metrics

View metrics for a validation run.

stella groundtruth validate metrics --run-id <id> [--output-format table|json] [--verbose]

Options:

Option Alias Description Required
--run-id -r Validation run ID Yes

Example:

stella groundtruth validate metrics --run-id vr-20260122100532 --output-format json

Output (table):

Run ID: vr-20260122100532
Duration: 2026-01-22T10:00:00Z - 2026-01-22T10:15:32Z
Pairs: 48/50 successful
Function Match Rate: 94.2%
False-Negative Rate: 2.1%
SBOM Hash Stability: 3/3
Verify Time (p50/p95): 423ms / 1.2s

stella groundtruth validate export

Export validation report.

stella groundtruth validate export --run-id <id> --output <path> [--format <fmt>] [--verbose]

Options:

Option Alias Description Default
--run-id -r Validation run ID (required)
--output -o Output file path (required)
--format -f Export format: markdown, html, json markdown

Example:

stella groundtruth validate export \
  --run-id vr-20260122100532 \
  --format markdown \
  --output validation-report.md

See Also: Ground-Truth CLI Guide


stella groundtruth bundle

Manage evidence bundles for offline verification of patch provenance.

Sprint: SPRINT_20260121_036_BinaryIndex_golden_corpus_bundle_verification

Usage:

stella groundtruth bundle <command> [options]

Subcommands:

  • export - Create evidence bundles for air-gapped environments
  • import - Import and verify evidence bundles

stella groundtruth bundle export

Export evidence bundles containing pre/post binaries, SBOMs, delta-sig predicates, and timestamps.

stella groundtruth bundle export [options]

Options:

Option Description Required
--packages <list> Comma-separated package names (e.g., openssl,curl) Yes
--distros <list> Comma-separated distributions (e.g., debian,ubuntu) Yes
--output <path> Output bundle path (.tar.gz or .oci.tar) Yes
--sign-with <signer> Signing method: cosign, sigstore, none No
--include-debug Include debug symbols No
--include-kpis Include KPI validation results No
--include-timestamps Include RFC 3161 timestamps No

Example:

stella groundtruth bundle export \
  --packages openssl,zlib,glibc \
  --distros debian,fedora \
  --output evidence/security-bundle.tar.gz \
  --sign-with cosign \
  --include-debug \
  --include-kpis \
  --include-timestamps

Exit Codes:

  • 0 - Bundle created successfully
  • 1 - Bundle creation failed
  • 2 - Invalid input or configuration error

stella groundtruth bundle import

Import and verify evidence bundles in air-gapped environments.

stella groundtruth bundle import [options]

Options:

Option Description Required
--input <path> Input bundle path Yes
--verify-signature Verify bundle signatures No
--trusted-keys <path> Path to trusted public keys No
--trust-profile <path> Trust profile for verification No
--output <path> Output verification report No
--format <fmt> Report format: markdown, json, html No

Example:

stella groundtruth bundle import \
  --input symbol-bundle.tar.gz \
  --verify-signature \
  --trusted-keys /etc/stellaops/trusted-keys.pub \
  --trust-profile /etc/stellaops/trust-profiles/global.json \
  --output verification-report.md

Verification Steps:

  1. Validate bundle manifest signature
  2. Verify all blob digests match manifest
  3. Validate DSSE envelope signatures against trusted keys
  4. Verify RFC 3161 timestamps against trusted TSA certificates
  5. Run IR matcher to confirm patched functions
  6. Verify SBOM canonical hash matches signed predicate
  7. Output verification report with KPI line items

Exit Codes:

  • 0 - All verifications passed
  • 1 - One or more verifications failed
  • 2 - Invalid input or configuration error

stella groundtruth validate check

Check KPI regression against baseline thresholds.

Sprint: SPRINT_20260121_036_BinaryIndex_golden_corpus_bundle_verification

stella groundtruth validate check [options]

Options:

Option Description Default
--results <path> Path to validation results JSON (required)
--baseline <path> Path to baseline JSON (required)
--precision-threshold <pp> Max precision drop (percentage points) 0.01
--recall-threshold <pp> Max recall drop (percentage points) 0.01
--fn-rate-threshold <pp> Max FN rate increase (percentage points) 0.01
--determinism-threshold <rate> Min determinism rate 1.0
--ttfrp-threshold <pct> Max TTFRP p95 increase (percentage) 0.20
--output <path> Output report path stdout
--format <fmt> Report format: markdown, json markdown

Example:

stella groundtruth validate check \
  --results bench/results/20260122.json \
  --baseline bench/baselines/current.json \
  --precision-threshold 0.01 \
  --recall-threshold 0.01 \
  --fn-rate-threshold 0.01 \
  --determinism-threshold 1.0 \
  --output regression-report.md

Regression Gates:

Metric Threshold Action
Precision Drops > threshold Fail
Recall Drops > threshold Fail
False-negative rate Increases > threshold Fail
Deterministic replay Drops below threshold Fail
TTFRP p95 Increases > threshold Warn

Exit Codes:

  • 0 - All gates passed
  • 1 - One or more gates failed
  • 2 - Invalid input or configuration error

stella groundtruth baseline

Manage KPI baselines for regression detection.

Sprint: SPRINT_20260121_036_BinaryIndex_golden_corpus_bundle_verification

Usage:

stella groundtruth baseline <command> [options]

Subcommands:

  • update - Update baseline from validation results
  • show - Display baseline contents

stella groundtruth baseline update

Update baseline from validation results.

stella groundtruth baseline update [options]

Options:

Option Description Required
--from-results <path> Path to validation results JSON Yes
--output <path> Output baseline path Yes
--description <text> Description for the baseline update No
--source <commit> Source commit SHA for traceability No

Example:

stella groundtruth baseline update \
  --from-results bench/results/20260122.json \
  --output bench/baselines/current.json \
  --description "Post algorithm-v2.3 update" \
  --source "$(git rev-parse HEAD)"

stella groundtruth baseline show

Display baseline contents.

stella groundtruth baseline show --baseline <path> [--format table|json]

Options:

Option Description Default
--baseline <path> Path to baseline JSON (required)
--format Output format: table, json table

Output (table):

Baseline ID: baseline-20260122120000
Created: 2026-01-22T12:00:00Z
Source: abc123def456
Description: Post-semantic-diffing-v2 baseline

KPIs:
  Precision:              0.9500
  Recall:                 0.9200
  False Negative Rate:    0.0800
  Determinism:            1.0000
  TTFRP p95:              150ms

See Also: Ground-Truth CLI Guide


Attestation Commands

stella attest attach

Attach an attestation (DSSE envelope) to an OCI image via ORAS referrers.

Sprint: SPRINT_20260122_040_Platform_oci_delta_attestation_pipeline (040-01)

Usage:

stella attest attach --image <ref> --attestation <path> [options]

Options:

Option Alias Description Default
--image -i OCI image reference (e.g., registry.example.com/app:v1.2) (required)
--attestation -a Path to DSSE envelope JSON file (required)
--media-type Media type for the attestation layer application/vnd.dsse.envelope.v1+json
--registry-url Override registry URL From image reference
--verbose -v Show detailed progress false

Example:

stella attest attach \
  --image registry.example.com/app:v1.2 \
  --attestation delta-sig.dsse.json \
  --verbose

Exit Codes:

  • 0 - Attestation attached successfully
  • 1 - Attachment failed (registry error, invalid envelope)
  • 2 - Invalid input or configuration error

stella attest verify

Verify attestations attached to an OCI image. Lists and validates DSSE envelopes, checks signatures, and optionally verifies Rekor annotations.

Sprint: SPRINT_20260122_040_Platform_oci_delta_attestation_pipeline (040-02)

Usage:

stella attest verify --image <ref> [options]

Options:

Option Alias Description Default
--image -i OCI image reference to verify (required)
--predicate-type Filter by predicate type URI (all)
--trusted-keys Path to trusted public keys directory (none)
--require-rekor Require valid Rekor inclusion annotations false
--output -o Output format: table, json table
--verbose -v Show detailed verification steps false

Example:

stella attest verify \
  --image registry.example.com/app:v1.2 \
  --predicate-type "https://stellaops.dev/delta-sig/v1" \
  --require-rekor \
  --output json

Exit Codes:

  • 0 - All attestations verified successfully
  • 1 - One or more attestations failed verification
  • 2 - Invalid input or configuration error

Binary Analysis Commands

stella binary delta-sig attest

Sign a delta-sig predicate with an EC key and optionally submit to a Rekor transparency log. Produces a DSSE envelope suitable for stella attest attach.

Sprint: SPRINT_20260122_040_Platform_oci_delta_attestation_pipeline (040-05)

Usage:

stella binary delta-sig attest --predicate <path> --key <path> [options]

Options:

Option Alias Description Default
--predicate -p Path to delta-sig predicate JSON file (required)
--key -k Path to EC private key (PEM) for DSSE signing (required)
--output -o Path to write the DSSE envelope stdout
--rekor-url Rekor transparency log URL for submission (none)
--receipt Path to save Rekor receipt JSON (none, only with --rekor-url)
--dry-run Validate predicate and key without signing false
--verbose -v Show detailed signing and submission steps false

Example:

# Sign predicate and submit to Rekor
stella binary delta-sig attest \
  --predicate delta-sig-predicate.json \
  --key signing-key.pem \
  --output signed-envelope.dsse.json \
  --rekor-url https://rekor.sigstore.dev \
  --receipt rekor-receipt.json \
  --verbose

# Dry run (validate only)
stella binary delta-sig attest \
  --predicate delta-sig-predicate.json \
  --key signing-key.pem \
  --dry-run

Signing Behavior:

  • Key must be an ECDSA private key (PEM format)
  • Produces an in-toto v1 statement wrapping the predicate as DSSE payload
  • PAE (Pre-Authentication Encoding) used per DSSE specification
  • Signature is Base64-encoded in the envelope

Rekor Submission:

  • When --rekor-url is provided, the signed envelope is submitted to the transparency log
  • On success, Rekor UUID and log index are displayed
  • Receipt JSON includes uuid, logIndex, integratedTime, and logUrl

Exit Codes:

  • 0 - Signing (and optional Rekor submission) succeeded
  • 1 - Signing or submission failed
  • 2 - Invalid predicate, key format, or configuration error

Bundle Commands

stella bundle verify

Verify offline evidence bundles with full cryptographic verification. Checks manifest integrity, blob digests, DSSE signatures, Rekor proofs, timestamps, payload types, and optionally replays large blob content verification.

Sprint: SPRINT_20260122_040_Platform_oci_delta_attestation_pipeline (040-06)

Usage:

stella bundle verify --bundle <path> [options]

Options:

Option Alias Description Default
--bundle -b Path to bundle (tar.gz or directory) (required)
--trust-root Path to trusted root certificate (PEM) (none)
--rekor-checkpoint Path to Rekor checkpoint for offline proof verification (none)
--offline Run in offline mode (no network access) false
--output -o Output format: table, json table
--strict Fail on any warning (missing optional artifacts) false
--signer Path to signing key (PEM) for verification report (none)
--signer-cert Path to signer certificate PEM (for report metadata) (none)
--replay Verify binary content by fetching/reading large blobs referenced in attestations false
--blob-source Override blob source (registry URL or local directory path) (auto-detect)
--verbose -v Show detailed verification steps false

Verification Steps:

  1. Manifest checksum - Validate bundle manifest integrity
  2. Blob digests - Verify all blob file SHA-256 digests match manifest
  3. DSSE signatures - Validate envelope signatures against trusted keys
  4. Rekor proofs - Verify inclusion proofs against checkpoint (when provided)
  5. Timestamps - Validate RFC 3161 timestamps against TSA certificates
  6. Payload types - Verify predicate types match expectations
  7. Blob Replay (when --replay) - Fetch and verify large blobs referenced in attestations

Blob Replay Behavior:

  • For full bundles (blobs embedded): verifies content from blobs/ directory against attestation digests
  • For light bundles (metadata only): fetches blobs from --blob-source (local dir or registry URL)
  • Supports sha256, sha384, sha512 digest algorithms
  • In --offline mode, blob fetch from registries is blocked (only local sources work)

Example:

# Basic verification
stella bundle verify --bundle evidence-bundle.tar.gz

# Full verification with replay and trust root
stella bundle verify \
  --bundle /path/to/bundle \
  --trust-root /etc/stellaops/tsa-root.pem \
  --rekor-checkpoint checkpoint.json \
  --replay \
  --verbose

# Light bundle with local blob source
stella bundle verify \
  --bundle light-bundle/ \
  --replay \
  --blob-source /path/to/blobs/

# Strict offline verification with signed report
stella bundle verify \
  --bundle evidence-bundle/ \
  --offline \
  --strict \
  --signer report-key.pem \
  --signer-cert report-cert.pem

Exit Codes:

  • 0 - All verifications passed
  • 1 - One or more verifications failed
  • 2 - Invalid input or configuration error

Evidence Commands

stella evidence export-bundle

Export evidence bundles for offline verification. Supports two-tier export modes: light (metadata and attestations only) and full (includes embedded binary blobs).

Sprint: SPRINT_20260122_040_Platform_oci_delta_attestation_pipeline (040-04)

Usage:

stella evidence export-bundle --image <ref> --output <path> [options]

Options:

Option Alias Description Default
--image -i OCI image reference to export evidence for (required)
--output -o Output bundle path (.tar.gz or directory) (required)
--full Export in full mode (embed binary blobs alongside attestations) false (light mode)
--sign-with Signing method for bundle: cosign, sigstore, none none
--verbose -v Show detailed export progress false

Export Modes:

Mode Flag Contents Size Use Case
Light (default) Manifest, attestation envelopes, metadata Small Quick transfer, metadata audit
Full --full Light + embedded binary blobs in blobs/ dir Large Air-gap verification, replay

Example:

# Light export (default)
stella evidence export-bundle \
  --image registry.example.com/app:v1.2 \
  --output evidence-light.tar.gz

# Full export with embedded blobs
stella evidence export-bundle \
  --image registry.example.com/app:v1.2 \
  --output evidence-full.tar.gz \
  --full \
  --verbose

Exit Codes:

  • 0 - Bundle exported successfully
  • 1 - Export failed
  • 2 - Invalid input or configuration error

Reporting & Export Commands

stella report

Generate compliance reports from scan results.

Usage:

stella report --scan <path> --format <format> [--output <path>] [--verbose]

Formats:

  • html - HTML report
  • pdf - PDF report
  • markdown - Markdown report
  • csv - CSV export
  • json - JSON export

Example:

# Generate HTML report
stella report --scan scan-result.json --format html --output report.html

# Generate PDF report
stella report --scan scan-result.json --format pdf --output report.pdf

stella export

Export scan results in various formats.

Usage:

stella export --scan <path> --format <format> [--output <path>] [--verbose]

Formats:

  • csv - CSV export for spreadsheets
  • sarif - SARIF format for CI/CD integration
  • json - JSON export
  • xml - XML export

Example:

# Export to CSV for Excel analysis
stella export --scan scan-result.json --format csv --output vulnerabilities.csv

# Export to SARIF for GitHub Code Scanning
stella export --scan scan-result.json --format sarif --output results.sarif

Offline Operations

stella offline sync

Synchronize offline package for air-gapped environments.

Usage:

stella offline sync [--output <path>] [--feeds nvd,osv,github] [--verbose]

Example:

# Create offline package
stella offline sync \
  --feeds nvd,osv,github \
  --output stellaops-offline-$(date +%F).tar.gz

stella offline load

Load offline package into air-gapped instance.

Usage:

stella offline load --package <path> [--verbose]

Example:

stella offline load --package stellaops-offline-2025-12-23.tar.gz

System & Configuration

stella config

Manage CLI configuration.

Usage:

stella config <command> [options]

Subcommands:

  • show - Show current configuration
  • set - Set configuration value
  • get - Get configuration value
  • list - List all configuration keys
  • profile - Manage profiles

Examples:

# Show current config
stella config show

# Set backend URL
stella config set Backend.BaseUrl https://api.stellaops.example.com

# Get backend URL
stella config get Backend.BaseUrl

# Create profile
stella config profile create prod --backend-url https://api.stellaops.example.com

# Switch profile
stella config profile use prod

stella system diagnostics

Run system diagnostics.

Usage:

stella system diagnostics [--verbose]

Output:

System Diagnostics:
✅ CLI version: 2.1.0
✅ .NET Runtime: 10.0.0
✅ Backend reachable: https://api.stellaops.example.com
✅ Authentication: Valid (expires 2025-12-24)
✅ Crypto providers: default, gost
⚠️  PostgreSQL: Not configured (offline mode)

stella version

Show version information.

Usage:

stella version [--verbose]

Output:

stella CLI version 2.1.0
Build: 2025-12-23T10:00:00Z
Commit: dfaa207
Distribution: stella-russia
Platform: linux-x64
.NET Runtime: 10.0.0

Explainability Commands

stella explain block

Explain why an artifact was blocked by policy gates. Produces deterministic trace with referenced evidence artifacts.

Sprint: SPRINT_20260117_026_CLI_why_blocked_command Moat Reference: M2 (Explainability with proof, not narrative)

Usage:

stella explain block <digest> [options]

Arguments:

  • <digest> - Artifact digest (sha256:abc123..., raw hex, or OCI reference)

Options:

Option Description Default
--format <format> Output format: table, json, markdown table
--show-evidence Include full evidence artifact details false
--show-trace Include policy evaluation trace false
--replay-token Include replay token in output false
--output <path> Write to file instead of stdout stdout
--offline Query local verdict cache only false

Examples:

# Basic explanation
stella explain block sha256:abc123def456...

# JSON output for CI/CD
stella explain block sha256:abc123... --format json --output reason.json

# Full explanation with evidence and trace
stella explain block sha256:abc123... --show-evidence --show-trace

# Markdown for PR comment
stella explain block sha256:abc123... --format markdown | gh pr comment 123 --body-file -

Exit Codes:

  • 0 - Artifact is NOT blocked (all gates passed)
  • 1 - Artifact IS blocked
  • 2 - Error (not found, API error)

Output (table):

Artifact: sha256:abc123def456789012345678901234567890123456789012345678901234
Status: BLOCKED

Gate: VexTrust
Reason: Trust score below threshold (0.45 < 0.70)
Suggestion: Obtain VEX statement from trusted issuer

Evidence:
  [VEX   ] vex:sha256:de...23  vendor-x  2026-01-15T10:00:00Z
  [REACH ] reach:sha256...56   static    2026-01-15T09:55:00Z

Replay: stella verify verdict --verdict urn:stella:verdict:sha256:abc123:v2.3.0:1737108000

See Also: Explain Commands Documentation


Additional Commands

stella vuln query

Query vulnerability database.

Usage:

stella vuln query <cve-id> [--verbose]

stella findings

Manage scan findings.

Usage:

stella findings <command> [options]

stella advise

Get AI-powered remediation advice for vulnerabilities.

Usage:

stella advise --cve <cve-id> [--verbose]

stella reachability

Analyze vulnerability reachability in code.

Usage:

stella reachability analyze --scan <path> --code <path> [--output <path>]

stella graph

Call graph evidence and lineage commands.

Usage:

stella graph explain --graph-id <id> [--vuln-id <id>] [--purl <purl>] [--json]
stella graph verify --hash <blake3:...> [--format text|json|markdown]
stella graph lineage show <digest|purl> [--format json|graphson|mermaid] [--output <path>]

stella mirror

Manage local package mirrors for offline operation.

Usage:

stella mirror <command> [options]

stella notify

Send notifications about scan results.

Usage:

stella notify --scan <path> --channel slack --webhook <url>

stella issuer

Manage issuer keys for signing and verification.

Usage:

stella issuer keys list --format json
stella issuer keys create --type ecdsa --name primary --format json
stella issuer keys rotate <id> --format json
stella issuer keys revoke <id> --format json

Language-Specific Commands

stella ruby

Ruby-specific operations.

stella ruby analyze <path>

stella python

Python-specific operations.

stella python analyze <path>

stella php

PHP-specific operations.

stella php analyze <path>

Exit Codes

Standard exit codes across all commands:

Code Meaning
0 Success
1 General error
2 Policy violations (with --fail-on-policy-violations)
3 Authentication error
4 Configuration error
5 Network error
10 Invalid arguments

Environment Variables

Variable Description Example
STELLAOPS_BACKEND_URL Backend API URL https://api.stellaops.example.com
STELLAOPS_API_KEY API key for authentication sk_live_...
STELLAOPS_TENANT Default tenant acme-corp
STELLAOPS_CRYPTO_PROVIDER Default crypto provider gost, eidas, sm
STELLAOPS_LOG_LEVEL Log level Debug, Info, Warning, Error
STELLAOPS_OFFLINE_MODE Enable offline mode true
STELLAOPS_CONFIG_PATH Custom config file path ~/.stellaops/custom.yaml

See Also