cdx- proto (英语)

以协议缓冲器来串行化/去串行化 CyproneDX BOM 的运行时库. 该项目是利用 原生基因( 原生基因) 从官方 原型 规格.

2.0.0 要点

• 版本特定子路径导出 : @cdxgen/cdx-proto/v1.5, (中文(简体) ), v1.6,以及 v1.7
• 用于计划选择和BOM编码/解码工作流程的助手 API
• 已生成的更精简 npm 包内容 docs/

样本使用情况

import {
  createBom,
  decodeBomBinary,
  encodeBomBinary,
  encodeBomJson,
  getBomSchema,
  parseBomJson,
} from "@cdxgen/cdx-proto";
import { BomSchema as BomSchema16 } from "@cdxgen/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) 返回匹配 BomSchema 用于气旋DX 1.5, (中文(简体) ), 1.6,或 1.7。 。 。 .
• createBom(specVersion, init) 创建 BOM 信件并自动设定 specVersion。 。 。 .
• parseBomJson(json) 财务报告和审定财务报表 parseBomJsonString(json) 自动从 specVersion 编号 : spec_version。 。 。 .
• decodeBomBinary(specVersion, bytes) 当已知 schema 版本时解码出一个 protobuf BOM.
• encodeBomBinary(bom), (中文(简体) ), encodeBomJson(bom),以及 encodeBomJsonString(bom) 从BOM中选择正确的方案.
• toBomMessage(value, specVersion?, options?) 是“将我拥有的都转换成 BOM 消息”的单个切入点: 解码消息通过(参见 isBomMessage),JSON字符串被解析出,Canonical JSON对象被嵌入式版本(或默认为最新支持的倒置版本)所发送出,而缺置输入输出出一空BOM. 这取代了消费者先前携带的输入-发送再执行.
• isBomMessage(value) 是一个类型守护符,用于解码BOM 消息中任何支持的 spec 版本,按键于 $typeName 而不是鸭子型的形状.
• convertBom(bom, targetSpecVersion) 光谱版本之间的交叉转换。 回返 { bom, warnings } 地点 warnings 列出在失落下级时掉入的字段路径。 更改不同版本之间主要关系的字段(metadata.licenses 财务报告和审定财务报表 components[].evidence.identity,1.5分单数,1.6分后的一个阵列被自动重塑——包裹在升级后倒塌为首次降级,其中报告的被丢弃的兄弟姐妹在降级时倒下 warnings ——所以跨越1.5/1.6分界线的转换不再抛出. 升级通常不会产生警告.
• bomStats(bom) 返回组件/依赖性计数和带有压缩比的 JSON/二进制字节大小.
• detectBomSpecVersion(value) 从 BOM 对象或信件读取 spec 版本.
• normalizeSpecVersion(specVersion) 规范化 "v1.6", (中文(简体) ), 1.6,以及 "1.6.0" 将拼写成一个被支持的版本,以其他任何方式进行; isSupportedSpecVersion(value) 是它的非抛出探测器.
• encodeBomBase64(bom) 为无法携带生字节的上下文(OCI标签,内到上游,环境变量)生产出原生取出二进制的基质64字符串. decodeBomBase64(specVersion, string) 带有已知版本的解码器 parseBomBase64(string) 自动检测,镜像二进制帮助器.

JSON担保

助推层被设计为与犬科气旋DX JSON相配合,而不是与原生出活泼的JSON相配合.

• parseBomJson() 财务报告和审定财务报表 decodeBomJson() 接受冠状气旋DX输入,例如:
  • 根字段类 bomFormat 财务报告和审定财务报表 specVersion
  • 破碎的别名, 如 bom-ref, (中文(简体) ), mime-type,以及 x-trust-boundary
  • 犬科散列内容字段 hashes[].content
  • 犬类标准/声明对象,而不是原生取材清单包装
• 未定义的对象属性和未定义的数组条目在原地取出解析之前进行静态化,这样调用者就可以通过普通的JavaScript对象而无需手动取出 undefined 数值第一.
• encodeBomJson() 财务报告和审定财务报表 encodeBomJsonString() 在输出时恢复犬形气旋DX JSON,包括:
  • bomFormat: "CycloneDX"
  • 管理局 specVersion
  • 粗体铝值而不是原生的铝名称,例如 CLASSIFICATION_*, (中文(简体) ), HASH_ALG_*,或 EXTERNAL_REFERENCE_TYPE_*
  • 犬形对象形状 definitions 财务报告和审定财务报表 declarations
  • 平顶 dependencies[].dependsOn: string[] 而不是原生的窝 dependencies 树 (见下文)
• parseBomBinary() 自动检测嵌入式支持的计划版本(1.5, (中文(简体) ), 1.6,或 1.7)和可以配对 encodeBomJson() 读取原生的 BOMs 回作为犬科气旋DX JSON.

校正原生字段名称, 并与使用已发布的工具交互

释放出气旋DX protobuf schemas中,三个字段命名不同 而不是在气旋DX JSON 计划 他们应该镜像。 计划 这里的销售商都纠正了所有三个, 所以一个原生的 BOM 由这个图书馆使用 与JSON对应的同名:

互通性在两个方面都得到保留:

• 二进制不需要特殊处理. 每个字段号码都不变 所以 线条格式是字节-同义的,无论产生何种方案.
• 输入时接受JSON两种拼音. 工具发射的Protobuf-JSON 从一个释放的图案中生成的 仍然使用旧名, 所以这些解码也. 输出总是使用 Canonic JSON 名称.

如果您直接从打出的消息读取这些字段(cdx_16.*, (中文(简体) ), cdx_17.*(中文(简体) ) 而不是通过犬科JSON帮助者,使用修正后的名字.

依赖性图连接

Canonical CircleDX JSON 表示依赖图为平整数组 { ref, dependsOn: [ref, ...], provides: [ref, ...] } 条目。 原生植物 镜像 XML 模型,并将孩子嵌入为 repeated Dependency dependencies, (中文(简体) ), 所以没有图书馆的桥梁 dependsOn 密钥未知为原生出自 被拒绝(默认选项)或默不作声地放弃 (单位:千美元)ignoreUnknownFields: true),从而空出依赖图.

帮助层在两种形式之间自动转换:

• JSON - > protobuf: 每个 dependsOn 字符串变成嵌入 { ref } 儿童 dependencies。已经原型 dependencies 数组和字符串/对象的混合数组也被接受.
• protobuf - > 贾森: 有窝 dependencies 被平整回来 dependsOn。如果一个嵌入式入口带有自己的边缘(它本身的边缘) dependencies 或者说 provides),它被竖起到一个兄弟的上层入口,如此过渡 边缘永远不会消失。 条目由 ref。 。 。 .

