diff --git a/content/faq/how-do-i-use-vex.md b/content/faq/how-do-i-use-vex.md index 8451234..6167cf1 100644 --- a/content/faq/how-do-i-use-vex.md +++ b/content/faq/how-do-i-use-vex.md @@ -1,8 +1,8 @@ --- title: "How do I use VEX with sbomify?" description: "Learn how Vulnerability Exploitability eXchange (VEX) lets you communicate which vulnerabilities actually affect your product, and how to upload, triage, and distribute VEX documents through sbomify." -answer: "A VEX document tells consumers which vulnerabilities in your SBOM are actually exploitable in your product and which are not. sbomify ingests CycloneDX VEX, OpenVEX, and CSAF 2.0 VEX, applies your statements to OSV and Dependency Track findings so noise is suppressed, and publishes the VEX alongside your SBOMs in your Trust Center. You can also triage vulnerabilities directly in sbomify and generate a VEX from your decisions." -tldr: "VEX is the companion to your SBOM that says \"this CVE is in our dependency tree but it does not actually affect our product, here is why.\" sbomify accepts VEX in CycloneDX, OpenVEX, and CSAF 2.0 formats, suppresses VEX'd findings in your vulnerability results, flags CISA KEV entries, and shares VEX next to SBOMs in the Trust Center." +answer: "A VEX document tells consumers which vulnerabilities in your SBOM are actually exploitable in your product and which are not. sbomify ingests CycloneDX VEX, OpenVEX, and CSAF 2.0 VEX, applies your statements to OSV and Dependency Track findings so noise is suppressed, and publishes the VEX alongside your SBOMs in your Trust Center. You can also triage vulnerabilities directly in sbomify, generate a VEX from your decisions, and have sbomify flag statements that have gone stale or High and Critical findings that no statement covers." +tldr: "VEX is the companion to your SBOM that says \"this CVE is in our dependency tree but it does not actually affect our product, here is why.\" sbomify accepts VEX in CycloneDX, OpenVEX, and CSAF 2.0 formats, suppresses VEX'd findings in your vulnerability results, flags CISA KEV entries, shares VEX next to SBOMs in the Trust Center, and runs scheduled drift detection so stale statements and uncovered High/Critical findings do not go unnoticed." weight: 67 keywords: [VEX, CycloneDX VEX, OpenVEX, CSAF VEX, vulnerability exploitability, SBOM VEX, vulnerability triage, CISA KEV, false positive, CRA VEX] url: /faq/how-do-i-use-vex/ @@ -133,10 +133,21 @@ You do not have to author VEX by hand or in an external tool. sbomify has an in- - **In-app triage.** Review scanner findings on the vulnerability dashboard, record `not_affected` decisions with justifications, apply bulk decisions across CVEs, and preview the effect with a dry run before committing. - **CISA KEV flags.** Findings that appear in the CISA Known Exploited Vulnerabilities catalog are flagged so you triage the vulnerabilities that attackers actually use first. - **Self-VEX generation.** sbomify generates a CycloneDX VEX from your triage decisions, complete with CISA tracking fields (serial number and statement timestamps), so your published VEX always matches your ledger. -- **Dependency Track sync.** If Dependency Track is your triage system of record, sbomify syncs your DT analysis decisions in as VEX and pins them to the matching releases. +- **Dependency Track sync.** If Dependency Track is your triage system of record, opt in and sbomify syncs your DT analysis decisions in as VEX, pinning them to the matching releases so you do not triage the same finding twice. Alternatively, keep a source-controlled `vex/` directory in the same repo that produces the SBOM, merge the per-CVE statements in CI, and upload the result alongside the SBOM. Pull requests on `vex/` carry the audit trail. +## Keeping your statements current + +A VEX statement is a claim about a specific version of your product, and claims expire. The vulnerable code path you ruled unreachable last quarter may be reachable after a refactor, and a new release can pull in High or Critical findings that no existing statement covers. Left alone, a stale `not_affected` is worse than no VEX at all: it tells your customers you have assessed something you have not. + +sbomify checks for this on a schedule and tells you when your VEX has drifted away from reality: + +- **Stale statements.** Statements that no longer match the findings on your current release are surfaced rather than silently carried forward. +- **Uncovered High and Critical findings.** New findings at High or Critical severity with no VEX statement covering them are flagged, so the gap between "scanned" and "assessed" does not quietly widen between releases. + +This runs without configuration. The point is that VEX becomes something you can rely on for audit and customer questions, instead of a document that was accurate on the day it was written. + ## Signing your VEX A VEX is a security-relevant claim about your product. Sign it with the same machinery you use to [sign your SBOM](/faq/how-do-i-sign-an-sbom/) - typically `actions/attest-build-provenance` against the VEX file path - so consumers can verify the VEX came from your CI pipeline and was not modified in transit. Without a signature, a VEX is only as trustworthy as the channel that delivered it. diff --git a/content/faq/how-does-sbomify-count-vulnerabilities.md b/content/faq/how-does-sbomify-count-vulnerabilities.md new file mode 100644 index 0000000..c01d5a3 --- /dev/null +++ b/content/faq/how-does-sbomify-count-vulnerabilities.md @@ -0,0 +1,43 @@ +--- +title: "How does sbomify count vulnerabilities?" +description: "sbomify counts vulnerabilities against your current posture - the latest artifact per component and format - not by summing findings across every SBOM version you have ever uploaded." +answer: "Vulnerability counts in sbomify reflect your current posture: the findings present in the latest artifact for each component and format, with VEX-suppressed findings excluded. They are not a running total across every historical SBOM version. If your counts dropped noticeably after upgrading to v26.7.1, that is the fix for exactly this behaviour landing - the earlier numbers were inflated by superseded SBOM versions." +tldr: "Counts reflect your current posture, not the sum of every SBOM you have ever uploaded. Fixing a vulnerability and uploading a new SBOM makes the count go down. If your totals dropped after v26.7.1, the old numbers were counting superseded versions." +weight: 69 +keywords: [vulnerability count, vulnerability dashboard, current posture, historical SBOM versions, count dropped, vulnerability totals, VEX suppression] +url: /faq/how-does-sbomify-count-vulnerabilities/ +--- + +## The short answer + +Counts reflect **current posture**: the findings present in the latest artifact for each component and format, after VEX statements are applied. They are not a cumulative total of everything ever scanned. + +This is the behaviour you want, because it means the number responds to your work. Fix a vulnerability, upload a new SBOM, and the count goes down. + +## Why your count may have dropped + +If you have been using sbomify for a while and your totals fell noticeably around v26.7.1, nothing broke and nothing was fixed in your software. The counts were previously aggregated across **every historical SBOM version** for a component rather than the current one. + +The practical effect was a number that could only ever go up. Upload ten iterations of a component over six months, remediate along the way, and findings from all ten versions were still counted, including ones you had already fixed and superseded. + +That is now corrected, so expect the totals to drop, in many cases substantially. The new number is the honest one. + +## What is included in a count + +- **The latest artifact per component and format.** A CycloneDX SBOM and an SPDX SBOM for the same component are both current; version 3 of that CycloneDX SBOM supersedes versions 1 and 2. +- **Findings from your enabled scanners**, whether that is the built-in OSV scanning or [Dependency Track](/faq/how-do-i-enable-vulnerability-scanning/). +- **Minus anything covered by VEX.** Findings you have marked `not_affected` are suppressed, so the dashboard shows triaged exposure rather than raw scanner output. See [How do I use VEX with sbomify?](/faq/how-do-i-use-vex/). + +Skipped assessments are reported as skipped rather than counted as problems, so a scan that could not run does not inflate or deflate your posture. + +## Release-scoped counts + +A release pins specific artifacts, so a release's vulnerability posture is calculated against the artifacts pinned to it rather than whatever is newest on the component. This is deliberate: a release you shipped six months ago should report the posture of what you actually shipped, not of your current `main`. + +That release posture is what your customers see on the public [Trust Center](/features/trust-center/) release page. + +## Further reading + +- [How do I enable vulnerability scanning?](/faq/how-do-i-enable-vulnerability-scanning/) - where the findings come from +- [How do I use VEX with sbomify?](/faq/how-do-i-use-vex/) - suppressing findings that do not affect you +- [How do I create a software release?](/faq/how-do-i-create-a-software-release/) - how artifacts get pinned to a release diff --git a/content/faq/what-is-a-cbom.md b/content/faq/what-is-a-cbom.md index e7c2778..6a131a4 100644 --- a/content/faq/what-is-a-cbom.md +++ b/content/faq/what-is-a-cbom.md @@ -2,7 +2,7 @@ title: "What is a CBOM and how does sbomify support it?" description: "A Cryptography Bill of Materials (CBOM) inventories the cryptographic assets in your software. sbomify auto-detects CBOMs, builds a crypto inventory, and assesses post-quantum readiness." answer: "A CBOM (Cryptography Bill of Materials) is a CycloneDX BOM that inventories cryptographic assets: algorithms, keys, certificates, and protocols. sbomify auto-detects CBOM content on upload, renders a crypto-asset inventory, runs a post-quantum cryptography (PQC) readiness assessment against NIST guidance, and publishes CBOMs on your public release pages next to your SBOMs." -tldr: "A CBOM is the cryptographic sibling of an SBOM: it lists the algorithms, keys, certificates, and protocols your software uses. sbomify ingests and auto-classifies CBOMs, shows a crypto inventory with a post-quantum readiness view, and shares them through your Trust Center." +tldr: "A CBOM is the cryptographic sibling of an SBOM: it lists the algorithms, keys, certificates, and protocols your software uses. sbomify ingests and auto-classifies CBOMs from any generator, normalizes them against the CycloneDX 1.7 crypto registry, shows a crypto inventory with a post-quantum readiness view, and shares them through your Trust Center." weight: 68 keywords: [CBOM, Cryptography Bill of Materials, crypto inventory, post-quantum cryptography, PQC readiness, quantum-safe, CycloneDX CBOM] url: /faq/what-is-a-cbom/ @@ -16,9 +16,10 @@ That question is becoming urgent. Migrating to post-quantum cryptography starts ## What sbomify does with CBOMs -- **Auto-detection.** Upload a CycloneDX document containing cryptographic assets and sbomify automatically classifies it as a CBOM, no special flag needed. You can also be explicit with `BOM_TYPE: cbom` in [sbomify-action](https://github.com/sbomify/sbomify-action), which uploads the document verbatim. +- **Auto-detection, whatever produced it.** Upload a CycloneDX document containing cryptographic assets and sbomify automatically classifies it as a CBOM, no special flag needed. Every CBOM lineage is ingested, and assets are normalized against the CycloneDX 1.7 cryptographic registry, so output from different generators lands in the same shape instead of depending on which tool you happened to use. You can also be explicit with `BOM_TYPE: cbom` in [sbomify-action](https://github.com/sbomify/sbomify-action), which uploads the document verbatim. - **Crypto-asset inventory.** The document detail page renders an inventory of the cryptographic assets found: algorithms, key sizes, certificates, and protocols. - **Post-quantum readiness.** The PQC readiness assessment plugin classifies each asset against NIST guidance and gives your component a post-quantum posture view, so you can see at a glance which algorithms are quantum-vulnerable and where. +- **Workspace-level crypto posture.** Your workspace dashboard summarizes crypto posture alongside your other artifacts, so post-quantum readiness is visible across the estate rather than one component at a time. - **Trust Center distribution.** CBOMs appear on your public release pages next to SBOMs and VEX, with the same access controls, and are exposed through the [Transparency Exchange API](/faq/how-do-i-enable-tea-in-sbomify/) as a supported artifact type. ## How do I generate a CBOM?