Back to glossary

Common Security Advisory Framework (CSAF)

CSAF (Common Security Advisory Framework) is an OASIS JSON standard for machine-readable security advisories and VEX, with rules for publishing them.

Also known as CSAF 2.0, CSAF 2.1, CSAF VEX, CVRF, Common Vulnerability Reporting Framework, ISO/IEC 20153

The Common Security Advisory Framework (CSAF) is an OASIS standard JSON format for machine-readable security advisories. A CSAF document lists products in a product tree, then states each product's status for each vulnerability, from known_affected to fixed. CSAF also defines how vendors publish advisories so tools can find, verify, and match them automatically. It replaced CVRF.

CSAF 2.0 became an OASIS Standard on 18 November 2022. ISO adopted the same text as ISO/IEC 20153:2025, published in February 2025. As of November 2026, CSAF 2.1 is still a draft: the public review of its fourth Committee Specification Draft closed on 6 November 2026. Red Hat, SUSE, Microsoft, and CISA already publish CSAF 2.0 documents.

CSAF is product-centric by design. The issuing party names its own builds, firmware, and images, and says what each one should do about each vulnerability. That is the right model for a vendor talking to its customers, and we think every vendor that ships software should publish CSAF. It is the wrong unit for open source dependencies. A CSAF document identifies the vendor's product, such as an RPM, and can mention the npm or PyPI package that contains the bug only in prose, as the example below shows. Matching a lockfile is a job for OSV. And the JSON schema is the easy part of CSAF. A document can pass it while pointing at products that do not exist, so consumers must run the specification's mandatory tests as well.

What is CSAF?

#

CSAF is a JSON language for security advisories with three top-level parts: document for metadata, product_tree for products, and vulnerabilities for what is wrong with them. The specification states its main design rule plainly: "Wherever possible repetition of data has been replaced by linkage through ID elements." Each product is defined once in the product tree and gets a product_id. Everything else in the document refers to products by that ID.

The document object holds the publisher, a tracking ID, a version, a revision history, a Traffic Light Protocol (TLP) label, and a category. The category selects a profile. A profile is a set of fields that must be present for one use case, layered on top of the CSAF Base minimum.

Profile/document/categoryWhat it addsVersion
CSAF Basecsaf_basePublisher, title, tracking, and revision history only2.0
Security incident responsecsaf_security_incident_responseNotes and an external reference about an incident2.0
Informational advisorycsaf_informational_advisoryNotes and references about a non-vulnerability issue; vulnerabilities must be absent2.0
Security advisorycsaf_security_advisoryProduct tree, vulnerabilities, notes, and a status for each product2.0, stricter in 2.1
VEXcsaf_vexA CVE or other ID, a status per product, an impact statement for each unaffected product, an action statement for each affected one2.0
Deprecated security advisorycsaf_deprecated_security_advisoryThe 2.0 security advisory rules, kept for converted documents2.1 draft
Withdrawn and supersededcsaf_withdrawn, csaf_supersededThe reason, and for superseded documents a pointer to the replacement2.1 draft
Vulnerability reportcsaf_vulnerability_reportA private report between finder, vendor, and coordinator during coordinated disclosure2.1 draft

The product_tree describes products as nested branches: vendor, product family, product name, architecture, product version. A leaf carries a product_id and, optionally, a product_identification_helper such as a CPE string, a package URL (purl), file hashes, or a serial number. A separate relationships list builds composite products, such as "this RPM as a component of that operating system release." Each composite product gets its own ID.

The vulnerabilities array lists issues by CVE ID, or by other identifiers in an ids field. Each entry carries product_status, a set of lists of product IDs. CSAF 2.0 defines eight lists: first_affected, known_affected, last_affected, known_not_affected, first_fixed, fixed, recommended, and under_investigation. The CSAF 2.1 draft adds unknown for products nobody is investigating. Remediations, scores, and threats point at the same product IDs.

CSAF asks vendors to list exact versions rather than ranges. In the words of the CSAF 2.0 specification, "it is always recommended to enumerate product versions instead of providing version ranges." A product_version_range branch exists, and it should use the vers range syntax, but equality on an enumerated version is the matching path the spec prefers. That choice fits a vendor, which ships a finite set of builds. It fits an open source registry poorly, where any future release can land inside an affected range.

