audit work, fixed StellaOps.sln warnings/errors, fixed tests, sprints work, new advisories

docs/modules/cli/guides/commands/vex.md

@@ -1,9 +1,11 @@
-# stella vex — Command Guide
+# 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.
@@ -21,3 +23,126 @@
 ## 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
+
+```bash
+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
+
+```bash
+stella vex gen --from-drift --image sha256:abc123
+```
+
+#### Specify baseline seal
+
+```bash
+stella vex gen --from-drift --image myregistry.io/app:v2.0 --baseline seal-xyz789
+```
+
+#### Output to file with specific status
+
+```bash
+stella vex gen --from-drift --image sha256:abc123 \
+  --output vex-authorization.json \
+  --status not_affected
+```
+
+### Output Format (OpenVEX)
+
+```json
+{
+  "@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
+
+```bash
+# 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](./seal.md)
+- [Facet Drift Analysis](./facet-drift.md)
+- [Admission Webhook Configuration](../admin/admission-webhook.md)