CycloneDX/cyclonedx-webpack-plugin
GitHub: CycloneDX/cyclonedx-webpack-plugin
在 webpack 编译时自动生成 CycloneDX 标准的软件物料清单，精准记录实际打包使用的依赖项。
Stars: 30 | Forks: 11
# CycloneDX _webpack_ 插件
[![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]
此 _[webpack]_ 插件用于创建 _[CycloneDX]_ 软件物料清单 (SBoM)，其中包含所有捆绑依赖项的聚合。
这可能是基于 webpack 构建的最准确、最完整的 SBOM 生成器。
此插件利用 _webpack_ 生成的链接关系来创建依赖图，其中仅包含（在 [tree-shaking](https://webpack.js.org/guides/tree-shaking/) 之后）实际使用的依赖项。
生成的 SBOM 文档遵循[官方规范和标准](https://github.com/CycloneDX/specification)。
## 要求
* _Node.js_ `>= 20.18`
* _webpack_ `^5`
不过，此插件有旧版本支持：
* _Node.js_ v8.0.0 或更高版本
* _webpack_ v4.0.0 或更高版本
## 安装
```
npm i -D @cyclonedx/webpack-plugin
yarn add -D @cyclonedx/webpack-plugin
```
## 用法
```
new CycloneDxWebpackPlugin(options?: object)
```
### 选项与配置
| 名称 | 类型 | 默认值 | 描述 |
|:-----|:----:|:-------:|:------------|
| **`specVersion`** | `{string}`
取值: `"1.2"`, `"1.3"`, `"1.4"`, `"1.5"`, `"1.6"`, `"1.7"` | `"1.6"` | 使用哪个版本的 [CycloneDX-spec]。
支持的值取决于已安装的依赖项 [CycloneDX-javascript-library]。 | | **`reproducibleResults`** | `{boolean}` | `false` | 是否更进一步使输出可重现。
可重现性可能会导致丢失基于时间和随机性的值。 | | **`validateResults`** | `{boolean}` | `true` | 是否验证 BOM 结果。
如果未满足要求，则跳过验证。需要 [transitive optional dependencies](https://github.com/CycloneDX/cyclonedx-javascript-library#optional-dependencies)。 | | **`outputLocation`** | `{string}` | `"./cyclonedx"` | 输出写入路径。该路径相对于 _webpack_ 的总体输出路径。 | | **`includeWellknown`** | `{boolean}` | `true` | 是否写入 Wellknowns。 | | **`wellknownLocation`** | `{string}` | `"./.well-known"` | 写入 Wellknowns 的路径。该路径相对于 _webpack_ 的总体输出路径。 | | **`rootComponentAutodetect`** | `{boolean}` | `true` | 是否尝试自动检测 RootComponent。
尝试找到最近的 `package.json` 并从中构建 CycloneDX 组件，以便将其分配给 `bom.metadata.component`。 | | **`rootComponentType`** | `{string}` | `"application"` | 设置 RootComponent 的类型。
参阅[有效值列表](https://cyclonedx.org/docs/1.7/json/#metadata_component_type)。支持的值取决于 [CycloneDX-javascript-library] 的枚举 `ComponentType`。 | | **`rootComponentName`** | 可选 `{string}` | `undefined` | 如果 `rootComponentAutodetect` 被禁用，则此值将被视为 `package.json` 的 "name"。 | | **`rootComponentVersion`** | 可选 `{string}` | `undefined` | 如果 `rootComponentAutodetect` 被禁用，则此值将被视为 `package.json` 的 "version"。 | | **`rootComponentVCS`** | 可选 `{string}` | `undefined` | 如果 `rootComponentAutodetect` 被禁用或在 `package.json` 中未声明版本控制系统，则此值将用作 [RootComponent 的 External References][docs_cdx_metadata_component_externalReferences] 类型为 "vcs" 的 URL。 | | **`rootComponentBuildSystem`** | 可选 `{string}` | `undefined` | 设置 [RootComponent 的 External References][docs_cdx_metadata_component_externalReferences] 类型为 "build-system" 的 URL。
无论 `rootComponentAutodetect` 的状态如何，此行为均适用。 | | **`collectEvidence`** | `{boolean}` | `false` | 是否收集（许可证）证据并将其附加到生成的 SBOM 中。 | ### 示例 在您的 [webpack config] 中添加 CycloneDX 插件： ``` 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) ] } ``` 查看更多[示例][examples]。 ### 支持 IETF /.well-known/sbom CycloneDX _webpack_ 插件支持将 CycloneDX SBOM 放置在预定义位置，具体为 `/.well-known/sbom`。此选项默认启用。可以通过覆盖 `includeWellknown` 和 `wellknownLocation` 的值来更改此行为。 有关规范的更多信息，请参阅 [draft-ietf-opsawg-sbom-access]，目前为 IETF 草案。 在您的 [webpack config] 中添加 CycloneDX 插件： ``` 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 使用 _Angular_ 在底层使用 _webpack_。因此，可以通过使用 [@angular-builders/custom-webpack](https://www.npmjs.com/package/@angular-builders/custom-webpack) 来集成此插件。 请参阅此处的示例：[integration with Angular17/webpack5](https://github.com/CycloneDX/cyclonedx-webpack-plugin/tree/master/tests/_testbeds/webpack5-angular17)。 ### 配合 React 使用 _React_ 在底层使用 _webpack_。因此，可以集成此插件。 请参阅此处的示例：[integration with React18/webpack5](https://github.com/CycloneDX/cyclonedx-webpack-plugin/tree/master/tests/_testbeds/webpack5-react18)。 ## 内部机制 此 _webpack_ 插件利用 [CycloneDX library][CycloneDX-javascript-library] 来生成实际的数据结构。 除了类 `CycloneDxWebpackPlugin` 和接口 `CycloneDxWebpackPluginOptions` 之外， 此 _webpack_ 插件**不**暴露任何额外的公共 API 或类 —— 所有代码均为内部代码，可能会在版本升级期间随时更改，恕不另行通知。 ## 开发与贡献 欢迎提交 issue、错误报告或 pull request。 详情请参阅 [CONTRIBUTING][contributing_file] 文件。 ## 许可证 在 Apache 2.0 许可证条款下，授予修改和重新分发的权限。 有关完整许可证，请参阅 [LICENSE][license_file] 文件。
取值: `"1.2"`, `"1.3"`, `"1.4"`, `"1.5"`, `"1.6"`, `"1.7"` | `"1.6"` | 使用哪个版本的 [CycloneDX-spec]。
支持的值取决于已安装的依赖项 [CycloneDX-javascript-library]。 | | **`reproducibleResults`** | `{boolean}` | `false` | 是否更进一步使输出可重现。
可重现性可能会导致丢失基于时间和随机性的值。 | | **`validateResults`** | `{boolean}` | `true` | 是否验证 BOM 结果。
如果未满足要求，则跳过验证。需要 [transitive optional dependencies](https://github.com/CycloneDX/cyclonedx-javascript-library#optional-dependencies)。 | | **`outputLocation`** | `{string}` | `"./cyclonedx"` | 输出写入路径。该路径相对于 _webpack_ 的总体输出路径。 | | **`includeWellknown`** | `{boolean}` | `true` | 是否写入 Wellknowns。 | | **`wellknownLocation`** | `{string}` | `"./.well-known"` | 写入 Wellknowns 的路径。该路径相对于 _webpack_ 的总体输出路径。 | | **`rootComponentAutodetect`** | `{boolean}` | `true` | 是否尝试自动检测 RootComponent。
尝试找到最近的 `package.json` 并从中构建 CycloneDX 组件，以便将其分配给 `bom.metadata.component`。 | | **`rootComponentType`** | `{string}` | `"application"` | 设置 RootComponent 的类型。
参阅[有效值列表](https://cyclonedx.org/docs/1.7/json/#metadata_component_type)。支持的值取决于 [CycloneDX-javascript-library] 的枚举 `ComponentType`。 | | **`rootComponentName`** | 可选 `{string}` | `undefined` | 如果 `rootComponentAutodetect` 被禁用，则此值将被视为 `package.json` 的 "name"。 | | **`rootComponentVersion`** | 可选 `{string}` | `undefined` | 如果 `rootComponentAutodetect` 被禁用，则此值将被视为 `package.json` 的 "version"。 | | **`rootComponentVCS`** | 可选 `{string}` | `undefined` | 如果 `rootComponentAutodetect` 被禁用或在 `package.json` 中未声明版本控制系统，则此值将用作 [RootComponent 的 External References][docs_cdx_metadata_component_externalReferences] 类型为 "vcs" 的 URL。 | | **`rootComponentBuildSystem`** | 可选 `{string}` | `undefined` | 设置 [RootComponent 的 External References][docs_cdx_metadata_component_externalReferences] 类型为 "build-system" 的 URL。
无论 `rootComponentAutodetect` 的状态如何，此行为均适用。 | | **`collectEvidence`** | `{boolean}` | `false` | 是否收集（许可证）证据并将其附加到生成的 SBOM 中。 | ### 示例 在您的 [webpack config] 中添加 CycloneDX 插件： ``` 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) ] } ``` 查看更多[示例][examples]。 ### 支持 IETF /.well-known/sbom CycloneDX _webpack_ 插件支持将 CycloneDX SBOM 放置在预定义位置，具体为 `/.well-known/sbom`。此选项默认启用。可以通过覆盖 `includeWellknown` 和 `wellknownLocation` 的值来更改此行为。 有关规范的更多信息，请参阅 [draft-ietf-opsawg-sbom-access]，目前为 IETF 草案。 在您的 [webpack config] 中添加 CycloneDX 插件： ``` 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 使用 _Angular_ 在底层使用 _webpack_。因此，可以通过使用 [@angular-builders/custom-webpack](https://www.npmjs.com/package/@angular-builders/custom-webpack) 来集成此插件。 请参阅此处的示例：[integration with Angular17/webpack5](https://github.com/CycloneDX/cyclonedx-webpack-plugin/tree/master/tests/_testbeds/webpack5-angular17)。 ### 配合 React 使用 _React_ 在底层使用 _webpack_。因此，可以集成此插件。 请参阅此处的示例：[integration with React18/webpack5](https://github.com/CycloneDX/cyclonedx-webpack-plugin/tree/master/tests/_testbeds/webpack5-react18)。 ## 内部机制 此 _webpack_ 插件利用 [CycloneDX library][CycloneDX-javascript-library] 来生成实际的数据结构。 除了类 `CycloneDxWebpackPlugin` 和接口 `CycloneDxWebpackPluginOptions` 之外， 此 _webpack_ 插件**不**暴露任何额外的公共 API 或类 —— 所有代码均为内部代码，可能会在版本升级期间随时更改，恕不另行通知。 ## 开发与贡献 欢迎提交 issue、错误报告或 pull request。 详情请参阅 [CONTRIBUTING][contributing_file] 文件。 ## 许可证 在 Apache 2.0 许可证条款下，授予修改和重新分发的权限。 有关完整许可证，请参阅 [LICENSE][license_file] 文件。
标签：CMS安全, CycloneDX, DevSecOps, GNU通用公共许可证, JavaScript, MITM代理, Node.js, NPM包, OSV-Scalibr, SBOM, Tree Shaking, Webpack 5, Webpack插件, 上游代理, 依赖管理, 前端安全, 动态调试, 数据可视化, 文档安全, 硬件无关, 组件分析, 自定义脚本, 自定义脚本, 跌倒检测, 软件开发工具包, 软件物料清单, 透明度日志