How to Diff a VEX Document Claim by Claim

Diffing a VEX document claim by claim means comparing two versions of a Vulnerability Exploitability eXchange (VEX) document at the level of each product and vulnerability statement, rather than treating the files as undifferentiated text. This helps you spot changed status, justification, impact, and version scope while avoiding false alarms caused by formatting or ordering differences. You will need both document versions and a way to inspect their contents as structured JSON or in a VEX-aware tool.

What You’ll Need

• The earlier and later VEX documents, saved separately and identified by version or date.
• A text editor or JSON-aware diff tool. A VEX viewer or script that understands your document format can make the comparison easier.
• Knowledge of the VEX format used. Common formats include CSAF and OpenVEX; their field names and structures differ.
• The related product and vulnerability identifiers, if you need to verify whether a changed claim is accurate.

Step-by-Step

1. Keep the originals and confirm the pair. Make read-only copies of both files and record which is older. Check filenames, publication dates, document identifiers, and revision metadata where available. Do not assume the file with the newer timestamp is the newer VEX; files can be copied or regenerated without changing their claims.
2. Check that both files can be parsed. Open each in a format-aware viewer or validate it against the relevant schema or specification. Confirm that each document is complete and that you are comparing the same VEX format and compatible versions. If one file is malformed, repair or obtain a valid source before interpreting a diff.
3. Normalize presentation, not meaning. If using a text diff, format JSON consistently and remove irrelevant differences such as whitespace, indentation, or key ordering. Do not discard fields or rewrite identifiers just to make the files look alike. Preserve the originals so you can verify any transformation.
4. Build a claim key for matching. Match claims using the vulnerability identifier and the affected product identity or product identifier. Include version or product-status scope when the format expresses it. A vulnerability alone is not a sufficient key: one document may make different claims for different products or versions. If a claim cannot be matched confidently, mark it as added or removed for review rather than pairing it by position.
5. Compare the claim set first. List claims present in both documents, claims added in the newer document, and claims removed from it. Check for duplicate claims, changed product identifiers, and altered version ranges. A removed claim is not automatically a resolved vulnerability; it may indicate a scope change, restructuring, or an incomplete update.
6. Compare each matched claim field by field. Record old and new values for status, justification, impact statement, and any explanation or action recommended to users. Depending on the format, a status may be expressed as affected, not affected, fixed, or under investigation. Compare only fields that exist in the relevant format, and distinguish a substantive change from a wording or formatting edit.
7. Check scope and supporting detail. Review product versions, platforms, components, and any status-specific justification or response detail. For example, “not affected” for one version does not imply the product is unaffected across all versions. Ensure that supporting text still describes the stated status and that references or notes have not been detached from the claim.
8. Review document-level changes separately. Compare publisher, document tracking and revision information, timestamps, and acknowledgments separately from claim changes. These fields provide context but are not themselves proof that a claim changed or that a new assessment is more accurate.
9. Validate consequential changes with the source. For a status or scope change that could affect decisions, check the supplier’s release notes, security advisory, or other authoritative supporting material. Confirm that the product and version in that material match the VEX claim. A diff identifies changes; it does not establish whether the revised assessment is correct.
10. Save a reviewable report. Record the claim key, changed field, previous value, new value, and reviewer notes. Include the source filenames and comparison date. Keep the report distinct from the VEX itself, and do not edit the published document merely to make the comparison easier to read.

Common Mistakes

• Using a raw line diff as the conclusion. JSON key order, whitespace, or reordered arrays can create a large-looking diff without changing claims.
• Matching by row or list position. Claims may be reordered between revisions. Match by vulnerability and product identity, then check version scope.
• Ignoring version ranges. A status can change for one release while remaining unchanged for others. Record the precise scope.
• Treating absence as a status. A missing claim does not mean “not affected,” “fixed,” or “under investigation.” Report it as removed or absent until its meaning is confirmed.
• Conflating document metadata with assessment changes. A new revision date may accompany no claim changes, while a substantive change can be easy to miss in a small text diff.
• Assuming a changed claim is correct. The comparison shows what differs, not whether evidence supports the new value.

Tips

• Use a table with one row per matched claim and separate columns for product, vulnerability, version scope, old status, new status, and notes.
• Keep “added,” “removed,” and “changed” as distinct categories. This makes gaps and scope changes easier to discuss.
• When comparing repeated releases, retain prior reports so reviewers can trace how a claim evolved.
• Quote or link to the exact field and source location when raising a question. This avoids ambiguity when a document contains many claims.
• For automated comparisons, test the matching rules on a small set of known examples and have a person review ambiguous matches.

Troubleshooting

The files look completely different. First check whether they use different formats or schema versions. If they are compatible JSON documents, reformat them consistently before diffing; do not convert formats unless you can verify that the conversion preserves claim meaning.

The tool reports every claim as new or removed. Your matching key may use fields that changed, or the documents may identify products differently. Inspect product identifiers and version scope manually, then adjust matching carefully. Avoid matching solely on vulnerability ID where multiple products are present.

A claim appears to have changed status but not scope. Compare the surrounding product and version fields in both originals. Some formats express scope in nested structures, so a simplified export may hide a change. Recheck the parsed source before recording a status-only change.

You cannot open or validate a file. Confirm that it was not truncated, saved with the wrong encoding, or given the wrong extension. Obtain a clean copy from its publisher if necessary. Do not infer claims from a partial document.

The change has no explanation. Record the exact difference and request clarification from the document publisher or consult its linked advisory. Do not fill in missing rationale by assumption.

Frequently Asked Questions

What does “diff a VEX document” mean?
It means comparing two VEX revisions to identify added, removed, or changed vulnerability claims, including their product and version scope.

Can I use a normal text diff tool?
Yes, for an initial comparison, especially after consistent formatting. For reliable claim-level results, use structured comparison or manually group fields by product and vulnerability.

Should I compare the whole document or only status?
Compare the whole claim. Status, scope, justification, impact, and explanatory details can all affect how the statement should be understood.

Does a removed claim mean the vulnerability is fixed?
No. Removal only shows that the claim is absent from the newer document. Check the publisher’s explanation or supporting advisory.

What if product identifiers differ between versions?
Check whether the identifiers refer to the same product and release range using the publisher’s documentation. Mark uncertain matches for review rather than silently merging them.

Can a diff tell me which VEX document is correct?
No. It identifies differences. Assessing correctness requires checking the evidence and authoritative information behind the claim.

Related

• Kva to Mva Calculator: Convert kVA to MVA
• mEq to mL Calculator: Convert Using Concentration
• Samsung Smart TV Firmware Update: Step-by-Step Guide