CycloneDX/cyclonedx-javascript-library
GitHub: CycloneDX/cyclonedx-javascript-library
面向 JavaScript/TypeScript 的 CycloneDX SBOM 核心开发库，提供完整的 BOM 数据模型、JSON/XML 序列化与规范校验能力。
Stars: 22 | Forks: 15
# CycloneDX JavaScript 库
[![shield_npm-version]][link_npm]
[![shield_rtfd]][link_rtfd]
[![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]
[_CycloneDX_][link_website] 面向 _JavaScript_ (_Node.js_ 或 _WebBrowsers_) 的核心功能，
使用 _TypeScript_ 编写并针对目标环境进行编译。
## 职责
* 为 _Node.js_ 和 _WebBrowsers_ 提供 [_CycloneDX_][link_website] 的通用 _JavaScript_ 实现。
* 为上述实现提供类型定义，以便开发者和开发工具可以依赖它。
* 提供用于处理 _CycloneDX_ 的数据模型。
* 提供 JSON 和 XML 规范化器（Normalizers），这些工具...
* 支持所有内置的数据模型。
* 遵循注入的任何 [_CycloneDX_ 规范][CycloneDX-spec] 并生成符合该规范的有效输出。
* 可配置为生成可复现/确定性（deterministic）的输出。
* 能够准备用于 JSON 和 XML 序列化的数据结构。
* 序列化：
* 为所有目标环境提供通用的 JSON 序列化器。
* 为所有目标环境提供 XML 序列化器。
* 支持针对特定环境定制的自定义 XML 序列化器的下游实现
通过提供一个抽象基类来处理规范化和 BomRef 区分。
这样做是因为 _JavaScript_ 中没有通用的 XML 支持。
* 根据 [_CycloneDX_ 规范][CycloneDX-spec] 提供正式的 JSON 和 XML 验证器。（目前仅支持 _Node.js_）
## 功能特性
* 用于以下用例的枚举：
* `AttachmentEncoding`
* `ComponentScope`
* `ComponentType`
* `ExternalReferenceType`
* `HashAlgorithm`
* `Vulnerability` 相关：
* `AffectStatus`
* `AnalysisJustification`
* `AnalysisResponse`
* `AnalysisState`
* `RatingMethod`
* `Severity`
* 用于以下用例的数据模型：
* `Attachment`
* `Bom`
* `BomLink`, `BomLinkDocument`, `BomLinkElement`
* `BomRef`, `BomRefRepository`
* `Component`, `ComponentRepository`, `ComponentEvidence`
* `ExternalReference`, `ExternalReferenceRepository`
* `Hash`, `HashContent`, `HashDictionary`
* `LicenseExpression`, `NamedLicense`, `SpdxLicense`, `LicenseRepository`
* `Metadata`
* `OrganizationalContact`, `OrganizationalContactRepository`
* `OrganizationalEntity`, `OrganizationalEntityRepository`
* `Property`, `PropertyRepository`
* `SWID`
* `Tool`, `ToolRepository`, `Tools`
* `Vulnerability` 相关：
* `Advisory`, `AdvisoryRepository`
* `Affect`, `AffectRepository`, `AffectedSingleVersion`, `AffectedVersionRange`, `AffectedVersionRepository`
* `Analysis`
* `Credits`
* `Rating`, `RatingRepository`
* `Reference`, `ReferenceRepository`
* `Source`
* `Vulnerability`, `VulnerabilityRepository`
* 用于以下用例的工具：
* 为 `Bom.serialNumber` 生成有效的随机 SerialNumber
* 从文件收集许可证证据（仅限 _Node.js_）
* 用于以下用例的工厂：
* 从任何许可证描述符字符串创建数据模型
* 特定于 _Node.js_：从 PackageJson 类数据结构及派生数据创建数据模型
* 用于以下用例的构建器：
* 特定于 _Node.js_：从 PackageJson 类数据结构创建深层 `Tool` 或 `Component` 数据模型
* 以下版本 [_CycloneDX_ 规范][CycloneDX-spec] 的实现：
* `1.7`
* `1.6`
* `1.5`
* `1.4`
* `1.3`
* `1.2`
* 将数据模型转换为 JSON 结构的规范化器
* 将数据模型转换为 XML 结构的规范化器
* 将 `Bom` 数据模型转换为 JSON 字符串的通用序列化器
* 将 `Bom` 数据模型转换为 XML 字符串的特定序列化器：
* 特定于 _WebBrowsers_：实现利用特定于浏览器的文档生成器和打印机。
* 特定于 _Node.js_：实现利用如下所述的[可选依赖](#optional-dependencies)
* 针对 JSON 字符串和 XML 字符串的正式验证器（目前仅限 _Node.js_）
需要如下所述的[可选依赖](#optional-dependencies)
## 安装
此包和构建结果可通过 _npm_, _pnpm_ 和 _yarn_ 获取：
```
npm i -S @cyclonedx/cyclonedx-library
pnpm add @cyclonedx/cyclonedx-library
yarn add @cyclonedx/cyclonedx-library
```
您可以从源码安装该包，
它将在安装时自动构建：
```
npm i -S github:CycloneDX/cyclonedx-javascript-library
pnpm add github:CycloneDX/cyclonedx-javascript-library
yarn add @cyclonedx/cyclonedx-library@github:CycloneDX/cyclonedx-javascript-library # only with yarn-2
```
## 可选 Peer Dependencies
某些功能需要可选的 peer dependencies —— 有关版本详情，请参阅 `package.json`。
* 在 _Node.js_ 上序列化为 XML 需要以下任一项：
* [`xmlbuilder2`](https://www.npmjs.com/package/xmlbuilder2)
* 在 _Node.js_ 上验证 JSON 需要以下所有项：
* [`ajv`](https://www.npmjs.com/package/ajv)
* [`ajv-formats`](https://www.npmjs.com/package/ajv-formats)
* [`ajv-formats-draft2019`](https://www.npmjs.com/package/ajv-formats-draft2019)
* 在 _Node.js_ 上验证 XML 需要以下任一项：
* [`libxmljs2`](https://www.npmjs.com/package/libxmljs2)
* 在某些情况下，系统可能需要满足 [`node-gyp`](https://github.com/TooTallNate/node-gyp#installation) 的要求。
此外，针对相关的第三方标准，我们有一些建议：
* [`packageurl-js`](https://www.npmjs.com/package/packageurl-js)
用于构建和解析 PackageURL。
* [`spdx-expression-parse`](https://www.npmjs.com/package/spdx-expression-parse)
用于验证 SPDX 许可证表达式。
## 用法
请参阅扩展的 [示例][examples]。
### 作为 _Node.js_ 包
```
const CDX = require('@cyclonedx/cyclonedx-library')
const bom = new CDX.Models.Bom()
bom.metadata.component = new CDX.Models.Component(
CDX.Enums.ComponentType.Application,
'MyProject'
)
const componentA = new CDX.Models.Component(
CDX.Enums.ComponentType.Library,
'myComponentA',
)
bom.components.add(componentA)
bom.metadata.component.dependencies.add(componentA.bomRef)
```
为了确保在 **打包（bundling）** 时实现最佳的 **tree-shaking**，请仅从库发布的 [入口点](https://nodejs.org/api/packages.html#package-entry-points) 导入您实际需要的符号。您可以在包的 `package.json` 的 `exports` 字段中找到所有可用的入口点。
```
const { Bom, Component } = require('@cyclonedx/cyclonedx-library/Models')
const { ComponentType } = require('@cyclonedx/cyclonedx-library/Enums')
const bom = new Bom()
bom.metadata.component = new Component(
ComponentType.Application,
'MyProject'
)
const componentA = new Component(
ComponentType.Library,
'myComponentA',
)
bom.components.add(componentA)
bom.metadata.component.dependencies.add(componentA.bomRef)
```
### 在 _WebBrowsers_ 中
```
```
## API 文档
我们提供了带有注释的类型定义，以便您的 IDE 和工具在您下游使用此库时能够获取文档。
此外，还有托管在 [readthedocs][link_rtfd] 上的预渲染文档。
## 开发与贡献
欢迎提交 issue、bug 报告或 pull request。
详情请参阅 [CONTRIBUTING][contributing_file] 文件。
## 许可证
在 Apache 2.0 许可证的条款下，允许修改和重新分发。
完整许可证请参阅 [LICENSE][license_file] 文件。
标签：BOM, CMS安全, CycloneDX, GNU通用公共许可证, GPT, JavaScript, JSON, MITM代理, Node.js, SBOM, TypeScript, WebSocket, Web浏览器, XML, 代码安全, 依赖分析, 安全合规, 安全插件, 序列化, 数据可视化, 数据模型, 暗色界面, 漏洞枚举, 漏洞管理, 硬件无关, 组件分析, 网络代理, 自动化攻击, 自动化攻击, 自动化攻击, 跌倒检测, 软件物料清单