简言之:如果向帮助者API提供犬形气旋DX JSON,在二进制后或消息回转后,应当得到犬形气旋DX JSON.

特定版本进口

使用子路径导出来避免装入您不需要的计划版本 :

import { BomSchema as BomSchema15 } from "@cdxgen/cdx-proto/v1.5";
import { BomSchema as BomSchema16 } from "@cdxgen/cdx-proto/v1.6";
import { BomSchema as BomSchema17 } from "@cdxgen/cdx-proto/v1.7";

仅节点文件帮助器

@cdxgen/cdx-proto/node 添加文件系统方便包 污染主(浏览器安全)入口 node: 进口:

import {
  isProtoBomFile,
  readBomFile,
  writeBomFile,
} from "@cdxgen/cdx-proto/node";

// Format is auto-detected from the extension: `.json` for canonical JSON,
// `.b64`/`.base64` for base64 protobuf payloads, and anything else
// (`.cdx`, `.cdx.bin`, `.proto`, `.bin`, ...) as raw protobuf binary.
const bom = readBomFile("bom.cdx");
const bomJson = readBomFile("bom.cdx", { asJson: true });

writeBomFile("bom.json", bom); // pretty canonical JSON
writeBomFile("bom.cdx", bomJson); // coerced back to a message, then binary
writeBomFile("bom.b64", bom); // base64 protobuf payload

isProtoBomFile("bom.CDX.BIN"); // true — the extension list lives here once

国 际

货包是零依赖的 cdx-proto 转换、检查、, 并验证贝壳中的BOM。 格式由文件自动检测 扩展.json 为犬JSON, .b64编号 :.base64 用于基础64原生出, 任何其它的原生的二进制.

# Convert JSON to protobuf binary (~2x smaller for typical BOMs)
npx cdx-proto convert bom.json bom.bin

# Downgrade a 1.7 BOM to 1.5, warning about dropped fields
npx cdx-proto convert bom.json bom-1.5.json --to 1.5

# Convert to a base64 payload for embedding in labels or predicates
npx cdx-proto convert bom.json bom.b64

# Inspect component/dependency counts and byte sizes
npx cdx-proto inspect bom.bin

# Validate that a file parses cleanly
npx cdx-proto validate bom.json

许可证

麻省理工学院