Inside a real CSAF VEX document

#

A real CSAF document makes the structure concrete. We use CIQ's CSAF VEX document for CVE-2022-25883, the regular expression denial of service in npm's semver package that our VEX and OSV entries also dissect. CIQ ships enterprise distributions based on Rocky Linux, and the file states that its content is derived from Red Hat's CSAF VEX documents. We pinned the file at commit fe3030b. It is 55,555 bytes, has SHA-256 7a1367ff…6af10, and is at version 8, revised on 29 September 2026.

Here is the document cut down to one product. Every value is copied from the file. We dropped the remaining 36 products, the revision history, and the score and threat entries:

JSON
{
  "document": {
    "category": "csaf_vex",
    "csaf_version": "2.0",
    "publisher": { "category": "vendor", "name": "Ctrl IQ, Inc", "namespace": "https://www.ciq.com" },
    "tracking": { "id": "CVE-2022-25883", "status": "final", "version": "8" }
  },
  "product_tree": {
    "branches": [{
      "category": "vendor", "name": "CIQ",
      "branches": [
        { "category": "product_family", "name": "CIQ LTS",
          "branches": [{ "category": "product_name", "name": "CIQ LTS 8.6",
            "product": { "name": "CIQ LTS 8.6", "product_id": "lts-8.6",
              "product_identification_helper": { "cpe": "cpe:2.3:o:ciq:rocky_linux_from_ciq:8.6:*:*:*:*:*:*:lts" } } }] },
        { "category": "architecture", "name": "x86_64",
          "branches": [{ "category": "product_version",
            "name": "npm-6.14.18-1.14.21.3.1.module+el8.6.0+1809+17812759.x86_64",
            "product": { "name": "npm-6.14.18-1.14.21.3.1.module+el8.6.0+1809+17812759.x86_64",
              "product_id": "npm-6.14.18-1.14.21.3.1.module+el8.6.0+1809+17812759.x86_64",
              "product_identification_helper": { "purl": "pkg:rpm/ciq/npm@6.14.18-1.14.21.3.1.module+el8.6.0+1809+17812759?arch=x86_64" } } }] }
      ]
    }],
    "relationships": [{
      "category": "default_component_of",
      "product_reference": "npm-6.14.18-1.14.21.3.1.module+el8.6.0+1809+17812759.x86_64",
      "relates_to_product_reference": "lts-8.6",
      "full_product_name": {
        "name": "npm-6.14.18-1.14.21.3.1.module+el8.6.0+1809+17812759.x86_64 as a component of CIQ LTS 8.6",
        "product_id": "lts-8.6:npm-6.14.18-1.14.21.3.1.module+el8.6.0+1809+17812759.x86_64"
      }
    }]
  },
  "vulnerabilities": [{
    "cve": "CVE-2022-25883",
    "cwe": { "id": "CWE-1333", "name": "Inefficient Regular Expression Complexity" },
    "notes": [{ "category": "description", "title": "Vulnerability Description",
      "text": "Versions of the package semver before 7.5.2 are vulnerable to Regular Expression Denial of Service (ReDoS) via the function new Range, when untrusted user data is provided as a range." }],
    "product_status": { "fixed": ["lts-8.6:npm-6.14.18-1.14.21.3.1.module+el8.6.0+1809+17812759.x86_64"] },
    "remediations": [{ "category": "vendor_fix",
      "details": "Update to the fixed package version from CIQ repositories",
      "product_ids": ["lts-8.6:npm-6.14.18-1.14.21.3.1.module+el8.6.0+1809+17812759.x86_64"] }]
  }]
}

Read it from the bottom. product_status.fixed names lts-8.6:npm-6.14.18-…x86_64. That ID does not appear in the branches. The relationship defines it, by combining the RPM leaf npm-6.14.18-…x86_64 with the operating system release lts-8.6. The RPM leaf carries the purl a scanner would match. The full file repeats this chain 37 times. Its branches hold 38 products: one operating system release and 37 RPM builds. Its 37 relationships produce 37 composite IDs, and all 37 are listed as fixed, each with the same vendor_fix remediation, a CVSS 3.1 base score of 7.5, and an impact threat of "Moderate."

Figure 1. One product, traced through CIQ's CSAF VEX document for CVE-2022-25883. The full file repeats this chain for 37 RPM builds.

