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 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

@@ -56,6 +56,10 @@
     {
       "name": "Tristan Bastian",
       "url": "https://github.com/reey"
+    },
+    {
+      "name": "Frozen_byte",
+      "url": "https://github.com/Frozen-byte"
     }
   ],
   "type": "commonjs",

src/_helpers.ts

@@ -17,8 +17,8 @@ SPDX-License-Identifier: Apache-2.0
 Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
-import { existsSync, readFileSync } from 'fs'
-import { dirname, isAbsolute, join, sep } from 'path'
+import { existsSync, readdirSync, readFileSync } from 'fs'
+import { dirname, extname, isAbsolute, join, sep } from 'path'
 
 export interface PackageDescription {
   path: string
@@ -74,3 +74,51 @@ export function loadJsonFile (path: string): any {
   // as soon as this spec is properly implemented.
   // see https://github.com/tc39/proposal-import-attributes
 }
+
+const LICENSE_FILENAME_PATTERN = /^(?:UN)?LICEN[CS]E|NOTICE/i
+/**
+ * Searches typical files in the package path which have typical a license notice text inside
+ *
+ * @param {string} searchFolder folder to look for common filenames
+ *
+ * @yields {{ filepath: string, contentType: string}} Next matching file containing path and MIME type
+ */
+export function * searchEvidenceSources (searchFolder: string): Generator<{
+  filepath: string
+  contentType: string
+}> {
+  for (const dirent of readdirSync(searchFolder, { withFileTypes: true })) {
+    if (
+      !dirent.isFile() ||
+      !LICENSE_FILENAME_PATTERN.test(dirent.name)
+    ) {
+      continue
+    }
+
+    const contentType = determineContentType(dirent.name)
+    if (contentType === undefined) {
+      continue
+    }
+
+    yield {
+      filepath: `${dirent.parentPath}/${dirent.name}`,
+      contentType
+    }
+  }
+}
+
+// common file endings that are used for notice/license files
+const CONTENT_TYPE_MAP: Record<string, string> = {
+  '': 'text/plain',
+  '.txt': 'text/plain',
+  '.md': 'text/markdown',
+  '.xml': 'text/xml'
+} as const
+
+/**
+ * Returns the MIME type for the file or undefined if nothing was matched
+ * @param {string} filename filename or complete filepath
+ */
+export function determineContentType (filename: string): string | undefined {
+  return CONTENT_TYPE_MAP[extname(filename)]
+}

src/extractor.ts

@@ -18,10 +18,12 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
 import * as CDX from '@cyclonedx/cyclonedx-library'
+import { readFileSync } from 'fs'
 import * as normalizePackageJson from 'normalize-package-data'
+import { basename, dirname } from 'path'
 import { type Compilation, type Module } from 'webpack'
 
-import { getPackageDescription, type PackageDescription } from './_helpers'
+import { getPackageDescription, type PackageDescription, searchEvidenceSources } from './_helpers'
 
 type WebpackLogger = Compilation['logger']
 
@@ -40,7 +42,7 @@ export class Extractor {
     this.#purlFactory = purlFactory
   }
 
-  generateComponents (modules: Iterable<Module>, logger?: WebpackLogger): Iterable<CDX.Models.Component> {
+  generateComponents (modules: Iterable<Module>, collectEvidence?: boolean, logger?: WebpackLogger): Iterable<CDX.Models.Component> {
     const pkgs: Record<string, CDX.Models.Component | undefined> = {}
     const components = new Map<Module, CDX.Models.Component>()
 
@@ -59,7 +61,7 @@ export class Extractor {
       if (component === undefined) {
         logger?.log('try to build new Component from PkgPath:', pkg.path)
         try {
-          component = this.makeComponent(pkg, logger)
+          component = this.makeComponent(pkg, collectEvidence, logger)
         } catch (err) {
           logger?.debug('unexpected error:', err)
           logger?.warn('skipped Component from PkgPath', pkg.path)
@@ -81,7 +83,7 @@ export class Extractor {
   /**
    * @throws {Error} when no component could be fetched
    */
-  makeComponent (pkg: PackageDescription, logger?: WebpackLogger): CDX.Models.Component {
+  makeComponent (pkg: PackageDescription, collectEvidence?: boolean, logger?: WebpackLogger): CDX.Models.Component {
     try {
       const _packageJson = structuredClonePolyfill(pkg.packageJson)
       normalizePackageJson(_packageJson as object /* add debug for warnings? */)
@@ -108,6 +110,14 @@ export class Extractor {
     component.purl = this.#purlFactory.makeFromComponent(component)
     component.bomRef.value = component.purl?.toString()
 
+    if (collectEvidence === true) {
+      try {
+        component.evidence = this.makeComponentEvidence(pkg)
+      } catch (e) {
+        logger?.warn('collecting Evidence from PkgPath', pkg.path, 'failed:', e)
+      }
+    }
+
     return component
   }
 
@@ -121,6 +131,32 @@ export class Extractor {
       }
     }
   }
+
+  /**
+   * Look for common files that may provide licenses and attach them to the component as evidence
+   * @param pkg
+   */
+  makeComponentEvidence (pkg: PackageDescription): CDX.Models.ComponentEvidence {
+    const cdxComponentEvidence = new CDX.Models.ComponentEvidence()
+
+    // Add license evidence
+    for (const { contentType, filepath } of searchEvidenceSources(dirname(pkg.path))) {
+      cdxComponentEvidence.licenses.add(new CDX.Models.NamedLicense(
+        `file: ${basename(filepath)}`,
+        {
+          text: new CDX.Models.Attachment(
+            readFileSync(filepath).toString('base64'),
+            {
+              contentType,
+              encoding: CDX.Enums.AttachmentEncoding.Base64
+            }
+          )
+        }
+      ))
+    }
+
+    return cdxComponentEvidence
+  }
 }
 
 function isNonNullable<T> (value: T): value is NonNullable<T> {

src/plugin.ts

@@ -53,6 +53,13 @@ export interface CycloneDxWebpackPluginOptions {
    */
   validateResults?: CycloneDxWebpackPlugin['validateResults']
 
+  /**
+   * Look for common files that may provide licenses 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,7 @@ export class CycloneDxWebpackPlugin {
     this.specVersion = specVersion
     this.reproducibleResults = reproducibleResults
     this.validateResults = validateResults
+    this.collectEvidence = collectEvidence
     this.resultXml = joinPath(outputLocation, './bom.xml')
     this.resultJson = joinPath(outputLocation, './bom.json')
     this.resultWellknown = includeWellknown
@@ -224,7 +234,7 @@ export class CycloneDxWebpackPlugin {
         const extractor = new Extractor(compilation, cdxComponentBuilder, cdxPurlFactory)
 
         thisLogger.log('generating components...')
-        for (const component of extractor.generateComponents(modules, thisLogger.getChildLogger('Extractor'))) {
+        for (const component of extractor.generateComponents(modules, this.collectEvidence, thisLogger.getChildLogger('Extractor'))) {
           if (bom.metadata.component !== undefined &&
             bom.metadata.component.group === component.group &&
             bom.metadata.component.name === component.name &&

tests/integration/feature-issue676/.gitignore

@@ -0,0 +1,42 @@
+# See http://help.github.com/ignore-files/ for more about ignoring files.
+
+# Compiled output
+/dist
+/tmp
+/out-tsc
+/bazel-out
+
+# Node
+/node_modules
+npm-debug.log
+yarn-error.log
+
+# IDEs and editors
+.idea/
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+
+# Visual Studio Code
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+.history/*
+
+# Miscellaneous
+/.angular/cache
+.sass-cache/
+/connect.lock
+/coverage
+/libpeerconnection.log
+testem.log
+/typings
+
+# System files
+.DS_Store
+Thumbs.db