Publish VEX Documents

VEX documents answer the critical question customers ask when vulnerabilities are disclosed: "Does this CVE actually affect MY deployment of YOUR software?" Without VEX, customers face endless scanning false positives, treating every component vulnerability as critical regardless of actual exploitability.

Publishing quality VEX requires understanding vulnerability analysis, communicating effectively, and coordinating with SBOM lifecycle. This workflow transforms reactive vulnerability firefighting into systematic disclosure management.

When to Publish VEX

VEX publication follows different triggers than SBOM generation. While SBOMs align with software releases, VEX aligns with vulnerability discoveries and analysis milestones.

Initial VEX Publication

Publish your first VEX for a vulnerability when:

CVE disclosed affecting your components. Public vulnerability database publishes CVE identifying component you use. Even before completing analysis, publish preliminary VEX with under_investigation status showing customers you're aware and analyzing.

Customer inquiry about vulnerability. Customer contacts asking about specific CVE. If you haven't published VEX yet, this inquiry triggers immediate publication showing responsive security practices.

Internal discovery of unreported vulnerability. Security team identifies vulnerability not yet publicly disclosed. VEX with appropriate confidentiality controls communicates status to customers who need to know.

Regulatory or contractual obligation. Some industries or contracts mandate vulnerability disclosure within specific timeframes. VEX publication demonstrates compliance.

VEX Updates

Update existing VEX when:

Analysis completes. Initial under_investigation status transitions to definitive status: not_affected, affected, or fixed. Update VEX with determination and justification.

Patch released. Software version containing fix releases. Update VEX showing which versions remain vulnerable versus which include fixes.

Workaround identified. Before patch availability, mitigation discovered reducing risk. Update VEX with workaround details enabling customers to reduce exposure.

Exploitability assessment changes. New information reveals vulnerability more or less severe than initially assessed. Update CVSS scores, severity ratings, or justifications accordingly.

Additional versions identified as affected. Initially assessed v1.0.0 only; later discover v2.0.0 also vulnerable. Update VEX expanding scope.

VEX Status Determination

The core VEX element: definitive statement of whether vulnerability affects your product.

Four Required Statuses

under_investigation — Analysis not yet complete, definitive status unknown. Use this immediately upon CVE disclosure while security team analyzes actual impact. Communicates awareness and responsiveness even before conclusions.

Timeline: Publish within 24-48 hours of CVE disclosure for components you use. Delays suggest unresponsive security practices.

not_affected — Vulnerability exists in component but doesn't create exploitable conditions in your product. Requires justification explaining why. This status provides the most value, eliminating false positive alerts that waste customer security team time.

Justifications include:

• Vulnerable code not present (e.g., platform-specific code excluded from your build)
• Vulnerable code not in execute path (e.g., unreachable admin interface)
• Inline mitigations already exist (e.g., input validation preventing exploitation)
• Requires configuration not used in your product
• Requires additional component not present
• Requires runtime environment not applicable

affected — Vulnerability does create exploitable conditions in your product. Triggers customer remediation workflows. Requires communicating severity, impacted versions, and remediation timeline.

Include in affected VEX:

• Severity rating (CVSS score and qualitative assessment)
• Affected version ranges precisely
• Recommended response actions
• Estimated fix timeline if known
• Available workarounds if any

fixed — Vulnerability remediated in specific version(s). Enables customers to verify patch application and prioritize upgrades.

Include in fixed VEX:

• Which versions contain fix
• Which versions remain vulnerable
• Upgrade instructions
• Breaking changes or compatibility notes if relevant

Analysis Workflow

Systematic analysis produces defensible VEX status determinations:

Step 1: Verify component presence Check SBOMs for all supported product versions. Does vulnerable component actually exist in your software? If not, you're not affected—but verify thoroughly. Tools sometimes miss components, and absence of evidence isn't evidence of absence.

Step 2: Identify vulnerable code paths If component present, does your usage trigger vulnerable code? Read CVE details, examine source code if available, test exploitation conditions. Many vulnerabilities require specific API usage or configuration to exploit.

Step 3: Assess realistic exploitability Even if theoretically vulnerable, can attackers practically exploit in your deployment? Consider:

• Is vulnerable functionality exposed to untrusted input?
• Are required preconditions realistic in your use case?
• Do security controls elsewhere mitigate the vulnerability?
• What's actual attacker capability required vs threat model?