Figure 1 in text: the product tree has a vendor branch, CIQ, with two children. The first is the product family CIQ LTS, whose product name CIQ LTS 8.6 has ID lts-8.6 and a CPE helper. The second is the architecture x86_64, whose product version is the RPM npm-6.14.18-1…x86_64 with a purl helper pkg:rpm/ciq/npm@…. A default_component_of relationship combines that RPM with lts-8.6 into the composite ID lts-8.6:npm-6.14.18-1…x86_64, which has no identification helper of its own. Four parts of the CVE-2022-25883 entry point at that composite ID: product_status.fixed (this build contains the fix), remediations[0] (vendor_fix: update from CIQ repositories), scores[0] (CVSS 3.1 base score 7.5), and threats[0] (impact "Moderate"). The npm package pkg:npm/semver, where the bug actually lives, is not in the product tree at all. It appears only in English text in notes[].text.

Three properties of this document matter to anyone matching it automatically.

The vulnerable component is not a product. The bug lives in the npm package semver, but the product tree names RPMs such as nodejs, npm, nodejs-nodemon, and nodejs-packaging. The string "semver" appears twice in 55 KB, both times in copies of the same English description. No purl of the form pkg:npm/semver appears anywhere. A developer whose package-lock.json pins semver@7.5.1 learns nothing from this file. The OSV record for the same CVE names {"ecosystem": "npm", "name": "semver"} and its fixed versions instead. The two formats answer different questions for different readers.

The document lists only fixed builds. It never names an affected build. To decide whether an installed nodejs-14.21.1 RPM is affected, a consumer has to apply RPM version ordering, which CSAF does not define. The CSAF 2.1 draft closes that gap for the security advisory profile, which must give the corresponding affected version for every fixed product. The VEX profile carries no such rule.

Four of the most important products cannot be matched by machine. The main nodejs binary RPMs, versions 10.24.0 and 14.21.3 for aarch64 and x86_64, carry no identification helper: no purl, no CPE, only a name string. Those are the packages a scanner most needs to find.

How do you validate a CSAF document?

#

A CSAF document is validated in two layers: the JSON schema first, then the specification's semantic tests. The schema checks types, enumerations, and required fields. The schema cannot check that a product ID used in product_status is defined in the product tree. Section 6 of the specification defines those cross-reference checks as mandatory, optional, and informative tests. CSAF 2.0 defines 33 numbered mandatory tests, and the CSAF 2.1 draft defines 66.

Germany's Federal Office for Information Security (BSI) publishes an open source implementation of these tests, csaf-validator-lib. We ran version 3.0.2 against the pinned file with Node 22.23.4 on 8 November 2026:

JavaScript
import { readFileSync } from 'node:fs'
import validateStrict from '@secvisogram/csaf-validator-lib/validateStrict.js'
import * as basic from '@secvisogram/csaf-validator-lib/basic.js'       // schema + mandatory tests
import * as optional from '@secvisogram/csaf-validator-lib/optionalTests.js'

const doc = JSON.parse(readFileSync(process.argv[2], 'utf8'))
const { isValid, tests } = await validateStrict(
  [...Object.values(basic), ...Object.values(optional)], doc)

console.log('isValid:', isValid)
for (const t of tests)
  for (const level of ['errors', 'warnings'])
    if (t[level].length)
      console.log(level, t.name, t[level].length, t[level][0].message)
Plain text
isValid: true
warnings optionalTest_6_2_16 41 missing product identification helper
warnings optionalTest_6_2_19 37 environmental score should be 0 since "lts-8.6:nodejs-10.24.0-1.module+el8.6.0+1809+8324a6fa.aarch64" is listed as fixed
warnings optionalTest_6_2_6 1 older current release date than revision history

The document passes the schema and every mandatory test. It also raises 79 optional-test warnings. Test 6.2.16 flags 41 products without an identification helper: the four nodejs RPMs above plus all 37 composite products. Test 6.2.19 flags CVSS scores attached to 37 products listed as fixed. A consumer that sorts findings by score would rank already-patched builds at 7.5. Test 6.2.6 flags a current_release_date older than the newest revision entry. The two timestamps differ by 7 milliseconds, a generator artifact.

