feat: collect evidences for license

README.md

@@ -49,6 +49,7 @@ new CycloneDxWebpackPlugin(options?: object)
 | **`specVersion`** | `{string}`<br/>one of: `"1.2"`, `"1.3"`, `"1.4"`, `"1.5"`, `"1.6"` | `"1.4"` |  Which version of [CycloneDX-spec] to use.<br/> Supported values depend on the installed dependency [CycloneDX-javascript-library]. |
 | **`reproducibleResults`** | `{boolean}` | `false` | Whether to go the extra mile and make the output reproducible.<br/> Reproducibility might result in loss of time- and random-based-values. |
 | **`validateResults`** | `{boolean}` | `true` | Whether to validate the BOM result.<br/>Validation is skipped, if requirements not met. Requires [transitive optional dependencies](https://github.com/CycloneDX/cyclonedx-javascript-library#optional-dependencies). |
+| **`collectEvidence`** | `{boolean}` | `false` | Look for common files that may provide licenses or copyrights and attach them to the component as evidence. |
 | **`outputLocation`** | `{string}` | `"./cyclonedx"` | Path to write the output to. The path is relative to _webpack_'s overall output path. |
 | **`includeWellknown`** | `{boolean}` | `true` | Whether to write the Wellknowns. |
 | **`wellknownLocation`** | `{string}` | `"./.well-known"` | Path to write the Wellknowns to. The path is relative to _webpack_'s overall output path. | 

package.json

@@ -60,7 +60,7 @@
   ],
   "type": "commonjs",
   "engines": {
-    "node": ">=14"
+    "node": ">=18"
   },
   "dependencies": {
     "@cyclonedx/cyclonedx-library": "^6.11.0",

src/_helpers.ts

@@ -17,6 +17,9 @@
 Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
+import { readdirSync } from 'node:fs'
+
+import * as CDX from '@cyclonedx/cyclonedx-library'
 import { existsSync, readFileSync } from 'fs'
 import { dirname, isAbsolute, join, sep } from 'path'
 
@@ -74,3 +77,94 @@
   // as soon as this spec is properly implemented.
   // see https://github.com/tc39/proposal-import-attributes
 }
+
+/**
+ * Searches typical files in the package path which have typical a license notice or copyright text inside
+ *
+ * @param {string} searchFolder folder to look for common filenames
+ * @returns {Array<string>} filepath to files that may contain
+ */
+export function searchEvidenceSources (searchFolder: string): Array<{ filepath: string, contentType: string }> {
+  const typicalFilenameRex = /^(un)?licen[cs]e|notice|copyrightnotice/i
+  const evidenceFilenames = []
+
+  for (const dirent of readdirSync(searchFolder, { withFileTypes: true })) {
+    if (!typicalFilenameRex.test(dirent.name)) {
+      continue
+    }
+
+    const contentType = determineContentType(dirent.name)
+    if (contentType === undefined) {
+      continue
+    }
+
+    const filepath = dirent.parentPath + dirent.name
+
+    evidenceFilenames.push({
+      filepath,
+      contentType
+    })
+  }
+
+  return evidenceFilenames
+}
+
+/**
+ * Returns the MIME type for the file or undefined if nothing was matched
+ * @param filename
+ */
+export function determineContentType (filename: string): string | undefined {
+  // common file endings that are used for notice/license files
+  const contentTypeMap: Record<string, string> = {
+    '': 'text/plain',
+    txt: 'text/plain',
+    md: 'text/markdown',
+    xml: 'text/xml'
+  }
+  const fileExt = filename.lastIndexOf('.') === -1 ? '' : filename.split('.').at(-1)
+
+  return fileExt !== undefined ? contentTypeMap[fileExt] : undefined
+}
+
+/**
+ * Look for common files that may provide licenses or copyrights and attach them to the component as evidence
+ * @param pkg
+ * @param licenseFactory
+ */
+export function getComponentEvidence (pkg: PackageDescription, licenseFactory: CDX.Factories.LicenseFactory): CDX.Models.ComponentEvidence {
+  const evidenceFilenames = searchEvidenceSources(pkg.path.slice(0, 'package.json'.length * -1))
+  const cdxComponentEvidence = new CDX.Models.ComponentEvidence()
+
+  evidenceFilenames.forEach(({ contentType, filepath }) => {
+    const encoding = CDX.Enums.AttachmentEncoding.Base64
+    const buffer = readFileSync(filepath)
+
+    // Add license evidence
+    const attachment = licenseFactory.makeDisjunctive(pkg.packageJson.license as string)
+    attachment.text = {
+      contentType,
+      encoding,
+      content: buffer.toString(encoding)
+    }
+
+    cdxComponentEvidence.licenses.add(attachment)
+
+    // Add copyright evidence
+    const linesStartingWithCopyright = buffer.toString('utf-8')
+      .split(/\r\n?|\n/)
+      .map(line => line.trimStart())
+      .filter(trimmedLine => {
+        return trimmedLine.startsWith('opyright', 1) && // include copyright statements
+          !trimmedLine.startsWith('opyright notice', 1) && // exclude lines from license text
+          !trimmedLine.startsWith('opyright and related rights', 1) &&
+          !trimmedLine.startsWith('opyright license to reproduce', 1)
+      })
+      .filter((value, index, list) => index === 0 || value !== list[0]) // remove duplicates
+
+    linesStartingWithCopyright.forEach(line => {
+      cdxComponentEvidence.copyright.add(line)
+    })
+  })
+
+  return cdxComponentEvidence
+}

