stella vex — Command Guide

The stella vex command group works with Vulnerability Exploitability eXchange (VEX) data in Stella Ops: it queries the VEX consensus projection, exports deterministic VEX evidence, manages webhook subscriptions, and generates VEX statements from facet-drift analysis. It is the operator surface over VexLens consensus and is aggregation-only — the CLI never infers verdicts beyond the upstream consensus projection.

Audience: release operators, security engineers, and CI/CD pipelines that gate deployments on VEX status.

Command summary

Command	Purpose
`stella vex consensus --query <filter>`	List VEX consensus states for a filter.
`stella vex get --id <consensusId>`	Fetch a single consensus record by id.
`stella vex simulate --input <vexDocs> --policy <policyConfig>`	Re-run consensus against candidate documents/policy.
`stella vex evidence export <target>`	Export deterministic VEX evidence for a digest or component.
`stella vex webhooks list\|add\|remove`	Manage VEX webhook subscriptions.
`stella vex gen --from-drift --image <IMAGE>`	Generate VEX statements from facet drift.

Flags (common)

--offline: use cached consensus snapshots; fail with exit code 5 if remote would be hit.
--policy <path>: apply trust/weighting config; aggregation-only outputs.
--page-size, --page-token: deterministic pagination.

Inputs/outputs

Inputs: VEX consensus projection (VexLens); optional cached snapshots when offline.
Outputs: consensus states with consensus_state, confidence, weights, issuers, rationale; stable ordering.

Determinism rules

Sort by consensusId; pagination tokens deterministic.
No verdict inference beyond upstream consensus projection; CLI stays aggregation-only.

Offline/air-gap notes

Cached snapshots are required when --offline; otherwise exit code 5 with remediation message.
Trust roots for signature verification are loaded from STELLA_TRUST_ROOTS when verifying cached snapshots.

stella vex evidence export

Export deterministic VEX evidence for a digest or component identifier.

Usage

stella vex evidence export <target> [--format json|openvex] [--output <path>]

Examples

stella vex evidence export sha256:abc --format json
stella vex evidence export pkg:npm/lodash@4.17.21 --format openvex --output vex-evidence.json

stella vex webhooks

Manage VEX webhook subscriptions.

Usage

stella vex webhooks list --format json
stella vex webhooks add --url <url> --events vex.created vex.updated --format json
stella vex webhooks remove <id> --format json

stella vex gen --from-drift

Sprint: SPRINT_20260105_002_004_CLI

Generate VEX statements from facet drift analysis. This command analyzes drift between a baseline seal and the current image state, then generates OpenVEX documents for facets that require authorization.

Usage

stella vex gen --from-drift --image <IMAGE> [OPTIONS]

Required Options

Option	Alias	Description
`--from-drift`		Enable drift-based VEX generation
`--image <REF>`	`-i`	Image reference or digest to analyze

Optional Options

Option	Alias	Description	Default
`--baseline <ID>`	`-b`	Baseline seal ID for comparison	latest seal
`--output <PATH>`	`-o`	Output file path	stdout
`--format <FMT>`	`-f`	VEX format: `openvex`, `csaf`	`openvex`
`--status <STATUS>`	`-s`	VEX status: `under_investigation`, `not_affected`, `affected`	`under_investigation`
`--verbose`	`-v`	Enable verbose output	`false`

Examples

Generate VEX from drift

stella vex gen --from-drift --image sha256:abc123

Specify baseline seal

stella vex gen --from-drift --image myregistry.io/app:v2.0 --baseline seal-xyz789

Output to file with specific status

stella vex gen --from-drift --image sha256:abc123 \
  --output vex-authorization.json \
  --status not_affected

Output Format (OpenVEX)

{
  "@context": "https://openvex.dev/ns",
  "@id": "https://stellaops.io/vex/abc123-def456",
  "author": "StellaOps CLI",
  "timestamp": "2026-01-05T10:30:00Z",
  "version": 1,
  "statements": [
    {
      "@id": "vex:statement-1",
      "status": "under_investigation",
      "timestamp": "2026-01-05T10:30:00Z",
      "products": [
        {
          "@id": "sha256:abc123...",
          "identifiers": {
            "facet": "runtime"
          }
        }
      ],
      "justification": "Facet drift authorization for runtime. Churn: 15.50% (3 added, 1 removed, 2 modified)",
      "action_statement": "Review required before deployment"
    }
  ]
}

Exit Codes

Code	Description
`0`	Success
`1`	Error or no baseline seal found
`2`	Image resolution failed

Workflow Integration

The vex gen --from-drift command is typically used in a release pipeline:

Build — the container image is built.
Seal — stella seal creates a baseline seal at build time.
Deploy — the release is submitted through the release control plane.
Drift detection — if facet drift exceeds quota, the release is blocked.
VEX generation — stella vex gen --from-drift creates an authorization document.
Review — the security team reviews and signs the VEX.
Retry — with the VEX in place, the release proceeds.

# After a release is blocked due to drift
stella vex gen --from-drift --image $IMAGE_DIGEST \
  --output vex-authorization.json

# Review and sign the VEX document
stella vex sign --input vex-authorization.json --key $SIGNING_KEY

# Ingest the signed VEX
stella vex ingest --input vex-authorization.signed.json

# Retry the release
stella release retry --manifest release.yaml