138% more reported CVEs per day in 2026 than last year.New: always-on Fixboxes. Vulnerable dependencies, fixed and verified.

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, 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.

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.json at /.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.txt and changes.csv works 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.json there with the CSAF: 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_advisory profile
  • Validation against the schema and the tests in the standard
  • provider-metadata.json at /.well-known/csaf/
  • A CSAF: line in security.txt
  • A ROLIE feed, or a directory with index.txt and changes.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