AppThreat/cdx-proto
GitHub: AppThreat/cdx-proto
基于 Protocol Buffers 实现 CycloneDX SBOM 序列化与反序列化的运行时库，解决多版本 JSON 与二进制格式间的高效转换问题。
Stars: 0 | Forks: 0
# cdx-proto
使用 protocol buffers 序列化/反序列化 CycloneDX BOM 的运行时库。该项目是使用 [protoc-gen-es](https://github.com/bufbuild/protobuf-es) 从官方 [proto](https://github.com/CycloneDX/specification/blob/master/schema/bom-1.5.proto) 规范生成的。
## 2.0.0 版本亮点
- 特定版本的子路径导出：`@appthreat/cdx-proto/v1.5`、`v1.6` 和 `v1.7`
- 用于 schema 选择和 BOM 编码/解码工作流的辅助 API
- 更精简的 npm 包内容，不再发布生成的 `docs/`
## 示例用法
```
import {
createBom,
decodeBomBinary,
encodeBomBinary,
encodeBomJson,
getBomSchema,
parseBomJson,
} from "@appthreat/cdx-proto";
import { BomSchema as BomSchema16 } from "@appthreat/cdx-proto/v1.6";
import { fromJson } from "@bufbuild/protobuf";
// Use version-specific entrypoints when you only need one schema version.
const bom16 = fromJson(BomSchema16, {
specVersion: "1.6",
version: 1,
});
// Or use the helper API to auto-select schemas and encode/decode BOMs.
const bom = createBom("1.7", {
version: 1,
serialNumber: "urn:uuid:11111111-1111-1111-1111-111111111111",
});
const binary = encodeBomBinary(bom, {
writeUnknownFields: true,
});
const decoded = decodeBomBinary("1.7", binary, {
readUnknownFields: true,
});
const json = encodeBomJson(decoded, {
alwaysEmitImplicit: true,
});
const parsed = parseBomJson({
specVersion: "1.6",
version: 1,
});
const schema = getBomSchema(parsed.specVersion);
```
### 辅助 API
- `getBomSchema(specVersion)` 返回 CycloneDX `1.5`、`1.6` 或 `1.7` 对应的 `BomSchema`。
- `createBom(specVersion, init)` 创建一个 BOM 消息并自动设置 `specVersion`。
- `parseBomJson(json)` 和 `parseBomJsonString(json)` 从 `specVersion` / `spec_version` 自动检测 schema。
- `decodeBomBinary(specVersion, bytes)` 在已知 schema 版本时解码 protobuf BOM。
- `encodeBomBinary(bom)`、`encodeBomJson(bom)` 和 `encodeBomJsonString(bom)` 从 BOM 本身选择正确的 schema。
### 规范化 JSON 保证
辅助层旨在与规范化 CycloneDX JSON 而非 protobuf 风格的 JSON 配合使用。
- `parseBomJson()` 和 `decodeBomJson()` 接受规范的 CycloneDX 输入，例如：
- 根字段，如 `bomFormat` 和 `specVersion`
- 带连字符的别名，如 `bom-ref`、`mime-type` 和 `x-trust-boundary`
- 规范的哈希内容字段，如 `hashes[].content`
- 规范的 standards/declarations 对象，而不是 protobuf 列表包装器
- 未定义的对象属性和未定义的数组条目在 protobuf 解析之前会被清除，因此调用者可以直接传递普通的 JavaScript 对象，而无需先手动剥离 `undefined` 值。
- `encodeBomJson()` 和 `encodeBomJsonString()` 在输出时恢复规范的 CycloneDX JSON，包括：
- `bomFormat: "CycloneDX"`
- BOM 的 `specVersion`
- 规范的枚举值，而不是 protobuf 枚举名称，例如 `CLASSIFICATION_*`、`HASH_ALG_*` 或 `EXTERNAL_REFERENCE_TYPE_*`
- `definitions` 和 `declarations` 的规范对象结构
- `parseBomBinary()` 会自动检测嵌入的支持的 schema 版本（`1.5`、`1.6` 或 `1.7`），并且可以与 `encodeBomJson()` 配合使用，将 protobuf BOM 重新读取为规范的 CycloneDX JSON。
简而言之：如果你向辅助 API 提供规范的 CycloneDX JSON，在经过二进制或消息的往返处理后，你应该能返回规范的 CycloneDX JSON。
### 特定版本的导入
使用子路径导出来避免加载你不需要的 schema 版本：
```
import { BomSchema as BomSchema15 } from "@appthreat/cdx-proto/v1.5";
import { BomSchema as BomSchema16 } from "@appthreat/cdx-proto/v1.6";
import { BomSchema as BomSchema17 } from "@appthreat/cdx-proto/v1.7";
```
## 许可证
Apache-2.0
标签：bufbuild, CMS安全, CycloneDX, GPT, JavaScript, MITM代理, npm包, Protobuf, Protocol Buffers, SBOM, TypeScript, 反序列化, 安全合规, 安全插件, 序列化, 数据可视化, 数据序列化, 数据转换, 漏洞管理, 硬件无关, 编码, 网络代理, 自动化攻击, 解码, 跌倒检测, 软件物料清单, 运行时库