Now delete one relationship, the kind of damage a buggy generator or a bad merge could do:

Plain text
$ python3 -c "
import json; d = json.load(open('cve-2022-25883.json'))
del d['product_tree']['relationships'][0]
json.dump(d, open('broken.json', 'w'))"
$ node validate.mjs broken.json
isValid: false
errors mandatoryTest_6_1_1 4 definition of product id missing
warnings optionalTest_6_2_1 1 is not referenced
warnings optionalTest_6_2_16 40 missing product identification helper
warnings optionalTest_6_2_19 37 environmental score should be 0 since "lts-8.6:nodejs-10.24.0-1.module+el8.6.0+1809+8324a6fa.aarch64" is listed as fixed
warnings optionalTest_6_2_6 1 older current release date than revision history

The broken file still passes the JSON schema alone; we checked it with the library's csaf_2_0_strict schema test by itself. Mandatory test 6.1.1 fails at four paths, because product_status, remediations, scores, and threats all reference a product ID that no longer exists. A consumer that stops at schema validation would ingest a fixed status for a product it cannot identify. The retrieval rules in section 7.3.2 of the specification already say to "execute mandatory tests on the CSAF document" after the schema check. We would make that non-negotiable: reject any document that fails a mandatory test.

How are CSAF documents published and discovered?

#

CSAF documents are published under one of three issuer roles, and the role decides what a consumer can automate. Section 7 of the specification lists 23 numbered distribution requirements and groups them into roles.

RoleRequirements it must meetWhat a consumer gets
CSAF publisher1 to 4: valid documents, the filename rule, TLS, and free access to TLP:WHITE documentsDocuments, with no defined way to find them
CSAF providerPublisher, plus 5 to 7 (access control for TLP:AMBER and TLP:RED, no redirects, a provider-metadata.json), at least one of 8 to 10 (discovery), and either 11 to 14 (directory) or 15 to 17 (ROLIE feeds)Automatic discovery and enumeration
CSAF trusted providerProvider, plus 18 to 20: a hash file and an OpenPGP signature for every document, and a published public keyIntegrity and origin checks
CSAF lister or aggregator6, 21, and 22: an aggregator.json that lists at least two independent issuers. Aggregators also meet 1 to 5 and 23, and mirror and sign copiesOne place to fetch many vendors

Discovery starts from a domain name. A retriever first tries https://<domain>/.well-known/csaf/provider-metadata.json, then the CSAF: field in the domain's security.txt, and only if both fail, the host csaf.data.security.<domain>. The provider-metadata.json file says where documents live, which role the issuer claims, and which OpenPGP keys sign them. The retriever then enumerates documents through ROLIE feeds or through index.txt and changes.csv next to per-year folders. For trusted providers it verifies the hash and signature of each document, then runs the schema and mandatory tests.

Figure 2. How a CSAF consumer finds and verifies a vendor’s advisories, per section 7.3 of CSAF 2.0.

Figure 2 in text: step 1 starts from the issuer's domain, such as example.com. Step 2 locates provider-metadata.json in this order: the well-known path /.well-known/csaf/provider-metadata.json, then the CSAF: field in security.txt, then DNS csaf.data.security.example.com only if the first two fail. A retriever can also find it indirectly through a lister's or aggregator's aggregator.json. Step 3 reads provider-metadata.json for role, distributions, public_openpgp_keys, and list_on_CSAF_aggregators. Step 4 enumerates documents through ROLIE feeds (requirements 15 to 17), which are preferred when both exist, or through a directory with index.txt, changes.csv, and YYYY/ folders (requirements 11 to 14). Step 5 fetches each document with its .sha512 hash and .asc OpenPGP signature, verifies both, runs the JSON schema and the mandatory tests, and matches identification helpers to the inventory. Hash and signature files exist only for trusted providers, so unsigned documents go straight to the schema check.

CIQ's metadata file shows the low end of this ladder:

