Merge pull request #63 from oasis-tcs/seeding-csaf-v-2-1

Sync across the forkscape with a merge commit
oasis-tcs · Dec 11, 2023 · 6fa161b · 6fa161b
2 parents 20aa5e0 + 00634fe
commit 6fa161b
Show file tree

Hide file tree

Showing 48 changed files with 4,674 additions and 21 deletions.
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -21,7 +21,7 @@ jobs:
           python3-wheel
         pip3 install jsonschema[format]
     - name: Check jsonschema version
-      run: jsonschema --version
+      run: python3 -c "from importlib.metadata import version; print(version('jsonschema'))"
     - name: Test examples against CSAF schema
       run: ./csaf_2.0/test/csaf_schema/run_tests.sh
     - name: Test VEX examples against CSAF schema
@@ -31,7 +31,7 @@ jobs:
     - name: Test examples against Aggregator schema
       run: ./csaf_2.0/test/aggregator_schema/run_tests.sh
     - name: Upload strict JSON schema artifact
-      uses: actions/upload-artifact@v2
+      uses: actions/upload-artifact@v3
       with:
         name: strict-schemas
         path: |

diff --git a/.github/workflows/validator.yml b/.github/workflows/validator.yml
@@ -20,7 +20,7 @@ jobs:
           python3-wheel
         pip3 install jsonschema[format]
     - name: Check jsonschema version
-      run: jsonschema --version
+      run: python3 -c "from importlib.metadata import version; print(version('jsonschema'))"
     - name: Test validator/data/mandatory against schema
       run: ./csaf_2.0/test/validator/run_tests.sh mandatory
     - name: Test validator/data/optional against schema

