git.stella-ops.org/docs/modules/cli/guides/commands/vex.md

stella vex - Command Guide

Commands

• stella vex consensus --query <filter> [--output json|ndjson|table] [--offline]
• stella vex get --id <consensusId> [--offline]
• stella vex simulate --input <vexDocs> --policy <policyConfig> [--offline]
• stella vex gen --from-drift --image <IMAGE> [--baseline <SEAL_ID>] [--output <PATH>]

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 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 deployment pipeline:

1. Build: Container image is built
2. Seal: stella seal creates baseline seal at build time
3. Deploy: Deployment triggers admission webhook
4. Drift Detection: If drift exceeds quota, deployment is blocked
5. VEX Generation: stella vex gen --from-drift creates authorization document
6. Review: Security team reviews and signs VEX
7. Retry Deploy: With VEX in place, deployment proceeds

# After deployment 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 deployment (webhook will now accept)
kubectl apply -f deployment.yaml

Related Documentation

• Facet Seal Command
• Facet Drift Analysis
• Admission Webhook Configuration