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 (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:
- Security Advisory: The standard profile detailing a vulnerability, its CVSS score, and remediation steps.
- 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").
- 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 structure is the easy part. The difficult part for engineering organizations is consistently populating that structure.
You cannot hand-write CSAF JSON documents. If your product line is complex, the product_tree alone can span thousands of lines of JSON.
To adopt CSAF, your engineering organization must treat vulnerability advisories as . You need a pipeline that takes raw vulnerability data from your internal Jira/issue tracker (CVE ID, CVSS score, affected version branches) and automatically compiles it into valid CSAF 2.0 JSON. Furthermore, your CSAF generation engine must validate the output against the strict OASIS JSON schemas before publication.
Why CSAF is Inevitable
The shift from human-readable PDFs to machine-readable JSON is driven by necessity. Enterprise customers (and government procurement offices) are demanding automated VEX and CSAF documents to manage their massive supply chain risks.
Furthermore, as the EU Cyber Resilience Act enforcement begins, regulatory authorities like ENISA will likely require vulnerability reports to be submitted via APIs in standardized machine-readable formats. If your organization is not building the infrastructure to generate CSAF advisories today, you will be scrambling to comply with both customer demands and regulatory mandates tomorrow.