From 87c3b1b9f4f21ff4581348d1372dab385d729e3a Mon Sep 17 00:00:00 2001 From: Fahed Dorgaa Date: Wed, 23 Sep 2026 10:57:52 +0200 Subject: [PATCH 1/2] Add tutorial for rating findings in context Signed-off-by: Fahed Dorgaa --- docs/tutorials/.pages | 1 + docs/tutorials/rating-a-finding-in-context.md | 184 ++++++++++++++++++ 2 files changed, 185 insertions(+) create mode 100644 docs/tutorials/rating-a-finding-in-context.md diff --git a/docs/tutorials/.pages b/docs/tutorials/.pages index ab9690ab..83c6bc06 100644 --- a/docs/tutorials/.pages +++ b/docs/tutorials/.pages @@ -4,5 +4,6 @@ nav: - quickstart.md - creating-a-component-policy.md - setting-up-notifications.md + - rating-a-finding-in-context.md - rehearsing-the-v4-migration.md - ... diff --git a/docs/tutorials/rating-a-finding-in-context.md b/docs/tutorials/rating-a-finding-in-context.md new file mode 100644 index 00000000..af5111f1 --- /dev/null +++ b/docs/tutorials/rating-a-finding-in-context.md @@ -0,0 +1,184 @@ +# Rating a finding in context + +In this tutorial, we will give one vulnerability two different OWASP risk ratings in two projects, +and watch each rating land on its finding. + +Severity comes from the vulnerability and says nothing about where we run the affected component. +A VEX can carry an [OWASP risk rating](https://owasp.org/www-community/OWASP_Risk_Rating_Methodology) +instead of an analysis decision, so the same component can be risky in one deployment and harmless +in another. We will write one document for an internet-facing service and one for a nightly batch +job. + +## What we need + +- A running Dependency-Track stack from the [Quick start](quickstart.md), version 5.1.0 or later. +- The `PORTFOLIO_MANAGEMENT`, `BOM_UPLOAD`, `VULNERABILITY_MANAGEMENT`, `VULNERABILITY_ANALYSIS`, + `VIEW_PORTFOLIO`, and `VIEW_VULNERABILITY` [permissions](../reference/permissions.md). + The `admin` account has all six. + +We will build everything else as we go, so we do not have to wait for a vulnerability mirror. + +## Creating the two projects + +We open **Projects**, select **Create Project**, and create `checkout-api` with version `1.0.0`. +We repeat this for `nightly-report`, also version `1.0.0`. + +Both projects will hold the same component, and only the risk we record differs. + +## Uploading the same BOM to both projects + +```json title="billing.cdx.json" linenums="1" +{ + "bomFormat": "CycloneDX", + "specVersion": "1.6", + "version": 1, + "components": [ + { + "bom-ref": "billing-lib@1.4.2", + "type": "library", + "group": "com.example", + "name": "billing-lib", + "version": "1.4.2", + "purl": "pkg:maven/com.example/billing-lib@1.4.2" + } + ] +} +``` + +We open `checkout-api`, switch to the **Components** tab, select **Upload BOM**, and choose the +file. We do the same for `nightly-report`. Each project now holds one component and no findings. + +## Creating a vulnerability that affects the component + +We need a finding to rate, and we write the vulnerability ourselves so that this tutorial produces +the same result on every instance. + +We open **Vulnerabilities** and select **Create Vulnerability**: + +| Field | Value | +|------------------|---------------------------------------------| +| Vulnerability ID | `INT-BILLING-0001` | +| Title | `Incorrect pattern matching in billing-lib` | +| Severity | `Medium` | + +On the **Affected Components** tab, we select the **+** icon and enter: + +| Field | Value | +|-----------------|---------------------------------------------| +| Identifier Type | `Package URL (PURL)` | +| Identifier | `pkg:maven/com.example/billing-lib@1.4.2` | +| Version Type | `Exact` | + +The version travels inside the PURL. Dependency-Track drops a PURL it cannot parse without +reporting an error, so the identifier has to match what the BOM declares. + +After saving, we return to each project and select **Reanalyze** on the **Audit Vulnerabilities** +tab. Within a few seconds both projects show one finding for `INT-BILLING-0001`, each with severity +*Medium*. We refresh the tab if the finding has not appeared yet. + +Both projects carry the same severity, which our two documents will now qualify. + +## Writing the two VEX documents + +Each document names the vulnerability and points at the product as a whole, so `affects[].ref` +carries the `bom-ref` of `metadata.component`. See +[About VEX](../concepts/vex.md#what-an-import-changes) for what an import can and cannot change. + +```json title="vex-checkout-api.json" linenums="1" +{ + "bomFormat": "CycloneDX", + "specVersion": "1.6", + "version": 1, + "metadata": { + "component": { + "bom-ref": "product", + "type": "application", + "name": "checkout-api", + "version": "1.0.0" + } + }, + "vulnerabilities": [ + { + "id": "INT-BILLING-0001", + "source": { "name": "INTERNAL" }, + "ratings": [ + { + "method": "OWASP", + "vector": "OWASP/SL:9/M:9/O:9/S:9/ED:9/EE:9/A:9/ID:9/LC:7/LI:7/LAV:7/LAC:7/FD:7/RD:7/NC:7/PV:7", + "score": 63.0 + } + ], + "affects": [{ "ref": "product" }] + } + ] +} +``` + +The first eight factors describe how likely an attack is and the last eight what it costs us, and +the score is those two averages multiplied, out of 81. `checkout-api` takes traffic from the +internet and handles payments, so both halves run high. + +Only the rating changes in the second document. The product name follows the project it describes, +but `metadata.component` never selects the target: the upload does. + +```json title="vex-nightly-report.json" linenums="1" +{ + "bomFormat": "CycloneDX", + "specVersion": "1.6", + "version": 1, + "metadata": { + "component": { + "bom-ref": "product", + "type": "application", + "name": "nightly-report", + "version": "1.0.0" + } + }, + "vulnerabilities": [ + { + "id": "INT-BILLING-0001", + "source": { "name": "INTERNAL" }, + "ratings": [ + { + "method": "OWASP", + "vector": "OWASP/SL:1/M:1/O:0/S:2/ED:1/EE:1/A:1/ID:1/LC:2/LI:1/LAV:1/LAC:1/FD:1/RD:1/NC:2/PV:3", + "score": 1.5 + } + ], + "affects": [{ "ref": "product" }] + } + ] +} +``` + +Neither document carries an `analysis` object, and a rating with `method: OWASP` is enough on its +own. + +## Applying each document to its project + +We open `checkout-api`, select **Apply VEX**, choose `vex-checkout-api.json`, and select +**Upload**. We repeat this on `nightly-report` with `vex-nightly-report.json`. + +## Comparing the results + +We open the finding for `INT-BILLING-0001` in `checkout-api` and expand it. A field labeled +**OWASP RR Vector** now holds the vector we sent. The **Audit Trail** records both values: + +```text linenums="1" +OWASP Vector: (None) → OWASP/SL:9/M:9/O:9/S:9/ED:9/EE:9/A:9/ID:9/LC:7/LI:7/LAV:7/LAC:7/FD:7/RD:7/NC:7/PV:7 +OWASP Score: (None) → 63.0 +``` + +The same finding in `nightly-report` carries the other vector, and a score of `1.5`. + +One vulnerability, one component, two deployments, two ratings. The severity stayed *Medium* in +both projects: an imported rating sits beside the severity rather than replacing it. + +## What's next + +- [Exchanging VEX documents](../guides/user/exchanging-vex-documents.md): export decisions, and + target individual components rather than the product. +- [VEX and VDR documents](../reference/vex-and-vdr.md#import): the rules an import follows, and why + it skips an entry. +- [Community integrations](../reference/community-integrations.md): tools that produce these + documents for you. From 4d80d2b1c57db3fab5e2923202668c2fb32668f7 Mon Sep 17 00:00:00 2001 From: Fahed Dorgaa Date: Wed, 23 Sep 2026 12:47:11 +0200 Subject: [PATCH 2/2] List vens under community integrations Signed-off-by: Fahed Dorgaa --- .vale/styles/config/vocabularies/DependencyTrack/accept.txt | 1 + docs/reference/community-integrations.md | 1 + 2 files changed, 2 insertions(+) diff --git a/.vale/styles/config/vocabularies/DependencyTrack/accept.txt b/.vale/styles/config/vocabularies/DependencyTrack/accept.txt index c8c452e7..ab9a8043 100644 --- a/.vale/styles/config/vocabularies/DependencyTrack/accept.txt +++ b/.vale/styles/config/vocabularies/DependencyTrack/accept.txt @@ -192,5 +192,6 @@ subpath timestamptz truststore userinfo +vens walkthroughs? zstd diff --git a/docs/reference/community-integrations.md b/docs/reference/community-integrations.md index 3aa4fb35..354b1ce8 100644 --- a/docs/reference/community-integrations.md +++ b/docs/reference/community-integrations.md @@ -42,6 +42,7 @@ own tools and automation scripts. |:-----|:------------|:-----| | SecObserve | Dependency-Track integration | [GitHub](https://github.com/MaibornWolff/SecObserve) | | SD Elements (Security Compass) | Dependency-Track integration | [securitycompass.com](https://securitycompass.com) | +| vens | Writes OWASP risk ratings into a VEX for import | [GitHub](https://github.com/venslabs/vens) | ## Reporting and Auditing