OASIS Common Security Advisory Framework (CSAF) TC
Omar Santos (osantos@cisco.com), Cisco
Langley Rock (lrock@redhat.com), Red Hat
Stefan Hagen (stefan@hagen.link), Individual
Thomas Schmidt (thomas.schmidt@bsi.bund.de), Federal Office for Information Security (BSI) Germany
In Memory of Eric Johnson, TIBCO Software inc., an active member of the OASIS CSAF Committee.
This prose specification is one component of a Work Product that also includes:
- JSON schema: csaf.json
- Other parts (list titles and/or file names)
(Note: Any normative computer language definitions that are part of the Work Product, such as XML instances, schemas and Java(TM) code, including fragments of such, must be (a) well formed and valid, (b) provided in separate plain text files, (c) referenced from the Work Product; and (d) where any definition in these separate files disagrees with the definition found in the specification, the definition in the separate file prevails. Remove this note before submitting for publication.)
This specification replaces or supersedes:
- The CSAF Common Vulnerability Reporting Framework (CVRF) Version 1.2. http://docs.oasis-open.org/csaf/csaf-cvrf/v1.2/csprd01/csaf-cvrf-v1.2-csprd01.html
This specification is related to:
- Related specifications (include hyperlink, preferably to HTML format)
(remove "Related work" section or the "replaces" or "related" subsections if no entries)
The Common Security Advisory Framework (CSAF) Version 2.0 is the definitive reference for the language which supports creation, update, and interoperable exchange of security advisories as structured information on products, vulnerabilities and the status of impact and remediation among interested parties.
This document was last revised or approved by the OASIS Common Security Advisory Framework (CSAF) TC on the above date. The level of approval is also listed above. Check the "Latest version" location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Technical Committee (TC) are listed at https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=openc2#technical.
TC members should send comments on this specification to the TC's email list. Others should send comments to the TC's public comment list, after subscribing to it by following the instructions at the "Send A Comment" button on the TC's web page at https://www.oasis-open.org/committees/openc2/.
This specification is provided under the Non-Assertion Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established. For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the TC's web page (https://www.oasis-open.org/committees/openc2/ipr.php).
Note that any machine-readable content (Computer Language Definitions) declared Normative for this Work Product is provided in separate plain text files. In the event of a discrepancy between any such plain text file and display content in the Work Product's prose narrative document(s), the content in the separate plain text file prevails.
Initial publication URI:
https://docs.oasis-open.org/tc-name/wp-abbrev-xxxxx/v1.0/csd01/wp-abbrev-xxxxx-v1.0-csd01.html
Permanent "Latest version" URI:
https://docs.oasis-open.org/tc-name/wp-abbrev-xxxxx/v1.0/wp-abbrev-xxxxx-v1.0.html
(Note: Publication URIs are managed by OASIS TC Administration; please don't modify.)
When referencing this specification the following citation format should be used:
[csaf-v2.0]
Common Security Advisory Framework Version 2.0. Edited by Langley Rock and Stefan Hagen. 00 Month 2021. OASIS Committee Specification Draft 01 / Public Review Draft 01. this-version.html. Latest version: latest-version.html.
Copyright © OASIS Open 2021. All Rights Reserved.
All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
As stated in the OASIS IPR Policy, the following three paragraphs in brackets apply to OASIS Standards Final Deliverable documents (Committee Specification, Candidate OASIS Standard, OASIS Standard, or Approved Errata).
[OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Standards Final Deliverable, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this deliverable.]
[OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this OASIS Standards Final Deliverable by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this OASIS Standards Final Deliverable. OASIS may include such claims on its website, but disclaims any obligation to do so.]
[OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this OASIS Standards Final Deliverable or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Standards Final Deliverable, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.]
The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark for above guidance.
[[TOC will be inserted here]]
Fixes in the css (shall) address:
- blockquotes shall maintain constant indentation
- code blocks shall expose block rectangle (not per line width right margin) - still unpatched
- Logo and title page shall not be within the table of content (manually removal required currently - maybe addressable by processor options or markup changes)
This specification is provided under the Non-Assertion Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established. For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the TC's web page (https://www.oasis-open.org/committees/openc2/ipr.php).
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] and [RFC8174] when, and only when, they appear in all capitals, as shown here.
For purposes of this document, the following terms and definitions apply:
advisory: reporting item that describes a condition present in an artifact and that requires action by the consumers
advisory document: artifact in which an analysis tool reports a result
advisory management system: software system that consumes the documents produced by analysis tools, produces advisories that enable engineering ad operating organizations to assess the quality of these software artifacts at a point in time, and performs functions such as filing security advisories and displaying information about individual advisories. Note: An advisory management system can interact with a document viewer to display information about individual advisories.
advisory matching: process of determining whether two advisories are targeting the same products and conditions
artifact: sequence of bytes addressable via a URI. Examples: A physical file in a file system such as a source file, an object file, a configuration file or a data file; a specific version of a file in a version control system; a database table accessed via an HTTP request; an arbitrary stream of bytes returned from an HTTP request, a product URL, a common product enumeration value.
CSAF asset matching system: program that connects to or is asset database and is able to manage CSAF documents as required by CSAF management system as well as matching them to assets of the asset database.
CSAF basic validator: A program that reads a document and checks it against the JSON schema and performs mandatory tests.
CSAF consumer: program that reads and interprets a CSAF document
CSAF content management system: program that is able to create, review and manage CSAF documents and is able to preview their details as required by CSAF viewer.
CSAF converter: CSAF producer that transforms the output of an analysis tool from its native output format into the CSAF format
CSAF direct producer: analysis tool which acts as a CSAF producer
CSAF document: security advisory text document in the format defined by this document.
CSAF extended validator: A CSAF basic validator that additionally performs optional tests.
CSAF full validator: A CSAF extended validator that additionally performs informative tests.
CSAF management system: program that is able to manage CSAF documents and is able to display their details as required by CSAF viewer.
CSAF modifier: CSAF post-processor which takes a CSAF document as input and modifies the structure or values of properties. The output is a valid CSAF document.
CSAF post-processor: CSAF producer that transforms an existing CSAF document into a new CSAF document, for example, by removing or redacting elements according to sharing policies.
CSAF producer: program that emits output in the CSAF format
CSAF translator: CSAF post-processor which takes a CSAF document as input and translates values of properties into another language. The output is a valid CSAF document.
CSAF viewer: CSAF consumer that reads a CSAF document, displays a list of the results it contains, and allows an end user to view each result in the context of the artifact in which it occurs.
CVRF CSAF converter: CSAF producer which takes a CVRF document as input and converts it into a valid CSAF document.
document: output file produced by an analysis tool, which enumerates the results produced by the tool
driver: tool component containing an analysis tool’s or converter’s primary executable, which controls the tool’s or converter’s execution, and which in the case of an analysis tool typically defines a set of analysis rules
embedded link: syntactic construct which enables a message string to refer to a location mentioned in the document
empty array: array that contains no elements, and so has a length of 0
empty object: object that contains no properties
empty string: string that contains no characters, and so has a length of 0
(end) user: person who uses the information in a document to investigate, triage, or resolve results
engineering system: software analysis environment within which analysis tools execute. Note: An engineering system might include a build system, a source control system, a result management system, a bug tracking system, a test execution system, and so on.
extension: tool component other than the driver (for example, a plugin, a configuration file, or a taxonomy)
external property file: file containing the values of one or more externalized properties
externalizable property: property that can be contained in an external property file
externalized property: property stored outside of the CSAF document to which it logically belongs
false positive: result which an end user decides does not actually represent a problem
fingerprint: stable value that can be used by a result management system to uniquely identify a result over time, even if a relevant artifact is modified
formatted message: message string which contains formatting information such as Markdown formatting characters
fully qualified logical name: string that fully identifies the programmatic construct specified by a logical location, typically by means of a hierarchical identifier.
hierarchical string: string in the format <component>{/<component>}*
line: contiguous sequence of characters, starting either at the beginning of an artifact or immediately after a newline sequence, and ending at and including the nearest subsequent newline sequence, if one is present, or else extending to the end of the artifact
line (number): 1-based index of a line within a file. Note: Abbreviated to "line" when there is no danger of ambiguity with "line" in the sense of a sequence of characters.
localizable: subject to being translated from one natural language to another
message string: human-readable string that conveys information relevant to an element in a CSAF document
nested artifact: artifact that is contained within another artifact
newline sequence: sequence of one or more characters representing the end of a line of text. Note: Some systems represent a newline sequence with a single newline character; others represent it as a carriage return character followed by a newline character.
notification: reporting item that describes a condition encountered by a tool during its execution
opaque: neither human-readable nor machine-parsable into constituent parts
parent (artifact): artifact which contains one or more nested artifacts
plain text message: message string which does not contain any formatting information
plugin: tool component that defines additional rules
policy: set of rule configurations that specify how results that violate the rules defined by a particular tool component are to be treated
problem: result which indicates a condition that has the potential to detract from the quality of the program. Examples: A security vulnerability, a deviation from contractual or legal requirements.
product: is any deliverable (e.g. software, hardware, specification,...) which can be referred to with a name. This applies regardless of the origin, the license model, or the mode of distribution of the deliverable.
property: attribute of an object consisting of a name and a value associated with the name
redactable property: property that potentially contains sensitive information that a CSAF direct producer or a CSAF post-processor might wish to redact
reporting item: unit of output produced by a tool, either a result or a notification
reporting configuration: the subset of reporting metadata that a tool can configure at runtime, before performing its scan. Examples: severity level, rank
repository container for a related set of files in a version control system
taxonomy: classification of analysis results into a set of categories
tag: string that conveys additional information about the CSAF document element to which it applies
text artifact: artifact considered as a sequence of characters organized into lines and columns
text region: region representing a contiguous range of zero or more characters in a text artifact
tool component: component of an analysis tool or converter, either its driver or an extension, consisting of one or more files
top-level artifact: artifact which is not contained within any other artifact
translation: rendering of a tool component's localizable strings into another language
triage: decide whether a result indicates a problem that needs to be corrected
user: see end user.
VCS: version control system
vendor: the community, individual, or organization that created or maintains a product (including open source software and hardware providers)
VEX: Vulnerability Exploitability eXchange - enables a supplier or other party to assert whether or not a particular product is affected by a specific vulnerability, especially helpful in efficiently consuming SBOM data.
viewer: see CSAF viewer.
XML: eXtensible Markup Language - the format used by the predecessors of this standard, namely CVRF 1.1 and CVRF 1.2.
JSON Schema: A Media Type for Describing JSON Documents, draft-handrews-json-schema-02, September 2019, https://json-schema.org/draft/2019-09/json-schema-core.html.
JSON Schema Validation: A Vocabulary for Structural Validation of JSON, draft-handrews-json-schema-validation-02, September 2019, https://json-schema.org/draft/2019-09/json-schema-validation.html.
JSON Hyper-Schema: A Vocabulary for Hypermedia Annotation of JSON, draft-handrews-json-schema-hyperschema-02, September 2019, https://json-schema.org/draft/2019-09/json-schema-hypermedia.html.
Relative JSON Pointers, draft-handrews-relative-json-pointer-02, September 2019, https://json-schema.org/draft/2019-09/relative-json-pointer.html.
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. http://www.ietf.org/rfc/rfc2119.txt.
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, http://www.rfc-editor.org/info/rfc8174.
T. Bray, Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 8259, DOI 10.17487/RFC8259, December 2017, http://www.rfc-editor.org/info/rfc8259.
Common Platform Enumeration: Applicability Language Specification Version 2.3 (NISTIR 7698), D. Waltermire, P. Cichonski, K. Scarfone, Editors, NIST Interagency Report 7698, August 2011, http://dx.doi.org/10.6028/NIST.IR.7698.
Common Platform Enumeration: Dictionary Specification Version 2.3, P. Cichonski, D. Waltermire, K. Scarfone, Editors, NIST Interagency Report 7697, August 2011, http://dx.doi.org/10.6028/NIST.IR.7697.
Common Platform Enumeration: Naming Matching Specification Version 2.3, M. Parmelee, H. Booth, D. Waltermire, K. Scarfone, Editors, NIST Interagency Report 7696, August 2011,http://dx.doi.org/10.6028/NIST.IR.7696.
Common Platform Enumeration: Naming Specification Version 2.3, B. Cheikes, D. Waltermire, K. Scarfone, Editors, NIST Interagency Report 7695, August 2011, http://dx.doi.org/10.6028/NIST.IR.7695.
Common Vulnerability and Exposures (CVE) – The Standard for Information Security Vulnerability Names, MITRE, 1999, https://cve.mitre.org/about/.
Common Vulnerability and Exposures (CVE) – The Standard for Information Security Vulnerability Names - CVE ID Syntax Change, MITRE, January 01, 2014, https://cve.mitre.org/cve/identifiers/syntaxchange.html.
The Common Vulnerability Reporting Framework (CVRF) Version 1.1, M. Schiffman, Editor, May 2012, Internet Consortium for Advancement of Security on the Internet (ICASI), http://www.icasi.org/the-common-vulnerability-reporting-framework-cvrf-v1-1/.
CSAF Common Vulnerability Reporting Framework (CVRF) Version 1.2. Edited by Stefan Hagen. 13 September 2017. OASIS Committee Specification 01. http://docs.oasis-open.org/csaf/csaf-cvrf/v1.2/cs01/csaf-cvrf-v1.2-cs01.html. Latest version: http://docs.oasis-open.org/csaf/csaf-cvrf/v1.2/csaf-cvrf-v1.2.html.
A Complete Guide to the Common Vulnerability Scoring System Version 2.0, P. Mell, K. Scarfone, S. Romanosky, Editors, First.org, Inc., June 2007, https://www.first.org/cvss/cvss-v2-guide.pdf.
Common Vulnerability Scoring System v3.0: Specification Document, FIRST.Org, Inc., June 2019, https://www.first.org/cvss/v3.0/cvss-v30-specification_v1.9.pdf.
Common Vulnerability Scoring System v3.1: Specification Document, FIRST.Org, Inc., June 2019, https://www.first.org/cvss/v3-1/cvss-v31-specification_r1.pdf.
Common Weakness Enumeration (CWE) – A Community-Developed List of Software Weakness Types, MITRE, 2005, http://cwe.mitre.org/about/.
CycloneDX Software Bill-of-Material Specification JSON schema version 1.3, cyclonedx.org, May 2021, https://github.com/CycloneDX/specification/blob/1.3/schema/bom-1.3.schema.json.
DCMI Metadata Terms v1.1, Dublin Core Metadata Initiative, DCMI Rec., June 14, 2012, http://dublincore.org/documents/2012/06/14/dcmi-terms/. Latest version available at http://dublincore.org/documents/dcmi-terms/.
GitHub's fork of cmark, a CommonMark parsing and rendering library and program in C, https://github.com/github/cmark.
GitHub Engineering: A formal spec for GitHub Flavored Markdown, https://githubengineering.com/a-formal-spec-for-github-markdown/.
Data elements and interchange formats — Information interchange — Representation of dates and times, International Standard, ISO 8601:2004(E), December 1, 2004, https://www.iso.org/standard/40874.html.
Information technology — IT asset management — Part 2: Software identification tag, International Standard, ISO 19770-2:2015, September 30, 2015, https://www.iso.org/standard/65666.html.
Information technology — Security techniques — Vulnerability disclosure, International Standard, ISO 29147:2014(E), February 15, 2014, https://www.iso.org/standard/45170.html.
GTLS/SSL and crypto library, OpenSSL Software Foundation, https://www.openssl.org/.
Package URL (PURL), GitHub Project, https://github.com/package-url/purl-spec
Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on Security Considerations", BCP 72, RFC 3552, DOI 10.17487/RFC3552, July 2003, https://www.rfc-editor.org/info/rfc3552.
N. Williams., "JavaScript Object Notation (JSON) Text Sequences", RFC 7464, DOI 10.17487/RFC7464, February 2015, http://www.rfc-editor.org/info/rfc7464.
The Technical Specification for the Security Content Automation Protocol (SCAP): SCAP Version 1.2, D. Waltermire, S. Quinn, K. Scarfone, A. Halbardier, Editors, NIST Spec. Publ. 800‑126 rev. 2, September 2011, http://dx.doi.org/10.6028/NIST.SP.800-126r2.
Foudil, E. and Shafranovich, Y., Security.txt Project, https://securitytxt.org/.
Semantic Versioning 2.0.0, T. Preston-Werner, June 2013, https://semver.org/.
The Software Package Data Exchange (SPDX®) Specification Version 2.2, Linux Foundation and its Contributors, 2020, https://spdx.github.io/spdx-spec/.
Vulnerability Exploitability eXchange (VEX) - Overview and Concepts, Draft version 0.3, VEX sub-group of the Framing Working Group in the NTIA SBOM initiative, 06 June 2021, TODO: add the link.
Extensible Markup Language (XML) 1.0 (Fifth Edition), T. Bray, J. Paoli, M. Sperberg-McQueen, E. Maler, F. Yergeau, Editors, W3C Recommendation, November 26, 2008, http://www.w3.org/TR/2008/REC-xml-20081126/. Latest version available at http://www.w3.org/TR/xml.
W3C XML Schema Definition Language (XSD) 1.1 Part 1: Structures, S. Gao, M. Sperberg-McQueen, H. Thompson, N. Mendelsohn, D. Beech, M. Maloney, Editors, W3C Recommendation, April 5, 2012, http://www.w3.org/TR/2012/REC-xmlschema11-1-20120405/. Latest version available at http://www.w3.org/TR/xmlschema11-1/.
W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes, D. Peterson, S. Gao, A. Malhotra, M. Sperberg-McQueen, H. Thompson, Paul V. Biron, Editors, W3C Recommendation, April 5, 2012, http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/. Latest version available at http://www.w3.org/TR/xmlschema11-2/.
Keywords defined by this specification use this monospaced
font.
Normative source code uses this paragraph style.
Text following the special symbol («) – an opening Guillemet (or French quotation mark) – within this specification identifies conformance statements. Every conformance statement is separated from the following text with the special end symbol (») – a closing Guillemet, and has been assigned a reference that follows that end symbol in the format [CSAF-section#-local#].
Some sections of this specification are illustrated with non-normative examples introduced with "Example" or "Examples" like so:
Examples:
Informative examples also use this paragraph style but preceded by the text "Example(s)".
All examples in this document are informative only.
All other text is normative unless otherwise labeled e.g. like:
Informative Comment:
This is a pure informative comment that may be present, because the information conveyed is deemed useful advice or common pitfalls learned from implementer or operator experience and often given including the rationale.
The Common Security Advisory Framework (CSAF) is a language to exchange Security Advisories formulated in JSON.
Informative Comment:
The term Security Advisory as used in this document describes any notification of security issues in products of and by providers. Anyone providing a product is considered in this document as a vendor, i.e. developers or maintainers of information system products or services. This includes all authoritative product vendors, Product Security Incident Response Teams (PSIRTs), and product resellers and distributors, including authoritative vendor partners. A security issue is not necessarily constraint to a problem statement, the focus of the term is on the security aspect impacting (or not impacting) specific product-platform-version combinations. Information on presence or absence of work-arounds is also considered part of the security issue. This document is the definitive reference for the language elements of CSAF version 2.0. The encompassing JSON schema file noted in the Additional Artifacts section of the title page shall be taken as normative in the case a gap or an inconsistency in this explanatory document becomes evident. The following presentation in this section is grouped by topical area, and is not simply derivative documentation from the schema document itself. The information contained aims to be more descriptive and complete. Where applicable, common conventions are stated and known common issues in usage are pointed out informatively to support implementers of document producers and consumers alike. The section SCHEMA_SECTION_NUMBER Schema derives from the JSON schema itself as a service for the reader.
« From a high-level perspective, any Security Advisory purported by a CSAF version 2.0 adhering JSON text document MUST provide the document
member with at least the following five properties defined: category
, csaf_version
, title
, publisher
, and tracking
. » [CSAF-2-1]
This minimal required information set does not provide any useful information on products, vulnerabilities, or security advisories. Thus, any real-world Security Advisory will carry additional information as specified in SCHEMA_SECTION_NUMBER section Schema.
Care has been taken, to design the containers for product and vulnerability information to support fine-grained mapping of security advisories onto product and vulnerability and minimize data duplication through referencing. The display of the elements representing Product Tree and Vulnerability information has been placed in the sections named accordingly.
As the JSON format is not primarily targeting human readers but more programs parsing, validating and transforming no example is given in this introduction but instead examples derived from several real-world security advisories are stated in the non-normative Appendix E Complete Examples.
A Security Advisory defined as a CSAF document is the result of complex orchestration of many players and distinct and partially difficult to play schemas.
The format chosen is [JSONSchema] which allows validation and delegation to sub schema providers. The latter aligns well with separation of concerns and shares the format family of information interchange utilized by the providers of product and vulnerability information which migrated from XML to JSON since the creation of CSAF CVRF version 1.2, the predecessor of this specification.
The acronym CSAF, “Common Security Advisory Framework”, stands for the target of concerted mitigation and remediation accomplishment.
Technically the use of JSON schema allows validation and proof of model conformance (through established schema based validation) of the declared information inside CSAF documents.
The CSAF schema structures its derived documents into three main classes of the information conveyed:
- The frame, aggregation, and reference information of the document
- Product information considered relevant by the creator
- Vulnerability information and its relation to the products declared in 2.
Wherever possible repetition of data has been replaced by linkage through ID elements. Consistency on the content level thus is in the responsibility of the producer of such documents, to link e.g. vulnerability information to the matching product.
A dictionary like presentation of all defined schema elements is given in the section SCHEMASECTIONNUMBER Schema. Any expected relations to other elements (linkage) is described there. This linking relies on setting attribute values accordingly (mostly guided by industry best practice and conventions) and thus implies, that any deep validation on a semantic level is to be ensured by the producer and consumer of CSAF documents. It is out of scope for this specification.
Proven and intended usage patterns from practice are given where possible.
Delegation to industry best practices technologies is used in referencing schemas for:
- Platform Data:
- Common Platform Enumeration (CPE) Version 2.3 [CPE23-N]
- Vulnerability Scoring:
- Common Vulnerability Scoring System (CVSS) Version 3.1 [CVSS31]
- JSON Schema Reference https://www.first.org/cvss/cvss-v3.1.json
- Common Vulnerability Scoring System (CVSS) Version 3.0 [CVSS30]
- JSON Schema Reference https://www.first.org/cvss/cvss-v3.0.json
- Common Vulnerability Scoring System (CVSS) Version 2.0 [CVSS2]
- JSON Schema Reference https://www.first.org/cvss/cvss-v2.0.json
- Common Vulnerability Scoring System (CVSS) Version 3.1 [CVSS31]
- Vulnerability Classification
- Common Weakness Enumeration (CWE) [CWE]
- CWE List: http://cwe.mitre.org/data/index.html
- Common Weakness Enumeration (CWE) [CWE]
- Classfication for Document Distribution
- Traffic Light Protocol (TLP)
- Default Definition: https://www.first.org/tlp/
- Traffic Light Protocol (TLP)
The CSAF schema describes how to represent security advisory information as a JSON document.
The CSAF schema Version 2.0 builds on the JSON Schema draft 2019-09 rules.
"$schema": "https://json-schema.org/draft/2019-09/schema"
The schema identifier is (before publication):
"$id": "https://raw.githubusercontent.com/oasis-tcs/csaf/master/csaf_2.0/json_schema/csaf_json_schema.json"
The further documentation of the schema is organized via Definitions and Properties.
- Definitions provide types that extend the JSON schema model
- Properties use these types to support assembling security advisories
Types and properties together provide the vocabulary for the domain specific language supporting security advisories.
The single mandatory property is document
.
The optional two additional properties are product_tree
and vulnerabilities
.
The definitions ($defs
) introduce the following domain specific types into the CSAF language:
Acknowledgments (acknowledgments_t
), Branches (branches_t
), Full Product Name (full_product_name_t
), Language (lang_t
), Notes (notes_t
),
Product Group ID (product_group_id_t
), Product Groups (product_groups_t
), Product ID (product_id_t
), Products (products_t
), References (references_t
),
and Version (version_t
).
"$defs": {
"acknowledgments_t": {
// ...
},
"branches_t": {
// ...
},
"full_product_name_t": {
// ...
},
"lang_t": {
// ...
},
"notes_t": {
// ...
},
"product_group_id_t": {
// ...
},
"product_groups_t": {
// ...
},
"product_id_t": {
// ...
},
"products_t": {
// ...
},
"references_t": {
// ...
},
"version_t": {
// ...
}
},
List of Acknowledgments (acknowledgments_t
) type instances of value type array with 1 or more elements contain a list of Acknowledgment
elements.
"acknowledgments_t": {
// ...
"items": {
// ...
}
},
The value type of Acknowledgment is object
with at least 1 and at most 4 properties. Every such element acknowledges contributions by describing those that contributed.
The properties are: names
, organization
, summary
, and urls
.
"properties": {
"names": {
// ...
},
"organization": {
// ...
},
"summary": {
// ...
},
"urls": {
// ...
}
}
List of acknowledged names (names
) has value type array
with 1 or more items holds the names of entities being recognized.
Every such item of value type string
with 1 or more characters represents the name of entity being recognized and contains the name of a single person.
Examples:
Johann Sebastian Bach
Albert Einstein
The contributing organization (organization
) has value type string
with 1 or more characters and holds the name of the contributing organization being recognized.
Examples:
CISA
Talos
Google Project Zero
Summary of the acknowledgment (summary
) of value type string
with 1 or more characters SHOULD represent any contextual details the document producers wish to make known about the acknowledgment or acknowledged parties.
Example:
First analysis of Coordinated Multi-Stream Attack (CMSA)
List of URLs (urls
) of acknowledgment is a container (value type array
) for 1 or more string
of type URL that specifies a list of URLs or location of the reference to be acknowledged.
Any URL of acknowledgment contains the URL or location of the reference to be acknowledged.
Value type is string with format URI (uri
).
Example:
"acknowledgments": [
{
"names": [
"Johann Sebastian Bach",
"Georg Philipp Telemann",
"Georg Friedrich Händel"
],
"organization": "Baroque composers",
"summary": "wonderful music"
},
{
"organization": "CISA"
"summary": "coordination efforts",
"urls": [
"https://cisa.gov"
]
},
{
"organization": "BSI",
"summary": "assistance in coordination"
},
{
"names": [
"Antonio Vivaldi"
],
"summary": "influencing other composers"
},
]
The example above should lead to the following outcome in a human-readable advisory:
We thank the following parties for their efforts:
- Johann Sebastian Bach, Georg Philipp Telemann, Georg Friedrich Händel from Baroque composers for wonderful music
- CISA for coordination efforts (see: https://cisa.gov)
- BSI for assistance in coordination
- Antonio Vivaldi for influencing other composers
List of branches (branches_t
) with value type array
contains 1 or more branch elements as children of the current element.
"branches_t": {
//...
"items": {
// ...
}
},
Every Branch holds exactly 3 properties and is a part of the hierarchical structure of the product tree.
The properties name
and category
are mandatory. In addition, the object contains either a branches
or a product
property.
"properties": {
"branches": {
// ...
},
"category": {
// ...
},
"name": {
// ...
},
"product": {
// ...
}
}
List of branches (branches
) has the value type branches_t
.
Category of the branch (category
) of value type string
as enum
describes the characteristics of the labeled branch.
Valid enum
values are:
architecture
host_name
language
legacy
patch_level
product_family
product_name
product_version
service_pack
specification
vendor
The value architecture
indicates the architecture for which the product is intended.
The value host_name
indicates the host name of a system/service.
The value language
indicates the language of the product.
The value legacy
indicates an entry that has reached its end of life.
The value patch_level
indicates the patch level of the product.
The value product_family
indicates the product family that the product falls into.
The value product_name
indicates the name of the product.
The value product_version
indicates the product version, can be numeric or some other descriptor.
The value service_pack
indicates the service pack of the product.
The value specification
indicates the specification such as a standard, best common practice, etc.
The value vendor
indicates the name of the vendor or manufacturer that makes the product.
Name of the branch (name
) of value type string with 1 character or more contains the canonical descriptor or 'friendly name' of the branch.
Examples:
Microsoft
Siemens
Windows
Office
SIMATIC
10
365
PCS 7
Product (product
) has the value type Full Product Name (full_product_name_t
).
Full Product Name (full_product_name_t
) with value type object
specifies information about the product and assigns the product ID.
The properties name
and product_id
are required. The property product_identification_helper
is optional.
"full_product_name_t": {
// ...
"properties": {
"name": {
// ...
},
"product_id": {
// ...
},
"product_identification_helper": {
// ...
}
}
},
Textual description of the product (name
) has value type string
with 1 or more characters.
The value should be the product's full canonical name, including version number and other attributes, as it would be used in a human-friendly document.
Examples:
Microsoft Host Integration Server 2006 Service Pack 1
Cisco AnyConnect Secure Mobility Client 2.3.185
Product ID (product_id
) holds a value of type Product ID (product_id_t
).
Helper to identify the product (product_identification_helper
) of value type object
provides in its properties at least one method which aids in identifying the product in an asset database.
Of the given seven properties cpe
, hashes
, purl
, sbom_urls
, serial_numbers
, skus
and x_generic_uris
, one is mandatory.
"product_identification_helper": {
// ...
"properties": {
"cpe": {
// ...
},
"hashes": {
// ...
},
"purl": {
// ...
},
"sbom_urls": {
// ...
},
"serial_numbers": {
// ...
},
"skus": {
// ...
},
"x_generic_uris": {
// ...
}
}
Common Platform Enumeration representation (cpe
) of value type string
of 5 or more characters with pattern
(regular expression):
^(cpe:2\\.3:[aho\\*\\-](:(((\\?*|\\*?)([a-zA-Z0-9\\-\\._]|(\\\\[\\\\\\*\\?!\"#\\$%&'\\(\\)\\+,/:;<=>@\\[\\]\\^`\\{\\|\\}~]))+(\\?*|\\*?))|[\\*\\-])){5}(:(([a-zA-Z]{2,3}(-([a-zA-Z]{2}|[0-9]{3}))?)|[\\*\\-]))(:(((\\?*|\\*?)([a-zA-Z0-9\\-\\._]|(\\\\[\\\\\\*\\?!\"#\\$%&'\\(\\)\\+,/:;<=>@\\[\\]\\^`\\{\\|\\}~]))+(\\?*|\\*?))|[\\*\\-])){4})|([c][pP][eE]:/[AHOaho]?(:[A-Za-z0-9\\._\\-~%]*){0,6})$
The Common Platform Enumeration (CPE) attribute refers to a method for naming platforms external to this specification. See [CPE23-N] for details.
List of hashes (hashes
) of value type array
holding at least one item contains a list of cryptographic hashes usable to identify files.
"hashes": {
// ...
"items": {
// ...
}
}
Cryptographic hashes of value type object
contains all information to identify a file based on its cryptographic hash values.
Any cryptographic hashes object has the 2 mandatory properties file_hashes
and filename
.
"properties": {
"file_hashes": {
// ...
},
"filename": {
// ...
}
}
List of file hashes (file_hashes
) of value type array
holding at least one item contains a list of cryptographic hashes for this file.
"file_hashes": {
// ...
"items": {
// ...
}
}
Each File hash of value type object
contains one hash value and algorithm of the file to be identified. Any File hash object has the 2 mandatory properties algorithm
and value
.
"properties": {
"algorithm": {
// ...
},
"value": {
// ...
}
}
The algorithm of the cryptographic hash representation (algorithm
) of type string
with one or more characters contains the name of the cryptographic hash algorithm used to calculate the value.
The default value for algorithm
is sha256
.
Examples:
sha256
sha384
sha512
sha3-512
blake2b512
These values are derived from the currently supported digests OpenSSL [OPENSSL]. Leading dashs were removed.
The command
openssl dgst -list
(Version 1.1.1f from 2020-03-31) outputs the following:Supported digests: -blake2b512 -blake2s256 -md4 -md5 -md5-sha1 -ripemd -ripemd160 -rmd160 -sha1 -sha224 -sha256 -sha3-224 -sha3-256 -sha3-384 -sha3-512 -sha384 -sha512 -sha512-224 -sha512-256 -shake128 -shake256 -sm3 -ssl3-md5 -ssl3-sha1 -whirlpool
The Value of the cryptographic hash representation (value
) of value type string
of 32 or more characters with pattern
(regular expression):
^[0-9a-fA-F]{32,}$
The Value of the cryptographic hash attribute contains the cryptographic hash value in hexadecimal representation.
Examples:
4775203615d9534a8bfca96a93dc8b461a489f69124a130d786b42204f3341cc
9ea4c8200113d49d26505da0e02e2f49055dc078d1ad7a419b32e291c7afebbb84badfbd46dec42883bea0b2a1fa697c
37df33cb7464da5c7f077f4d56a32bc84987ec1d85b234537c1c1a4d4fc8d09dc29e2e762cb5203677bf849a2855a0283710f1f5fe1d6ce8d5ac85c645d0fcb3
The filename representation (filename
) of type string
with one or more characters contains the name of the file which is identified by the hash values.
Examples:
WINWORD.EXE
msotadddin.dll
sudoers.so
If the value of the hash matches and the filename does not, a user should prefer the hash value. In such cases, the filename should be used as informational property.
The package URL (PURL) representation (purl
) is a string
of 4 or more characters with pattern
(regular expression):
^pkg:
This package URL (PURL) attribute refers to a method for reliably identifying and locating software packages external to this specification. See [PURL] for details.
The list of SBOM URLs (sbom_urls
) of value type array
with 1 or more items contains a list of URLs where SBOMs for this product can be retrieved.
The SBOMs might differ in format or depth of detail. Currently supported formats are SPDX, CycloneDX, and SWID.
"sbom_urls": {
//...
"items": {
//...
}
}
Any given SBOM URL of value type string
and format uri
contains a URL of one SBOM for this product.
The list of serial numbers (serial_numbers
) of value type array
with 1 or more items contains a list of parts, or full serial numbers.
A list of serial numbers SHOULD only be used if a certain range of serial numbers with its corresponding software version is affected, or the serial numbers change during update.
"serial_numbers": {
//...
"items": {
//...
}
}
Any given serial number of value type string
with at least 1 character represents a part, or a full serial number of the component to identify.
If a part of a serial number of the component to identify is given, it SHOULD begin with the first character of the serial number and stop at any point.
Characters which should not be matched MUST be replaced by either ?
(for a single character) or *
(for zero or more characters).
Two *
MUST NOT follow each other.
The list of stock keeping units (skus
) of value type array
with 1 or more items contains a list of parts, or full stock keeping units.
A list of stock keeping units SHOULD only be used if the list of relationships is used to decouple e.g. hardware from the software, or the stock keeping units change during update. In the latter case the remediations SHALL include the new stock keeping units is or a description how it can be obtained.
The use of the list of relationships in the first case is important. Otherwise, the end user is unable to identify which version (the affected or the not affected / fixed one) is used.
"skus": {
//...
"items": {
//...
}
}
Any given stock keeping unit of value type string
with at least 1 character represents a part, or a full stock keeping unit (SKU) of the component to identify.
Sometimes this is also called "item number", "article number" or "product number".
If a part of a stock keeping unit of the component to identify is given, it SHOULD begin with the first character of the stock keeping unit and stop at any point.
Characters which should not be matched MUST be replaced by either ?
(for a single character) or *
(for zero or more characters).
Two *
MUST NOT follow each other.
List of generic URIs (x_generic_uris
) of value type array
with at least 1 item contains a list of identifiers which are either vendor-specific or derived from a standard not yet supported.
"x_generic_uris": {
// ...
"items": {
// ...
}
}
Any such Generic URI item of value type object
provides the two mandatory properties Namespace (namespace
) and URI (uri
).
"properties": {
"namespace": {
// ...
},
"uri": {
// ...
}
}
The namespace of the generic URI (namespace
) of value type string
and format uri
refers to a URL which provides the name and knowledge about the specification used or is the namespace in which these values are valid.
The URI (uri
) of value type string
and format uri
contains the identifier itself.
Language type (lang_t
) has value type string
with pattern
(regular expression):
^[a-zA-Z]{2,3}(-.+)?$
The value identifies a language, corresponding to IETF BCP 47 / RFC 5646. See IETF language registry: https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry
Examples:
de
en
fr
frc
jp
List of notes (notes_t
) of value type array
with 1 or more items of type Note
contains notes which are specific to the current context.
"notes_t": {
// ..
"items": {
// ...
}
},
Value type of every such Note item is object
with the mandatory properties category
and text
providing a place to put all manner of text blobs related to the current context.
A Note object
may provide the optional properties audience
and title
.
"properties": {
"audience": {
// ...
},
"category": {
// ...
},
"text": {
// ...
},
"title": {
// ...
}
}
Audience of note (audience
) of value type string
with 1 or more characters indicates who is intended to read it.
Examples:
all
executives
operational management and system administrators
safety engineers
Note category (category
) of value type string
as enum
indicates the choice of what kind of note this is.
Valid enum
values are:
description
details
faq
general
legal_disclaimer
other
summary
The value description
indicates the note is a description of something. The optional sibling property title
MAY have more information in this case.
The value details
indicates the note is a low-level detailed discussion. The optional sibling property title
MAY have more information in this case.
The value faq
indicates the note is a list of frequently asked questions.
The value general
indicates the note is a general, high-level note. The optional sibling property title
MAY have more information in this case.
The value legal_disclaimer
indicates the note represents any possible legal discussion, including constraints, surrounding the document.
The value other
indicates the note is something that doesn’t fit the other categories. The optional sibling attribute title
SHOULD have more information to indicate clearly what kind of note to expect in this case.
The value summary
indicates the note is a summary of something. The optional sibling property title
MAY have more information in this case.
Note contents (text
) of value type string
with 1 or more characters holds the contents of the note. Content varies depending on type.
Title of note (title
) of value type string
with 1 or more characters provides a concise description of what is contained in the text of the note.
Examples:
Details
Executive summary
Technical summary
Impact on safety systems
The Product Group ID Type (product_group_id_t
) of value type string
with 1 or more characters is a reference token for product group instances.
The value is a token required to identify a group of products so that it can be referred to from other parts in the document.
There is no predefined or required format for the Product Group ID (product_group_id
) as long as it uniquely identifies a product group in the context of the current document.
"product_group_id_t": {
// ...
},
Examples:
CSAFGID-0001
CSAFGID-0002
CSAFGID-0020
Even though the standard does not require a specific format it is recommended to use different prefixes for the Product ID and the Product Group ID to support reading and parsing the document.
List of Product Group ID (product_groups_t
) of value type array
with 1 or more unique items (a set
) of type Product Group ID (product_group_id_t
) specifies a list of product_group_ids
to give context to the parent item.
"product_groups_t": {
// ...
"items": {
// ...
}
},
The Product ID Type (product_id_t
) of value type string
with 1 or more characters is a reference token for product instances.
The value is a token required to identify a full_product_name
so that it can be referred to from other parts in the document. There is no predefined or required format for the Product ID (product_id
) as long as it uniquely identifies a product in the context of the current document.
"product_id_t": {
// ...
},
Examples:
CSAFPID-0004
CSAFPID-0008
Even though the standard does not require a specific format it is recommended to use different prefixes for the Product ID and the Product Group ID to support reading and parsing the document.
List of Product IDs (products_t
) of value type array
with 1 or more unique items (a set
) of type Product ID (product_id_t
) specifies a list of product_ids
to give context to the parent item.
"products_t": {
// ...
"items": {
// ...
}
},
List of references (references_t
) of value type array
with 1 or more items of type Reference holds a list of Reference objects.
"references_t": {
// ...
"items": {
// ...
}
}
},
Value type of every such Reference item is object
with the mandatory properties url
and summary
holding any reference to conferences, papers, advisories, and other resources that are related and considered related to either a surrounding part of or the entire document and to be of value to the document consumer.
A reference object
may provide the optional property category
.
"properties": {
"category": {
// ...
},
"summary": {
// ...
},
"url": {
// ...
}
}
Category of reference (category
) of value type string
as enum
indicates whether the reference points to the same document or vulnerability in focus (depending on scope) or to an external resource.
Valid enum
values are:
external
self
The default value for category
is external
.
The value external
indicates, that this document is an external reference to a document or vulnerability in focus (depending on scope).
The value self
indicates, that this document is a reference to this same document or vulnerability (also depending on scope).
Summary of the reference (summary
) of value type string
with 1 or more characters indicates what this reference refers to.
URL of reference (url
) of value type string
and format uri
provides the URL for the reference.
The Version (version_t
) type has value type string
with pattern
(regular expression):
^(0|[1-9][0-9]*)$|^((0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?)$
The version specifies a version string to denote clearly the evolution of the content of the document. There are two options how it can be used:
- semantic versioning (preferred; according to the rules below)
- integer versioning
A CSAF document MUST use only one versioning system.
Examples:
1
4
0.9.0
1.4.3
2.40.0+21AF26D3
Integer versioning increments for each version where the /document/tracking/status
is final
the version number by one. The regular expression for this type is:
^(0|[1-9][0-9]*)$
The following rules apply:
- Once a versioned document has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version.
- Version zero (0) is for initial development before the
initial_release_date
. The document status MUST bedraft
. Anything MAY change at any time. The document SHOULD NOT be considered stable. - Version 1 defines the initial public release. Each new version where
/document/tracking/status
isfinal
has a version number incremented by one. - Pre-release versions (document status
draft
) MUST carry the new version number. Sole exception is before the initial release (see rule 2). The combination of document statusdraft
and version 1 MAY be used to indicate that the content is unlikely to change. - Build metadata is never included in the version.
- Precedence MUST be calculate by integer comparison.
Semantic versioning derived the rules from [SemVer]. The regular expression for this type is:
^((0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?)$
The goal of this structure is to provide additional information to the end user whether a new comparison with the asset database is needed. The "public API" in regards to CSAF is the CSAF document with its structure and content. This results in the following rules:
-
A normal version number MUST take the form X.Y.Z where X, Y, and Z are non-negative integers, and MUST NOT contain leading zeroes. X is the major version, Y is the minor version, and Z is the patch version. Each element MUST increase numerically. For instance: 1.9.0 -> 1.10.0 -> 1.11.0.
-
Once a versioned document has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version.
-
Major version zero (0.y.z) is for initial development before the
initial_release_date
. The document status MUST bedraft
. Anything MAY change at any time. The document SHOULD NOT be considered stable. Changes which would increment the major version according to rule 7 are tracked in this stage with (0.y.z) by incrementing the minor version y instead. Changes that would increment the minor or patch version according to rule 6 or 5 are both tracked in this stage with (0.y.z) by incrementing the patch version z instead. -
Version 1.0.0 defines the initial public release. The way in which the version number is incremented after this release is dependent on the content and structure of the document and how it changes.
-
Patch version Z (x.y.Z | x > 0) MUST be incremented if only backwards compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behavior.
In the context of the document this is the case e.g. for spelling mistakes.
-
Minor version Y (x.Y.z | x > 0) MUST be incremented if the content of an existing element changes except for those which are covert through rule 7. It MUST be incremented if substantial new information are introduced or new elements are provided. It MAY include patch level changes. Patch version MUST be reset to 0 when minor version is incremented.
-
Major version X (X.y.z | X > 0) MUST be incremented if a new comparison with the end user's asset database is required. This includes:
- changes (adding, removing elements or modifying content) in
/product_tree
or elements which contain/product_tree
in their path - adding or removing items of
/vulnerabilities
- adding or removing elements in:
/vulnerabilities[]/product_status/first_affected
/vulnerabilities[]/product_status/known_affected
/vulnerabilities[]/product_status/last_affected
- removing elements from:
/vulnerabilities[]/product_status/first_fixed
/vulnerabilities[]/product_status/fixed
/vulnerabilities[]/product_status/known_not_affected
It MAY also include minor and patch level changes. Patch and minor version MUST be reset to 0 when major version is incremented.
- changes (adding, removing elements or modifying content) in
-
A pre-release version (document status
draft
) MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.– -
Pre-release MUST NOT be included if
/document/tracking/status
isfinal
. -
Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3—-117B344092BD.
-
Precedence refers to how versions are compared to each other when ordered.
-
Precedence MUST be calculated by separating the version into major, minor, patch and pre-release identifiers in that order (Build metadata does not figure into precedence).
-
Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Major, minor, and patch versions are always compared numerically.
Example:
1.0.0 < 2.0.0 < 2.1.0 < 2.1.1
-
When major, minor, and patch are equal, a pre-release version has lower precedence than a normal version:
Example:
1.0.0-alpha < 1.0.0
-
Precedence for two pre-release versions with the same major, minor, and patch version MUST be determined by comparing each dot separated identifier from left to right until a difference is found as follows:
- Identifiers consisting of only digits are compared numerically.
- Identifiers with letters or hyphens are compared lexically in ASCII sort order.
- Numeric identifiers always have lower precedence than non-numeric identifiers.
- A larger set of pre-release fields has a higher precedence than a smaller set, if all of the preceding identifiers are equal.
Example:
1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0
-
These final three subsections document the three properties of a CSAF document. The single mandatory property document
, as well as the optional properties product_tree
and vulnerabilities
in that order.
Document level meta-data (document
) of value type object
with the 5 mandatory properties Category (category
), CSAF Version (csaf_version
), Publisher (publisher
), Title (title
), and Tracking (tracking
) captures the meta-data about this document describing a particular set of security advisories.
In addition, the document
object may provide the 7 optional properties Acknowledgments (acknowledgments
), Aggregate Severity (aggregate_severity
), Distribution (distribution
), Language (lang
), Notes (notes
), References (references
), and Source Language (source_lang
).
"document": {
// ...
"properties": {
"acknowledgments": {
// ...
},
"aggregate_severity" : {
// ...
},
"category": {
// ...
},
"csaf_version": {
// ...
},
"distribution": {
// ...
},
"lang": {
// ...
},
"notes": {
// ...
},
"publisher": {
// ...
},
"references": {
// ...
},
"source_lang": {
// ...
},
"title": {
// ...
},
"tracking": {
// ...
}
}
},
List of acknowledgments (acknowledgments
) of value type acknowledgments_t
contains a list of acknowledgment elements.
"acknowledgments": {
// ...
},
Aggregate severity (aggregate_severity
) of value type object
with the mandatory property text
and the optional property namespace
is a vehicle that is provided by the document producer to convey the urgency and criticality with which the one or more vulnerabilities reported should be addressed. It is a document-level metric and applied to the document as a whole — not any specific vulnerability. The range of values in this field is defined according to the document producer's policies and procedures.
"aggregate_severity": {
// ...
"properties": {
"namespace": {
// ...
},
"text": {
// ...
}
}
},
The Namespace of aggregate severity (namespace
) of value type string
and format uri
points to the namespace so referenced.
The Text of aggregate severity (text
) of value type string
with 1 or more characters provides a severity which is independent of - and in addition to - any other standard metric for determining the impact or severity of a given vulnerability (such as CVSS).
Examples:
Moderate
Important
Critical
Document category (category
) with value type string
of 1 or more characters defines a short canonical name, chosen by the document producer, which will inform the end user as to the category of document.
It is directly related to the profiles defined in section 5.
"category": {
// ...
}
Examples:
Example Company Security Notice
generic_csaf
security_advisory
vex
CSAF version (csaf_version
) of value type string
and enum
gives the version of the CSAF specification which the document was generated for.
The single valid value for this enum
is:
2.0
Rules for sharing document (distribution
) of value type object
with at least 1 of the 2 properties Text (text
) and Traffic Light Protocol TLP (tlp
) describes any constraints on how this document might be shared.
"distribution": {
// ...
"properties": {
"text": {
// ...
},
"tlp": {
// ...
}
}
},
The Textual description (text
) of value type string
with 1 or more characters provides a textual description of additional constraints.
Examples:
Share only on a need-to-know-basis only.
Distribute freely.
Copyright 2019, Example Company, All Rights Reserved.
Traffic Light Protocol (TLP) (tlp
) of value type object
with the mandatory property Label (label
) and the optional property URL (url
) provides details about the TLP classification of the document.
"tlp": {
// ...
"properties": {
"label": {
// ...
},
"url": {
// ...
}
}
}
The Label of TLP (label
) with value type string
and enum
provides the TLP label of the document.
Valid values of the enum
are:
RED
AMBER
GREEN
WHITE
The URL of TLP version (url
) with value type string
and format uri
provides a URL where to find the textual description of the TLP version which is used in this document. The default value is the URL to the definition by FIRST:
https://www.first.org/tlp/
Examples:
https://www.us-cert.gov/tlp
https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Kritis/Merkblatt_TLP.pdf
Document language (lang
) of Language Type (lang_t
) identifies the language used by this document, corresponding to IETF BCP 47 / RFC 5646.
Notes (notes
) associated with the whole document of Notes Type (notes_t
) holds notes about this set of vulnerabilities.
Publisher (publisher
) has value type object
with the mandatory properties Category (category
), Name (name
) and Namespace (namespace
) and provides information on the publishing entity.
The 2 other optional properties are: contact_details
and issuing_authority
.
"publisher": {
// ...
"properties": {
"category": {
// ...
},
"contact_details": {
// ...
},
"issuing_authority": {
// ...
},
"name": {
// ...
}
"namespace": {
// ...
}
}
},
The Category of publisher (category
) of type string
and enum
provides information about the category of publisher releasing the document.
The valid values are:
coordinator
discoverer
other
translator
user
vendor
The value coordinator
indicates individuals or organizations that manage a single vendor’s response or multiple vendors’ responses to a vulnerability, a security flaw, or an incident. This includes all Computer Emergency/Incident Response Teams (CERTs/CIRTs) or agents acting on the behalf of a researcher.
The value discoverer
indicates individuals or organizations that find vulnerabilities or security weaknesses. This includes all manner of researchers.
The value translator
indicates individuals or organizations that translate CSAF documents. This includes all manner of language translators, also those who work for the party issuing the original advisory.
The value other
indicates a catchall for everyone else. Currently this includes editors, reviewers, forwarders, republishers, and miscellaneous contributors.
The value user
indicates anyone using a vendor’s product.
The value vendor
indicates developers or maintainers of information system products or services. This includes all authoritative product vendors, Product Security Incident Response Teams (PSIRTs), and product resellers and distributors, including authoritative vendor partners.
Contact details (contact_details
) of value type string
with 1 or more characters provides information on how to contact the publisher, possibly including details such as web sites, email addresses, phone numbers, and postal mail addresses.
Example:
Example Company can be reached at contact_us@example.com, or via our website at https://www.example.com/contact.
Issuing authority (issuing_authority
) of value type string
with 1 or more characters Provides information about the authority of the issuing party to release the document, in particular, the party's constituency and responsibilities or other obligations.
The Name of publisher (name
) of type string
contains the name of the issuing party.
Example:
BSI
Cisco PSIRT
Siemens ProductCERT
The Namespace of publisher (namespace
) of value type string
and format uri
contains a URL which is under control of the issuing party and can be used as a globally unique identifier for that issuing party. The URL SHALL be normalized.
An issuing party can choose any URL which fulfills the requirements state above. It is not required that the URL delivers any content. If an issuing party has chosen a URL it SHOULD NOT change. Tools can make use of the combination of /document/publisher/namespace
and /document/tracking/id
as it identifies a CSAF document globally unique.
If an issuing party decides to change its Namespace it SHOULD reissue all CSAF documents with an incremented (patch) version which has no other changes than:
- the new publisher information
- the updated revision history
- the updated item in
/document/references[]
which points to the new version of the CSAF document - an added item in
/document/references[]
which points to the previous version of the CSAF document (if the URL changed)
Example:
http://www.example.com
https://csaf.io
References (references
) of References Type (references_t
).
"references": {
// ...
},
Source language (source_lang
) of Language Type (lang_t
) identifies if this copy of the document is a translation then the value of this property describes from which language this document was translated.
The property MUST be present and set for any CSAF document with the value translator
in /document/publisher/category
.
Title of this document (title
) of value type string
with 1 or more characters SHOULD be a canonical name for the document, and sufficiently unique to distinguish it from similar documents.
Examples:
Example Company Cross-Site-Scripting Vulnerability in Example Generator
Cisco IPv6 Crafted Packet Denial of Service Vulnerability
Tracking (tracking
) of value type object
with the six mandatory properties: Current Release Date (current_release_date
), Identifier (id
), Initial Release Date (initial_release_date
), Revision History (revision_history
), Status (status
), and Version (version
) is a container designated to hold all management attributes necessary to track a CSAF document as a whole.
The two optional additional properties are Aliases (aliases
) and Generator (generator
).
"tracking": {
// ...
"properties": {
"aliases": {
// ...
},
"current_release_date": {
// ...
},
"generator": {
// ...
},
"id": {
// ...
},
"initial_release_date": {
// ...
},
"revision_history": {
// ...
},
"status": {
// ...
},
"version": {
// ...
}
}
},
Aliases (aliases
) of value type array
with 1 or more unique items (a set
) representing Alternate Names contains a list of alternate names for the same document.
"aliases": {
// ...
"items": {
// ...
}
},
Every such Alternate Name of value type string
with 1 or more characters specifies a non-empty string that represents a distinct optional alternative ID used to refer to the document.
Example:
CVE-2019-12345
Current release date (current_release_date
) with value type string
and format date-time
holds the date when the current revision of this document was released.
Document Generator (generator
) of value type object
with mandatory property Engine (engine
) and optional property Date (date
) is a container to hold all elements related to the generation of the document. These items will reference when the document was actually created, including the date it was generated and the entity that generated it.
"generator": {
// ...
"properties": {
"date": {
// ...
},
"engine": {
// ...
}
}
},
Date of document generation (date
) of value type string
with format date-time
SHOULD be the current date that the document was generated.
Because documents are often generated internally by a document producer and exist for a nonzero amount of time before being released, this field MAY be different from the Initial Release Date and Current Release Date.
Engine of document generation (engine
) of value type object
with mandatory property Engine name (name
) and optional property Engine version (version
) contains information about the engine that generated the CSAF document.
"engine": {
// ...
"properties": {
"name": {
// ...
},
"version": {
// ...
}
}
},
Engine name (name
) of value type string
with 1 or more characters represents the name of the engine that generated the CSAF document.
Examples:
Red Hat rhsa-to-cvrf
Secvisogram
TVCE
Engine version (version
) of value type string
with 1 or more characters contains the version of the engine that generated the CSAF document.
Although it is not formally required, the TC suggests to use a versioning which compatible wth Semantic Versioning as described in the external specification [SemVer]. This could help the end user to identify when CSAF consumers have to be updated.
Examples:
0.6.0
2
1.0.0-beta+exp.sha.a1c44f85
Unique identifier for the document (id
) of value type string
with 1 or more characters holds the Identifier.
The ID is a simple label that provides for a wide range of numbering values, types, and schemes.
Its value SHOULD be assigned and maintained by the original document issuing authority. It MUST be unique for that organisation.
Examples:
Example Company - 2019-YH3234
RHBA-2019:0024
cisco-sa-20190513-secureboot
The combination of
/document/publisher/namespace
and/document/tracking/id
identifies a CSAF document globally unique.
This value is also used to define the filename for the CSAF document. The following rules MUST be applied to determine the filename for the CSAF document:
- The value
/document/tracking/id
is converted into lower case. - Each character which is not part of one of the following groups MUST be replaced by an underscore (
_
):- Lower case ASCII letters (0x61 - 0x7A)
- digits (0x30 - 0x39)
- special characters:
+
(0x2B),-
(0x2D),_
(0x5F)
- The file extension
.json
MUST be appended.
Examples:
example_company_-_2019-yh3234.json
rhba-2019_0024.json
cisco-sa-20190513-secureboot.json
Initial release date (initial_release_date
) with value type string
and format date-time
holds the date when this document was first published.
The Revision History (revision_history
) with value type array
of 1 or more Revision History Entries holds one revision item for each version of the CSAF document, including the initial one.
"revision_history": {
// ...
"items": {
// ...
}
},
Each Revision contains all the information elements required to track the evolution of a CSAF document. Revision History Entry items are of type object
with the three mandatory properties: Date (date
), Number (number
), and Summary (summary
).
"properties": {
"date": {
// ...
},
"number": {
// ...
},
"summary": {
// ...
}
}
The Number (number
) has value type Version (version_t
).
The Date of the revision (date
) of value type string
with format date-time
states the date of the revision entry.
The Summary of the revision (summary
) of value type string
with 1 or more characters holds a single non-empty string representing a short description of the changes.
Each Revision item which has a number
of 0
or 0.y.z
MUST be removed from the document if the document status is final
. Versions of the document which are pre-release SHALL NOT have its own revision item. All changes MUST be tracked in the item for the next release version. Build metadata SHOULD NOT be included in the number
of any revision item.
Document status (status
) of value type string
and enum
defines the draft status of the document.
The value MUST be one of the following:
draft
final
interim
The value draft
indicates, that this is a pre-release, intended for issuing party's internal use only, or possibly used externally when the party is seeking feedback or indicating its intentions regarding a specific issue.
The value final
indicates, that the issuing party asserts the content is unlikely to change. “Final” status is an indication only, and does not preclude updates. This SHOULD be used if the issuing party expects no, slow or few changes.
The value interim
indicates, that the issuing party expects rapid updates. This SHOULD be used if the expected rate of release for this document is significant higher than for other documents. Once the rate slows down it MUST be changed to final
. This may be done in a patch version.
This is extremly useful for downstream vendors to constantly inform the end users about ongoing investigation. It can be used as an indication to pull the CSAF document more frequently.
Version has the value type Version (version_t
).
Product Tree (product_tree
) has value type object
with 1 or more properties is a container for all fully qualified product names that can be referenced elsewhere in the document.
The properties are Branches (branches
), Full Product Names (full_product_names
), Product Groups (product_groups
), and Relationships (relationships
).
"product_tree": {
// ...
"properties": {
"branches": {
// ...
},
"full_product_names": {
// ...
},
"product_groups": {
// ...
},
"relationships": {
// ...
}
}
},
List of branches (branches
) of value type branches_t
.
List of full product names (full_product_names
) of value type array
with 1 or more items of type full_product_name_t
contains a list of full product names.
List of product groups (product_groups
) of value type array
with 1 or more items of type object
contains a list of product groups.
"product_groups": {
// ...
"items": {
// ...
}
},
The product group items are of value type object
with the 2 mandatory properties Group ID (group_id
) and Product IDs (product_ids
) and the optional Summary (summary
) property.
"properties": {
"group_id": {
// ...
},
"product_ids": {
// ...
},
"summary": {
// ...
}
}
The summary of the product group (summary
) of type string
with 1 or more characters gives a short, optional description of the group.
Examples:
The x64 versions of the operating system.
Products supporting Modbus.
Group ID (group_id
) has value type Product Group ID (product_group_id_t
).
List of Product IDs (product_ids
) of value type array with 2 or more unique items of type Product ID (product_id_t
) lists the product_ids of those products which known as one group in the document.
List of relationships (relationships
) of value type array
with 1 or more items contains a list of relationships.
"relationships": {
// ...
"items": {
// ...
}
}
The Relationship item is of value type object
and has four mandatory properties: Relationship category (category
), Full Product Name (full_product_name
), Product Reference (product_reference
), and Relates to Product Reference (relates_to_product_reference
). The Relationship item establishes a link between two existing full_product_name_t
elements, allowing the document producer to define a combination of two products that form a new full_product_name
entry.
"properties": {
"category": {
// ...
},
"full_product_name": {
// ...
},
"product_reference": {
// ...
},
"relates_to_product_reference": {
// ...
}
}
Relationship category (category
) of value string
and enum
defines the category of relationship for the referenced component.
The valid values are:
default_component_of
external_component_of
installed_on
installed_with
optional_component_of
The value default_component_of
indicates that the entity labeled with one Product ID (e.g. CSAFPID-0001) is a default component of an entity with another Product ID (e.g. CSAFPID-0002). These Product IDs SHOULD NOT be identical to provide minimal redundancy.
The value external_component_of
indicates that the entity labeled with one Product ID (e.g. CSAFPID-0001) is an external component of an entity with another Product ID (e.g. CSAFPID-0002). These Product IDs SHOULD NOT be identical to provide minimal redundancy.
The value installed_on
indicates that the entity labeled with one Product ID (e.g. CSAFPID-0001) is installed on a platform entity with another Product ID (e.g. CSAFPID-0002). These Product IDs SHOULD NOT be identical to provide minimal redundancy.
The value installed_with
indicates that the entity labeled with one Product ID (e.g. CSAFPID-0001) is installed alongside an entity with another Product ID (e.g. CSAFPID-0002). These Product IDs SHOULD NOT be identical to provide minimal redundancy.
The value optional_component_of
indicates that the entity labeled with one Product ID (e.g. CSAFPID-0001) is an optional component of an entity with another Product ID (e.g. CSAFPID-0002). These Product IDs SHOULD NOT be identical to provide minimal redundancy.
Full Product Name (full_product_name
) of value type Full Product Name type (full_product_name_t
).
Product Reference (product_reference
) holds a Product ID (product_id_t
) value.
Relates to Product Reference (relates_to_product_reference
) holds also a Product ID (product_id_t
) value.
Vulnerabilities (vulnerabilities
) of value type array
with 1 or more objects representing vulnerabilities and providing 1 or more properties represents a list of all relevant vulnerability information items.
"vulnerabilities": {
// ...
"items": {
// ...
}
}
The Vulnerability item of value type object
with 1 or more properties is a container for the aggregation of all fields that are related to a single vulnerability in the document.
Any vulnerability may provide the optional properties Acknowledgments (acknowledgments
), Common Vulnerabilities and Exposures (CVE) (cve
), Common Weakness Enumeration (CWE) (cwe
), Discovery Date (discovery_date
), ID (id
), Involvements (involvements
), Notes (notes
), Product Status (product_status
), References (references
), Release Date (release_date
), Remediations (remediations
), Scores (scores
), Threats (threats
), and Title (title
).
"properties": {
"acknowledgments": {
// ...
},
"cve": {
// ...
},
"cwe": {
// ...
},
"discovery_date": {
// ...
},
"id": {
// ...
},
"involvements": {
// ...
},
"notes": {
// ...
},
"product_status": {
// ...
},
"references": {
// ...
},
"release_date": {
// ...
},
"remediations": {
// ...
},
"scores": {
// ...
},
"threats": {
// ...
},
"title": {
// ...
}
}
List of acknowledgments (acknowledgments
) of value type array
with 1 or more items of type Acknowledgment contains a list of acknowledgment elements.
CVE (cve
) of value type string
with pattern
(regular expression):
^CVE-[0-9]{4}-[0-9]{4,}$
holds the MITRE standard Common Vulnerabilities and Exposures (CVE) tracking number for the vulnerability.
CWE (cwe
) of value type object
with the 2 mandatory properties Weakness ID (id
) and Weakness Name (name
) holds the MITRE standard Common Weakness Enumeration (CWE) for the weakness associated. For more information cf. [CWE].
"cwe": {
// ...
"properties": {
"id": {
// ...
},
"name": {
// ...
}
}
},
The Weakness ID (id
) has value type string
with pattern
(regular expression):
^CWE-[1-9]\\d{0,5}$
and holds the ID for the weakness associated.
Examples:
CWE-79
CWE-22
CWE-352
The Weakness name (name
) has value type string
with 1 or more characters and holds the full name of the weakness as given in the CWE specification.
Examples:
Improper Neutralization of Input During Web Page Generation ('Cross-site Scripting')
Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal')
Cross-Site Request Forgery (CSRF)
Discovery date (discovery_date
) of value type string
with format date-time
holds the date and time the vulnerability was originally discovered.
ID (id
) of value type object
with the two mandatory properties System Name (system_name
) and Text (text
) gives the document producer a place to publish a unique label or tracking ID for the vulnerability (if such information exists).
"id": {
// ...
"properties": {
"system_name": {
// ...
},
"text": {
// ...
}
}
},
System name (system_name
) of value type string
with 1 or more characters indicates the name of the vulnerability tracking or numbering system.
Example:
Cisco Bug ID
GitHub Issue
Text (text
) of value type string
with 1 or more characters is unique label or tracking ID for the vulnerability (if such information exists).
Example:
CSCso66472
oasis-tcs/csaf#210
General examples may include an identifier from a vulnerability tracking system that is available to customers, such as:
- a Cisco bug ID,
- a GitHub Issue number,
- an ID from a Bugzilla system, or
- an ID from a public vulnerability database such as the X-Force Database.
The ID may be a vendor-specific value but is not to be used to publish the CVE tracking numbers (MITRE standard Common Vulnerabilities and Exposures), as these are specified inside the dedicated CVE element.
List of involvements (involvements
) of value type array
with 1 or more items of type object
contains a list of involvements.
"involvements": {
// ...
"items": {
// ...
}
},
Every Involvement item of value type object
with the 2 mandatory properties Party (party
), Status (status
) and the 2 optional properties Date of involvement (date
) and Summary (summary
) is a container that allows the document producers to comment on the level of involvement (or engagement) of themselves (or third parties) in the vulnerability identification, scoping, and remediation process. It can also be used to convey the disclosure timeline. The ordered tuple of the values of party
, status
and date
(if present) SHALL be unique within involvements
.
"properties": {
"date": {
// ...
},
"party": {
// ...
},
"status": {
// ...
},
"summary": {
// ...
},
}
Date of involvement (date
) of value type string
with format date-time
holds the date and time of the involvement entry.
Party category (party
) of value type string
and enum
defines the category of the involved party.
Valid values are:
coordinator
discoverer
other
user
vendor
These values follow the same definitions as given for the publisher category (cf. section 3.2.1.8.1).
Party status (status
) of value type string
and enum
defines contact status of the involved party.
Valid values are:
completed
contact_attempted
disputed
in_progress
not_contacted
open
Each status is mutually exclusive - only one status is valid for a particular vulnerability at a particular time. As the vulnerability ages, a party's involvement could move from state to state. However, in many cases, a document producer may choose not to issue CSAF documents at each state, or simply omit this element altogether. It is recommended, however, that vendors that issue CSAF documents indicating an open or in-progress involvement should eventually expect to issue a document containing one of the statuses disputed
or completed
as the latest one.
The two vulnerability involvement status states,
contact_attempted
andnot_contacted
are intended for use by document producers other than vendors (such as research or coordinating entities).
The value completed
indicates that the party asserts that investigation of the vulnerability is complete. No additional information, fixes, or documentation from the party about the vulnerability should be expected to be released.
The value contact_attempted
indicates that the document producer attempted to contact the party.
The value disputed
indicates that the party disputes the vulnerability report in its entirety. This status should be used when the party believes that a vulnerability report regarding a product is completely inaccurate (that there is no real underlying security vulnerability) or that the technical issue being reported has no security implications.
The value in_progress
indicates that some hotfixes, permanent fixes, mitigations, workarounds, or patches may have been made available by the party, but more information or fixes may be released in the future. The use of this status by a vendor indicates that future information from the vendor about the vulnerability is to be expected.
The value not_contacted
indicates that the document producer has not attempted to make contact with the party.
The value open
is the default status. It doesn’t indicate anything about the vulnerability remediation effort other than the fact that the party has acknowledged awareness of the vulnerability report. The use of this status by a vendor indicates that future updates from the vendor about the vulnerability are to be expected.
Summary of involvement (summary
) of value type string
with 1 or more characters contains additional context regarding what is going on.
Notes (notes
) have value type Notes (notes_t
).
Product status (product_status
) of value type object
with 1 or more properties contains different lists of product_ids which provide details on the status of the referenced product related to the current vulnerability.
The eight defined properties are First affected (first_affected
), First fixed (first_fixed
), Fixed (fixed
), Known affected (known_affected
), Known not affected (known_not_affected
), Last affected (last_affected
), Recommended (recommended
), and Under investigation (under_investigation
) are all of value type Products (products_t
).
"product_status": {
// ...
"properties": {
"first_affected": {
// ...
},
"first_fixed": {
// ...
},
"fixed": {
// ...
},
"known_affected": {
// ...
},
"known_not_affected": {
// ...
},
"last_affected": {
// ...
},
"recommended": {
// ...
},
"under_investigation": {
// ..
}
}
},
First affected (first_affected
) of value type Products (products_t
) represents that these are the first versions of the releases known to be affected by the vulnerability.
First fixed (first_fixed
) of value type Products (products_t
) represents that these versions contain the first fix for the vulnerability but may not be the recommended fixed versions.
Fixed (fixed
) of value type Products (products_t
) represents that these versions contain a fix for the vulnerability but may not be the recommended fixed versions.
Known affected (known_affected
) of value type Products (products_t
) represents that these versions are known to be affected by the vulnerability. Actions are recommended to remediate or address this vulnerability.
This could include for instance learning more about the vulnerability and context, and/or making a risk-based decision to patch or apply defense-in-depth measures. See
/vulnerabilities[]/remediations
,/vulnerabilities[]/notes
and/vulnerabilities[]/threats
for more details.
Known not affected (known_not_affected
) of value type Products (products_t
) represents that these versions are known not to be affected by the vulnerability. No remediation is required regarding this vulnerability.
This could for instance be because the code referenced in the vulnerability is not present, not exposed, compensating controls exist, or other factors. See
/vulnerabilities[]/threats
in categoryimpact
for more details.
Last affected (last_affected
) of value type Products (products_t
) represents that these are the last versions in a release train known to be affected by the vulnerability. Subsequently released versions would contain a fix for the vulnerability.
Recommended (recommended
) of value type Products (products_t
) represents that these versions have a fix for the vulnerability and are the vendor-recommended versions for fixing the vulnerability.
Under investigation (under_investigation
) of value type Products (products_t
) represents that it is not known yet whether these versions are or are not affected by the vulnerability. However, it is still under investigation - the result will be provided in a later release of the document.
References (references
) have value type References (references_t
).
Release date (release_date
) with value type string
of format date-time
holds the date and time the vulnerability was originally released into the wild.
List of remediations (remediations
) of value type array
with 1 or more Remediation items of type object
contains a list of remediations.
"remediations": {
// ...
"items": {
// ...
}
},
Every Remediation item of value type object
with the 2 mandatory properties Category (category
) and Details (details
) specifies details on how to handle (and presumably, fix) a vulnerability.
In addition, any Remediation may expose the six optional properties Date (date
), Entitlements (entitlements
), Group IDs (group_ids
), Product IDs (product_ids
), Restart required (restart_required
), and URL (url
).
"properties": {
"category": {
// ...
},
"date": {
// ...
},
"details": {
// ...
},
"entitlements": {
// ...
},
"group_ids": {
// ...
},
"product_ids": {
// ...
},
"restart_required": {
// ...
},
"url": {
// ...
}
}
Category of the remediation (category
) of value type string
and enum
specifies the category which this remediation belongs to.
Valid values are:
workaround
mitigation
vendor_fix
none_available
no_fix_planned
The value workaround
indicates that the remediation contains information about a configuration or specific deployment scenario that can be used to avoid exposure to the vulnerability. There may be none, one, or more workarounds available. This is typically the “first line of defense” against a new vulnerability before a mitigation or vendor fix has been issued or even discovered.
The value mitigation
indicates that the remediation contains information about a configuration or deployment scenario that helps to reduce the risk of the vulnerability but that does not resolve the vulnerability on the affected product. Mitigations may include using devices or access controls external to the affected product. Mitigations may or may not be issued by the original author of the affected product, and they may or may not be officially sanctioned by the document producer.
The value vendor_fix
indicates that the remediation contains information about an official fix that is issued by the original author of the affected product. Unless otherwise noted, it is assumed that this fix fully resolves the vulnerability.
The value none_available
indicates that there is currently no fix available. The description should contain details about why there is no fix.
The value no_fix_planned
indicates that there is no fix for the vulnerability and it is not planned to provide one at any time. This is often the case when a product has been orphaned, declared end-of-life, or otherwise deprecated. The description should contain details about why there will be no fix issued.
Date of the remediation (date
) of value type string
with format date-time
contains the date from which the remediation is available.
Details of the remediation (details
) of value type string
with 1 or more characters contains a thorough human-readable discussion of the remediation.
List of entitlements (entitlements
) of value type array
with 1 or more items of type Entitlement of the remediation as string
with 1 or more characters contains a list of entitlements.
"entitlements": {
// ....
"items": {
// ...
}
},
Every Entitlement of the remediation contains any possible vendor-defined constraints for obtaining fixed software or hardware that fully resolves the vulnerability.
Group IDs (group_ids
) are of value type Product Groups (product_groups_t
).
Product IDs (product_ids
) are of value type Products (products_t
).
Restart required by remediation (restart_required
) of value type object
with the 1 mandatory property Category (category
) and the optional property Details (details
) provides information on category of restart is required by this remediation to become effective.
"restart_required": {
// ...
"properties": {
"category": {
// ...
}
"details": {
// ...
}
}
},
Category of restart (category
) of value type string
and enum
specifies what category of restart is required by this remediation to become effective.
Valid values are:
none
vulnerable_component
service
parent
dependencies
connected
machine
zone
system
The values must be used as follows:
none
: No restart required.vulnerable_component
: Only the vulnerable component (as given by the elements ofproduct_ids
orgroup_ids
in the current remediation item) needs to be restarted.service
: The vulnerable component and the background service used by the vulnerable component need to be restarted.parent
: The vulnerable component and its parent process need to be restarted. This could be the case if the parent process has no build-in way to restart the vulnerable component or process values / context is only given at the start of the parent process.dependencies
: The vulnerable component and all components which require the vulnerable component to work need to be restarted. This could be the case e.g. for a core service of a software.connected
: The vulnerable component and all components connected (via network or any type of inter-process communication) to the vulnerable component need to be restarted.machine
: The machine on which the vulnerable component is installed on needs to be restarted. This is the value which should be used if an OS needs to be restarted. It is typically the case for OS upgrades.zone
: The security zone in which the machine resides on which the vulnerable component is installed needs to be restarted. This value might be useful for a remediation if no patch is available. If the malware can be wiped out by restarting the infected machines but the infection spreads fast the controlled shutdown of all machines at the same time and restart afterwards can leave one with a clean system.system
: The whole system which the machine resides on which the vulnerable component is installed needs to be restarted. This may include multiple security zones. This could be the case for a major system upgrade in an ICS system or a protocol change.
Additional restart information (details
) of value type string
with 1 or more characters provides additional information for the restart. This can include details on procedures, scope or impact.
URL (url
) of value type string
with format uri
contains the URL where to obtain the remediation.
List of scores (scores
) of value type array
with 1 or more items of type score holds a list of score objects for the current vulnerability.
"scores": {
// ...
"items": {
// ...
}
}
},
Value type of every such Score item is object
with the mandatory property products
and the optional properties cvss_v2
and cvss_v3
specifies information about (at least one) score of the vulnerability and for which products the given value applies. Each Score item has at least 2 properties.
"properties": {
"cvss_v2": {
// ...
},
"cvss_v3": {
"oneOf": [
// ...
]
}
"products": {
// ...
}
}
The property CVSS v2 (cvss_v2
) holding a CVSS v2.0 value abiding by the schema at https://www.first.org/cvss/cvss-v2.0.json.
The property CVSS v3 (cvss_v3
) holding a CVSS v3.x value abiding by one of the schemas at https://www.first.org/cvss/cvss-v3.0.json or https://www.first.org/cvss/cvss-v3.1.json.
Product IDs (products
) of value type products_t
with 1 or more items indicates for which products the given scores apply.
List of threats (threats
) of value type array
with 1 or more items of type object
representing Threats contains information about a vulnerability that can change with time.
"threats": {
// ...
"items": {
// ...
}
},
A Threat item is of value type object
with the two mandatory properties Category (category
) and Details (details
) and contains the vulnerability kinetic information.
This information can change as the vulnerability ages and new information becomes available.
In addition, threat items may provide the three optional properties Date (date
), Group IDs (group_ids
) and Product IDs (product_ids
).
"properties": {
"category": {
// ...
}
"date": {
// ...
},
"details": {
// ...
},
"group_ids": {
// ...
},
"product_ids": {
// ...
}
}
Category of the threat (category
) of value type string
and enum
categorizes the threat according to the rules of the specification.
Valid values are:
exploit_status
impact
target_set
The value exploit_status
indicates that the details
field contains a description of the degree to which an exploit for the vulnerability is known. This knowledge can range from information privately held among a very small group to an issue that has been described to the public at a major conference or is being widely exploited globally. For consistency and simplicity, this section can be a mirror image of the CVSS "Exploitability" metric. However, it can also contain a more contextual status, such as "Weaponized" or "Functioning Code".
The value impact
indicates that the details
field contains an assessment of the impact on the user or the target set if the vulnerability is successfully exploited or a description why it cannot be exploited. If applicable, for consistency and simplicity, this section can be a textual summary of the three CVSS impact metrics. These metrics measure how a vulnerability detracts from the three core security properties of an information system: Confidentiality, Integrity, and Availability.
The value target_set
indicates that the details
field contains a description of the currently known victim population in whatever terms are appropriate. Such terms may include: operating system platform, types of products, user segments, and geographic distribution.
Date of the threat (date
) of value type string
with format date-time
contains the date when the assessment was done or the threat appeared.
Details of the threat (details
) of value type string
with 1 or more characters represents a thorough human-readable discussion of the threat.
Group IDs (group_ids
) are of value type Product Groups (product_groups_t
).
Product IDs (product_ids
) are of value type Products (products_t
).
Title (title
) has value type string
with 1 or more characters and gives the document producer the ability to apply a canonical name or title to the vulnerability.
The following three subsections list a number of tests which all will have a short description and an excerpt of an example which fails the test.
Mandatory tests MUST NOT fail at a valid CSAF document. A program MUST handle a test failure as an error.
For each element of type /definitions/product_id_t
which is not inside a Full Product Name (type: full_product_name_t
) and therefore reference an element within the product_tree
it must be tested that the Full Product Name element with the matching product_id
exists. The same applies for all items of elements of type /definitions/products_t
.
The relevant paths for this test are:
/product_tree/product_groups[]/product_ids[]
/product_tree/relationships[]/product_reference
/product_tree/relationships[]/relates_to_product_reference
/vulnerabilities[]/product_status/first_affected[]
/vulnerabilities[]/product_status/first_fixed[]
/vulnerabilities[]/product_status/fixed[]
/vulnerabilities[]/product_status/known_affected[]
/vulnerabilities[]/product_status/known_not_affected[]
/vulnerabilities[]/product_status/last_affected[]
/vulnerabilities[]/product_status/recommended[]
/vulnerabilities[]/product_status/under_investigation[]
/vulnerabilities[]/remediations[]/product_ids[]
/vulnerabilities[]/scores[]/products[]
/vulnerabilities[]/threats[]/product_ids[]
Example which fails the test:
"product_tree": {
"product_groups": [
{
"group_id": "CSAFGID-1020300",
"product_ids": [
"CSAFPID-9080700",
"CSAFPID-9080701"
]
}
]
}
Neither
CSAFPID-9080700
norCSAFPID-9080701
were defined in theproduct_tree
.
For each Product ID (type /definitions/product_id_t
) in Full Product Name elements (type: /definitions/full_product_name_t
) it must be tested that the product_id
was not already defined within the same document.
The relevant paths for this test are:
/product_tree/branches[](/branches[])*/product/product_id
/product_tree/full_product_names[]/product_id
/product_tree/relationships[]/full_product_name/product_id
Example which fails the test:
"product_tree": {
"full_product_names": [
{
"product_id": "CSAFPID-9080700",
"name": "Product A"
},
{
"product_id": "CSAFPID-9080700",
"name": "Product B"
}
]
}
CSAFPID-9080700
was defined twice.
For each new defined Product ID (type /definitions/product_id_t
) in items of relationships (/product_tree/relationships
) it must be tested that the product_id
does not end up in a cirle.
The relevant path for this test it:
/product_tree/relationships[]/full_product_name/product_id
As this can be quite complex a program for large CSAF documents, a program could check first whether a Product ID defined in a relationship item is used as
product_reference
orrelates_to_product_reference
. Only for those which fulfill this condition it is necessary to run the full check following the references.
Example which fails the test:
"product_tree": {
"full_product_names": [
{
"product_id": "CSAFPID-9080700",
"name": "Product A"
}
],
"relationships": [
{
"category": "installed_on"
"full_product_name": {
"name": "Product B",
"product_id": "CSAFPID-9080701"
},
"product_reference": "CSAFPID-9080700",
"relates_to_product_reference": "CSAFPID-9080701",
}
]
}
CSAFPID-9080701
refers to itself - this is a circular definition.
For each element of type /definitions/product_group_id_t
which is not inside a Product Group (/product_tree/product_groups[]
) and therefore reference an element within the product_tree
it must be tested that the Product Group element with the matching group_id
exists. The same applies for all items of elements of type /definitions/product_groups_t
.
The relevant paths for this test are:
/vulnerabilities[]/remediations[]/group_ids
/vulnerabilities[]/threats[]/group_ids
Example which fails the test:
"product_tree": {
"full_product_names": [
{
"product_id": "CSAFPID-9080700",
"name": "Product A"
}
]
},
"vulnerabilities": [
{
"threats": [
{
"category": "exploit_status",
"details": "Reliable exploits integrated in Metasploit.",
"group_ids": [
"CSAFGID-1020301"
]
}
]
}
]
CSAFGID-1020301
was not defined in the Product Tree.
For each Product Group ID (type /definitions/product_group_id_t
) Product Group elements (/product_tree/product_groups[]
) it must be tested that the group_id
was not already defined within the same document.
The relevant path for this test is:
/product_tree/product_groups[]/group_id
Example which fails the test:
"product_tree": {
"full_product_names": [
{
"product_id": "CSAFPID-9080700",
"name": "Product A"
},
{
"product_id": "CSAFPID-9080701",
"name": "Product B"
},
{
"product_id": "CSAFPID-9080702",
"name": "Product C"
}
],
"product_groups": [
{
"group_id": "CSAFGID-1020300",
"product_ids": [
"CSAFPID-9080700",
"CSAFPID-9080701"
]
},
{
"group_id": "CSAFGID-1020300",
"product_ids": [
"CSAFPID-9080700",
"CSAFPID-9080702"
]
}
]
}
CSAFGID-1020300
was defined twice.
It must be tested that the same Product ID is not member of contradicting product status groups.
Contradiction groups are:
-
Affected:
/vulnerabilities[]/product_status/first_affected[] /vulnerabilities[]/product_status/known_affected[] /vulnerabilities[]/product_status/last_affected[]
-
Not affected:
/vulnerabilities[]/product_status/known_not_affected[]
-
Fixed:
/vulnerabilities[]/product_status/first_fixed[] /vulnerabilities[]/product_status/fixed[]
-
Under investigation:
/vulnerabilities[]/product_status/under_investigation[]
Note: An issuer might recommend (
/vulnerabilities[]/product_status/recommended
) a product version from any group - also from the affected group, i.e. if it was discoveres that fixed versions introduce a more severe vulnerability.
Example which fails the test:
"product_tree": {
"full_product_names": [
{
"product_id": "CSAFPID-9080700",
"name": "Product A"
}
]
},
"vulnerabilities": [
{
"product_status": {
"known_affected": [
"CSAFPID-9080700"
],
"known_not_affected": [
"CSAFPID-9080700"
]
}
}
]
CSAFPID-9080700
is a member of the two contradicting groups "Affected" and "Not affected".
It must be tested that the same Product ID is not member of more than one CVSS-Vectors with the same version.
The relevant path for this test is:
/vulnerabilities[]/scores[]
Example which fails the test:
"product_tree": {
"full_product_names": [
{
"product_id": "CSAFPID-9080700",
"name": "Product A"
}
]
},
"vulnerabilities": [
{
"scores": [
{
"products": [
"CSAFPID-9080700"
],
"cvss_v3": {
"version": "3.1",
"vectorString": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H",
"baseScore": 10,
"baseSeverity": "CRITICAL"
}
},
{
"products": [
"CSAFPID-9080700"
],
"cvss_v3": {
"version": "3.1",
"vectorString": "CVSS:3.1/AV:L/AC:L/PR:H/UI:R/S:U/C:H/I:H/A:H",
"baseScore": 6.5,
"baseSeverity": "MEDIUM"
}
}
]
}
]
Two CVSSv3.1 scores are given for
CSAFPID-9080700
.
It must be tested that the given CVSS object is valid according to the referenced schema.
The relevant paths for this test are:
/vulnerabilities[]/scores[]/cvss_v2
/vulnerabilities[]/scores[]/cvss_v3
Example which fails the test:
"cvss_v3": {
"version": "3.1",
"vectorString": "CVSS:3.1/AV:L/AC:L/PR:H/UI:R/S:U/C:H/I:H/A:H",
"baseScore": 6.5
}
The required element
baseSeverity
is missing.
It must be tested that the given CVSS object has the values computed correctly according to the definition.
The relevant paths for this test are:
/vulnerabilities[]/scores[]/cvss_v2/baseScore
/vulnerabilities[]/scores[]/cvss_v2/temporalScore
/vulnerabilities[]/scores[]/cvss_v2/environmentalScore
/vulnerabilities[]/scores[]/cvss_v3/baseScore
/vulnerabilities[]/scores[]/cvss_v3/baseSeverity
/vulnerabilities[]/scores[]/cvss_v3/temporalScore
/vulnerabilities[]/scores[]/cvss_v3/temporalSeverity
/vulnerabilities[]/scores[]/cvss_v3/environmentalScore
/vulnerabilities[]/scores[]/cvss_v3/environmentalSeverity
Example which fails the test:
"cvss_v3": {
"version": "3.1",
"vectorString": "CVSS:3.1/AV:L/AC:L/PR:H/UI:R/S:U/C:H/I:H/A:H",
"baseScore": 10.0,
"baseSeverity": "LOW"
}
Neither
baseScore
norbaseSeverity
has the correct value according to the specification.
It must be tested that the given CVSS properties do not contratict the CVSS vector.
The relevant paths for this test are:
/vulnerabilities[]/scores[]/cvss_v2
/vulnerabilities[]/scores[]/cvss_v3
Example which fails the test:
"cvss_v3": {
"version": "3.1",
"vectorString": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
"baseScore": 9.8,
"baseSeverity": "CRITICAL",
"attackVector": "LOCAL",
"attackComplexity": "LOW",
"privilegesRequired": "NONE",
"userInteraction": "NONE",
"scope": "CHANGED",
"confidentialityImpact": "HIGH",
"integrityImpact": "HIGH",
"availabilityImpact": "LOW"
}
The values in CVSS vector differs from values of the properties
attackVector
,scope
andavailabilityImpact
.
It must be tested that given CWE exists and is valid.
The relevant path for this test is:
/vulnerabilities[]/cwe
Example which fails the test:
"cwe": {
"id": "CWE-79",
"name": "Improper Input Validation"
}
The
CWE-79
exists. However, its name isImproper Neutralization of Input During Web Page Generation ('Cross-site Scripting')
.
For each element of type /definitions/language_t
it must be tested that the language code is valid and exists.
The relevant paths for this test are:
/document/lang
/document/source_lang
Example which fails the test:
"lang": "TG"
TG
is not a valid language. It is the subtag for the region "Togo".
It must be tested that the value of number
of items of the revision history are sorted ascending when the items are sorted ascending by date
.
The relevant path for this test is:
/document/tracking/revision_history
Example which fails the test:
"revision_history": [
{
"date": "2021-04-22T10:00:00.000Z",
"number": "2",
"summary": "Second version."
},
{
"date": "2021-04-23T10:00:00.000Z",
"number": "1",
"summary": "Initial version."
}
]
The first item has a higher version number than the second.
It must be tested that /document/source_lang
is present and set if the value translator
is used for /document/publisher/category
.
The relevant path for this test is:
/document/source_lang
Example which fails the test:
"document": {
// ...
"publisher": {
"category": "translator",
"name": "CSAF TC Translator"
},
// ...
"source_lang": ""
}
The element
source_lang
is present but not set.
It must be tested that document version has the same value as the the number
in the last item of Revision History when it is sorted ascending by date
. Build metadata is ignored in the comparison.
The relevant path for this test is:
/document/tracking/version
Example which fails the test:
"tracking": {
// ...
"revision_history": [
{
"date": "2021-04-23T10:00:00.000Z",
"number": "1",
"summary": "Initial version."
},
{
"date": "2021-04-23T1100:00.000Z",
"number": "2",
"summary": "Second version."
}
],
"version": "1"
}
The value of
number
of the last item after sorting is2
. However, the document version is1
.
It must be tested that document status is draft
if the document version is 0
or 0.y.z
or contains the pre-release part.
The relevant path for this test is:
/document/tracking/status
Example which fails the test:
"tracking": {
// ...
"status": "final",
"version": "0.9.5"
}
The
/document/tracking/version
is0.9.5
but the document status isfinal
.
It must be tested that no item of the revision history has a number
of 0
or 0.y.z
when the document status is final
or interim
.
The relevant path for this test is:
/document/tracking/revision_history[]/number
Example which fails the test:
"tracking": {
// ...
"revision_history": [
{
"date": "2021-04-17T10:00:00.000Z",
"number": "0",
"summary": "First draft"
},
{
"date": "2021-05-06T10:00:00.000Z",
"number": "1",
"summary": "Initial version."
}
],
"status": "final",
"version": "1"
}
The document status is
final
but the revision history includes an item which has0
as value fornumber
.
It must be tested that no item of the revision history has a number
which includes pre-release information.
The relevant path for this test is:
/document/tracking/revision_history[]/number
Example which fails the test:
"revision_history": [
{
"date": "2021-04-23T10:00:00.000Z",
"number": "1.0.0-rc",
"summary": "Release Candidate for initial version."
},
{
"date": "2021-04-23T10:00:00.000Z",
"number": "1.0.0",
"summary": "Initial version."
}
]
The revision history contains an item which has a
number
that indicates that this is pre-release.
It must be tested that document version does not contain a pre-release part if the document status is final
or interim
.
The relevant path for this test is:
/document/tracking/version
Example which fails the test:
"tracking": {
// ...
"status": "interim",
"version": "1.0.0-alpha"
}
The document status is
interim
but the document version contains the pre-release part-alpha
.
It must be tested that items of the revision history do not omit a version number when the items are sorted ascending by date
. In the case of semantic versioning, this applies only to the Major version.
The relevant path for this test is:
/document/tracking/revision_history
Example which fails the test:
"revision_history": [
{
"date": "2021-04-22T10:00:00.000Z",
"number": "1",
"summary": "Initial version."
},
{
"date": "2021-04-23T10:00:00.000Z",
"number": "3",
"summary": "Some other changes."
}
]
The item for version
2
is missing.
It must be tested that items of the revision history do not contain the same version number.
The relevant path for this test is:
/document/tracking/revision_history
Example which fails the test:
"revision_history": [
{
"date": "2021-04-22T10:00:00.000Z",
"number": "1",
"summary": "Initial version."
},
{
"date": "2021-04-23T10:00:00.000Z",
"number": "1",
"summary": "Some other changes."
}
]
The revision history contains two items with the version number
1
.
It must be tested that a CVE is not used in multiple vulnerability items.
The relevant path for this test is:
/vulnerabilities[]/cve
Example which fails the test:
"vulnerabilities": [
{
"cve": "CVE-2017-0145"
},
{
"cve": "CVE-2017-0145"
}
]
The vulnerabilities array contains two items with the same CVE identifier
CVE-2017-0145
.
It must be tested that items of the list of involements do not contain the tuple of party
and status
more than once at any date
.
The relevant path for this test is:
/vulnerabilities[]/involvements
Example which fails the test:
"vulnerabilities": [
{
"involvements": [
{
"date": "2021-04-23T10:00:00.000Z",
"party": "vendor",
"status": "in_progress"
},
{
"date": "2021-04-23T10:00:00.000Z",
"party": "vendor",
"status": "in_progress",
"summary": "The vendor has released a mitigation and is working to fully resolve the issue."
}
]
}
The list of involements contains two items with the same tuple
party
,status
anddate
.
Optional tests SHOULD NOT fail at a valid CSAF document without a good reason. Failing such a test does not make the CSAF document invalid. These tests may include information about features which are still supported but expected to be deprecated in a future version of CSAF. A program MUST handle a test failure as a warning.
For each Product ID (type /definitions/product_id_t
) in Full Product Name elements (type: /definitions/full_product_name_t
) it must be tested that the product_id
is referenced somewhere within the same document.
The relevant paths for this test are:
/product_tree/branches[](/branches[])*/product/product_id
/product_tree/full_product_names[]/product_id
/product_tree/relationships[]/full_product_name/product_id
A program might suggest and implement a quick fix: Remove the defined but unused element.
Example which fails the test:
"product_tree": {
"full_product_names": [
{
"product_id": "CSAFPID-9080700",
"name": "Product A"
}
]
}
CSAFPID-9080700
was defined but never used.
For each Product ID (type /definitions/product_id_t
) in the Product Status groups Affected and Under investigation it must be tested that a remediation exists.
The remediation might be of the category
none_available
.
The relevant paths for this test are:
/vulnerabilities[]/product_status/first_affected[]
/vulnerabilities[]/product_status/known_affected[]
/vulnerabilities[]/product_status/last_affected[]
/vulnerabilities[]/product_status/under_investigation[]
Example which fails the test:
"product_tree": {
"full_product_names": [
{
"product_id": "CSAFPID-9080700",
"name": "Product A"
}
]
},
"vulnerabilities": [
{
"product_status": {
"last_affected": [
"CSAFPID-9080700"
]
}
}
]
CSAFPID-9080700
has in Product Statuslast_affected
but there is no remediation object for this Product ID.
For each Product ID (type /definitions/product_id_t
) in the Product Status groups Affected it must be tested that a score object exists which covers this product.
The relevant paths for this test are:
/vulnerabilities[]/product_status/first_affected[]
/vulnerabilities[]/product_status/known_affected[]
/vulnerabilities[]/product_status/last_affected[]
Example which fails the test:
"product_tree": {
"full_product_names": [
{
"product_id": "CSAFPID-9080700",
"name": "Product A"
}
]
},
"vulnerabilities": [
{
"product_status": {
"first_affected": [
"CSAFPID-9080700"
]
}
}
]
CSAFPID-9080700
has in Product Statusfirst_affected
but there is no score object which covers this Product ID.
For each item in revision history it must be tested that number
does not include build metadata.
The relevant path for this test is:
/document/tracking/revision_history[]/number
Example which fails the test:
"revision_history": [
{
"date": "2021-04-23T10:00:00.000Z",
"number": "1.0.0+exp.sha.ac00785",
"summary": "Initial version."
}
]
The revision history contains an item which has a
number
that includes the build metadata+exp.sha.ac00785
.
For each item in the list of involvements it must be tested that it includes the property date
.
The relevant path for this test is:
/vulnerabilities[]/involvements
Example which fails the test:
"vulnerabilities": [
{
"involvements": [
{
"party": "vendor",
"status": "in_progress"
}
]
}
The list of involements contains an item which does not contain the property
date
.
Informative tests provide insights in common mistakes and bad practices. They MAY fail at a valid CSAF document. It is up to the issuing party to decide whether this was an intended behavior and can be ignore or should be treated. These tests may include information about recommended usage. A program MUST handle a test failure as a information.
CSAF documents do not have many required fields as they can be used for different purposes. To ensure a common understanding which fields are required in a use case the standard defines profiles. Each subsection describes such a profile by describing necessary content for that specific use case and providing insights into its purpose. The value of /document/category
is used to identify a CSAF document's profile. Each profile extends the generic profile Generic CSAF making additional fields from the standard mandatory. Any other optional field from the standard can also be added to a CSAF document which conforms with a profile without breaking conformance with the profile. One and only exempt is when the profile requires not to have a certain set of fields.
This profile defines the default required fields for any CSAF document. Therefore, it is a "catch all" for CSAF documents that do not satisfy any other profile. Furthermore, it is the foundation all other profiles are build on.
A CSAF document SHALL fulfill the following requirements to satisfy the profile "Generic CSAF":
- The following elements must exist and be valid:
/document/category
/document/publisher/category
/document/publisher/name
/document/title
/document/tracking/current_release_date
/document/tracking/id
/document/tracking/initial_release_date
/document/tracking/revision_history[]/date
/document/tracking/revision_history[]/number
/document/tracking/revision_history[]/summary
/document/tracking/status
/document/tracking/version
- The value of
/document/category
SHALL NOT be equal to any value that is intended to only be used by another profile nor the (case insensitive) name of any other profile. To explicitly select the use of this profile the valuegeneric_csaf
SHOULD be used.
Neither
Security Advisory
norsecurity advisory
are valid values for/document/category
.
An issuing party might choose to set /document/publisher/name
in front of a value that is intended to only be used by another profile to state that the CSAF document does not use the profile associated with this value. This should be done if the issuing party is able or unwilling to use the value generic_csaf
, e.g. due to legal or cooperate identity reasons.
Both values
Example Company Security Advisory
andExample Company security_advisory
in/document/category
use the profile "Generic CSAF". This is important to prepare forward compatibility as later versions of CSAF might add new profiles. Therefore, the values which can be used for the profile "Generic CSAF" might change.
This profile SHOULD be used to provide a response to a security breach or incident. This MAY also be used to convey information about an incident that is unrelated to the issuing party's own products or infrastructure.
Example Company might use a CSAF document satisfying this profile to respond to a security incident at ACME Inc. and the implications on its own products and infrastructure.
A CSAF document SHALL fulfill the following requirements to satisfy the profile "Security incident response":
- The following elements must exist and be valid:
- all elements required by the profile "Generic CSAF".
/document/notes
with at least one item which has acategory
ofdescription
,details
,general
orsummary
Reasoning: Without at least one note item which contains information about response to the event referred to this doesn't provide any useful information.
/document/references
This should be used to refer to one or more documents or websites which provides more details about the incident.
- The value of
/document/category
SHALL besecurity_incident_response
.
This profile SHOULD be used to provide information which are not related to a vulnerability but e.g. a misconfiguration.
A CSAF document SHALL fulfill the following requirements to satisfy the profile "Informational Advisory":
- The following elements must exist and be valid:
- all elements required by the profile "Generic CSAF".
/document/notes
with at least one item which has acategory
ofdescription
,details
,general
orsummary
Reasoning: Without at least one note item which contains information about the "issue" which is the topic of the advisory it is useless.
/document/references
This should be used to refer to one or more documents or websites which provide more details about the issue or its remediation (if possible). This could be a hardening guide, a manual, best practices or any other helpful information.
- The value of
/document/category
SHALL beinformational_advisory
. - The element
/vulnerabilities
SHALL NOT exist. If there is any information that would reside in the element/vulnerabilities
the CSAF document SHOULD use another profile, e.g. "Security Advisory".
If the element /product_tree
exists, a user MUST assume that all products mentioned are affected.
This profile SHOULD be used to provide information which is related to vulnerabilities and corresponding remediations.
A CSAF document SHALL fulfill the following requirements to satisfy the profile "Security Advisory":
- The following elements must exist and be valid:
- all elements required by the profile "Generic CSAF".
/product_tree
which lists all products referenced later on in the CSAF document regardless of their state./vulnerabilities[]/notes
Provides details about the vulnerability.
/vulnerabilities[]/product_status
Lists each product's status in regard to the vulnerability.
- The value of
/document/category
SHALL besecurity_advisory
.
This profile SHOULD be used to provide information of the "Vulnerability Exploitability eXchange". The main purpose of the VEX format is to state that and why a certain product is, or is not, affected by a vulnerability. See [VEX] for details.
A CSAF document SHALL fulfill the following requirements to satisfy the profile "VEX":
- The following elements must exist and be valid:
- all elements required by the profile "Generic CSAF".
/product_tree
which lists all products referenced later on in the CSAF document regardless of their state.- at least one of
/vulnerabilities[]/product_status/fixed
/vulnerabilities[]/product_status/known_affected
/vulnerabilities[]/product_status/known_not_affected
/vulnerabilities[]/product_status/under_investigation
- at least one of
/vulnerabilities[]/cve
/vulnerabilities[]/id
/vulnerabilities[]/notes
Provides details about the vulnerability.
- For each item in
/vulnerabilities[]/product_status/known_not_affected
an impact statement SHALL exist in/vulnerabilities[]/threats
. Thecategory
value for such a statement MUST beimpact
and thedetails
field SHALL contain a a description why the vulnerability cannot be exploited./vulnerabilities[]/product_status/known_affected
additional product specific information SHALL be provided in/vulnerabilities[]/remediations
as an action statement. Optional, additional information MAY also be provide through/vulnerabilities[]/notes
and/vulnerabilities[]/threats
.
Even though Product status lists Product IDs, Product Group IDs can be used in the
remediations
andthreats
object. However, it MUST be ensured that for each Product ID the required information according to its product status as stated in the two points above is available. This implies that all products with the statusknown_not_affected
MUST have an impact statement and all products with the statusknown_affected
MUST have additional product specific information regardless whether that is referenced through the Product ID or a Product Group ID. - The value of
/document/category
SHALL bevex
.
This section lists requirements and roles defined for distributing CSAF documents. The first subsection provides all requirements - the second one the roles. It is mandatory to fulfill the basic role "CSAF publisher".
The requirements in this subsection are consecutively numbered to be able to refer to them directly. The order does not give any hint about the importance. Not all requirements have to be fulfilled - the sets are defined in section 5.2.
The document is a valid CSAF document (cf. Conformance clause 1).
The CSAF document has a filename according to the rules in section 3 (cf. section 3.2.1.12.4).
The CSAF document is retrievable from a website which uses TLS for encryption and server authenticity. The CSAF document MUST not be downloadable from a location which does not encrypt the transport.
If the CSAF document is labeled TLP:WHITE, it MUST be freely accessible.
This does not exclude that such a document is also available in an access protected customer portal. However, there MUST be one copy of the document available for people without access to the portal.
Reasoning: If an advisory is already in the media, an end user should not be forced to collect the pieces of information from a press release but be able to retrieve the CSAF document.
In the security.txt there MUST be at least one field CSAF
which points to either the ROLIE service document or a directory with CSAF files. If this field indicates a web URI, then it MUST begin with "https://" (as per section 2.7.2 of [RFC7230]). See [SECURITY-TXT] for more details.
At the time of this writing, the security.txt is still a proposed standard. The
CSAF
field has not been officially added yet.
Examples:
CSAF: https://domain.tld/security/data/csaf/
CSAF: https://psirt.domain.tld/advisories/csaf/
CSAF: https://domain.tld/security/csaf/csaf-service.json
The DNS record csaf.data.security.domain.tld
SHALL resolve as a webserver which either serves directly the ROLIE service document or a directory with CSAF files.
The CSAF documents must be located within folders named <YYYY>
where <YYYY>
is the year given in the value of /document/tracking/initial_release_date
.
Examples:
2021
2020
The index.txt file within MUST provide a list of all filenames of CSAF documents which are located in the sub-directories with their filenames.
Examples:
2020/example_company_-_2020-yh4711.json
2019/example_company_-_2019-yh3234.json
2018/example_company_-_2018-yh2312.json
This can be used to download all CSAF documents.
The file changes.csv must contain the filename as well as the value of /document/tracking/current_release_date
for each CSAF document in the sub-directories without a heading; lines must be sorted by the current_release_date
timestamp with the latest one first.
Examples:
2020/example_company_-_2020-yh4711.json, "2020-07-01T10:09:07Z"
2018/example_company_-_2018-yh2312.json, "2020-07-01T10:09:01Z"
2019/example_company_-_2019-yh3234.json, "2019-04-17T15:08:41Z"
2018/example_company_-_2018-yh2312.json, "2019-03-01T06:01:00Z"
Directory listing SHALL be enabled to support manual navigation.
Resource-Oriented Lightweight Information Exchange (ROLIE) is a standard to ease discovery of security content. ROLIE is built on top of the Atom Publishing Format and Protocol, with specific requirements that support publishing security content. The ROLIE service document MUST be a JSON file that conforms with [RFC8322] and lists the ROLIE feed documents.
TODO: Provide Example
All CSAF documents with the same TLP level MUST be listed in a single ROLIE feed. At least one of the feeds
- TLP:WHITE
- TLP:GREEN
- unlabeled
MUST exist. Each ROLIE feed document MUST be a JSON file that conforms with [RFC8322].
Example:
{
"feed": {
"id": "example-csaf-feed-tlp-white",
"title": "Example CSAF feed (TLP:WHITE)",
"link": [
{
"rel": "self",
"href": "https://psirt.domain.tld/advisories/csaf/feed-tlp-white.json"
}
],
"category": {
"scheme": "urn:ietf:params:rolie:category:information-type",
"term": "security advisory"
},
"updated": "2021-01-01T12:00Z",
"entry": [
{
"id": "2020-ESA-001",
"title": "Example Security Advisory 001",
"link": [
{
"rel": "self",
"href": "https://psirt.domain.tld/advisories/csaf/2020/ESA-001.json"
}
],
"published": "2021-01-01T11:00Z",
"updated": "2021-01-01T12:00Z",
"summary": {
"content": "Vulnerabilities fixed in ABC 0.0.1"
},
"content": {
"type": "application/json",
"src": "https://psirt.domain.tld/advisories/csaf/2020/ESA-001.json"
},
"format": {
"schema": "https://raw.githubusercontent.com/oasis-tcs/csaf/master/csaf_2.0/json_schema/csaf_json_schema.json",
"version": "2.0"
}
}
]
}
}
The use and therefore the existence of ROLIE category document is optional. If it is used, each ROLIE category document MUST be a JSON file that conforms with [RFC8322]. It should be used for to further dissects CSAF documents by their document categories.
TODO: Provide Example
CSAF documents labeled TLP:AMBER or TLP:RED MUST be access protected. If they are provided via a webserver this SHALL be done under a different path than for TLP:WHITE, TLP:GREEN and unlabeled CSAF documents. TLS client authentication, access tokens or any other automatable authentication method SHALL be used.
An issuing party MAY agree with the receipients to use any kind of secured drop at the receipients' side to avoid putting them on their own website. However, it mUST be ensured that the documents are still access protected.
Redirects SHOULD NOT be used. If they are inevitable only HTTP Header redirects are allowed.
Reasoning: Clients, as e.g.
curl
, do not follow any other kind of redirects.
All CSAF documents SHALL have at least one hash file computed with a secure cryptographic hash algorithm (e.g. SHA-512 or SHA-3) to ensure their integrity. The filename is constructed by appending the file extension which is given by the algorithm.
MD5 and SHA1 SHOULD NOT be used.
Example:
File name of CSAF document: example_company_-_2019-yh3234.json
File name of SHA-256 hash file: example_company_-_2019-yh3234.json.sha256
File name of SHA-512 hash file: example_company_-_2019-yh3234.json.sha512
The file content SHALL start with the first byte of the hexadecimal hash value. Any subsequent data (like a filename) which is optional SHALL be separated by at least one space.
Example:
ea6a209dba30a958a78d82309d6cdcc6929fcb81673b3dc4d6b16fac18b6ff38 example_company_-_2019-yh3234.json
All CSAF documents SHALL have at least one OpenPGP signature file which is provided under the same filename which is extended by the appropriate extension.
Example:
File name of CSAF document: example_company_-_2019-yh3234.json
File name of signature file: example_company_-_2019-yh3234.json.asc
The public part of the PGP key used to sign the CSAF documents MUST be available. It SHOULD also be available at a public key server.
This subsection groups the requirements from the previous subsection into named sets which target the roles with the same name. This allows end users to request their supplieres to fulfill a certain set of requirements. A supplier can use roles for advertising and marketing.
A distributing party satisfies the "CSAF publisher" role if the party:
- satisfies the requirements 1 to 4 in section 6.1.
- distributes only CSAF documents on behalf of its own.
A CSAF publisher satisfies the "CSAF provider" role if the party fulfills the following three groups of requirements:
Firstly, the party:
- satisfies the "CSAF publisher" role profile.
- additionally satisfies the requirements 14 and 15 in section 6.1.
Secondly, the party:
- satisfies the requirements 5 or 6 in section 6.1.
Thirdly, the party:
- satisfies the requirements 7 to 10 in section 6.1 or requirements 11 to 13 in section 6.1.
A CSAF provider satisfies the "CSAF trusted provider" role if the party:
- satisfies the "CSAF provider" role profile.
- additionally satisfies the requirements 16 to 18 in section 6.1.
CSAF documents are based on JSON, thus the security considerations of [RFC8259] apply and are repeated here as service for the reader:
Generally, there are security issues with scripting languages. JSON is a subset of JavaScript but excludes assignment and invocation.
Since JSON's syntax is borrowed from JavaScript, it is possible to use that language's
eval()
function to parse most JSON texts (but not all; certain characters such asU+2028 LINE SEPARATOR
andU+2029 PARAGRAPH SEPARATOR
are legal in JSON but not JavaScript). This generally constitutes an unacceptable security risk, since the text could contain executable code along with data declarations. The same consideration applies to the use of eval()-like functions in any other programming language in which JSON texts conform to that language's syntax.
In addition, CSAF documents may be rendered by consumers in various human-readable formats like HTML or PDF. Thus, for security reasons, CSAF producers and consumers SHALL adhere to the following:
- CSAF producers SHALL NOT emit messages that contain HTML, even though all variants of Markdown permit it.
- Deeply nested markup can cause a stack overflow in the Markdown processor [GFMENG]. To reduce this risk, CSAF consumers SHALL use a Markdown processor that is hardened against such attacks.
Note: One example is the GitHub fork of the
cmark
Markdown processor [GFMCMARK]. - To reduce the risk posed by possibly malicious CSAF files that do contain arbitrary HTML (including, for example, javascript: links), CSAF consumers SHALL either disable HTML processing (for example, by using an option such as the --safe option in the cmark Markdown processor) or run the resulting HTML through an HTML sanitizer. CSAF consumers that are not prepared to deal with the security implications of formatted messages SHALL NOT attempt to render them and SHALL instead fall back to the corresponding plain text messages.
In the only subsection of this section, the conformance targets and clauses are listed. The clauses, matching the targets one to one, are listed in separate sub-subsections of the targets listing subsection.
Informative Comments:
The order in which targets, and their corresponding clauses appear is somewhat arbitrary as there is no natural order on such diverse roles participating in the document exchanging ecosystem.
Except for the target CSAF document, all other 12 targets span a taxonomy of the complex CSAF ecosystems existing in and between diverse security advisory generating, sharing, and consuming communities.
In any case, there are no capabilities organized in increasing quality levels for targets because the security advisory sharing communities follow the chain link model. Instead, a single minimum capability level for every target is given to maintain important goals of providing a common framework for security advisories:
- Fast production, sharing, and actionable consumption of security advisories
- Consistent end to end automation through collaborating actors
- Clear baseline across the communities per this specification
- Additional per-community cooperative extensions which may flow back into future updates of this specification
This document defines requirements for the CSAF file format and for certain software components that interact with it. The entities ("conformance targets") for which this document defines requirements are:
- CSAF document: A security advisory text document in the format defined by this document.
- CSAF producer: A program which emits output in the CSAF format.
- CSAF direct producer: An analysis tool which acts as a CSAF producer.
- CSAF converter: A CSAF producer that transforms the output of an analysis tool from its native output format into the CSAF format.
- CVRF CSAF converter: A CSAF producer which takes a CVRF document as input and converts it into a valid CSAF document.
- CSAF content management system: A program that is able to create, review and manage CSAF documents and is able to preview their details as required by CSAF viewer.
- CSAF post-processor: A CSAF producer that transforms an existing CSAF document into a new CSAF document, for example, by removing or redacting elements according to sharing policies.
- CSAF modifier: A CSAF post-processor which takes a CSAF document as input and modifies the structure or values of properties. The output is a valid CSAF document.
- CSAF translator: A CSAF post-processor which takes a CSAF document as input and translates values of properties into another language. The output is a valid CSAF document.
- CSAF consumer: A program that reads and interprets a CSAF document.
- CSAF viewer: A CSAF consumer that reads a CSAF document, displays a list of the results it contains, and allows an end user to view each result in the context of the artifact in which it occurs.
- CSAF management system: A program that is able to manage CSAF documents and is able to display their details as required by CSAF viewer.
- CSAF asset matching system: A program that connects to or is an asset database and is able to manage CSAF documents as required by CSAF management system as well as matching them to assets of the asset database.
- CSAF basic validator: A program that reads a document and checks it against the JSON schema and performs mandatory tests.
- CSAF extended validator: A CSAF basic validator that additionally performs optional tests.
- CSAF full validator: A CSAF extended validator that additionally performs informative tests.
A text file satisfies the "CSAF document" conformance profile if the text file:
- conforms to the syntax and semantics defined in section 3.
- does not fail any mandatory test defined in section 4.1.
- satisfies at least one profile defined in section 5.
A program satisfies the "CSAF producer" conformance profile if the program:
- produces output in the CSAF format, according to the syntax and semantics defined in section 3. The output MUST not fail any mandatory test defined in section 4.1.
- satisfies those normative requirements in section 3 that are designated as applying to CSAF producers.
An analysis tool satisfies the "CSAF direct producer" conformance profile if the analysis tool:
- satisfies the "CSAF producer" conformance profile.
- additionally satisfies those normative requirements in section 3 that are designated as applying to "direct producers" or to "analysis tools".
- does not emit any objects, properties, or values which, according to section 3, are intended to be produced only by converters.
A converter satisfies the “CSAF converter” conformance profile if the converter:
- satisfies the "CSAF producer" conformance profile.
- additionally satisfies those normative requirements in section 3 that are designated as applying to converters.
- does not emit any objects, properties, or values which, according to section 3, are intended to be produced only by direct producers.
A program satisfies the "CVRF CSAF converter" conformance profile if the program fulfills the following two groups of requirements:
Firstly, the program:
- satisfies the "CSAF producer" conformance profile.
- takes only CVRF documents as input.
- additionally satisfies the normative requirements given below.
Secondly, the program fulfills the following for all items of:
- type
/definitions/version_t
: If any element doesn't match the semantic versioning, replace the all elements of type/definitions/version_t
with the corresponding integer version. For that, CVRF CSAF converter sorts the items of/document/tracking/revision_history
bynumber
ascending according to the rules of CVRF. Then, it replaces the value ofnumber
with the index number in the array (starting with 1). The value of/document/tracking/version
is replaced by value ofnumber
of the corresponding revision item. The match must be calculated by the original values used in the CVRF document. /document/acknowledgments[]/organization
and/vulnerabilities[]/acknowledgments[]/organization
: If more than one cvrf:Organization instance is given, the CVRF CSAF converter converts the first one into theorganization
. In addition the converter outputs a warning that information might be lost during conversion of document or vulnerability acknowledgment./document/publisher/name
and/document/publisher/namespace
: Sets the value as given in the configuration of the program or the corresponding argument the program was invoked with. If values from both sources are present, the program should prefer the latter one. The program SHALL NOT use hard-coded values./vulnerabilities[]/scores[]
: If noproduct_id
is given, the CVRF CSAF converter appends all Product IDs which are listed under../product_status
in the arraysknown_affected
,first_affected
andlast_affected
./vulnerabilities[]/scores[]
: If there are CVSSv3.0 and CVSSv3.1 Vectors available for the same product, the CVRF CSAF converter discards the CVSSv3.0 information and provide in CSAF only the CVSSv3.1 information./product_tree/relationships[]
: If more than one prod:FullProductName instance is given, the CVRF CSAF converter converts the first one into thefull_product_name
. In addition, the converter outputs a warning that information might be lost during conversion of product relationships.
A CSAF content management system satisfies the "CSAF content management system" conformance profile if the content management system:
-
satisfies the "CSAF producer" conformance profile.
-
satisfies the "CSAF viewer" conformance profile.
-
provides at least the following management functions:
-
create new CSAF documents
-
prefill CSAF documents based on values given in the configuration (see below)
-
create a new version of an existing CSAF document
-
checkout old versions of a CSAF document
-
show all differences between versions of a CSAF document
-
list all CSAF documents within the system
-
delete CSAF documents from the system
-
review CSAF documents in the system
-
approve CSAF documents
-
search for CSAF documents by values of required fields at
document
-level or their children within the system -
search for CSAF documents by values of
cve
within the system -
search for CSAF documents based on properties of
product_tree
-
filter on all properties which it is required to search for
-
export of CSAF documents
-
show an audit log for each CSAF document
-
identify the latest version of CSAF documents with the same
/document/tracking/id
-
suggest a
/document/tracking/id
based on the given configuration. -
track of the version of CSAF documents automatically and increment according to the versioning scheme (see also subsections of 3.1.11) selected in the configuration.
-
check that the document version is set correctly based on the changes in comparison to the previous version (see also subsections of 3.1.11).
-
suggest to use the document status
interim
if a CSAF document is updated more frequent than the given threshold in the configuration (default: 3 weeks) -
suggest to publish a new version of the CSAF document with the document status
final
if the document status wasinterim
and no new release has be done during the the given threshold in the configuration (default: 6 weeks) -
support the following workflows:
- "New Advisory": create a new advisory, request a review, provide review comments or approve it, resolve review comments; if the review approved it, the approval for publication can be requested; if granted the document status changes to
final
(orìnterim
based on the selection in approval or configuration) and the advisory is provided for publication (manual or time-based) - "Update Advisory": open an existing advisory, create new revision & change content, request a review, provide review comments or approve it, resolve review comments; if the review approved it, the approval for publication can be requested; if granted the document status changes to
final
(orìnterim
based on the selection in approval or configuration) and the advisory is provided for publication (manual or time-based)
- "New Advisory": create a new advisory, request a review, provide review comments or approve it, resolve review comments; if the review approved it, the approval for publication can be requested; if granted the document status changes to
-
-
publication may be immediately or at a given date/time.
-
handling of date/time and version is automated.
-
provide an API to retrieve all CSAF documents which are currently in the status published.
-
should provide an API to import or create new advisories from outside systems (e.g. bug tracker, CVD platform,...).
-
provide a user management and support at least the following roles:
- Registered: Able to see all published CSAF documents (but only in the published version).
- Author: inherits Registered permissions and also can Create and Edit Own (mostly used for automated creation, see above)
- Editor: inherits Author permissions and can Edit (mostly used in PSIRT)
- Publisher: inherits Editor permissions and can Change state and Review any (mostly used as HEAD of PSIRT or team lead)
- Reviewer: inherits Registered permissions and can Review advisories assigned to him (might be a subject matter expert or management)
- Manager: inherits Publisher permissions and can Delete; User management up to Publisher
- Administrator: inherits Manager permissions and can Change the configuration
-
may use groups to support client separation (multitenancy) and therefore restrict the roles to actions within their group. In this case, there must be a Group configurator which is able to change the values which are used to prefill fields in new advisories for that group. He might also do the user management for the group up to a configured level.
-
prefills the following fields in new CSAF documents with the values given below or based on the templates from configuration:
/document/csaf_version
with the value2.0
/document/language
/document/notes
legal_disclaimer
(Terms of use from the configuration)general
(General Security recommendations from the configuration)
/document/tracking/current_release_date
with the current date/document/tracking/generator
and children/document/tracking/initial_release_date
with the current date/document/tracking/revision_history
date
with the current datenumber
(based on the templates according to the versioning scheme configured)summary
(based on the templates from configuration; default: "Initial version.")
/document/tracking/status
withdraft
/document/tracking/version
with the value ofnumber
the latest/document/tracking/revision_history[]
element/document/publisher
and children/document/category
(based on the templates from configuration)
-
When updating an existing CSAF document:
- prefills all fields which have be present in the existing CSAF document
- adds a new item in
/document/tracking/revision_history[]
- updates the following fields with the values given below or based on the templates from configuration:
/document/csaf_version
with the value2.0
/document/language
/document/notes
legal_disclaimer
(Terms of use from the configuration)general
(General Security recommendations from the configuration)
/document/tracking/current_release_date
with the current date/document/tracking/generator
and children- the new item in
/document/tracking/revision_history[]
date
with the current datenumber
(based on the templates according to the versioning scheme configured)
/document/tracking/status
withdraft
/document/tracking/version
with the value ofnumber
the latest/document/tracking/revision_history[]
element/document/publisher
and children
A CSAF post-processor satisfies the "CSAF post-processor" conformance profile if the post-processor:
- satisfies the "CSAF consumer" conformance profile.
- satisfies the "CSAF producer" conformance profile.
- additionally satisfies those normative requirements in section 3 that are designated as applying to post-processors.
A program satisfies the "CSAF modifier" conformance profile if the program fulfills the two following groups of requirements:
The program:
- satisfies the "CSAF post-processor" conformance profile.
- adds, deletes or modifies at least one property, array, object or value of a property or item of an array.
- does not emit any objects, properties, or values which, according to section 8, are intended to be produced only by CSAF translators.
- satisfies the normative requirements given below.
The resulting modified document:
- does not have the same
/document/tracking/id
as the original document. The modified document can use a completely new/document/tracking/id
or compute one by appending the original/document/tracking/id
as a suffix after an ID from the naming scheme of the issuer of the modified version. It should not use the original/document/tracking/id
as a prefix. - includes a reference to the original advisory as first element of the array
/document/references[]
.
A program satisfies the "CSAF translator" conformance profile if the program fulfills the two following groups of requirements:
The program:
- satisfies the "CSAF post-processor" conformance profile.
- translates at least one value.
- preserves the same semantics and form across translations.
- satisfies the normative requirements given below and does not add or remove other elements than required below.
The resulting translated document:
- does not use the same
/document/tracking/id
as the original document. The translated document can use a completely new/document/tracking/id
or compute one by using the original/document/tracking/id
as a prefix and adding an ID from the naming scheme of the issuer of the translated version. It should not use the original/document/tracking/id
as a suffix. If an issuer uses a CSAF translator to publish his advisories in multiple languages they may use the combination of the original/document/tracking/id
and translated/document/lang
as a/document/tracking/id
for the translated document. - provides the
/document/lang
property with a value matching the language of the translation. - provides the
/document/source_lang
to contain the language of the original document (and should only be set by CSAF translators). - has the value
translator
set in/document/publisher/category
- includes a reference to the original advisory as first element of the array
/document/references[]
. - may contain translations for elements in arrays of
references_t
after the first element. However, it must keep the original URLs as references at the end.
A proccessor satisfies the "CSAF consumer" conformance profile if the processor:
- reads CSAF documents and interprets them according to the semantics defined in section 3.
- satisfies those normative requirements in section 3 that are designated as applying to CSAF consumers.
A viewer satisfies the "CSAF viewer" conformance profile if the viewer fulfills the two following groups of requirements:
The viewer:
- satisfies the "CSAF consumer" conformance profile.
- satisfies the normative requirements given below.
For each CVSS-Score in /vulnerabilities[]/scores[]
the viewer:
- preferably shows the
vector
if there is an inconsistency between thevector
and any other sibling attribute. - should prefer the item of
scores[]
for eachproduct_id
which has the highest CVSS Base Score and newest CVSS version (in that order) if aproduct_id
is listed in more than one item ofscores[]
.
A CSAF management system satisfies the "CSAF management system" conformance profile if the management system:
- satisfies the "CSAF viewer" conformance profile.
- provides at least the following management functions:
- add new CSAF documents (e.g. from file system or URL) to the system
- list all CSAF documents within the system
- delete CSAF documents from the system
- comment on CSAF documents in the system
- mark CSAF documents as read in the system
- search for CSAF documents by values of required fields at
document
-level or their children within the system - search for CSAF documents by values of
cve
within the system - search for CSAF documents based on properties of
/product_tree
- filter on all properties which it is required to search for
- sort on all properties which it is required to search for
- sort on CVSS scores and
/document/aggregate_severity/text
- identifies the latest version of CSAF documents with the same
/document/tracking/id
. - is able to show the difference between 2 versions of a CSAF document with the same
/document/tracking/id
.
A CSAF asset matching system satisfies the "CSAF asset matching system" conformance profile if the asset matching system:
- satisfies the "CSAF management system" conformance profile.
- is an asset database or connects to one.
- matches the CSAF documents within the system to the respective assets. This might be done with a probability which gives the end user the chance to broaden or narrow the results. The process of matching is also referred to as "run of the asset matching module".
- provides for each product of the asset database a list of matched advisories.
- provides for each asset of the asset database a list of matched advisories.
- provides for each CSAF document a list of matched product of the asset database.
- provides for each CSAF document a list of matched asset of the asset database.
- provides for each vulnerability within a CSAF document the option to mark a matched asset in the asset database as "not remediated", "remediation in progress", or "remediation done". A switch to mark all assets at once may be implemented.
- does not bring up a newer revision of a CSAF document as a new match if the remediation for the matched product or asset has not changed.
- detects the usage semantic version (as described in section 3).
- is able to trigger a run of the asset matching module:
- manually:
- per CSAF document
- per list of CSAF documents
- per asset
- per list of assets
- automatically:
- when a new CSAF document is inserted (for this CSAF document)
- when a new asset is inserted (for this asset)
- when the Major version in a CSAF document with semantic versioning changes (for this CSAF document)
These also apply if more than one CSAF document or asset was added. To reduce the computational efforts the runs can be pooled into one run which fulfills all the tasks at once (batch mode).
Manually and automatically triggered runs should not be pooled.
- manually:
- provides at least the following statistics for the count of assets:
- matching that CSAF document at all
- marked with a given status
A program satisfies the "CSAF basic validator" conformance profile if the program:
- reads documents and performs a check against the JSON schema.
- performs all mandatory tests as given in section 4.1.
A CSAF basic validator may provide an additional function to only run one or more selected mandatory tests.
A CSAF basic validator satisfies the "CSAF extended validator" conformance profile if the CSAF basic validator:
- satisfies the "CSAF basic validator" conformance profile.
- additionally performs all optional tests as given in section 4.2.
A CSAF extended validator may provide an additional function to only run one or more selected optional tests.
A CSAF extended validator satisfies the "CSAF full validator" conformance profile if the CSAF extended validator:
- satisfies the "CSAF extended validator" conformance profile.
- additionally performs all informative tests as given in section 4.3.
A CSAF full validator may provide an additional function to only run one or more selected informative tests.
The following individuals were members of the OASIS CSAF Technical Committee during the creation of this specification and their contributions are gratefully acknowledged:
CSAF TC Members:
First Name | Last Name | Company |
---|---|---|
Participated | in meetings | Something Company |
Alex | Amirnovman | Company B |
Kris | Anderman | Mini Micro |
Darren | Anstman | Big Networks |
The following individuals were members of the OASIS CSAF Technical Committee during the creation of the previous version (CVRF v1.2) of this specification and their contributions are gratefully acknowledged:
CSAF TC Members:
First Name | Last Name | Company |
---|---|---|
Adam | Montville | CIS |
Allan | Thomson | LookingGlass |
Anthony | Berglas | Cryptsoft Pty Ltd. |
Art | Manion | Carnegie Mellon University |
Aukjan | van Belkum | EclecticIQ |
Ben | Sooter | Electric Power Research Institute |
Bernd | Grobauer | Siemens AG |
Beth | Pumo | Kaiser Permanente |
Bret | Jordan | Symantec Corp. |
Bruce | Rich | Cryptsoft Pty Ltd. |
Chet | Ensign | OASIS |
Chok | Poh | Oracle |
Chris | Rouland | Individual |
David | Waltermire | NIST |
Denny | Page | TIBCO Software Inc. |
Doron | Shiloach | IBM |
Duncan | Sparrell | sFractal Consulting LLC |
Eric | Johnson | TIBCO Software Inc. |
Feng | Cao | Oracle |
Greg | Reaume | TELUS |
Greg | Scott | Cryptsoft Pty Ltd. |
Harold | Booth | NIST |
Jamison | Day | LookingGlass |
Jared | Semrau | "FireEye, Inc." |
Jason | Masters | TELUS |
Jerome | Athias | Individual |
Jessica | Fitzgerald-McKay | National Security Agency |
Jonathan | Bitle | Kaiser Permanente |
Justin | Corlett | Cryptsoft Pty Ltd. |
Karen | Scarfone | Individual |
Kazuo | Noguchi | "Hitachi, Ltd." |
Kent | Landfield | McAfee |
Lothar | Braun | Siemens AG |
Louis | Ronnau | Cisco Systems |
Mark | Davidson | NC4 |
Mark-David | McLaughlin | Cisco Systems |
Masato | Terada | "Hitachi, Ltd." |
Masood | Nasir | TELUS |
Nicole | Gong | Mitre Corporation |
Omar | Santos | Cisco Systems |
Patrick | Maroney | Wapack Labs LLC |
Paul | Patrick | "FireEye, Inc." |
Peter | Allor | IBM |
Phillip | Boles | "FireEye, Inc." |
Ravi | Balupari | Netskope |
Rich | Reybok | ServiceNow |
Richard | Struse | DHS Office of Cybersecurity and Communications (CS&C) |
Ritwik | Ghoshal | Oracle |
Robert | Coderre | VeriSign |
Robin | Cover | OASIS |
Rupert | Wimmer | Siemens AG |
Sanjiv | Kalkar | Individual |
Sean | Barnum | Mitre Corporation |
Stefan | Hagen | Individual |
Ted | Bedwell | Cisco Systems |
Thomas | Schreck | Siemens AG |
Tim | Hudson | Cryptsoft Pty Ltd. |
Tony | Cox | Cryptsoft Pty Ltd. |
Trey | Darley | "Kingfisher Operations, sprl" |
Vincent | Danen | Red Hat |
Zach | Turk | Microsoft |
Revision | Date | Editor | Changes Made |
---|---|---|---|
csaf-v2.0-wd20210521 | 2021-05-21 | Stefan Hagen | Editor revision for TC review |