Vulnerabilities
CSAF: the Common Security Advisory Framework for machine-readable advisories
Security advisories used to be web pages and PDFs that someone had to read, product by product. The Common Security Advisory Framework (CSAF) is the OASIS standard that turns them into JSON documents a tool can fetch, validate and match against the products you run.
Updated
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 fourth Committee Specification Draft went through public review from October 23 to November 6, 2026, and 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,recommendedandunder_investigation. Remediations are categorized asvendor_fix,workaround,mitigation,no_fix_plannedornone_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.jsondescribes the publisher and where its advisories are. Tools find it through at least one of three routes: aCSAFfield in the domain's security.txt, the well-known URL/.well-known/csaf/provider-metadata.json, or the DNS namecsaf.data.security.in front of the domain. -
Advisories are listed either in folders per year with an
index.txtandchanges.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.jsonat 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
csaftools 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.
Moving from web pages and RSS feeds to CSAF
Most vendors move to CSAF in five steps: get the product and version list right, choose the CSAF role you need, publish the discovery files and a feed, generate advisories instead of writing them by hand, and add VEX and the archive last. Moving to CSAF is mostly not about JSON. It is about having a product list your advisories can point at, and a path machines can follow to find them.
Where most vendors start
The usual setup is an HTML page per advisory, sometimes a PDF, an RSS or Atom feed and a mailing list. People can read it. A tool on the customer's side cannot do much with it: there are no stable product identifiers, no affected or not-affected status per version, no way to discover all of a vendor's advisories, and no integrity check. The BSI describes the same problem: either there is an RSS feed to subscribe to, or new advisories only appear on a website that someone has to visit. Each part of the old setup has a CSAF counterpart:
| Legacy element | CSAF equivalent |
|---|---|
| Advisory web page | A CSAF document with the profile csaf_security_advisory |
| "Affected versions" in prose | product_tree plus product_status |
| RSS feed | A ROLIE feed, or a directory with index.txt and changes.csv |
| "Subscribe" page | provider-metadata.json and a discovery route |
| PDF signature, or none | Hashes and OpenPGP signatures (trusted provider) |
| "Last updated" text | tracking and revision_history |
An RSS feed is a delivery channel; CSAF is a format. The FIRST PSIRT Services Framework lists "web document, RSS feed, or subscription" as ways to deliver an advisory, and separately suggests publishing advisories "in a machine-readable format such as the Common Security Advisory Framework (CSAF)" so customers can consume them with automation. You can keep the feed.
Step 1: get the product list right first
The product_tree is where migrations fail. Before the first CSAF document, you need a canonical list of
products and versions that matches what customers see on their devices and in their asset inventories, ideally with
a CPE or package URL for each. It is the same list a PSIRT needs to know which versions a CVE
affects, which is why scaling a PSIRT starts with a per-version inventory. A
branch runs from vendor to product family to product to version:
"product_tree": {
"branches": [{
"category": "vendor",
"name": "Example Networks",
"branches": [{
"category": "product_family",
"name": "EX Series",
"branches": [{
"category": "product_name",
"name": "EX-200",
"branches": [{
"category": "product_version",
"name": "4.2.1",
"product": {
"product_id": "EX200-4.2.1",
"name": "Example Networks EX-200 4.2.1",
"product_identification_helper": {
"cpe": "cpe:2.3:o:example:ex-200_firmware:4.2.1:*:*:*:*:*:*:*"
}
}
}]
}]
}]
}]
}
For a product that contains open source components, the advisory names your product versions. The component inventory behind the decision, which versions contain the vulnerable library, is the SBOM (what is an SBOM?).
Step 2: choose your role
The five roles are described above. For a vendor, the choice comes down to three:
| Role | Choose it when | What it adds |
|---|---|---|
| CSAF publisher | You only need valid CSAF documents on your site, as a starting point | Valid documents over TLS; tools cannot discover them on their own |
| CSAF provider | Customers should fetch your advisories automatically: the realistic minimum | provider-metadata.json, a discovery route and a directory or ROLIE feed |
| CSAF trusted provider | Customers or authorities expect signed advisories | Hashes, OpenPGP signatures and a published public key |
Lister and aggregator are for coordinators, not vendors. The gocsaf/csaf tools include
csaf_provider, which implements a trusted provider, and csaf_checker, which tests a
provider setup against section 7 of the standard. Run the checker before you announce the feed.
Step 3: discovery and the feed
-
Publish
provider-metadata.jsonat/.well-known/csaf/on your domain. -
Point to it from security.txt.
RFC 9116 defines the file, and CSAF 2.0
requirement 8 adds the
CSAF:field, whose URL must start with https://.
Contact: mailto:[email protected]
Expires: 2027-11-11T00:00:00.000Z
# Our security advisories
CSAF: https://www.example.com/.well-known/csaf/provider-metadata.json
-
Replace the RSS feed with a ROLIE feed, or run both. ROLIE (Resource-Oriented Lightweight
Information Exchange, RFC 8322) is built on
Atom, so it is the natural successor to a feed you already publish. A directory with
index.txtandchanges.csvworks too. - Label every feed with a TLP level. CSAF 2.0 uses the TLP 1.0 labels WHITE, GREEN, AMBER and RED. FIRST's TLP 2.0, authoritative since August 2022, uses CLEAR, GREEN, AMBER and RED, with AMBER+STRICT as an extension of AMBER, and the CSAF 2.1 drafts adopt those labels. Public advisories are TLP:WHITE in CSAF 2.0.
Step 4: generate, don't hand-write
Generate new advisories from the record you already keep for each vulnerability, the case in your tracker or your
vulnerability database, and validate each one against the schema and the tests in the standard before it goes out.
Secvisogram works for low volume and for editing. Render the human-readable page from the same JSON document, so the
web page and the CSAF file never disagree. A revision updates tracking/version and
revision_history in the same document; you do not publish a new one.
Step 5: VEX and the archive
Publish not-affected statements as CSAF VEX for the CVEs customers ask about most, since every one of those stops a repeat question. Backfill older advisories last, starting with products still in support. If your old advisories are in CVRF, the specification's conversion rules cover them.
CSAF 2.0 or 2.1?
Publish 2.0 now. It is the approved OASIS Standard, and it is also published as an international standard,
ISO/IEC 20153:2025. CSAF 2.1 is still a Committee Specification Draft: the
fourth draft
was approved on October 21, 2026, and its public review closed on November 6, 2026. Tools are getting ready:
Secvisogram already edits 2.1 documents, while 2.1 support in the gocsaf/csaf tools is in development
for their next major version.
What the CRA and the BSI expect
- The Cyber Resilience Act does not name CSAF. Article 14(8) requires a manufacturer that becomes aware of an actively exploited vulnerability or a severe incident to inform the impacted users, and where appropriate all users, "where appropriate in a structured, machine-readable format that is easily automatically processable". Annex I, Part II, asks manufacturers to publicly disclose information about fixed vulnerabilities once a security update is available, and to have a policy on coordinated vulnerability disclosure. CSAF is one way to meet the machine-readable part.
-
The BSI publishes its own CERT-Bund advisories as CSAF. Its technical guideline
TR-03183-3 (Vulnerability Reports and
Notifications, v1.0.0, August 2025) names publication on the manufacturer's website using CSAF as the recommended
way to distribute advisories (section 3.1.5). It requires a security.txt file (section 4.2) and says the
manufacturer should list its
provider-metadata.jsonthere with theCSAF:field (section 4.2.8). A technical guideline is guidance, not law. - ENISA's Single Reporting Platform is for notifications to authorities under the CRA, not for advisories to users. Publishing a CSAF advisory does not replace a notification, and a notification does not inform your users.
A minimum viable CSAF setup
- A product and version list, with CPE or package URL identifiers where you have them
- Publisher metadata: name, category, namespace and contact details
- The first advisory in the
csaf_security_advisoryprofile - Validation against the schema and the tests in the standard
provider-metadata.jsonat/.well-known/csaf/- A
CSAF:line in security.txt - A ROLIE feed, or a directory with
index.txtandchanges.csv - TLS on every URL, without redirects
- The human-readable page rendered from the JSON
- A published signing key, once you move to trusted provider
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 does not write or publish advisories. It supplies the record an advisory's product status is built from. 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, and since when. 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, and also published as ISO/IEC 20153:2025. CSAF 2.1 is in progress: its fourth Committee Specification Draft was approved on October 21, 2026 and finished public review on November 6, 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.
How do we move our security advisories from a web page to CSAF?
Start with a canonical list of products and versions, then become a CSAF provider: publish provider-metadata.json, point to it from security.txt and list advisories in a ROLIE feed or a directory. Generate new advisories from your vulnerability records, render the web page from the same JSON, and backfill old advisories last.
Can we keep our RSS feed when we publish CSAF?
Yes. An RSS feed is a delivery channel and CSAF is a format, so the two can live side by side. If you want one feed for people and machines, a ROLIE feed is built on Atom and can replace the RSS feed. Generate both from the same advisory data so they never disagree.
Which CSAF role do we need: publisher, provider or trusted provider?
Most vendors need to be a CSAF provider: valid documents, provider-metadata.json, a discovery route and a directory or ROLIE feed, so customers can fetch advisories automatically. A publisher alone is a starting point that tools cannot discover. Become a trusted provider, with hashes, OpenPGP signatures and a public key, when customers or authorities expect signed advisories.
Does the Cyber Resilience Act require CSAF?
No. The CRA does not name a format. Article 14(8) asks manufacturers to inform impacted users of an actively exploited vulnerability or severe incident, where appropriate in a structured, machine-readable format that is easily automatically processable. CSAF is one way to meet that, and the format the BSI recommends.
What does the BSI expect from manufacturers about CSAF?
BSI TR-03183-3, a technical guideline rather than law, names publication on the manufacturer's website using CSAF as the recommended way to distribute advisories. It requires a security.txt file and says manufacturers should list their provider-metadata.json in it with the CSAF: field. The BSI publishes its own CERT-Bund advisories as CSAF.
Should we publish CSAF 2.0 or wait for 2.1?
Publish 2.0 now. It is the approved OASIS Standard and ISO/IEC 20153:2025, and the tools support it. CSAF 2.1 is still a Committee Specification Draft, with its fourth draft reviewed in October and November 2026. Moving to 2.1 later means updating your tooling, not a reason to wait.
Know which of your releases an advisory is about
An advisory starts with knowing which builds contain the vulnerable component. Book a demo to see it in the build history of your GitHub Actions builds.
Book a demo