What is CSAF 2.0? Machine-readable security advisories

For decades, the security advisory has been a PDF or a hastily formatted HTML page buried deep on a vendor's website. A security engineer at an enterprise would have to manually read these text documents, interpret the affected product versions, and manually cross-reference that information against their company's internal asset inventory to determine if they needed to patch.

This manual, human-centric approach to vulnerability disclosure is slow, error-prone, and entirely unscalable in an era of complex software supply chains.

The European Union's Cyber Resilience Act (CRA) explicitly encourages manufacturers to issue vulnerability disclosures in machine-readable formats. Enter CSAF (Common Security Advisory Framework), the standard developed by OASIS that is rapidly becoming the universal language for automated vulnerability communication.

Here is a technical deep dive into what CSAF is, how it works, and why your engineering team needs to start generating it.

What is CSAF?

The Common Security Advisory Framework (CSAF) Version 2.0 is a strictly defined JSON schema for creating machine-readable security advisories.

Instead of writing a paragraph saying "Our router model X is vulnerable to an XSS bug in firmware versions 1.2 to 1.4," a CSAF document encodes that assertion into a structured JSON payload. This allows automated vulnerability management systems, asset scanners, and continuous integration pipelines to ingest the advisory instantly and automatically flag vulnerable assets across a network without human intervention.

Currently, CSAF defines three primary document profiles:

1. Security Advisory: The standard profile detailing a vulnerability, its CVSS score, and remediation steps.
2. Vulnerability Exploitability eXchange (VEX): A specialized profile used to assert whether a product is actually affected by a known vulnerability in one of its components (e.g., "Yes, we ship the vulnerable Log4j library, but our configuration makes it impossible to exploit; therefore, Status: Not Affected").
3. Informational Advisory: Used for general security updates or bulletins that don't involve specific vulnerabilities.

The Anatomy of a CSAF 2.0 JSON Document

A CSAF JSON document is structured around three mandatory top-level objects: document, product_tree, and vulnerabilities. Let’s look at a simplified core structure.

{
  "document": { ... },
  "product_tree": { ... },
  "vulnerabilities": [ ... ]
}

1. The document Object (Metadata)

This section contains the administrative metadata about the advisory itself. It establishes who is publishing the information, when it was published, and how to track updates.

  "document": {
    "category": "csaf_security_advisory",
    "csaf_version": "2.0",
    "publisher": {
      "category": "vendor",
      "name": "Acme Widgets Corp",
      "namespace": "https://acmewidgets.com"
    },
    "title": "Buffer Overflow in Widget-Manager API",
    "tracking": {
      "current_release_date": "2025-02-15T12:00:00Z",
      "id": "ACME-SA-2025-001",
      "initial_release_date": "2025-02-15T12:00:00Z",
      "revision_history": [
        {
          "date": "2025-02-15T12:00:00Z",
          "number": "1",
          "summary": "Initial release."
        }
      ],
      "status": "final",
      "version": "1"
    }
  }

2. The product_tree Object (The Target)

This is the most critical and often the most complex part of a CSAF document. It exhaustively defines precisely which products, software packages, or hardware devices are being discussed in the advisory.

To enable automation, every distinct product variation (e.g., Widget-Manager v1.2 vs. Widget-Manager v1.3) must be assigned a unique product_id.

  "product_tree": {
    "branches": [
      {
        "category": "vendor",
        "name": "Acme",
        "branches": [
          {
            "category": "product_name",
            "name": "Widget-Manager",
            "branches": [
              {
                "category": "product_version",
                "name": "1.2.0",
                "product": {
                  "name": "Acme Widget-Manager 1.2.0",
                  "product_id": "CSAFPID-0001"
                }
              },
              {
                "category": "product_version",
                "name": "1.3.0",
                "product": {
                  "name": "Acme Widget-Manager 1.3.0",
                  "product_id": "CSAFPID-0002"
                }
              }
            ]
          }
        ]
      }
    ]
  }

Note: Advanced CSAF allows you to use CPEs (Common Platform Enumerations) or PURLs (Package URLs) to cryptographically link the product_id to exact software hashes or SBOM entries.

3. The vulnerabilities Object (The Threat and the Fix)

This array ties the vulnerabilities to the specific product_ids defined in the product_tree. It details the CVE, the CVSS scores, and the precise remediation status for every product node.

  "vulnerabilities": [
    {
      "cve": "CVE-2025-09999",
      "notes": [
        {
          "category": "description",
          "text": "A buffer overflow in the auth endpoint allows remote code execution."
        }
      ],
      "product_status": {
        "known_affected": [
          "CSAFPID-0001"
        ],
        "fixed": [
          "CSAFPID-0002"
        ]
      },
      "remediations": [
        {
          "category": "vendor_fix",
          "details": "Update to version 1.3.0 immediately.",
          "product_ids": [
            "CSAFPID-0001"
          ]
        }
      ],
      "scores": [
        {
          "cvss_v3": {
            "baseScore": 9.8,
            "baseSeverity": "CRITICAL",
            "vectorString": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
            "version": "3.1"
          },
          "products": [
            "CSAFPID-0001"
          ]
        }
      ]
    }
  ]

In this structure, a machine scanner can instantly read: CVE-2025-09999 affects CSAFPID-0001 (Widget-Manager 1.2.0) with a CVSS of 9.8. The fix is to upgrade, and it is resolved in CSAFPID-0002 (Widget-Manager 1.3.0).

The Operational Challenge for Engineering Teams

Understanding the JSON schema is simple. Populating that structure accurately and at scale is challenging.

Writing CSAF JSON by hand is impractical. For complex product lines, the product_tree alone spans thousands of lines of JSON.

Engineering teams must treat vulnerability advisories as structured data artifacts. Teams need automated pipelines that pull vulnerability data from internal issue trackers and compile valid CSAF 2.0 JSON. The generation pipeline must validate outputs against the OASIS JSON schema before publication.

Why CSAF is Essential

The transition from static text documents to machine-readable JSON is driven by automation requirements. Enterprise customers and government procurement bodies increasingly require automated VEX and CSAF feeds to monitor supply chain risk.

Under the EU Cyber Resilience Act, machine-readable vulnerability sharing accelerates coordinated response. Building CSAF generation capabilities now ensures readiness for both customer expectations and regulatory standards.