Creates CycloneDX Software Bill of Materials (SBoM) from webpack projects
npm install @cyclonedx/webpack-plugin[![shield_npm-version]][link_npm]
[![shield_gh-workflow-test]][link_gh-workflow-test]
[![shield_coverage]][link_codacy]
[![shield_ossf-best-practices]][link_ossf-best-practices]
[![shield_license]][license_file]
[![shield_website]][link_website]
[![shield_slack]][link_slack]
[![shield_groups]][link_discussion]
[![shield_twitter-follow]][link_twitter]
----
This plugin for _[webpack]_ creates a _[CycloneDX]_ Software Bill of Materials (SBoM) containing an aggregate of all bundled dependencies.
This is probably the most accurate, complete SBOM generator for webpack-based builds.
This plugin uses the linkages generated by _webpack_ to create a dependency graph which only contain the dependencies
that are actually used (after tree-shaking).
* _Node.js_ >= 20.18
* _webpack_ ^5
However, there are older versions of this plugin, that support
* _Node.js_ v8.0.0 or higher
* _webpack_ v4.0.0 or higher
``shell`
npm i -D @cyclonedx/webpack-plugin
yarn add -D @cyclonedx/webpack-plugin
`javascript`
new CycloneDxWebpackPlugin(options?: object)
| Name | Type | Default | Description |
|:-----|:----:|:-------:|:------------|
| specVersion | {string}
one of: , "1.3", "1.4", "1.5", "1.6", "1.7" | "1.6" | Which version of [CycloneDX-spec] to use.reproducibleResults
Supported values depend on the installed dependency [CycloneDX-javascript-library]. |
| | {boolean} | false | Whether to go the extra mile and make the output reproducible.validateResults
Reproducibility might result in loss of time- and random-based-values. |
| | {boolean} | true | Whether to validate the BOM result.outputLocation
Validation is skipped, if requirements not met. Requires transitive optional dependencies. |
| | {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. | rootComponentAutodetect
| | {boolean} | true | Whether to try auto-detection of the RootComponent.package.json
Tries to find the nearest and build a CycloneDX component from it, so it can be assigned to bom.metadata.component. |rootComponentType
| | {string} | "application" | Set the RootComponent's type.ComponentType
See the list of valid values. Supported values depend on [CycloneDX-javascript-library]'s enum . |rootComponentName
| | optional {string} | undefined | If rootComponentAutodetect is disabled, then this value is assumed as the "name" of the package.json. |rootComponentVersion
| | optional {string} | undefined | If rootComponentAutodetect is disabled, then this value is assumed as the "version" of the package.json. |rootComponentVCS
| | optional {string} | undefined | If rootComponentAutodetect is disabled or the Version Control System is not declared in the package.json, then this value is used as the URL for [RootComponent's External References'][docs_cdx_metadata_component_externalReferences] of type "vcs". |rootComponentBuildSystem
| | optional {string} | undefined | Set the URL for [RootComponent's External References'][docs_cdx_metadata_component_externalReferences] of type "build-system".rootComponentAutodetect
This behavior is regardless of 's status. |collectEvidence
| | {boolean} | false | Whether to collect (license) evidence and attach them to the resulting SBOM. |
In your [webpack config] add the CycloneDX plugin:
`javascript
const { CycloneDxWebpackPlugin } = require('@cyclonedx/webpack-plugin');
/* @type {import('@cyclonedx/webpack-plugin').CycloneDxWebpackPluginOptions} /
const cycloneDxWebpackPluginOptions = {
specVersion: '1.7',
outputLocation: './bom'
}
module.exports = {
// ...
plugins: [
new CycloneDxWebpackPlugin(cycloneDxWebpackPluginOptions)
]
}
`
See extended [examples].
The CycloneDX _webpack_ plugin supports placing the CycloneDX SBOM in a pre-defined location, specifically in
/.well-known/sbom. This option is enabled by default. The behavior can be changed by overriding the values includeWellknown
of and wellknownLocation.
See [draft-ietf-opsawg-sbom-access] for more information on the specification, currently an IETF draft.
In your [webpack config] add the CycloneDX plugin:
`javascript
const { CycloneDxWebpackPlugin } = require('@cyclonedx/webpack-plugin');
/* @type {import('@cyclonedx/webpack-plugin').CycloneDxWebpackPluginOptions} /
const cycloneDxWebpackPluginOptions = {
includeWellknown: true,
wellknownLocation: './.well-known'
}
module.exports = {
// ...
plugins: [
new CycloneDxWebpackPlugin(cycloneDxWebpackPluginOptions)
]
}
`
_Angular_ uses _webpack_ under the hood. Therefore, it is possible to integrate this plugin by utilizing
@angular-builders/custom-webpack.
See an example here: integration with Angular17/webpack5.
_React_ uses _webpack_ under the hood. Therefore, it is possible to integrate this plugin.
See an example here: integration with React18/webpack5.
This _webpack_ plugin utilizes the [CycloneDX library][CycloneDX-javascript-library] to generate the actual data structures.
Besides the class CycloneDxWebpackPlugin and the interface CycloneDxWebpackPluginOptions`,
this _webpack_ plugin does not expose any additional _public_ API or classes - all code is intended to be internal and might change without any notice during version upgrades.
Feel free to open issues, bugreports or pull requests.
See the [CONTRIBUTING][contributing_file] file for details.
Permission to modify and redistribute is granted under the terms of the Apache 2.0 license.
See the [LICENSE][license_file] file for the full license.
[CycloneDX]: https://cyclonedx.org/
[CycloneDX-spec]: https://github.com/CycloneDX/
[webpack]: https://webpack.js.org/
[webpack config]: https://webpack.js.org/configuration/
[draft-ietf-opsawg-sbom-access]: https://datatracker.ietf.org/doc/html/draft-ietf-opsawg-sbom-access
[CycloneDX-javascript-library]: https://github.com/CycloneDX/cyclonedx-javascript-library/
[license_file]: https://github.com/CycloneDX/cyclonedx-webpack-plugin/blob/master/LICENSE
[contributing_file]: https://github.com/CycloneDX/cyclonedx-webpack-plugin/blob/master/CONTRIBUTING.md
[examples]: https://github.com/CycloneDX/cyclonedx-webpack-plugin/tree/master/examples
[shield_gh-workflow-test]: https://img.shields.io/github/actions/workflow/status/CycloneDX/cyclonedx-webpack-plugin/nodejs.yml?branch=master&logo=GitHub&logoColor=white "tests"
[shield_npm-version]: https://img.shields.io/npm/v/%40cyclonedx%2fwebpack-plugin/latest?label=npm&logo=npm&logoColor=white "npm"
[shield_license]: https://img.shields.io/github/license/CycloneDX/cyclonedx-webpack-plugin?logo=open%20source%20initiative&logoColor=white "license"
[shield_ossf-best-practices]: https://img.shields.io/cii/percentage/7884?label=OpenSSF%20best%20practices "OpenSSF best practices"
[shield_coverage]: https://img.shields.io/codacy/coverage/100ece8926d548e99d8ca56b9d8cec78?logo=Codacy&logoColor=white "test coverage"
[shield_website]: https://img.shields.io/badge/https://-cyclonedx.org-blue.svg "homepage"
[shield_slack]: https://img.shields.io/badge/slack-join-blue?logo=Slack&logoColor=white "slack join"
[shield_groups]: https://img.shields.io/badge/discussion-groups.io-blue.svg "groups discussion"
[shield_twitter-follow]: https://img.shields.io/badge/Twitter-follow-blue?logo=Twitter&logoColor=white "twitter follow"
[link_website]: https://cyclonedx.org/
[link_gh-workflow-test]: https://github.com/CycloneDX/cyclonedx-webpack-plugin/actions/workflows/nodejs.yml?query=branch%3Amaster
[link_codacy]: https://app.codacy.com/gh/CycloneDX/cyclonedx-webpack-plugin/dashboard
[link_ossf-best-practices]: https://www.bestpractices.dev/projects/7884
[link_npm]: https://www.npmjs.com/package/@cyclonedx/webpack-plugin
[link_slack]: https://cyclonedx.org/slack/invite
[link_discussion]: https://groups.io/g/CycloneDX
[link_twitter]: https://twitter.com/CycloneDX_Spec
[docs_cdx_metadata_component_externalReferences]: https://cyclonedx.org/docs/1.7/json/#metadata_component_externalReferences