CSAF: the Common Security Advisory Framework for machine-readable advisories

What is CSAF?

The Common Security Advisory Framework (CSAF) is a standard from the OASIS CSAF Technical Committee for writing security advisories as structured JSON and distributing them so that they can be found and processed automatically. A CSAF document says which products and versions a vulnerability affects, which are not affected, which are fixed, and what users should do.

The current version is CSAF 2.0, approved as an OASIS Standard on November 18, 2022. CSAF 2.1 is on its way: its third Committee Specification Draft went through public review in September 2026, and as of October 2026 it is not yet an approved standard.

Advisories are written by vendors, usually by their product security incident response team (PSIRT), and by coordinators such as national CERTs. For how those two kinds of team differ, see PSIRT vs CSIRT.

From CVRF to CSAF

CSAF grew out of the Common Vulnerability Reporting Framework (CVRF), an XML format. ICASI published CVRF 1.1 in May 2012, and OASIS published CVRF 1.2 in September 2017. CSAF 2.0 replaced it with a JSON format, a JSON schema for validation, profiles for different kinds of documents, and rules for how advisories are distributed and found. The specification still defines how to convert CVRF documents to CSAF.

CSAF document structure

A CSAF document has three top-level parts:

• document: metadata. Five properties are mandatory: the category (which profile the document follows), the CSAF version, the publisher, the title and tracking data. Tracking holds the advisory ID, its status, its version, the initial and current release dates and a revision history.
• product_tree: every product the document mentions, usually as branches from vendor to product name to version, with product IDs that the rest of the document refers to. Products can also be identified by package URL (purl), CPE or hashes.
• vulnerabilities: one entry per vulnerability, with its CVE or other IDs, notes, scores, and a product status that sorts product IDs into lists: known_affected, known_not_affected, fixed, first_affected, last_affected, first_fixed, recommended and under_investigation. Remediations are categorized as vendor_fix, workaround, mitigation, no_fix_planned or none_available.

The five CSAF profiles

Few fields are mandatory in CSAF as a whole. Profiles say which ones a given kind of document must have, and the value of /document/category says which profile a document follows:

Profile	Category value	Use it for
CSAF Base	csaf_base	The minimum every CSAF document meets; the catch-all for documents that fit no other profile
Security incident response	csaf_security_incident_response	Responding to a security breach or incident, including one at another organization
Informational advisory	csaf_informational_advisory	Issues that are not vulnerabilities, such as a dangerous misconfiguration
Security advisory	csaf_security_advisory	Vulnerabilities and their remediations; the classic vendor advisory
VEX	csaf_vex	Stating whether, and why, each product is or is not affected by a vulnerability

A security advisory must have a product tree, the vulnerabilities, notes for each vulnerability and a product status. The VEX profile goes further: every product listed as known_not_affected needs an impact statement, either as a machine-readable flag or as text, and every known_affected product needs a remediation that tells users what to do.

CSAF VEX

VEX (Vulnerability Exploitability eXchange) tells users which vulnerabilities in a product's components actually affect the product. CSAF VEX is one of three common VEX formats, next to OpenVEX and CycloneDX VEX. Its flags use the same five not-affected justifications as CISA's VEX requirements, such as component_not_present and vulnerable_code_not_in_execute_path. Trivy and Grype both read CSAF VEX and drop findings it marks as not affected. Red Hat, for example, publishes its CSAF VEX documents in a separate directory next to its CSAF advisories.

How CSAF advisories are distributed

A standard format only helps if tools can find the documents. Section 7 of CSAF 2.0 sets out how:

• provider-metadata.json describes the publisher and where its advisories are. Tools find it through at least one of three routes: a CSAF field in the domain's security.txt, the well-known URL /.well-known/csaf/provider-metadata.json, or the DNS name csaf.data.security. in front of the domain.
• Advisories are listed either in folders per year with an index.txt and changes.csv, or in ROLIE feeds, served over TLS without redirects.
• Each file is named after its tracking ID. TLP:WHITE advisories must be freely accessible, and TLP:AMBER or TLP:RED ones must sit behind access control.
• Integrity: trusted providers add a hash and an OpenPGP signature for each document and publish their public key.

The standard defines five roles that a distributing party can claim:

Role	What it does
CSAF publisher	Publishes valid CSAF documents, on its own behalf only, over TLS
CSAF provider	A publisher that also offers provider-metadata.json, a discovery route and a directory or ROLIE feed
CSAF trusted provider	A provider that also publishes hashes, OpenPGP signatures and its public key
CSAF lister	Keeps a list of where to find other parties' CSAF documents, without copying them
CSAF aggregator	Mirrors the documents of at least two independent issuing parties in one place, with hashes and signatures

Consumers set up a downloader once and then pull new advisories from every provider their products depend on, instead of watching dozens of vendor web pages.

Who publishes CSAF

CSAF is most common among industrial, enterprise and infrastructure vendors and among national CERTs:

• Cisco serves a provider-metadata.json at its well-known CSAF URL.
• Siemens ProductCERT publishes its advisories as a CSAF ROLIE feed.
• Red Hat publishes CSAF advisories and, separately, CSAF VEX documents.
• BSI's CERT-Bund, Germany's national CERT, publishes CSAF feeds of its advisories.
• CISA announced in September 2023 that its ICS advisories come with CSAF documents, back to 2017, and urged vendors to adopt the standard.

Industrial suppliers working to IEC 62443-4-1 need a process for telling users about security issues in their products, and machine-readable advisories are a common way to meet their customers' expectations.

CSAF tooling

• Secvisogram is the BSI's web editor for CSAF documents, with a form editor, a JSON editor, an HTML preview and validation.
• The csaf tools from the BSI and Intevation (gocsaf/csaf, often called csaf_distribution) implement a trusted provider, a checker, an aggregator and a downloader, with a CSAF 2.1 version in development.
• Scanners such as Trivy and Grype consume CSAF VEX documents.

Writing a good security advisory

With or without CSAF, a useful advisory answers the same questions. This is the template most PSIRTs converge on, with the CSAF field that holds each answer:

Advisory element	What to write	In CSAF
ID and title	A stable advisory ID and a title naming the product and the kind of issue	tracking/id, title
Dates and revisions	First published, last updated, and what changed in each revision	tracking dates and revision_history
Affected products	Exact products and version ranges, not "older versions"	product_tree, known_affected
Not affected and fixed	Which products and versions are not affected, and which versions contain the fix	known_not_affected, fixed, first_fixed
Vulnerability	CVE IDs, a plain description, the impact and how it is exploited, without a recipe for attackers	cve, ids, notes
Severity	A CVSS score with its vector, so readers can check it	scores
Remediation	The fixed version, or a workaround or mitigation, or a clear statement that no fix is planned	remediations
Credits and references	Who reported it, links to related advisories and fixes	acknowledgments, references
Contact	Where to report problems and ask questions	publisher/contact_details

A few habits make the difference between an advisory people act on and one they ignore:

• Be exact about versions. The affected range is what customers act on. Name the first affected and first fixed version for each product line.
• Say what is not affected. Customers running products you have ruled out stop asking, and their scanners stop flagging them if you also publish VEX.
• Update, do not replace. Keep one advisory per issue and add revisions as fixes ship.
• Publish on the date you agreed. Advisories are the end point of coordinated vulnerability disclosure, released when the fix is available and the reporter has been told.

The steps before the advisory, from intake and triage to the fix, are covered in the vulnerability management lifecycle, and the people who do this work in PSIRT role.

The hard part is knowing what is affected

Every advisory, in CSAF or any other format, depends on one answer: which products and versions contain the vulnerable component. For software built from open source packages, that means knowing exactly which dependency versions went into each release, including transitive ones.

CRACI runs GitHub Actions builds on its own runners and records the packages each job actually fetched, including transitive dependencies, packages restored from caches and dependencies no lockfile lists. When a new vulnerability is published, monitored SBOMs are re-evaluated, and build history shows which past builds and releases contained the vulnerable dependency, directly or transitively, so you know the period you were affected. The inventory view shows which versions are deployed to which products, and triage routes each finding to the team that owns the fix. SBOMs export as CycloneDX or SPDX, and CRACI supports VEX. See vulnerability tracking.

CSAF: frequently asked questions

What does CSAF stand for?

In security, CSAF stands for the Common Security Advisory Framework, an OASIS standard for writing security advisories as machine-readable JSON documents and distributing them so that tools can find and process them automatically.

What is the current version of CSAF?

CSAF 2.0, approved as an OASIS Standard on November 18, 2022. CSAF 2.1 is in progress: its third Committee Specification Draft finished public review on September 29, 2026, and as of October 2026 it is not yet an approved OASIS Standard.

What is the difference between CSAF and CVE?

A CVE record identifies one vulnerability and describes it in general terms. A CSAF advisory is published by a vendor or coordinator and says how that vulnerability, and often several others, affects specific products and versions, and what to do about it. CSAF advisories reference CVE IDs.

What is CSAF VEX?

CSAF VEX is the csaf_vex profile of CSAF. It carries VEX statements: for each product, whether it is affected, not affected, fixed or under investigation, with an impact statement for products that are not affected and a remediation for products that are. Trivy and Grype can read it to suppress findings.

What is a CSAF provider?

A CSAF provider is an organization that publishes its own CSAF documents in a way tools can discover: a provider-metadata.json file, findable through security.txt, a well-known URL or a DNS name, and a directory or ROLIE feed of advisories. A trusted provider adds hashes, OpenPGP signatures and a published public key.

What did CSAF replace?

The Common Vulnerability Reporting Framework (CVRF), an XML format. CVRF 1.1 was published by ICASI in 2012, and CVRF 1.2 by OASIS in 2017. CSAF 2.0 moved to JSON and added profiles, product trees and distribution rules.

How do I write a CSAF advisory?

Most teams start in an editor such as Secvisogram, the BSI's web editor for CSAF, or generate the JSON from their own vulnerability tracking. Pick a profile, usually csaf_security_advisory, fill in the publisher, tracking data, product tree and vulnerabilities, validate it against the schema, and publish it through a provider.