cdxgen/cdxgen

[][jsr-cdxgen] [][npmjs-cdxgen] [][github-releases] [][npmjs-cdxgen] [][github-license] [][github-contributors] [][swh-cdxgen] # CycloneDX Generator (cdxgen) cdxgen 是一个 CLI 工具、库、[REPL](./ADVANCED.md) 和服务器，用于创建有效且合规的 [CycloneDX][cyclonedx-homepage] Bill of Materials (BOM)，其中包含 JSON 格式的所有项目依赖项的聚合。CycloneDX 是一种全栈 BOM 规范，易于创建，人类和机器可读，且易于解析。该工具支持 1.4 到 1.7 版本的 CycloneDX 规范。 支持的 BOM 格式： - 软件 (SBOM) - 适用于多种语言和容器镜像。 - 加密 (CBOM) - 适用于 Java 和 Python 项目。 - 运维 (OBOM) - 适用于 Linux 容器镜像以及运行 Linux 或 Windows 操作系统的虚拟机。 - 软件即服务 - 适用于 Java、Python、JavaScript、TypeScript 和 PHP 项目。 - 证明 (CDXA) - 使用多种标准的模板生成 SBOM。在细粒度级别对 BOM 文档进行签名，以提高真实性。 - 漏洞披露报告 (VDR) - 将 cdxgen 与 [OWASP depscan](https://github.com/owasp-dep-scan/dep-scan) 结合使用，以大规模自动化生成 VDR。 ## 为什么选择 cdxgen？ 大多数 SBOM 工具就像简单的条形码扫描仪。对于简单的应用程序，它们可以解析一些包清单，并仅基于这些文件创建组件列表，而无需任何深度检查。此外，一个典型的应用程序可能有多个存储库、组件和库，且具有复杂的构建要求。按语言或包清单生成 SBOM 的传统技术要么在企业环境中不起作用，要么无法提供合规性和自动化分析所需的置信度。所以我们构建了 cdxgen —— 一个通用、多语言、用户友好、精确且全面的 SBOM 生成器！ **我们的理念：** - _可解释性：_ 不要只是列出，要用证据解释。 - _精确性：_ 尝试使用多种技术来提高精确度，即使这需要额外的时间。 - _角色：_ 满足各类角色的需求，例如安全研究人员、合规审计师、开发人员和 SOC。 - _生命周期：_ 支持各种产品生命周期的 BOM 生成。 - _机器学习：_ 通过考虑各种模型属性，针对机器学习 (ML) 目的优化生成的数据。 ## 文档 请访问我们的 [GPT 应用][cdxgen-gpt] 或 [文档站点][docs-homepage] 以获取详细的使用方法、教程和支持文档。 章节包括： - [入门指南][docs-homepage] - [CLI 用法][docs-cli] - [服务器用法][docs-server] - [支持的项目类型][docs-project-types] - [环境变量][docs-env-vars] - [高级用法][docs-advanced-usage] - [权限][docs-permissions] - [支持（企业版与社区版）][docs-support] ## 用法 ## 对于贡献者 / 开发者 ``` pnpm install pnpm dlx cdxgen ``` ## 安装 ``` npm install -g @cyclonedx/cdxgen ``` 要在不安装的情况下运行 cdxgen（热加载），请使用 [pnpm dlx](https://pnpm.io/cli/dlx) 命令。 ``` corepack pnpm dlx @cyclonedx/cdxgen --help ``` 如果您是 [Homebrew][homebrew-homepage] 用户，也可以通过以下方式安装 [cdxgen][homebrew-cdxgen]： ``` $ brew install cdxgen ``` 如果您是 Windows 上的 [Winget][winget-homepage] 用户，也可以通过以下方式安装 cdxgen： ``` $ winget install cdxgen ``` Deno 和 bun 运行时可以在有限的支持下使用。 ``` deno install --allow-read --allow-env --allow-run --allow-sys=uid,systemMemoryInfo,gid,homedir --allow-write --allow-net -n cdxgen "npm:@cyclonedx/cdxgen/cdxgen" ``` 您也可以使用带有 node、deno 或 bun 运行时版本的 cdxgen 容器镜像。 默认版本使用 Node.js 23 ``` docker run --rm -e CDXGEN_DEBUG_MODE=debug -v /tmp:/tmp -v $(pwd):/app:rw -t ghcr.io/cyclonedx/cdxgen:master -r /app -o /app/bom.json ``` 要使用 deno 版本，请使用 `ghcr.io/cyclonedx/cdxgen-deno` 作为镜像名称。 ``` docker run --rm -e CDXGEN_DEBUG_MODE=debug -v /tmp:/tmp -v $(pwd):/app:rw -t ghcr.io/cyclonedx/cdxgen-deno:master -r /app -o /app/bom.json ``` 对于 bun 版本，请使用 `ghcr.io/cyclonedx/cdxgen-bun` 作为镜像名称。 ``` docker run --rm -e CDXGEN_DEBUG_MODE=debug -v /tmp:/tmp -v $(pwd):/app:rw -t ghcr.io/cyclonedx/cdxgen-bun:master -r /app -o /app/bom.json ``` 在 deno 应用程序中，cdxgen 可以直接导入而无需任何转换。请参阅关于[作为库集成](#integration-as-library)的章节 ``` import { createBom, submitBom } from "npm:@cyclonedx/cdxgen@^11.0.0"; ``` ## 获取帮助 ``` cdxgen [command] Commands: cdxgen completion Generate bash/zsh completion Options: -o, --output Output file. Default bom.json [default: "bom.json"] -t, --type Project type. Please refer to https://cdxgen.github.io/cdxgen/#/PROJECT_TYPES for supp orted languages/platforms. [array] --exclude-type Project types to exclude. Please refer to https://cdxgen.github.io/cdxgen/#/PROJECT_TY PES for supported languages/platforms. -r, --recurse Recurse mode suitable for mono-repos. Defaults to true. Pass --no-recurse to disable. [boolean] [default: true] -p, --print Print the SBOM as a table with tree. [boolean] -c, --resolve-class Resolve class names for packages. jars only for now. [boolean] --deep Perform deep searches for components. Useful while scanning C/C++ apps, live OS and oc i images. [boolean] --server-url Dependency track url. Eg: https://deptrack.cyclonedx.io --skip-dt-tls-check Skip TLS certificate check when calling Dependency-Track. [boolean] [default: false] --api-key Dependency track api key --project-group Dependency track project group --project-name Dependency track project name. Default use the directory name --project-version Dependency track project version [string] [default: ""] --project-tag Dependency track project tag. Multiple values allowed. [array] --project-id Dependency track project id. Either provide the id or the project name and version tog ether [string] --parent-project-id Dependency track parent project id [string] --required-only Include only the packages with required scope on the SBOM. Would set compositions.aggr egate to incomplete unless --no-auto-compositions is passed. [boolean] --fail-on-error Fail if any dependency extractor fails. [boolean] --no-babel Do not use babel to perform usage analysis for JavaScript/TypeScript projects. [boolean] --generate-key-and-sign Generate an RSA public/private key pair and then sign the generated SBOM using JSON We b Signatures. [boolean] --server Run cdxgen as a server [boolean] --server-host Listen address [default: "127.0.0.1"] --server-port Listen port [default: "9090"] --install-deps Install dependencies automatically for some projects. Defaults to true but disabled fo r containers and oci scans. Use --no-install-deps to disable this feature. [boolean] [default: true] --validate Validate the generated SBOM using json schema. Defaults to true. Pass --no-validate to disable. [boolean] [default: true] --evidence Generate SBOM with evidence for supported languages. [boolean] [default: false] --spec-version CycloneDX Specification version to use. Defaults to 1.6 [number] [choices: 1.4, 1.5, 1.6, 1.7] [default: 1.6] --filter Filter components containing this word in purl or component.properties.value. Multiple values allowed. [array] --only Include components only containing this word in purl. Useful to generate BOM with firs t party components alone. Multiple values allowed. [array] --author The person(s) who created the BOM. Set this value if you're intending the modify the B OM and claim authorship. [array] [default: "OWASP Foundation"] --profile BOM profile to use for generation. Default generic. [choices: "appsec", "research", "operational", "threat-modeling", "license-compliance", "generic", "machine-learning", "ml", "deep-learning", "ml-deep", "ml-tiny"] [default: "generic"] --include-regex glob pattern to include. This overrides the default pattern used during auto-detection . [string] --exclude, --exclude-regex Additional glob pattern(s) to ignore [array] --export-proto Serialize and export BOM as protobuf binary. [boolean] [default: false] --proto-bin-file Path for the serialized protobuf binary. [default: "bom.cdx"] --include-formulation Generate formulation section with git metadata and build tools. Defaults to false. [boolean] [default: false] --include-crypto Include crypto libraries as components. [boolean] [default: false] --standard The list of standards which may consist of regulations, industry or organizational-spe cific standards, maturity models, best practices, or any other requirements which can be evaluated against or attested to. [array] [choices: "asvs-5.0", "asvs-4.0.3", "bsimm-v13", "masvs-2.0.0", "nist_ssdf-1.1", "pcissc-secure-slc-1.1", "scv s-1.0.0", "ssaf-DRAFT-2023-11"] --json-pretty Pretty-print the generated BOM json. [boolean] [default: false] --min-confidence Minimum confidence needed for the identity of a component from 0 - 1, where 1 is 100% confidence. [number] [default: 0] --technique Analysis technique to use [array] [choices: "auto", "source-code-analysis", "binary-analysis", "manifest-analysis", "hash-comparison", "instrume ntation", "filename"] --auto-compositions Automatically set compositions when the BOM was filtered. Defaults to true [boolean] [default: true] -h, --help Show help [boolean] -v, --version Show version number [boolean] ``` 所有布尔参数都接受 `--no` 前缀来切换行为。 ## 示例 最小示例。 ``` cdxgen -o bom.json ``` 对于 Java 项目。cdxgen 会自动检测 maven、gradle 或 sbt 并相应地构建 bom ``` cdxgen -t java -o bom.json ``` 要将 SBOM 打印为表格，请传递 `-p` 参数。 ``` cdxgen -t java -o bom.json -p ``` 要递归地为所有语言生成单个 BOM，请传递 `-r` 参数。 ``` cdxgen -r -o bom.json ``` cdxgen 使用的默认规范是 1.6。要为不同的规范版本（例如 1.5 或 1.4）生成 BOM，请使用 `--spec-version` 参数传递版本号。 ``` # 1.5 受大多数工具支持 cdxgen -r -o bom.json --spec-version 1.5 ``` 要为 C 或 Python 生成 SBOM，请确保已安装 Java >= 21。 ``` # 安装 java >= 21 cdxgen -t c -o bom.json ``` 注意：已知 cdxgen 在 Java 8 或 11 下会冻结，因此请确保安装了 >= 21 的版本，并且 JAVA_HOME 环境变量配置正确。如有疑问，请使用 cdxgen 容器镜像。 ## 通用 SBOM 通过传递类型参数 `-t universal`，可以强制 cdxgen 通过扫描所有包、容器和 Kubernetes 清单来尽可能多地收集组件和服务。生成的 SBOM 可能包含上千个组件，因此在使用传统的 SCA 工具之前需要额外的分类。 ## SBOM 服务器 使用 `--server` 参数调用 cdxgen 以服务器模式运行。默认情况下，它监听端口 `9090`，可以使用参数 `--server-host` 和 `--server-port` 进行自定义。 ``` cdxgen --server ``` 或者使用容器镜像。 ``` docker run --rm -v /tmp:/tmp -p 9090:9090 -v $(pwd):/app:rw -t ghcr.io/cyclonedx/cdxgen -r /app --server --server-host 0.0.0.0 ``` 使用 curl 或您喜欢的工具将参数传递给 `/sbom` 路由。 ### 服务器参数 参数可以通过查询字符串或 JSON 正文传递。请参阅[服务器用法][docs-server] ### 健康检查端点 使用 /health 端点检查 SBOM 服务器是否已启动并正在运行。 ``` curl "http://127.0.0.1:9090/health" ``` ### 扫描本地路径 ``` curl "http://127.0.0.1:9090/sbom?path=/Volumes/Work/sandbox/vulnerable-aws-koa-app&multiProject=true&type=js" ``` ### 扫描 git 仓库 ``` curl "http://127.0.0.1:9090/sbom?url=https://github.com/HooliCorp/vulnerable-aws-koa-app.git&multiProject=true&type=js" ``` 如果需要传递凭据进行身份验证。 ``` curl "http://127.0.0.1:9090/sbom?url=https://@github.com/some/repo.git&multiProject=true&type=js" curl "http://127.0.0.1:9090/sbom?url=https://:@bitbucket.org/some/repo.git&multiProject=true&type=js" ``` 您可以 POST 参数。 ``` curl -H "Content-Type: application/json" http://localhost:9090/sbom -XPOST -d $'{"url": "https://github.com/HooliCorp/vulnerable-aws-koa-app.git", "type": "nodejs", "multiProject": "true"}' ``` ### Docker compose ``` git clone https://github.com/cdxgen/cdxgen.git docker compose up ``` ## War 文件支持 cdxgen 可以从给定的 war 文件生成 BOM 文件。 ``` # cdxgen -t java app.war cdxgen app.war ``` ## 解析类名 有时，需要解析 jar 文件中包含的类名。通过传递可选参数 `--resolve-class`，可以让 cdxgen 创建一个单独的映射文件，其中以 jar 名称（包括版本）作为键，以类名列表作为值。 ``` cdxgen -t java --resolve-class -o bom.json ``` 这将创建一个包含 jar - 类名映射的 bom.json.map 文件。请参阅[这些](test/data/bom-maven.json.map) [示例](test/data/bom-gradle.json.map)以了解其结构。 ## 解析许可证 cdxgen 可以自动查询公共注册表（如 maven、npm 或 nuget）来解析包许可证。这是一项耗时的操作，默认情况下处于禁用状态。要启用，请将环境变量 `FETCH_LICENSE` 设置为 `true`，如下所示。确保设置了 `GITHUB_TOKEN` 或由 [GitHub Actions 中的内置 GITHUB_TOKEN][github-rate-limit] 提供，否则速率限制可能会阻止许可证解析。 ``` export FETCH_LICENSE=true ``` ## 依赖树 cdxgen 可以在 `dependencies` 属性下保留少数受支持的包清单的依赖树。目前仅限于： - package-lock.json - yarn.lock - pnpm-lock.yaml - Maven (pom.xml) - Gradle - Scala SBT - Python (requirements.txt, setup.py, pyproject.toml, poetry.lock) - .NET (packages.lock.json, project.assets.json, paket.lock, .nuspec/.nupkg) - Go (go.mod) - PHP (composer.lock) - Ruby (Gemfile.lock) - Rust (Cargo.lock) ## 插件 cdxgen 可以通过外部二进制插件进行扩展，以支持更多的 SBOM 用例。这些现在作为可选依赖项安装。 ``` sudo npm install -g @cdxgen/cdxgen-plugins-bin ``` ## 插件 `cdxgen` 可以通过外部二进制插件进行扩展，以支持更多的 SBOM 用例。 这些现在作为可选依赖项安装，可以在无需全局安装的情况下使用。 ``` pnpm dlx @cdxgen/cdxgen-plugins-bin ``` ## Docker / OCI 容器支持 根据路径中是否存在 `sha256` 或 `docker.io` 前缀等值，会自动检测 `docker` 类型。 ``` cdxgen odoo@sha256:4e1e147f0e6714e8f8c5806d2b484075b4076ca50490577cdf9162566086d15e -o /tmp/bom.json ``` 您也可以使用仓库名称传递 `-t docker`。如果未指定，则只会拉取 `latest` 标签。 ``` cdxgen shiftleft/scan-slim -o /tmp/bom.json -t docker ``` 您也可以传递容器镜像的 .tar 文件。 ``` docker pull shiftleft/scan-slim docker save -o /tmp/slim.tar shiftleft/scan-slim podman save -q --format oci-archive -o /tmp/slim.tar shiftleft/scan-slim cdxgen /tmp/slim.tar -o /tmp/bom.json -t docker ``` ### 无根模式下的 Podman 以[无根][podman-github-rootless]或[远程][podman-github-remote]模式设置 podman 不要忘记启动 Linux 上 API 访问所需的 podman 套接字。 ``` systemctl --user enable --now podman.socket systemctl --user start podman.socket podman system service -t 0 & ``` ## 为实时系统生成 OBOM 您可以使用 `obom` 命令为实时系统或虚拟机生成 OBOM，以用于合规性和漏洞管理目的。此模式支持 Windows 和 Linux 操作系统。 ``` # obom 是 cdxgen -t os 的别名 obom # cdxgen -t os ``` 此功能由 osquery 提供支持，它与二进制插件一起[安装](https://github.com/cdxgen/cdxgen-plugins-bin/blob/main/build.sh#L8)。cdxgen 将尝试使用[默认查询](data/queries.json)尽可能地检测组件、应用程序和扩展。该过程将花费几分钟时间，并生成一个包含数千种不同类型组件（例如操作系统、设备驱动程序、文件和数据）的 SBOM 文件。 ## 生成加密物料清单 (CBOM) 使用 `cbom` 别名生成 CBOM。目前仅支持 Java 项目。 ``` cbom -t java # cdxgen -t java --include-crypto -o bom.json . ``` ## 生成 SaaSBOM 和组件证据 请参阅高级文档中的 [evinse 模式](./ADVANCED.md)。 ## BOM 签名 cdxgen 可以对生成的 BOM json 文件进行签名，以增加真实性和不可否认性能力。要启用此功能，请设置以下环境变量。 - SBOM_SIGN_ALGORITHM：算法。例如：RS512 - SBOM_SIGN_PRIVATE_KEY：RSA 私钥的位置 - SBOM_SIGN_PUBLIC_KEY：可选。RSA 公钥的位置 要通过传递参数 `--generate-key-and-sign` 来生成测试公钥/私钥对。生成的 json 文件将有一个名为 `signature` 的属性，可用于验证。[jwt.io][jwt-homepage] 是一个可用于此类签名验证的知名网站。  ### 验证签名 使用捆绑的 `cdx-verify` 命令，该命令支持验证在 bom 级别添加的单个签名。 ``` npm install -g @cyclonedx/cdxgen cdx-verify -i bom.json --public-key public.key ``` ### 验证签名 使用捆绑的 `cdx-verify` 命令，该命令支持验证在 BOM 级别添加的单个签名。 您可以使用 pnpm 直接运行它（无需全局安装）： ``` pnpm dlx @cyclonedx/cdxgen cdx-verify -i bom.json --public-key public.key ``` ### 自定义验证工具（Node.js 示例） 有许多[库][jwt-libraries]可用于验证 JSON Web Tokens。以下是一个 javascript 示例。 ``` # npm install jws const jws = require("jws"); const fs = require("fs"); // Location of the SBOM json file const bomJsonFile = "bom.json"; // Location of the public key const publicKeyFile = "public.key"; const bomJson = JSON.parse(fs.readFileSync(bomJsonFile, "utf8")); // Retrieve the signature const bomSignature = bomJson.signature.value; const validationResult = jws.verify(bomSignature, bomJson.signature.algorithm, fs.readFileSync(publicKeyFile, "utf8")); if (validationResult) { console.log("Signature is valid!"); } else { console.log("SBOM signature is invalid :("); } ``` ## 自动使用情况检测 对于 node.js 项目，首先解析 lock 文件，因此 SBOM 将包含所有依赖项，包括 dev 依赖项。然后使用由 babel-parser 驱动的 AST 解析器来检测被非测试代码导入和使用的包。此类导入的包会在生成的 SBOM 中自动将其 scope 属性设置为 `required`。您可以通过传递参数 `--no-babel` 来关闭此分析。然后，scope 属性将根据 lock 文件中的 `dev` 属性进行设置。 此属性以后可用于各种目的。例如，[dep-scan][depscan-github] 使用此属性来确定漏洞的优先级。不幸的是，像 dependency track 这样的工具不包括此功能，可能会过度报告 CVE。 使用参数 `--required-only`，您可以将 SBOM 限制为仅包含 scope 为“required”的包，通常称为生产或非 dev 依赖项。结合 `--no-babel`，将根据 lock 文件中 `dev` 属性为 false 的情况，将此列表限制为仅非 dev 依赖项。 对于 go，使用 `go mod why` 命令来识别必需的包。对于 php，解析 composer lock 文件以区分必需包 和可选包。 ## 自动服务检测 cdxgen 可以从 YAML 清单（例如 docker-compose、Kubernetes 或 Skaffold 清单）中自动检测服务名称。这些将填充在生成的 SBOM 中的 `services` 属性下。使用 [evinse](./ADVANCED.md)，可以通过解析源代码中的常见注释来检测其他服务。 ## 转换为 SPDX 格式 使用 [CycloneDX][cyclonedx-cli-github] 工具处理高级用例，例如转换、差异比较和合并。 ## 在结果中包含 .NET 全局程序集缓存依赖项 对于 `dotnet` 和 `dotnet-framework`，SBOM 可能包含没有版本号的组件。通常，这些组件以 `System.` 前缀开头。 全局程序集缓存 (GAC) 依赖项（系统运行时依赖项）必须在项目的构建输出中可用，以便进行版本检测。让 dotnet 构建将 GAC 依赖项复制到构建目录的一种简单方法是将文件 `Directory.Build.props` 放置在项目的根目录中，并确保其内容包含以下内容： ``` True ``` 然后，使用 `--deep` 参数运行 cdxgen cli。 ## 许可证 在 Apache 2.0 许可证的条款下，授予修改和重新分发的权限。有关完整许可证，请参阅 [LICENSE][github-license] 文件。 ## 作为库集成 cdxgen [仅支持 ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c)，可以在 deno 和 Node.js >= 20 中导入和使用 最小示例： ``` import { createBom, submitBom } from "npm:@cyclonedx/cdxgen@^9.0.1"; ``` 请参阅 [Deno Readme](./contrib/deno/README.md) 以获取详细说明。 ``` import { createBom, submitBom } from "@cyclonedx/cdxgen"; // bomNSData would contain bomJson const bomNSData = await createBom(filePath, options); // Submission to dependency track server const dbody = await submitBom(args, bomNSData.bomJson); ``` ## 贡献 如果您有兴趣提供帮助，请查看我们的 [未解决问题][github-contribute]。 ### Codeberg 镜像 该项目在 [Codeberg](https://codeberg.org/cdxgen/cdxgen) 上有镜像。用户可以使用以下 URL 克隆仓库： ``` git clone https://codeberg.org/cdxgen/cdxgen.git ``` 维护者接受针对 Codeberg 仓库的 Pull Requests (PR)。 在提出 PR 之前，请运行以下命令。 ``` corepack enable pnpm pnpm install:frozen # 使用 jsdoc 语法生成类型 pnpm run gen-types # 运行 biomejs formatter 和 linter 并自动修复 pnpm run lint # 运行 jest 测试 pnpm test ``` ### 测试主分支 使用 `pnpm add -g` 命令快速测试主分支。 ``` corepack pnpm bin -g corepack pnpm setup corepack pnpm add -g --allow-build @appthreat/sqlite3 https://github.com/cdxgen/cdxgen cdxgen --help ``` ### 测试主分支（无全局安装） 要在不全局安装的情况下快速测试最新的主分支，您可以在本地或临时环境中使用 `pnpm`。 ``` corepack enable pnpm install --prefer-offline pnpm dlx cdxgen --help ``` ## 赞助商

某些功能通过 [NGI Zero Core](https://nlnet.nl/core) 资助，这是一个由 [NLnet](https://nlnet.nl) 设立的基金，并得到了欧盟委员会 [下一代互联网](https://ngi.eu) 计划的财政支持。在 [NLnet 项目页面](https://nlnet.nl/project/OWASP-dep-scan) 了解更多信息。 [](https://nlnet.nl) [](https://nlnet.nl/core) cdxgen 是一个 OWASP 基金会生产项目。 [](https://owasp.org)

标签：AI应用开发, CycloneDX, Dependency Track, DevSecOps, Docker, GPT, IPv6支持, MITM代理, npm, SBOM, Web截图, 上游代理, 云安全监控, 人工智能安全, 依赖扫描, 合规性, 安全防御评估, 容器安全, 开源组件, 文档安全, 模型提供商, 漏洞管理, 硬件无关, 网络调试, 自动化, 自定义脚本, 请求拦截, 跌倒检测, 软件开发工具包, 软件物料清单, 静态分析