diff --git a/csaf_2.0/examples/aggregator/example-03-aggregator.json b/csaf_2.0/examples/aggregator/example-03-aggregator.json
@@ -0,0 +1,59 @@
+{
+  "aggregator": {
+    "category": "aggregator",
+    "contact_details": "Example Aggregator can be reached at contact_us@aggregator.example, or via our website at https://aggregator.example/security/csaf/aggregator/contact.",
+    "issuing_authority": "This service is provided as it is. It is free for everybody.",
+    "name": "Example Aggregator",
+    "namespace": "https://aggregator.example"
+  },
+  "aggregator_version": "2.0",
+  "canonical_url": "https://aggregator.example/.well-known/csaf-aggregator/aggregator.json",
+  "csaf_providers": [
+    {
+      "metadata": {
+        "last_updated": "2021-07-12T20:20:56.169Z",
+        "publisher": {
+          "category": "vendor",
+          "name": "Example Company ProductCERT",
+          "namespace": "https://psirt.example.com"
+        },
+        "url": "https://www.example.com/.well-known/csaf/provider-metadata.json"
+      },
+      "mirrors": [
+        "https://aggregator.example/.well-known/csaf-aggregator/Example_Company_ProductCERT/provider-metadata.json"
+      ]
+    },
+    {
+      "metadata": {
+        "last_updated": "2021-07-12T21:35:38.000Z",
+        "publisher": {
+          "category": "coordinator",
+          "name": "Example Coordinator CERT",
+          "namespace": "https://cert.example"
+        },
+        "url": "https://cert.example/advisories/csaf/provider-metadata.json"
+      },
+      "mirrors": [
+        "https://aggregator.example/.well-known/csaf-aggregator/Example_Coordinator_CERT/provider-metadata.json"
+      ]
+    }
+  ],
+  "csaf_publishers": [
+    {
+      "metadata": {
+        "last_updated": "2021-07-12T20:42:48.819Z",
+        "publisher": {
+          "category": "vendor",
+          "name": "Example Cooperation ProductCERT",
+          "namespace": "https://psirt.example.net"
+        },
+        "url": "https://www.example.net/.well-known/csaf/provider-metadata.json"
+      },
+      "mirrors": [
+        "https://aggregator.example/.well-known/csaf-aggregator/Example_Cooperation_ProductCERT/provider-metadata.json"
+      ],
+      "update_interval": "on best effort"
+    }
+  ],
+  "last_updated":"2021-07-12T22:35:38.978Z"
+}
diff --git a/csaf_2.0/guidance/cdn.md b/csaf_2.0/guidance/cdn.md
@@ -0,0 +1,59 @@
+# CSAF and Content Delivery Networks (CDNs)
+
+If you want to use a CDN to provide your CSAF files, please find some remarks below:
+
+- **Activate caching**: Most files are more or less static - activate caching to minimize risk for (D)DoS.
+- **Include path exemption**: The path `.well-known/csaf/` and potentially `.well-known/security.txt` need to be accessible for all HTTP-clients (also those that are usually detected as bots).
+
+  *Specifically, at least the files in this path ending on `.json`, `.asc`, `.sha256` and `.sha512` should be excluded.*
+- **Flush cache when updating files**: When new files are written or old files updated, the cache must be updated. Usually, this can be done through the API the CDN provides. Instead of flushing the whole cache (easy way), a more precise way can be used as files that need to be updated in the cache depend on the distribution method:
+
+  **Directory-based distribution:**
+
+  ```
+  <path-to-updated-CSAF-document>.json
+  <path-to-updated-CSAF-document>.json.asc
+  <path-to-updated-CSAF-document>.json.sha256
+  <path-to-updated-CSAF-document>.json.sha512
+  <path-of-index>.txt
+  <path-of-changes>.csv
+  ```
+
+  *Example:*
+
+  The CSAF advisory `ESA-2023-31816` was changed. Consequently, the following files in the cache need to be updated.
+
+  ```
+  .well-known/csaf/white/2023/esa-2023-31816.json
+  .well-known/csaf/white/2023/esa-2023-31816.json.asc
+  .well-known/csaf/white/2023/esa-2023-31816.json.sha256
+  .well-known/csaf/white/2023/esa-2023-31816.json.sha512
+  .well-known/csaf/white/index.txt
+  .well-known/csaf/white/changes.csv
+  ```
+
+  **ROLIE-based distribution:**
+
+  ```
+  <path-to-updated-CSAF-document>.json
+  <path-to-updated-CSAF-document>.json.asc
+  <path-to-updated-CSAF-document>.json.sha256
+  <path-to-updated-CSAF-document>.json.sha512
+  <path-of-ROLIE-feed>.json
+  <path-of-ROLIE-categories>.json
+  <path-of-ROLIE-services>.json
+  ```
+
+  *Example:*
+
+  The CSAF advisory `ESA-2023-31816` was changed. Consequently, the following files in the cache need to be updated.
+
+  ```
+  .well-known/csaf/white/2023/esa-2023-31816.json
+  .well-known/csaf/white/2023/esa-2023-31816.json.asc
+  .well-known/csaf/white/2023/esa-2023-31816.json.sha256
+  .well-known/csaf/white/2023/esa-2023-31816.json.sha512
+  .well-known/csaf/white/csaf-feed-tlp-white.json
+  .well-known/csaf/white/csaf-categories-tlp-white.json
+  .well-known/csaf/service.json
+  ```
diff --git a/csaf_2.0/guidance/faq.md b/csaf_2.0/guidance/faq.md
@@ -0,0 +1,57 @@
+# FAQ
+
+This document provides answers regarding frequently asked questions about CSAF 2.0. The TC will update the list if necessary. Questions can be suggested via [GitHub issues](https://github.com/oasis-tcs/csaf/issues) or via email on the [TC's comment mailing list](https://lists.oasis-open.org/archives/csaf-comment/).
+
+## General
+
+### What is the Common Security Advisory Framework (CSAF)?
+
+The Common Security Advisory Framework (CSAF) 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. You can [access the CSAF 2.0 standard here](https://docs.oasis-open.org/csaf/csaf/v2.0/os/csaf-v2.0-os.html).
+
+### What problems are addressed by CSAF?
+
+CSAF enables individuals and organizations to successfully disclose and consume security advisories in machine readable format. It also specifies the distribution and discovery of CSAF documents.
+
+## Relation to other standard and specifications
+
+### Is CSAF a replacement for CVE?
+
+**No.** CSAF is not a replacement for CVE. A CSAF document may include one or many security vulnerabilities that have been assigned a CVE. Not all vulnerabilities are assigned a CVE. CSAF also allows for any organization to be able to disclose or consume security vulnerabilities or responses that do not have an assigned CVE.
+
+### Is CSAF the replacement for CVRF?
+
+Yes. CSAF is the replacement for the [Common Vulnerability Reporting Framework (CVRF)](https://docs.oasis-open.org/csaf/csaf-cvrf/v1.2/csaf-cvrf-v1.2.html). It enhances the capabilities of CVRF including different profiles (e.g., CSAF Base, Informational Advisory, Incident Response, VEX, etc.). Each profile extends the base profile "CSAF Base" - directly or indirect through another profile from the standard - by making additional fields from the standard mandatory. A profile can always add, but never subtract nor overwrite requirements defined in the profile it extends. CSAF also provides several additional enhancements that were not supported in CVRF. In addition, CSAF uses JSON while CVRF used XML.
+
+### What is VEX and how is it supported in CSAF?
+
+The Vulnerability Exploitability eXchange (VEX) allows a software supplier or other parties to assert the status of specific vulnerabilities in a particular product. CSAF supports VEX to allow suppliers and other parties to provide the status of the vulnerabilities that may affect a product. As stated in [CISA's VEX Use Case documentation](https://www.cisa.gov/sites/default/files/publications/VEX_Use_Cases_Aprill2022.pdf), VEX is a form of a security advisory, similar to those already issued by mature product security teams today. There are a few important improvements for the VEX model over ‘traditional’ security advisories. First, VEX documents are machine readable, built to support integration into existing and novel security management tools, as well as broader vulnerability tracking platforms. Second, VEX data can support more effective use of [Software Bills of Materials (SBOM)](https://www.cisa.gov/sbom) data.
+
+### Why is CSAF 2.0 still using TLP v1?
+
+When the CSAF Committee Specification, which was later promoted to OASIS standard, was published the new [TLP v2](https://www.first.org/tlp/) was not available. Therefore, CSAF 2.0 only supports [TLP v1](https://www.first.org/tlp/v1/). Nevertheless, as TLP v2 is backwards compatible the following mapping table can be used to display the new TLP v2 terms in a human-readable advisory:
+
+| TLP v2 | TLP v1 |
+|--------|--------|
+| `TLP:CLEAR` | `TLP:WHITE` |
+| `TLP:GREEN` | `TLP:GREEN` |
+| `TLP:AMBER` | `TLP:AMBER` |
+| `TLP:AMBER+STRICT` | *not present* |
+| `TLP:RED` | `TLP:RED` |
+
+*Note:* There is no equivalent for the TLP v2 `TLP:AMBER+STRICT` in TLP v1. For situations, where the label `TLP:AMBER+STRICT` would be needed it is recommended to use the label `TLP:RED` in CSAF and explain the laxer requirement through `/document/distribution/text`.
+
+Starting with version CSAF 2.1, [CSAF will support TLP v2](https://github.com/oasis-tcs/csaf/issues/591).
+
+## CSAF Distribution
+
+### How can my organization be added to a CSAF lister or CSAF aggregator?
+
+CSAF lister and CSAF aggregator choose on their own which producing parties they add to their lists. Please reach out to the CSAF lister or CSAF aggregator in question. Their contact details are available in the metadata of the list.
+
+### I want to use a Content Delivery Network (CDN) to distribute CSAF files. What do I need to consider?
+
+Please see our advise on [CDNs](./cdn.md).
+
+### Where can I find a list of all parties that produce CSAF?
+
+Currently, there is no such list available. However, [BSI hosts a list with metadata of known parties](https://wid.cert-bund.de/.well-known/csaf-aggregator/aggregator.json) that produce CSAF files and distribute them in a way that they are automatically retrievable. This list is called a CSAF lister.
diff --git a/csaf_2.0/json_schema/aggregator_json_schema.json b/csaf_2.0/json_schema/aggregator_json_schema.json
@@ -175,7 +175,7 @@
         "type": "object",
         "required": [
           "metadata",
-          "mirror",
+          "mirrors",
           "update_interval"
         ],
         "properties": {

diff --git a/csaf_2.0/referenced_schema/first/cvss-v2.0.json b/csaf_2.0/referenced_schema/first/cvss-v2.0.json
@@ -0,0 +1,104 @@
+{
+    "license": [
+        "Copyright (c) 2017, FIRST.ORG, INC.",
+        "All rights reserved.",
+        "",
+        "Redistribution and use in source and binary forms, with or without modification, are permitted provided that the ",
+        "following conditions are met:",
+        "1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following ",
+        "   disclaimer.",
+        "2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the ",
+        "   following disclaimer in the documentation and/or other materials provided with the distribution.",
+        "3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote ",
+        "   products derived from this software without specific prior written permission.",
+        "",
+        "THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 'AS IS' AND ANY EXPRESS OR IMPLIED WARRANTIES, ",
+        "INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE ",
+        "DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, ",
+        "SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR ",
+        "SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, ",
+        "WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE ",
+        "OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+    ],
+
+    "$schema": "http://json-schema.org/draft-04/schema#",
+    "title": "JSON Schema for Common Vulnerability Scoring System version 2.0",
+    "id": "https://www.first.org/cvss/cvss-v2.0.json?20170531",
+    "type": "object",
+    "definitions": {
+        "accessVectorType": {
+            "type": "string",
+            "enum": [ "NETWORK", "ADJACENT_NETWORK", "LOCAL" ]
+        },
+        "accessComplexityType": {
+            "type": "string",
+            "enum": [ "HIGH", "MEDIUM", "LOW" ]
+        },
+        "authenticationType": {
+            "type": "string",
+            "enum": [ "MULTIPLE", "SINGLE", "NONE" ]
+        },
+        "ciaType": {
+            "type": "string",
+            "enum": [ "NONE", "PARTIAL", "COMPLETE" ]
+        },
+        "exploitabilityType": {
+            "type": "string",
+            "enum": [ "UNPROVEN", "PROOF_OF_CONCEPT", "FUNCTIONAL", "HIGH", "NOT_DEFINED" ]
+        },
+        "remediationLevelType": {
+            "type": "string",
+            "enum": [ "OFFICIAL_FIX", "TEMPORARY_FIX", "WORKAROUND", "UNAVAILABLE", "NOT_DEFINED" ]
+        },
+        "reportConfidenceType": {
+            "type": "string",
+            "enum": [ "UNCONFIRMED", "UNCORROBORATED", "CONFIRMED", "NOT_DEFINED" ]
+        },
+        "collateralDamagePotentialType": {
+            "type": "string",
+            "enum": [ "NONE", "LOW", "LOW_MEDIUM", "MEDIUM_HIGH", "HIGH", "NOT_DEFINED" ]
+        },
+        "targetDistributionType": {
+            "type": "string",
+            "enum": [ "NONE", "LOW", "MEDIUM", "HIGH", "NOT_DEFINED" ]
+        },
+        "ciaRequirementType": {
+            "type": "string",
+            "enum": [ "LOW", "MEDIUM", "HIGH", "NOT_DEFINED" ]
+        },
+        "scoreType": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 10
+        }
+    },
+    "properties": {
+        "version": {
+            "description": "CVSS Version",
+            "type": "string",
+            "enum": [ "2.0" ]
+        },
+        "vectorString": {
+            "type": "string",
+            "pattern": "^((AV:[NAL]|AC:[LMH]|Au:[MSN]|[CIA]:[NPC]|E:(U|POC|F|H|ND)|RL:(OF|TF|W|U|ND)|RC:(UC|UR|C|ND)|CDP:(N|L|LM|MH|H|ND)|TD:(N|L|M|H|ND)|[CIA]R:(L|M|H|ND))/)*(AV:[NAL]|AC:[LMH]|Au:[MSN]|[CIA]:[NPC]|E:(U|POC|F|H|ND)|RL:(OF|TF|W|U|ND)|RC:(UC|UR|C|ND)|CDP:(N|L|LM|MH|H|ND)|TD:(N|L|M|H|ND)|[CIA]R:(L|M|H|ND))$"
+        },
+        "accessVector":                   { "$ref": "#/definitions/accessVectorType" },
+        "accessComplexity":               { "$ref": "#/definitions/accessComplexityType" },
+        "authentication":                 { "$ref": "#/definitions/authenticationType" },
+        "confidentialityImpact":          { "$ref": "#/definitions/ciaType" },
+        "integrityImpact":                { "$ref": "#/definitions/ciaType" },
+        "availabilityImpact":             { "$ref": "#/definitions/ciaType" },
+        "baseScore":                      { "$ref": "#/definitions/scoreType" },
+        "exploitability":                 { "$ref": "#/definitions/exploitabilityType" },
+        "remediationLevel":               { "$ref": "#/definitions/remediationLevelType" },
+        "reportConfidence":               { "$ref": "#/definitions/reportConfidenceType" },
+        "temporalScore":                  { "$ref": "#/definitions/scoreType" },
+        "collateralDamagePotential":      { "$ref": "#/definitions/collateralDamagePotentialType" },
+        "targetDistribution":             { "$ref": "#/definitions/targetDistributionType" },
+        "confidentialityRequirement":     { "$ref": "#/definitions/ciaRequirementType" },
+        "integrityRequirement":           { "$ref": "#/definitions/ciaRequirementType" },
+        "availabilityRequirement":        { "$ref": "#/definitions/ciaRequirementType" },
+        "environmentalScore":             { "$ref": "#/definitions/scoreType" }
+    },
+    "required": [ "version", "vectorString", "baseScore" ]
+}