Step 4: Determine severity in your context CVE severity reflects general worst-case scenarios. Your actual severity depends on exposure, accessibility, and data sensitivity. Critical CVE in isolated internal component might be low severity for you. Moderate CVE in internet-exposed authentication might be critical.

Step 5: Document justification Record analysis rationale, not just conclusions. Future team members or auditors need to understand the reasoning. "Not affected because vulnerable code path unreachable due to configuration in deployment architecture" is defensible. "Not affected" alone isn't.

VEX Document Structure

Practical VEX document following CycloneDX 1.6 format:

{
  "bomFormat": "CycloneDX",
  "specVersion": "1.6",
  "serialNumber": "urn:uuid:a8b9c1d2-e3f4-5a6b-7c8d-9e0f1a2b3c4d",
  "version": 1,
  "metadata": {
    "timestamp": "2025-02-12T10:00:00Z",
    "component": {
      "name": "acme-application",
      "version": "2.5.0",
      "purl": "pkg:generic/acme-corp/acme-application@2.5.0"
    },
    "supplier": {
      "name": "Acme Corporation",
      "url": ["https://acme.example.com"],
      "contact": [
        {
          "name": "Security Team",
          "email": "security@acme.example.com"
        }
      ]
    }
  },
  "vulnerabilities": [
    {
      "id": "CVE-2025-1234",
      "source": {
        "name": "NVD",
        "url": "https://nvd.nist.gov/vuln/detail/CVE-2025-1234"
      },
      "description": "SQL injection vulnerability in authentication module",
      "recommendation": "Upgrade to version 2.5.1 or apply workaround",
      "ratings": [
        {
          "score": 8.1,
          "severity": "high",
          "method": "CVSSv31",
          "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:N/A:N"
        }
      ],
      "affects": [
        {
          "ref": "pkg:generic/acme-corp/acme-application@2.5.0",
          "versions": [
            { "version": "2.5.0", "status": "affected" },
            { "version": "2.4.0", "status": "affected" },
            { "version": "2.5.1", "status": "unaffected" }
          ]
        }
      ],
      "analysis": {
        "state": "resolved",
        "justification": "code_not_present",
        "response": ["will_not_fix", "update"],
        "detail": "Version 2.5.1 removes vulnerable authentication module. Versions 2.4.x and 2.5.0 should upgrade. Workaround: disable legacy authentication in config by setting auth.legacy=false",
        "firstIssued": "2025-02-10T09:00:00Z",
        "lastUpdated": "2025-02-12T10:00:00Z"
      }
    }
  ]
}

Key elements explained:

serialNumber: Unique VEX document identifier. Remains constant across versions of same VEX.

version: Increments with each update. Version 1 for initial publication, version 2 after first update, etc.

metadata.component: The product this VEX describes. Must match SBOM component identification for correlation.

vulnerabilities[].affects: Precisely which versions affected vs unaffected. Enables automated tooling to determine relevance.

analysis.state: Current status (in_triage, exploitable, resolved, not_affected, etc.)

analysis.justification: Why not affected if that's the determination. Required for not_affected status.

analysis.detail: Free-text explanation providing context beyond structured fields. Critical for human understanding.

Publication Channels

VEX documents reach customers through various channels depending on sensitivity and accessibility requirements.

Public Publication

Host VEX documents on public website alongside SBOMs. Appropriate for open source projects or organizations pursuing maximum transparency.

Implementation:

• HTTPS-accessible URL pattern (e.g., https://security.acme.com/vex/product-name/CVE-2025-1234.json)
• Machine-readable directory listing enabling automated discovery
• RSS/Atom feed for change notifications

Advantages: Immediate customer access, no authentication barriers, demonstrates security maturity publicly.

Risks: Vulnerability windows publicly visible, potential for competitive intelligence gathering, information may aid attackers.

Authenticated Customer Portal

Provide VEX via customer portal requiring authentication. Balance accessibility with controlled distribution.

Implementation:

• Login-protected download area
• API endpoints with API key authentication
• Notification system alerting customers to new VEX publications

Advantages: Known audience, audit trail of who accessed what, ability to provide customer-specific context.

Challenges: Authentication friction may reduce adoption, requires portal infrastructure, access control decisions needed.

Direct Customer Communication

Email VEX directly to affected customers or security contacts. Appropriate for sensitive disclosures or small customer base.

Implementation:

• Security advisory email with VEX attachment
• PGP-encrypted for confidential vulnerabilities
• Tracking to ensure delivery and receipt

Advantages: Ensures customer awareness, enables personalized messaging, suitable for sensitive information.

Challenges: Doesn't scale to large customer bases, requires maintained contact database, no automated discovery.

Coordination with SBOM Lifecycle

VEX and SBOM lifecycles intersect but remain independent. See SBOM and VEX Lifecycle for comprehensive coordination guidance.

When releasing patches:

1. Generate new SBOM for patched version
2. Update VEX showing old versions affected, new version fixed
3. Cross-reference between SBOM and VEX through component identifiers

When publishing VEX for existing versions:

1. Reference existing SBOMs (don't regenerate)
2. Ensure component identifiers in VEX match SBOM component identifiers precisely
3. VEX can reference multiple SBOM versions if vulnerability affects multiple releases

Consistency critical: VEX references to component versions must exactly match SBOM component declarations. Mismatches break automated correlation.

Automation Opportunities

While VEX requires human judgment (vulnerability analysis isn't fully automatable), partial automation improves efficiency and consistency.

Automated draft generation: When CVE published, script generates VEX template with:

• CVE details pulled from NVD API
• Product and version information from SBOM repository
• Status: under_investigation
• Placeholders for analysis details

Security analyst receives pre-populated draft requiring only analysis completion rather than starting from scratch.

Status update workflows: Changes triggering VEX updates (patch releases, analysis completion) automatically create draft updated VEX. Human reviews and approves before publication.

Publication automation: After human approval, VEX automatically published to all configured channels—website, customer portal, notification systems—ensuring consistent multi-channel distribution.

Quality gates: Automated validation ensures required fields present, status justifications provided when needed, component references valid. Prevents publishing incomplete or malformed VEX.

Communication Best Practices

Beyond technical VEX structure, effective communication enhances customer trust.

Timeliness: Publish initial under_investigation VEX within 24-48 hours of CVE disclosure. Extended silence suggests unresponsive security.

Transparency: When affected, communicate clearly. Downplaying severity or obfuscating impact damages trust more than honest disclosure.

Specificity: Vague statements like "customers should update" help little. Specific version ranges, precise workarounds, realistic timelines enable action.

Updates: When status changes, update VEX and notify customers. Don't leave them waiting indefinitely after under_investigation.

Accessibility: Make VEX easily findable. Customers shouldn't need to contact support to learn vulnerability status. Self-service access scales better and demonstrates transparency.

Measuring VEX Effectiveness

Track metrics demonstrating VEX program value:

Time to Initial VEX: Hours from CVE disclosure to first VEX publication. Target: under 48 hours for components you use.

Time to Definitive Status: Days from CVE disclosure to not_affected, affected, or fixed determination. Target: under 7 days for high severity, under 14 days for moderate.

False Positive Reduction: Customer inquiries about vulnerabilities you've already VEX'd as not_affected. Should decrease as customers adopt VEX consumption.

Customer Satisfaction: Survey customers about VEX usefulness. Measures whether effort translates to customer value.

Common VEX Mistakes

Mistake 1: Only publishing VEX for "not affected" determinations Organizations sometimes publish VEX only when they can say "you're safe." When affected, they go silent hoping customers won't notice. This destroys trust and defeats VEX purpose.

Solution: Publish VEX for all determinations. affected status with clear communication builds more trust than silence that customers interpret as hiding bad news.

Mistake 2: Insufficient justification for "not affected" Claiming not_affected without clear justification invites skepticism. Customers can't verify claims, so they may treat as affected anyway.

Solution: Provide detailed justification referencing specific code paths, configurations, or architectural decisions. Make claims verifiable.

Mistake 3: Overly optimistic severity assessments Downgrading CVE severity to reduce customer alarm. Customers compare your assessment to public CVE severity, notice discrepancies, lose trust in your analysis.

Solution: Use honest severity assessments. If CVE is critical, say so. Then clearly communicate remediation plan and timeline.

Mistake 4: Stale VEX after patch release Releasing patch that fixes vulnerability but forgetting to update VEX showing fixed status. Customers don't know patch exists or which version to upgrade to.

Solution: Automate VEX update triggers for software releases. When version releases, review all relevant VEX documents for updates.

Next Steps

• Understand when to update in SBOM and VEX Lifecycle
• Respond to disclosures systematically via Handle Vulnerability Disclosures
• Enable customer consumption through Consumer Workflows
• Apply VEX to Use Case - Vulnerability Management