CycloneDX/cyclonedx-esbuild
GitHub: CycloneDX/cyclonedx-esbuild
为 esbuild 和 Bun 构建的项目生成符合 CycloneDX 标准的软件物料清单（SBOM），仅包含实际打包的依赖项。
Stars: 3 | Forks: 2
# 适用于 _esbuild_ 和 _Bun_ 的 CycloneDX SBOM 生成器
[![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]
从使用 _[esbuild]_ 或 _[Bun]_ 构建的项目创建 _[CycloneDX]_ 软件物料清单 (SBOM)。
此包提供：
* 一个**适用于 _esbuild_ 兼容打包工具的插件** —— 适用于 _esbuild_ 和 _Bun_
* 一个 **CLI 工具**，用于从 esbuild 兼容的构建 [元文件](https://esbuild.github.io/api/#metafile) 生成 SBOM
该工具利用打包过程中生成的依赖链接信息来创建清单 。仅列出（在 [tree-shaking](https://esbuild.github.io/api/#tree-shaking) 之后）实际包含在最终 bundle 中的依赖项。
生成的 SBOM 文档遵循[官方规范和标准](https://github.com/CycloneDX/specification)。
## 功能特性
* 🔌 **适用于 esbuild 兼容打包工具的插件** (_esbuild_, _Bun_)
* 🖥️ **CLI 工具**，用于从 esbuild 兼容的 metafile 生成 SBOM
* 🎯 支持多种 **CycloneDX 规范版本** (1.2, 1.3, 1.4, 1.5, 1.6, 1.7)
* 🔍 从打包项目中提取组件和依赖项
* 📝 **许可证证据收集**
* ✅ 根据 CycloneDX schema **验证**生成的 SBOM
* 🔄 **可复现输出**选项，用于一致的 SBOM 生成
* 📊 适用于 _TypeScript_、_Angular_ 和其他现代框架
## 环境要求
需具备以下运行时之一：
* _Node.js_ `>= 20.18`
* _Bun_ `>= 1.3.6`
某些功能需要可选（peer）依赖项 —— 有关版本约束，请参阅 `package.json`。
* _esbuild_ —— 将插件与 esbuild 配合使用时需要
* _ajv_, _ajv-formats_ & _ajv-formats-draft2019_ —— SBOM JSON 结果验证所需
## 安装
使用您首选的包管理器并将其作为 dev-dependency 安装：
```
npm install --save-dev @cyclonedx/cyclonedx-esbuild
pnpm add --save-dev @cyclonedx/cyclonedx-esbuild
yarn add --dev @cyclonedx/cyclonedx-esbuild
bun add --dev @cyclonedx/cyclonedx-esbuild
```
## 使用方法
### 插件用法 (esbuild 和 Bun)
该插件适用于 **esbuild 兼容的打包工具**。
由于 Bun 提供了与 esbuild 兼容的插件 API，因此同一插件可在两种环境中使用。
#### 插件选项与配置
| 名称 | 类型 | 默认值 | 描述 |
|:-----|:----:|:-------:|:------------|
| **`specVersion`** | `{string}`
以下之一: `"1.2"`, `"1.3"`, `"1.4"`, `"1.5"`, `"1.6"`, `"1.7"` | `"1.6"` | 要使用的 [CycloneDX-spec] 版本。
支持的值取决于已安装的依赖项 [CycloneDX-javascript-library]。 | | **outputFile** | `{string}` | `"bom.json"` | 输出文件的路径。 | | **gatherLicenseTexts** | `{boolean}` | `false` | 在组件中搜索许可证文件并将其作为许可证证据包含在内。
此功能为实验性功能。 | | **outputReproducible** | `{boolean}` | `false` | 是否进一步努力使输出可复现。
这需要更多资源，并可能导致基于时间和随机数的值丢失。 | | **mcType** | `{string}` | `"application"` | 设置 MainComponent 的类型。
请参阅[有效值列表](https://cyclonedx.org/docs/1.7/json/#metadata_component_type)。 | | **validate** | `{boolean \| undefined}` | `undefined` | 在输出之前验证生成的 BOM。
如果不满足要求，则跳过验证。 | | **logLevel** | `{string \| undefined}` | `undefined` | 控制插件的详细程度。接受 [esbuild 的 `logLevel`](https://esbuild.github.io/api/#log-level) 或 Bun 中相应设置支持的相同值。
如果未设置，插件将从构建配置继承 `logLevel`。如果该值也未定义，则回退到 `"warning"`。 | #### 插件示例：esbuild ``` // build.js const esbuild = require('esbuild'); const { cyclonedxEsbuildPlugin } = require('@cyclonedx/cyclonedx-esbuild'); /** @type {import('@cyclonedx/cyclonedx-esbuild').CycloneDxEsbuildPluginOptions} */ const cyclonedxEsbuildPluginOptions = { specVersion: '1.7', outputFile: 'bom.json' } esbuild.build({ // ... plugins: [ cyclonedxEsbuildPlugin(cyclonedxEsbuildPluginOptions), ] }); ``` 请参阅示例：[integration with esbuild][example-plugin-esbuild]。 #### 插件示例：Bun 由于 _Bun_ 的插件 API 大致基于 _esbuild_，因此该插件也可用于使用内置打包工具的 _Bun_ 项目 (Bun v1.3.6+)。 ``` // build.ts import { cyclonedxEsbuildPlugin } from "@cyclonedx/cyclonedx-esbuild" await Bun.build({ // ... metafile: true, // required for `cyclonedxEsbuildPlugin` to work with Bun plugins: [ cyclonedxEsbuildPlugin({ outputFile: "bom.json", // ... }), ], }) export {} ``` 请参阅示例：[integration with Bun][example-plugin-bun]。 ### CLI 工具 用于从 [esbuild metafiles](https://esbuild.github.io/api/#metafile) 生成 SBOM 的命令行接口。 #### CLI 调用 调用 CLI 的方式取决于所使用的安装方法。 以下是针对各种包管理器和设置的示例： ``` npm exec -- cyclonedx-esbuild --help pnpm exec cyclonedx-esbuild --help yarn exec cyclonedx-esbuild --help ``` #### CLI 帮助页面 ``` Usage: cyclonedx-esbuild [options]
Create CycloneDX Software Bill of Materials (SBOM) from esbuild-compatible metafile.
Arguments:
metafile Path to esbuild-compatible metafile
Options:
--ewd, --esbuild-working-dir Working dir used in the esbuild process.
--gather-license-texts Search for license files in components and include them as license evidence.
This feature is experimental.
(default: false)
--sv, --spec-version Which version of CycloneDX spec to use.
(choices: "1.2", "1.3", "1.4", "1.5", "1.6", "1.7", default: "1.6")
--output-reproducible Whether to go the extra mile and make the output reproducible.
This requires more resources, and might result in loss of time- and random-based-values.
(env: BOM_REPRODUCIBLE)
-o, --output-file Path to the output file.
Set to "-" to write to STDOUT.
(default: write to STDOUT)
--validate Validate resulting BOM before outputting.
Validation is skipped, if requirements not met.
--no-validate Disable validation of resulting BOM.
--mc-type Type of the main component.
(choices: "application", "firmware", "library", default: "application")
-v, --verbose Increase the verbosity of messages.
Use multiple times to increase the verbosity even more.
-V, --version output the version number
-h, --help display help for command
```
### 与 Angular 配合使用
对于使用 _esbuild_ 的 _Angular_ 项目 (Angular 17+)，您可以从构建统计信息生成 SBOM。
```
// package.json
{
"scripts": {
"build:app": "ng build --stats-json",
"build:sbom": "cyclonedx-esbuild --gather-license-texts --output-reproducible -o dist/bom.json dist/stats.json",
"build": "npm run build:app && npm run build:sbom"
}
}
```
请在此处查看示例：[integration with Angular20](https://github.com/CycloneDX/cyclonedx-esbuild/tree/main/tests/_testbeds/angular20-npm)。
## 内部机制
此工具利用 [CycloneDX library][CycloneDX-javascript-library] 生成实际的数据结构。
除了类 `CycloneDxEsbuildPlugin` 和接口 `CycloneDxEsbuildPluginOptions` 之外，
此 _esbuild_ 插件和该工具**不**暴露任何额外的公开 API 或类 —— 所有代码均为内部代码，可能会在版本升级期间随时更改，恕不另行通知。
不过，CLI 是稳定的 —— 您可以像这样通过编程方式调用它：
```
const { execFileSync } = require('child_process')
const { constants: { MAX_LENGTH: BUFFER_MAX_LENGTH } } = require('buffer')
const sbom = JSON.parse(execFileSync(process.execPath, [
'../path/to/this/package/bin/cyclonedx-esbuild-cli.js',
'--spec-version', '1.7',
'--output-file', '-'
// additional CLI args
], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'buffer', maxBuffer: BUFFER_MAX_LENGTH }))
```
## 开发与贡献
欢迎提出问题 (issues)、错误报告 或拉取请求。
详情请参阅 [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]。 | | **outputFile** | `{string}` | `"bom.json"` | 输出文件的路径。 | | **gatherLicenseTexts** | `{boolean}` | `false` | 在组件中搜索许可证文件并将其作为许可证证据包含在内。
此功能为实验性功能。 | | **outputReproducible** | `{boolean}` | `false` | 是否进一步努力使输出可复现。
这需要更多资源，并可能导致基于时间和随机数的值丢失。 | | **mcType** | `{string}` | `"application"` | 设置 MainComponent 的类型。
请参阅[有效值列表](https://cyclonedx.org/docs/1.7/json/#metadata_component_type)。 | | **validate** | `{boolean \| undefined}` | `undefined` | 在输出之前验证生成的 BOM。
如果不满足要求，则跳过验证。 | | **logLevel** | `{string \| undefined}` | `undefined` | 控制插件的详细程度。接受 [esbuild 的 `logLevel`](https://esbuild.github.io/api/#log-level) 或 Bun 中相应设置支持的相同值。
如果未设置，插件将从构建配置继承 `logLevel`。如果该值也未定义，则回退到 `"warning"`。 | #### 插件示例：esbuild ``` // build.js const esbuild = require('esbuild'); const { cyclonedxEsbuildPlugin } = require('@cyclonedx/cyclonedx-esbuild'); /** @type {import('@cyclonedx/cyclonedx-esbuild').CycloneDxEsbuildPluginOptions} */ const cyclonedxEsbuildPluginOptions = { specVersion: '1.7', outputFile: 'bom.json' } esbuild.build({ // ... plugins: [ cyclonedxEsbuildPlugin(cyclonedxEsbuildPluginOptions), ] }); ``` 请参阅示例：[integration with esbuild][example-plugin-esbuild]。 #### 插件示例：Bun 由于 _Bun_ 的插件 API 大致基于 _esbuild_，因此该插件也可用于使用内置打包工具的 _Bun_ 项目 (Bun v1.3.6+)。 ``` // build.ts import { cyclonedxEsbuildPlugin } from "@cyclonedx/cyclonedx-esbuild" await Bun.build({ // ... metafile: true, // required for `cyclonedxEsbuildPlugin` to work with Bun plugins: [ cyclonedxEsbuildPlugin({ outputFile: "bom.json", // ... }), ], }) export {} ``` 请参阅示例：[integration with Bun][example-plugin-bun]。 ### CLI 工具 用于从 [esbuild metafiles](https://esbuild.github.io/api/#metafile) 生成 SBOM 的命令行接口。 #### CLI 调用 调用 CLI 的方式取决于所使用的安装方法。 以下是针对各种包管理器和设置的示例： ``` npm exec -- cyclonedx-esbuild --help pnpm exec cyclonedx-esbuild --help yarn exec cyclonedx-esbuild --help ``` #### CLI 帮助页面 ``` Usage: cyclonedx-esbuild [options]
标签：Bun, CLI, CMS安全, CycloneDX, esbuild, GNU通用公共许可证, JavaScript, MITM代理, Node.js, SBOM, TypeScript, Webpack替代, WiFi技术, 人工智能安全, 依赖管理, 前端安全, 合规性, 安全插件, 插件, 文档安全, 文档结构分析, 树摇优化, 硬件无关, 自动化攻击, 许可证管理, 跌倒检测, 软件开发工具包, 软件物料清单