feat(CSAF2.1): #447 add mandatory test 6.2.47 - refactor getCanonicalUrl, improve naming and messages

Author: rainer-exxcellent

csaf_2_1/recommendedTests/recommendedTest_6_2_47.js

@@ -1,6 +1,5 @@
 import Ajv from 'ajv/dist/jtd.js'
-
-const ajv = new Ajv()
+import { isCanonicalUrl } from '../../lib/shared/urlHelper.js'
 
 /** @typedef {import('ajv/dist/jtd.js').JTDDataType<typeof inputSchema>} InputSchema */
 
@@ -10,6 +9,8 @@ const ajv = new Ajv()
 
 /** @typedef {NonNullable<Metric['content']>} MetricContent */
 
+/** @typedef {{url?: string, category?: string}} Reference */
+
 const jtdAjv = new Ajv()
 
 const inputSchema = /** @type {const} */ ({
@@ -21,7 +22,7 @@ const inputSchema = /** @type {const} */ ({
         references: {
           elements: {
             additionalProperties: true,
-            properties: {
+            optionalProperties: {
               category: { type: 'string' },
               url: { type: 'string' },
             },
@@ -64,41 +65,24 @@ const inputSchema = /** @type {const} */ ({
   },
 })
 
-/** @typedef {{ url: string; category: string}} Reference */
-
-const referenceSchema = /** @type {const} */ ({
-  additionalProperties: true,
-  properties: {
-    category: { type: 'string' },
-    url: { type: 'string' },
-  },
-})
-
-const validate = jtdAjv.compile(inputSchema)
-const validateReference = ajv.compile(referenceSchema)
+const validateInput = jtdAjv.compile(inputSchema)
 
 /**
  * Get the canonical url from the document
  * @return {string} canonical url or empty when no canonical url exists
- * @param {Array<Reference> | undefined} references
- * @param {string | undefined} trackingId
+ * @param {Array<{url?: string, category?: string}>|undefined} references
+ * @param {string|undefined} trackingId
  */
 function getCanonicalUrl(references, trackingId) {
   if (references && trackingId) {
     // Find the reference that matches our criteria
     /** @type {Reference| undefined} */
-    const canonicalUrlReference = references.find(
-      (reference) =>
-        validateReference(reference) &&
-        reference.category === 'self' &&
-        reference.url.startsWith('https://') &&
-        reference.url.endsWith(
-          trackingId.toLowerCase().replace(/[^+\-a-z0-9]+/g, '_') + '.json'
-        )
+    const canonicalUrlReference = references.find((reference) =>
+      isCanonicalUrl(reference, trackingId)
     )
 
     // When we find a matching reference, we know it has the url property
-    // because validateReference ensures it matches the Reference schema
+    // because isCanonicalUrl ensures it matches the Reference schema
     return canonicalUrlReference?.url ?? ''
   } else {
     return ''
@@ -112,7 +96,7 @@ function getCanonicalUrl(references, trackingId) {
  * @param {string} canonicalURL
  * @return {boolean}
  */
-function hasServerRatingAndNoSource(metric, canonicalURL) {
+function hasSeverityRatingAndNoSource(metric, canonicalURL) {
   return (
     (!metric.source || metric.source === canonicalURL) &&
     !!metric?.content?.qualitative_severity_rating
@@ -129,18 +113,18 @@ function hasServerRatingAndNoSource(metric, canonicalURL) {
  * @param {any} doc
  */
 export function recommendedTest_6_2_47(doc) {
-  /** @type {Array<{ message: string; instancePath: string }>} */
-  const warnings = []
-  const context = { warnings }
-
-  if (!validate(doc)) {
-    return context
+  const ctx = {
+    warnings:
+      /** @type {Array<{ instancePath: string; message: string }>} */ ([]),
+  }
+  if (!validateInput(doc)) {
+    return ctx
   }
 
   /** @type {Array<Vulnerability>} */
   const vulnerabilities = doc.vulnerabilities
   const canonicalURL = getCanonicalUrl(
-    doc.document.references,
+    doc.document?.references,
     doc.document?.tracking?.id
   )
 
@@ -150,23 +134,23 @@ export function recommendedTest_6_2_47(doc) {
     /** @type {Array<String> | undefined} */
     const invalidPaths = metrics
       ?.map((metric, metricIndex) =>
-        hasServerRatingAndNoSource(metric, canonicalURL)
+        hasSeverityRatingAndNoSource(metric, canonicalURL)
           ? `/vulnerabilities/${vulnerabilityIndex}/metrics/${metricIndex}/content/qualitative_severity_rating`
           : null
       )
       .filter((path) => path !== null)
 
     if (!!invalidPaths) {
       invalidPaths.forEach((path) => {
-        context.warnings.push({
+        ctx.warnings.push({
           message:
-            'the metric has a qualitative severity rating and no source property' +
-            ' or a source property that ist equal to the canonical URL',
+            'a qualitative severity rating is used by the issuing party (as no "source" is given' +
+            '  or the source property equals to the canonical URL)',
           instancePath: path,
         })
       })
     }
   })
 
-  return context
+  return ctx
 }

lib/optionalTests/optionalTest_6_2_11.js

@@ -1,4 +1,5 @@
 import Ajv from 'ajv/dist/jtd.js'
+import { isCanonicalUrl } from '../shared/urlHelper.js'
 
 const ajv = new Ajv()
 
@@ -26,16 +27,7 @@ const inputSchema = /** @type {const} */ ({
   },
 })
 
-const referenceSchema = /** @type {const} */ ({
-  additionalProperties: true,
-  properties: {
-    category: { type: 'string' },
-    url: { type: 'string' },
-  },
-})
-
 const validate = ajv.compile(inputSchema)
-const validateReference = ajv.compile(referenceSchema)
 
 /**
  * @param {any} doc
@@ -58,15 +50,8 @@ export default function optionalTest_6_2_11(doc) {
     return ctx
   }
 
-  const hasCanonicalURL = doc.document.references.some(
-    (r) =>
-      validateReference(r) &&
-      r.category === 'self' &&
-      r.url.startsWith('https://') &&
-      r.url.endsWith(
-        doc.document.tracking.id.toLowerCase().replace(/[^+\-a-z0-9]+/g, '_') +
-          '.json'
-      )
+  const hasCanonicalURL = doc.document.references.some((reference) =>
+    isCanonicalUrl(reference, doc.document.tracking.id)
   )
 
   if (!hasCanonicalURL) {

lib/shared/urlHelper.js

@@ -0,0 +1,42 @@
+import Ajv from 'ajv/dist/jtd.js'
+
+const ajv = new Ajv()
+
+const referenceSchema = /** @type {const} */ ({
+  additionalProperties: true,
+  properties: {
+    category: { type: 'string' },
+    url: { type: 'string' },
+  },
+})
+const validateReference = ajv.compile(referenceSchema)
+
+/**
+ * Checks whether a reference contains a canonical URL
+ * It works for CSAF 2.0 and CSAF 2.1
+ * A canonical URL fulfills all the following:
+ * - It has the category self
+ * - The url starts with https://
+ * - The url ends with the valid filename for the CSAF document
+ * A filename must apply the following rules
+ * - The value /trackingId is converted into lower case
+ * - Any character sequence which is not part of one of the following groups MUST be replaced by a single underscore (_)
+ *   Lower case ASCII letters (0x61 - 0x7A)
+ *   digits (0x30 - 0x39)
+ *   special characters: + (0x2B), - (0x2D)
+ * - The file extension .json MUST be appended.
+ * @param {{url?: string, category?: string}} reference
+ * @param {string} trackingId
+ * @return {boolean}
+ */
+export function isCanonicalUrl(reference, trackingId) {
+  return (
+    validateReference(reference) &&
+    reference.category === 'self' &&
+    reference.url !== undefined &&
+    reference.url.startsWith('https://') &&
+    reference.url.endsWith(
+      trackingId.toLowerCase().replace(/[^+\-a-z0-9]+/g, '_') + '.json'
+    )
+  )
+}

tests/csaf_2_1/recommendedTest_6_2_47.js

@@ -8,4 +8,37 @@ describe('recommendedTest_6_2_47', function () {
       0
     )
   })
+
+  it('runs on references with empty category in reference', function () {
+    assert.equal(
+      recommendedTest_6_2_47({
+        document: {
+          references: [
+            {
+              category: 'self',
+              summary: 'The canonical URL for the CSAF document.',
+              url: 'https://example.com/.well-known/csaf/clear/2024/oasis_csaf_tc-csaf_2_1-2024-6-2-47-02.json',
+            },
+            { url: 'https://some.other.url' },
+          ],
+          tracking: {
+            id: 'OASIS_CSAF_TC-CSAF_2.1-2024-6-2-47-11',
+          },
+        },
+        vulnerabilities: [
+          {
+            metrics: [
+              {
+                content: {
+                  qualitative_severity_rating: 'low',
+                },
+                products: ['CSAFPID-9080700'],
+              },
+            ],
+          },
+        ],
+      }).warnings.length,
+      1
+    )
+  })
 })

tests/urlHelper.js

@@ -0,0 +1,60 @@
+import { isCanonicalUrl } from '../lib/shared/urlHelper.js'
+import { expect } from 'chai'
+
+describe('test url helper', function () {
+  it('test isCanonicalUrl', function () {
+    expect(
+      isCanonicalUrl(
+        {
+          url: 'https://example.com/.well-known/csaf/clear/2024/oasis_csaf_tc-csaf_2_1-2024-6-2-47-12.json',
+          category: 'self',
+        },
+        'OASIS_CSAF_TC-CSAF_2.1-2024-6-2-47-12'
+      ),
+      'Valid canonical URL'
+    ).to.be.true
+
+    expect(
+      isCanonicalUrl(
+        {
+          url: 'https://example.com/.well-known/csaf/clear/2024/oasis_csaf_tc-csaf_2_1-2024-6-2-47-12.json',
+          category: 'not_self',
+        },
+        'OASIS_CSAF_TC-CSAF_2.1-2024-6-2-47-12'
+      ),
+      'Invalid canonical URL - category not self'
+    ).to.be.false
+  })
+
+  expect(
+    isCanonicalUrl(
+      {
+        url: 'http://example.com/.well-known/csaf/clear/2024/oasis_csaf_tc-csaf_2_1-2024-6-2-47-12.json',
+        category: 'self',
+      },
+      'OASIS_CSAF_TC-CSAF_2.1-2024-6-2-47-12'
+    ),
+    'Invalid canonical URL - url starts not with https://'
+  ).to.be.false
+
+  expect(
+    isCanonicalUrl(
+      {
+        category: 'self',
+      },
+      'OASIS_CSAF_TC-CSAF_2.1-2024-6-2-47-12'
+    ),
+    'Invalid canonical URL - no URL '
+  ).to.be.false
+
+  expect(
+    isCanonicalUrl(
+      {
+        url: 'https://example.com/.well-known/csaf/clear/2024/oasis_csaf_tc-csaf_2_1-2024-6-2-47-12_invalid.json',
+        category: 'self',
+      },
+      'OASIS_CSAF_TC-CSAF_2.1-2024-6-2-47-12'
+    ),
+    'Valid canonical URL - URL ends not with valid filename'
+  ).to.be.false
+})