JSON
{
  "canonical_url": "https://raw.githubusercontent.com/ctrliq/advisories/main/csaf/provider-metadata.json",
  "distributions": [
    { "directory_url": "https://raw.githubusercontent.com/ctrliq/advisories/main/csaf/advisories/rocky/" },
    { "directory_url": "https://raw.githubusercontent.com/ctrliq/advisories/main/csaf/advisories/ciq/" },
    { "directory_url": "https://raw.githubusercontent.com/ctrliq/advisories/main/csaf/vex/cve/" }
  ],
  "last_updated": "2026-09-24T17:00:03.390229+00:00",
  "list_on_CSAF_aggregators": true,
  "metadata_version": "2.0",
  "mirror_on_CSAF_aggregators": false,
  "publisher": {
    "category": "vendor",
    "issuing_authority": "Ctrl IQ, Inc Security Team",
    "name": "Ctrl IQ, Inc",
    "namespace": "https://www.ciq.com"
  },
  "role": "csaf_publisher"
}

CIQ claims the csaf_publisher role and serves three directories from GitHub. On 8 November 2026, the VEX directory's index.txt listed 6,179 documents, and its changes.csv lets a client fetch only what changed since the last sync. No .sha256, .sha512, or .asc file sits next to cve-2022-25883.json. The only integrity guarantee is TLS to GitHub.

A signature does not make an advisory correct. A trusted provider's OpenPGP signature proves which issuer published the bytes. It does not prove that a known_not_affected claim is true, and an aggregator's signature on a mirrored copy only proves the copy was not altered in transit. Package provenance has the same limit: a valid signature over wrong content is still wrong content.

What is the difference between CSAF and VEX?

#

CSAF is a general advisory format, and VEX is one use case that CSAF implements as a profile. VEX is a statement of whether a specific product is affected by a specific vulnerability, with a justification when it is not. CISA's minimum requirements for VEX define the statuses and five justification labels. CSAF VEX, OpenVEX, CycloneDX VEX, and SPDX 3.0 are four encodings of those requirements.

A CSAF document is CSAF VEX when document.category is csaf_vex. The profile then requires a product tree, a CVE or other ID, notes, and at least one of four statuses: known_affected, known_not_affected, fixed, or under_investigation. Every known_not_affected product needs an impact statement. That statement is either a machine-readable flag with a label such as vulnerable_code_not_in_execute_path, or a human-readable threats entry of category impact. Every known_affected product needs an action statement in remediations.

The practical difference from OpenVEX is weight. OpenVEX is a flat list of statements that name products by purl. CSAF VEX carries a product tree, scores, remediations, a revision history, and the distribution layer described above. On 1 February 2023, Red Hat announced that its advisories had switched from csaf_security_advisory to csaf_vex, so its advisories themselves satisfy the VEX profile.

For open source dependency results, we chose the lighter format. Socket's Export OpenVEX Document API turns a full scan's reachability results into an OpenVEX v0.2.0 document. Unreachable vulnerabilities become not_affected with a justification, reachable ones become affected, and pending results become under_investigation.

From CVRF to CSAF

#

CSAF is the rebuilt successor to the Common Vulnerability Reporting Framework (CVRF), an XML format for the same job. The Industry Consortium for Advancement of Security on the Internet (ICASI) created CVRF and published version 1.1 in May 2012. The work then moved to the OASIS CSAF Technical Committee, which published CVRF 1.2 as a Committee Specification on 13 September 2017. The CSAF 2.0 specification names CVRF 1.2 as its predecessor, and the JSON format continues the numbering at 2.0.

CSAF 2.0 kept CVRF's model of document, products, and vulnerabilities, and replaced XML with JSON Schema. It also added what CVRF lacked: profiles, numbered semantic tests, and the publishing and discovery rules above. The specification defines a CVRF-to-CSAF converter as a conformance target, and the BSI publishes one. Most large publishers have moved. Red Hat deprecated CVRF and kept updating those files only until 1 September 2023. Microsoft added CSAF for all its CVEs on 12 November 2024 and kept its CVRF API running alongside it.

CSAF vs OSV vs OpenVEX: which format for which job

#

Three machine-readable formats overlap with CSAF, and each was built for a different author. The table compares them on the properties that decide which one a tool should read.