src/extractor.ts

@@ -21,23 +21,29 @@ import * as CDX from '@cyclonedx/cyclonedx-library'
 import * as normalizePackageJson from 'normalize-package-data'
 import { type Compilation, type Module } from 'webpack'
 
-import { getPackageDescription, type PackageDescription } from './_helpers'
+import { getComponentEvidence, getPackageDescription, type PackageDescription } from './_helpers'
 
 type WebpackLogger = Compilation['logger']
 
 export class Extractor {
   readonly #compilation: Compilation
   readonly #componentBuilder: CDX.Builders.FromNodePackageJson.ComponentBuilder
   readonly #purlFactory: CDX.Factories.FromNodePackageJson.PackageUrlFactory
+  readonly #licenseFactory: CDX.Factories.LicenseFactory
+  readonly #collectEvidence: boolean
 
   constructor (
     compilation: Compilation,
     componentBuilder: CDX.Builders.FromNodePackageJson.ComponentBuilder,
-    purlFactory: CDX.Factories.FromNodePackageJson.PackageUrlFactory
+    purlFactory: CDX.Factories.FromNodePackageJson.PackageUrlFactory,
+    licenseFactory: CDX.Factories.LicenseFactory,
+    collectEvidence: boolean
   ) {
     this.#compilation = compilation
     this.#componentBuilder = componentBuilder
     this.#purlFactory = purlFactory
+    this.#collectEvidence = collectEvidence
+    this.#licenseFactory = licenseFactory
   }
 
   generateComponents (modules: Iterable<Module>, logger?: WebpackLogger): Iterable<CDX.Models.Component> {
@@ -108,6 +114,14 @@ export class Extractor {
     component.purl = this.#purlFactory.makeFromComponent(component)
     component.bomRef.value = component.purl?.toString()
 
+    if (this.#collectEvidence) {
+      try {
+        component.evidence = getComponentEvidence(pkg, this.#licenseFactory)
+      } catch (e) {
+        logger?.warn('collecting Evidence from PkgPath', pkg.path, 'failed:', e)
+      }
+    }
+
     return component
   }
 

src/plugin.ts

@@ -53,6 +53,13 @@ export interface CycloneDxWebpackPluginOptions {
    */
   validateResults?: CycloneDxWebpackPlugin['validateResults']
 
+  /**
+   * Look for common files that may provide licenses or copyrights and attach them to the component as evidence
+   *
+   * @default false
+   */
+  collectEvidence?: boolean
+
   /**
    * Path to write the output to.
    * The path is relative to webpack's overall output path.
@@ -119,6 +126,7 @@ export class CycloneDxWebpackPlugin {
   specVersion: CDX.Spec.Version
   reproducibleResults: boolean
   validateResults: boolean
+  collectEvidence: boolean
 
   resultXml: string
   resultJson: string
@@ -133,6 +141,7 @@ export class CycloneDxWebpackPlugin {
     specVersion = CDX.Spec.Version.v1dot4,
     reproducibleResults = false,
     validateResults = true,
+    collectEvidence = false,
     outputLocation = './cyclonedx',
     includeWellknown = true,
     wellknownLocation = './.well-known',
@@ -144,6 +153,14 @@ export class CycloneDxWebpackPlugin {
     this.specVersion = specVersion
     this.reproducibleResults = reproducibleResults
     this.validateResults = validateResults
+    this.collectEvidence = collectEvidence
+    // evidence where introduced in v1.3
+    if ([CDX.Spec.Version.v1dot0, CDX.Spec.Version.v1dot1, CDX.Spec.Version.v1dot2].includes(specVersion)) {
+      throw new Error(
+        'Failed to generate valid BOM\n' +
+        'defined spec version has to be 1.3 or higher for collecting evidence'
+      )
+    }
     this.resultXml = joinPath(outputLocation, './bom.xml')
     this.resultJson = joinPath(outputLocation, './bom.json')
     this.resultWellknown = includeWellknown
@@ -221,7 +238,7 @@ export class CycloneDxWebpackPlugin {
       pluginName,
       (_, modules) => {
         const thisLogger = logger.getChildLogger('ComponentFetcher')
-        const extractor = new Extractor(compilation, cdxComponentBuilder, cdxPurlFactory)
+        const extractor = new Extractor(compilation, cdxComponentBuilder, cdxPurlFactory, cdxLicenseFactory, this.collectEvidence)
 
         thisLogger.log('generating components...')
         for (const component of extractor.generateComponents(modules, thisLogger.getChildLogger('Extractor'))) {