restructure VEX documentation into dedicated how-to-guides section by refoo0 · Pull Request #228 · l3montree-dev/devguard-documentation

refoo0 · 2026-08-03T09:09:50Z

No description provided.

Signed-off-by: rafi <refaei.shikho@hotmail.com>

timbastin · 2026-08-04T16:53:05Z

+## What is CSAF?

-**Affected**: Vulnerability impacts your application, requires remediation.
+<Tooltip><TooltipTrigger asChild><span className="underline decoration-dotted decoration-yellow-400 decoration-1 underline-offset-4 cursor-pointer">CSAF</span></TooltipTrigger><TooltipContent><p>Common Security Advisory Framework - Machine-readable security advisories</p></TooltipContent></Tooltip> (Common


I think we can use dwts glossary feature right here

timbastin · 2026-08-04T16:53:11Z

-**Without VEX**: Customers see scan results and assume you're vulnerable. You repeatedly explain why specific CVEs don't affect you.
-
-**With VEX**: Publish machine-readable assessments stating which vulnerabilities affect your product and which don't, with justifications. Customers' tools automatically consume this, eliminating redundant analysis.
+<Tooltip><TooltipTrigger asChild><span className="underline decoration-dotted decoration-yellow-400 decoration-1 underline-offset-4 cursor-pointer">VEX</span></TooltipTrigger><TooltipContent><p>Vulnerability Exploitability eXchange - Vulnerability impact assessments</p></TooltipContent></Tooltip> is a


I think we can use dwts glossary feature right here

timbastin · 2026-08-04T16:53:52Z

+distinguishes them, so you can choose what to publish and know what to expect when consuming someone else's.

-### VEX States
+If you have not yet met the concept, start with


I think at least a brief sentence about the concept would be great. Sharing vulnerability assessments

timbastin · 2026-08-04T16:54:29Z


-**Affected**: Vulnerability impacts your application, requires remediation.
+<Tooltip><TooltipTrigger asChild><span className="underline decoration-dotted decoration-yellow-400 decoration-1 underline-offset-4 cursor-pointer">CSAF</span></TooltipTrigger><TooltipContent><p>Common Security Advisory Framework - Machine-readable security advisories</p></TooltipContent></Tooltip> (Common
+Security Advisory Framework)[^1] is an OASIS standard for machine-readable security advisories. Where earlier


Answer the question, what a security advisory even is. Just a single sentence.

timbastin · 2026-08-04T16:55:36Z

+can process an advisory without a human reading it.

-**Fixed**: Vulnerability remediated through patching or other action.
+CSAF is broader than VEX. A CSAF document consists of:


I think we need a clear distinction right here. CSAF in general is about sharing advisories. There is a special csaf profile, which allows you to share vex in formation as well. Those are two distinct types in the csaf space

timbastin · 2026-08-04T16:59:50Z

+### CycloneDX VEX is component-centric

-Details vulnerabilities at component level using <Tooltip><TooltipTrigger asChild><span className="underline decoration-dotted decoration-yellow-400 decoration-1 underline-offset-4 cursor-pointer">PURL</span></TooltipTrigger><TooltipContent><p>Package URL - Standardized package identifier</p></TooltipContent></Tooltip> (Package URL).
+CycloneDX attaches the assessment to the component itself, inside the SBOM structure.


Elaborate a bit. It's a json file as well - same like csaf. Just a different structure. Used a lot as a format when exchanging vulnerabilities...

timbastin · 2026-08-04T17:00:40Z

-**CSAF VEX**: Complex supply chains needing detailed product structure. Ideal for regulated industries.
+This is simpler and more widely supported, but the <Tooltip><TooltipTrigger asChild><span className="underline decoration-dotted decoration-yellow-400 decoration-1 underline-offset-4 cursor-pointer">PURL</span></TooltipTrigger><TooltipContent><p>Package URL - Standardized package identifier</p></TooltipContent></Tooltip> is the whole
+identity — there is no way to say "affected via one path, not affected via another". Where DevGuard holds two
+different decisions for one component, the CycloneDX export collapses them and keeps the more severe state.


What does that mean?

timbastin · 2026-08-04T17:02:17Z

+### OpenVEX is minimal

-## DevGuard Support
+OpenVEX carries statements as a flat list, designed to be small and embeddable anywhere. DevGuard's OpenVEX


There are product and subcomponents as well in OpenVeX. In terms of functionality and information expressiveness cyclonedx and OpenVeX are pretty equal. But I can send an SBOM using cyclonedx, I can't do that using OpenVeX

timbastin · 2026-08-04T17:02:41Z


-## DevGuard Support
+OpenVEX carries statements as a flat list, designed to be small and embeddable anywhere. DevGuard's OpenVEX
+export is repository-level: each statement names the product as a whole rather than individual components.


That's wrong

timbastin · 2026-08-04T17:03:53Z

+## The point of publishing any of them

-**Supply Chain Automation**: Suppliers publish → You consume → Customers consume yours → Eliminates redundant analysis.
+**Without VEX**, customers see your scan results and assume you are vulnerable. You answer the same


That is like the motivation. We should start with that

timbastin · 2026-08-04T17:36:41Z

I did not finished the review yet

timbastin · 2026-08-05T07:27:09Z

 **Use Cases**: Reduce false positives, communicate actual exploitability, eliminate redundant analysis.

-**DevGuard**: Document Not Affected assessments, publish VEX endpoints, consume supplier VEX.
+**DevGuard**: Document Not Affected assessments, publish all three formats from the same decisions, consume supplier VEX and CSAF as rules.


We can link to vex rules here

timbastin · 2026-08-05T07:28:50Z

-# Vulnerability Mitigation Strategies & VEX Rules
+# Vulnerability Mitigation Strategies

 Discovering vulnerabilities is only the first step—the critical question is how to respond. Not every vulnerability requires immediate patching, and understanding your response options enables efficient resource allocation while maintaining security posture. DevGuard supports four distinct mitigation strategies based on the <Tooltip><TooltipTrigger asChild><span className="underline decoration-dotted decoration-yellow-400 decoration-1 underline-offset-4 cursor-pointer">VEX</span></TooltipTrigger><TooltipContent><p>Vulnerability Exploitability eXchange - A standard format for communicating vulnerability impact assessments</p></TooltipContent></Tooltip> standard[^1] and provides **VEX Rules** to automate these strategies at scale.


We can Link to the vex pages here.

timbastin · 2026-08-05T07:32:36Z

-### Rule Sources
-
-VEX rules can enter DevGuard through three paths:
+Rules reach DevGuard three ways: written by hand in the web UI or over the API, generated from a VEX document you upload, or synced from an upstream supplier's URL. Rules from external sources can be held back for manual review by enabling **Paranoid Mode** on the repository.


We can tell here, that devguard syncs official upstream vex source. Currently it's only the rancher vex hub but feel free to open a ticket if you know a vex source which should be part of devguard official vex rule database.

Add here, that official vex rules are distributed using the vulnerability database distribution mechanism. And they are recommended to you if they match a vulnerability part of your software.

timbastin · 2026-08-05T07:34:01Z


 <Callout type="warning" emoji="⚠️">
-    When creating VEX rules intended for sharing, choose your path pattern carefully. A pattern scoped to your specific application protects your project but doesn't help others. A pattern scoped to the library itself benefits the entire ecosystem—but requires deeper analysis to justify.
+    When creating VEX rules intended for sharing, scope the path carefully. A path scoped to your specific application protects your project but doesn't help others. A path scoped to the library itself benefits the entire ecosystem—but requires deeper analysis to justify.


timbastin · 2026-08-05T07:40:51Z

@@ -0,0 +1,202 @@
+---
+title: CEL Expression Reference for VEX Rules


I think we should move this file to the reference directory

timbastin · 2026-08-05T07:48:52Z

+  the URLs stable once you have handed them to customers.
+</Callout>
+
+Published CycloneDX documents reference each other: the VEX links to the SBOM and to the dashboard, so a


After enabling publish vulnerability assessment sharing the downloaded vex and SBOMs will include those urls as well for consumers as always up to date reference.

timbastin · 2026-08-05T07:49:41Z

+| Open / untriaged | `in_triage` | `under_investigation` | `under_investigation` |
+| False positive | `false_positive` | `not_affected` | `known_not_affected` + a `flags` label |
+| Accepted risk | `exploitable` + `will_not_fix` | `affected` | `known_affected` + `no_fix_planned` |
+| Fixed | `exploitable` + `update` | `fixed` | `fixed` |


I just removed that yesterday - wasn't really obvious for users. Let's just delete this table row

timbastin · 2026-08-05T07:52:06Z

+
+Use this when a supplier publishes VEX continuously. You configure the URL once and DevGuard re-syncs it.
+
+1. On the **VEX Rules** page, expand **Upstream VEX sources** and click **Add source** (or use


Would be great to have some end to end test here

timbastin · 2026-08-05T07:53:36Z

+| **CSAF** | `known_affected` with a `no_fix_planned` remediation | Accepted risk |
+| **CSAF** | `known_affected` without that remediation, `fixed`, `under_investigation` | *ignored* |
+| **CycloneDX** | `false_positive`, `not_affected` | False positive |
+| **CycloneDX** | `exploitable` + response `will_not_fix` | Accepted risk |


I think we don't do that

timbastin · 2026-08-05T09:28:22Z

I think we should merge this with the vex index page. What do you think?

…m/typescript/announcing-typescript-7-0/#running-side-by-side-with-typescript-6.0

…ixes links

restructure VEX documentation into dedicated how-to-guides section

7e7a556

Signed-off-by: rafi <refaei.shikho@hotmail.com>

timbastin reviewed Aug 4, 2026

View reviewed changes

timbastin requested changes Aug 5, 2026

View reviewed changes

timbastin added 11 commits August 5, 2026 12:05

Merge branch 'main' into restructure-vex-documentation

d884635

pr comments, abbreviations.yaml and update deps

635ea76

fixes seo check, updates glossary

cea1d43

resolves merge conflicts

947bd3d

fixes eslint installation by following: https://devblogs.microsoft.co…

efad866

…m/typescript/announcing-typescript-7-0/#running-side-by-side-with-typescript-6.0

fixing nextjs installation and eslint, fixes according to prettier, f…

355a37c

…ixes links

lychee not allowed to fail

dd85258

ignoring sites which block bots

48b20c9

moves patch package to deps

201e941

more on ignore list

624d201

removes ignores and allowing error

f544238

timbastin merged commit f544238 into main Aug 5, 2026
5 of 7 checks passed

timbastin deleted the restructure-vex-documentation branch August 5, 2026 13:04

		@@ -0,0 +1,202 @@
		---
		title: CEL Expression Reference for VEX Rules


		Use this when a supplier publishes VEX continuously. You configure the URL once and DevGuard re-syncs it.

		1. On the VEX Rules page, expand Upstream VEX sources and click Add source (or use

Uh oh!

Conversation

refoo0 commented Aug 3, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

timbastin commented Aug 4, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants