# VEX Auto-Generation Flow ## Overview The VEX (Vulnerability Exploitability eXchange) Auto-Generation Flow describes how StellaOps assists in creating VEX statements by analyzing reachability data, runtime observations, and historical patterns. This flow combines automated analysis with human review to produce accurate exploitability assessments. **Business Value**: Reduce false positive burden by automatically identifying vulnerabilities that are not exploitable in the specific deployment context. ## Actors | Actor | Type | Role | |-------|------|------| | Security Analyst | Human | Reviews and approves VEX statements | | AdvisoryAI | Service | ML-assisted analysis | | ReachGraph | Service | Provides reachability analysis | | Signals | Service | Provides runtime observations | | VexLens | Service | Stores and distributes VEX | | Scanner | Service | Provides SBOM context | ## Prerequisites - Image scanned with SBOM generated - Reachability analysis completed (optional but recommended) - Runtime signals available (optional) - VEX issuer identity configured ## VEX Statuses | Status | Description | Automation Confidence | |--------|-------------|----------------------| | `not_affected` | Vulnerability not exploitable | High (with evidence) | | `affected` | Vulnerability is exploitable | Medium | | `fixed` | Vulnerability has been remediated | High | | `under_investigation` | Status being determined | N/A | ## Justification Types (OpenVEX) | Justification | Description | |---------------|-------------| | `component_not_present` | Vulnerable component not in product | | `vulnerable_code_not_present` | Specific vulnerable code not included | | `vulnerable_code_not_in_execute_path` | Code present but unreachable | | `vulnerable_code_cannot_be_controlled_by_adversary` | Attack vector blocked | | `inline_mitigations_already_exist` | Compensating controls in place | ## Flow Diagram ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ VEX Auto-Generation Flow │ └─────────────────────────────────────────────────────────────────────────────────┘ ┌─────────┐ ┌───────────┐ ┌───────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ Analyst │ │AdvisoryAI │ │ ReachGraph│ │ Signals │ │ VexLens │ │ Scanner │ └────┬────┘ └─────┬─────┘ └─────┬─────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ │ │ │ │ │ │ Review │ │ │ │ │ │ finding │ │ │ │ │ │────────────>│ │ │ │ │ │ │ │ │ │ │ │ │ Get SBOM │ │ │ │ │ │ context │ │ │ │ │ │────────────────────────────────────────────────────>│ │ │ │ │ │ │ │ │ SBOM + │ │ │ │ │ │ call graph │ │ │ │ │ │<────────────────────────────────────────────────────│ │ │ │ │ │ │ │ │ Query reach │ │ │ │ │ │─────────────>│ │ │ │ │ │ │ │ │ │ │ │ │ Analyze │ │ │ │ │ │ call paths │ │ │ │ │ │───┐ │ │ │ │ │ │ │ │ │ │ │ │ │<──┘ │ │ │ │ │ │ │ │ │ │ │ K4 state + │ │ │ │ │ │ evidence │ │ │ │ │ │<─────────────│ │ │ │ │ │ │ │ │ │ │ │ Query runtime│ │ │ │ │ │─────────────────────────────> │ │ │ │ │ │ │ │ │ │ │ │ Check │ │ │ │ │ │ invocations│ │ │ │ │ │───┐ │ │ │ │ │ │ │ │ │ │ │ │ │<──┘ │ │ │ │ │ │ │ │ │ │ Runtime │ │ │ │ │ │ evidence │ │ │ │ │ │<───────────────────────────── │ │ │ │ │ │ │ │ │ │ Analyze │ │ │ │ │ │ with LLM │ │ │ │ │ │───┐ │ │ │ │ │ │ │ │ │ │ │ │ │<──┘ │ │ │ │ │ │ │ │ │ │ │ VEX draft │ │ │ │ │ │ + confidence│ │ │ │ │ │<────────────│ │ │ │ │ │ │ │ │ │ │ │ [Review] │ │ │ │ │ │ Approve/ │ │ │ │ │ │ Modify │ │ │ │ │ │───┐ │ │ │ │ │ │ │ │ │ │ │ │ │<──┘ │ │ │ │ │ │ │ │ │ │ │ │ Submit VEX │ │ │ │ │ │────────────────────────────────────────────────────────> │ │ │ │ │ │ │ │ │ │ │ │ Store │ │ │ │ │ │ + sign │ │ │ │ │ │───┐ │ │ │ │ │ │ │ │ │ │ │ │ │<──┘ │ │ │ │ │ │ │ │ VEX ID │ │ │ │ │ │<──────────────────────────────────────────────────────── │ │ │ │ │ │ │ ``` ## Step-by-Step ### 1. Finding Review Initiation Analyst selects finding for VEX assessment: ```json { "scan_id": "scan-abc123", "cve": "CVE-2024-1234", "package": "pkg:npm/lodash@4.17.20", "severity": "critical", "current_status": "affected", "request": "assess_exploitability" } ``` ### 2. Context Gathering AdvisoryAI gathers context from multiple sources: #### SBOM Context ```json { "component": { "purl": "pkg:npm/lodash@4.17.20", "locations": ["/app/node_modules/lodash"], "dependents": ["express", "webpack"], "scope": "runtime" }, "call_graph": { "entry_points": ["src/api/handler.js", "src/worker/processor.js"], "functions_imported": ["_.get", "_.merge", "_.template"] } } ``` #### Reachability Analysis ```json { "package": "pkg:npm/lodash@4.17.20", "k4_state": "StaticallyReachable", "vulnerable_function": "_.template", "analysis": { "function_imported": true, "call_sites": 3, "call_paths": [ { "path": ["src/api/handler.js:45", "lib/renderer.js:12", "_.template"], "reachable": true } ] } } ``` #### Runtime Signals ```json { "package": "pkg:npm/lodash@4.17.20", "observation_period": "30d", "signals": { "function_invocations": { "_.get": 15234, "_.merge": 892, "_.template": 0 }, "vulnerable_function_called": false, "last_check": "2024-12-29T10:00:00Z" } } ``` ### 3. AI-Assisted Analysis AdvisoryAI analyzes gathered evidence: ```json { "analysis": { "cve": "CVE-2024-1234", "vulnerable_function": "_.template", "evidence_summary": { "static_reachability": "reachable", "runtime_observation": "never_invoked", "import_analysis": "function_imported_but_not_called", "call_site_analysis": "call site exists but appears to be dead code" }, "recommendation": { "status": "not_affected", "justification": "vulnerable_code_not_in_execute_path", "confidence": 0.85, "reasoning": [ "Vulnerable function _.template is imported but analysis shows:", "1. Static analysis found 3 potential call sites", "2. Runtime signals over 30 days show 0 invocations", "3. Call sites appear to be in deprecated code path", "4. No user-controlled input reaches the function" ] } } } ``` ### 4. VEX Draft Generation AdvisoryAI generates draft VEX statement: ```json { "draft_vex": { "@context": "https://openvex.dev/ns/v0.2.0", "@id": "https://stellaops.local/vex/draft/vex-draft-123", "author": "StellaOps AdvisoryAI", "timestamp": "2024-12-29T10:30:00Z", "version": 1, "statements": [ { "vulnerability": { "@id": "https://nvd.nist.gov/vuln/detail/CVE-2024-1234" }, "products": [ { "@id": "pkg:oci/myorg/app@sha256:abc123", "subcomponents": [ {"@id": "pkg:npm/lodash@4.17.20"} ] } ], "status": "not_affected", "justification": "vulnerable_code_not_in_execute_path", "impact_statement": "The vulnerable _.template function is imported but never invoked. Runtime monitoring over 30 days confirms zero executions." } ] }, "confidence": 0.85, "evidence_refs": [ "reachability:reach-analysis-456", "signals:runtime-obs-789" ], "requires_human_review": true } ``` ### 5. Human Review Analyst reviews draft in Console UI: ``` ┌─────────────────────────────────────────────────────────────────┐ │ VEX Draft Review │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ CVE: CVE-2024-1234 (Critical) │ │ Package: lodash@4.17.20 │ │ Image: docker.io/myorg/app:v1.2.3 │ │ │ │ ┌─ AI Recommendation ──────────────────────────────────────────┐│ │ │ Status: not_affected ││ │ │ Justification: vulnerable_code_not_in_execute_path ││ │ │ Confidence: 85% ││ │ └──────────────────────────────────────────────────────────────┘│ │ │ │ ┌─ Evidence ───────────────────────────────────────────────────┐│ │ │ ✓ Static analysis: 3 potential call sites found ││ │ │ ✓ Runtime (30d): 0 invocations of _.template ││ │ │ ✓ Call graph: paths exist but appear unused ││ │ │ ⚠ Note: Function is imported in production code ││ │ └──────────────────────────────────────────────────────────────┘│ │ │ │ [Approve] [Modify] [Reject] [Request More Analysis] │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 6. VEX Submission After approval, VEX is signed and stored: ```json { "vex_id": "vex-789ghi", "status": "published", "signed_by": "analyst@acme.com", "signature": { "keyid": "sha256:analyst-key-fingerprint", "sig": "base64:signature..." }, "transparency_log": { "rekor_log_index": 12345678, "log_id": "sha256:rekor-log..." } } ``` ## Automation Levels ### Fully Automated (High Confidence) ```yaml vex_automation: auto_approve: - condition: component_not_present confidence_threshold: 0.99 - condition: fixed_version_deployed confidence_threshold: 0.95 ``` ### Semi-Automated (Human Review) ```yaml vex_automation: require_review: - condition: runtime_not_observed confidence_threshold: 0.70 review_timeout: 24h ``` ### Manual Only ```yaml vex_automation: manual_only: - condition: affected - condition: inline_mitigations ``` ## Data Contracts ### VEX Draft Request Schema ```typescript interface VexDraftRequest { scan_id: string; cve: string; package_purl: string; context?: { include_reachability: boolean; include_runtime: boolean; observation_period?: string; // ISO-8601 duration }; } ``` ### VEX Draft Response Schema ```typescript interface VexDraftResponse { draft_id: string; cve: string; product: string; recommended_status: VexStatus; recommended_justification?: VexJustification; confidence: number; evidence: Array<{ type: 'reachability' | 'runtime' | 'code_analysis'; summary: string; ref: string; }>; impact_statement: string; requires_human_review: boolean; expires_at?: string; } ``` ## Confidence Scoring | Evidence Type | Base Confidence | Modifiers | |--------------|-----------------|-----------| | Component not in SBOM | 0.99 | - | | Fixed version confirmed | 0.95 | - | | Runtime never invoked (30d+) | 0.85 | +0.05 per additional 30d | | Static unreachable | 0.70 | +0.10 with runtime confirm | | AI code analysis | 0.60 | Requires human review | | Historical pattern match | 0.50 | Requires human review | ## Error Handling | Error | Recovery | |-------|----------| | Reachability unavailable | Lower confidence, require review | | Runtime signals missing | Use static analysis only | | AI analysis timeout | Fall back to template-based | | Signing failure | Queue for retry | ## Observability ### Metrics | Metric | Type | Labels | |--------|------|--------| | `vex_drafts_generated_total` | Counter | `status`, `justification` | | `vex_drafts_approved_total` | Counter | `auto_approved` | | `vex_confidence_score` | Histogram | `status` | | `vex_review_duration_seconds` | Histogram | `outcome` | ### Key Log Events | Event | Level | Fields | |-------|-------|--------| | `vex.draft.generated` | INFO | `cve`, `status`, `confidence` | | `vex.draft.reviewed` | INFO | `draft_id`, `outcome`, `reviewer` | | `vex.published` | INFO | `vex_id`, `cve`, `status` | ## Related Flows - [Policy Evaluation Flow](04-policy-evaluation-flow.md) - VEX consumption - [Advisory Drift Re-scan Flow](11-advisory-drift-rescan-flow.md) - VEX updates - [Exception Approval Workflow](17-exception-approval-workflow.md) - Related approval pattern