PropertyCSAF 2.0OSVOpenVEX
Who writes itThe vendor, PSIRT, or CERT responsible for a productEcosystem databases such as GHSA, PyPI, and RustSec, aggregated at OSV.devWhoever builds the product, often a tool in the build
Unit of identityA product_id in a product tree, with an optional purl, CPE, or hashEcosystem plus package nameA product and subcomponents, usually by purl
How versions are expressedEnumerated builds preferred; ranges through versEvent ranges such as introduced and fixed, in the ecosystem's orderingOne statement per product version
Can say "not affected"Yes, in the VEX profile, with a justificationNoYes, with a justification
Discoveryprovider-metadata.json, security.txt, DNS, ROLIE feeds, aggregatorsOne API and bulk exports at OSV.devNone defined
IntegrityOpenPGP signature per document for trusted providersNone in the formatSigning recommended, no distribution rules
Covers malicious packagesOnly if someone issues an advisory afterwardYes, under the MAL prefixNo

Verdict: publish CSAF if you are a vendor issuing advisories for products you ship, and meet at least the provider role so tools can find you without a human. Use OSV to match open source dependencies against known vulnerabilities, because it names packages the way package managers do. Use OpenVEX for exploitability statements generated in a build or by reachability analysis. Consumers should ingest all three, keep each source document, and never treat a converted copy as the original.

CSAF 2.1: what changes

#

CSAF 2.1 is the next version of the standard, and as of November 2026 it is Committee Specification Draft 04, dated 21 October 2026. Its 15-day public review ran from 23 October to 6 November 2026. The draft changes the data model in five ways that matter to tool builders.

  • A metrics array replaces scores, and each metric names its products and source. It can carry CVSS v2, v3, and v4, EPSS, a qualitative severity rating, and SSVC decision points.
  • The security advisory profile gets stricter. It now requires at least one known_affected product, a CVE or other ID, and the corresponding affected version for every fixed product. Documents built to the old rules use csaf_deprecated_security_advisory.
  • New profiles cover withdrawn and superseded documents, and private vulnerability reports exchanged during coordinated disclosure.
  • Documents use TLP 2.0 labels, so TLP:CLEAR replaces TLP:WHITE.
  • The mandatory test suite grows from 33 numbered tests to 66, including checks on version ranges, SSVC, EPSS timestamps, and license expressions.

The draft also tells providers how to migrate. It recommends serving 2.0 and 2.1 in parallel, with the 2.0 metadata at /.well-known/csaf/v2.0/provider-metadata.json, and announcing a roll-over date when 2.1 becomes authoritative.

What CSAF cannot tell you

#

CSAF moves product matching to the party that knows the product. That matters more as central enrichment shrinks. As of August 17, 2026, the NVD listed 42,353 CVEs as "Not Scheduled" for enrichment, as we reported in NIST's plan for an AI-enabled NVD overhaul. A vendor's CSAF file states exactly which of its builds are affected, with no analyst in between writing CPE strings. CISA's Eric Goldstein made the same argument in November 2022: with CSAF, "vendors will dramatically reduce the time required for enterprises to understand organizational impact."

Machine-readable is not the same as matchable. The product_identification_helper is optional in CSAF 2.0. A product without a purl, CPE, or hash can only be matched by its name string, as 41 products in our example show.

A CSAF document arrives after the vendor's analysis. For a malicious package, that is too late by design. In the axios compromise on 31 March 2026, the payload ran from a dependency's install script. The resulting OSV record, MAL-2026-2307, lists a GHSA alias and no CVE. A vendor could still write a CSAF document for it, because the VEX profile accepts any ID in ids. That document would describe exposure after the malware had already run on install.

Regulation will push CSAF further. The EU Cyber Resilience Act requires manufacturers, in Annex I, Part II, point 4, to publicly disclose fixed vulnerabilities once a security update is available. The disclosure must describe the vulnerability, identify the affected products, state impact and severity, and help users remediate. Each of those maps to a CSAF field: notes, product_tree, scores or threats, and remediations. The CRA does not name a format. We expect CSAF to become the default way to meet that obligation, because it is the ISO-standardized advisory format with discovery and signing rules built in.

The open problem is the join between a vendor's product tree and a developer's lockfile. CIQ's document ties CVE-2022-25883 to 37 RPM builds. The OSV record ties it to npm versions of semver. No machine-readable field connects the npm package inside the RPM to the RPM itself. CSAF can already express that link: a branch with a pkg:npm/semver purl at the bundled version, plus a default_component_of relationship to the RPM, would do it. Until publishers ship that nesting, the most important fact in this 55 KB document, which open source package was broken, is the one a machine cannot read.