CycloneDX/cyclonedx-node-npm
GitHub: CycloneDX/cyclonedx-node-npm
该工具从 Node.js npm 项目中生成符合 CycloneDX 规范的软件物料清单（SBOM），解决依赖组件透明度与供应链合规管理问题。
Stars: 144 | Forks: 29
# 面向 _npm_ 的 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]
从 _[npm]_ 项目创建 [CycloneDX] Software Bill of Materials (SBOM)。
这可能是用于基于 npm 的项目最准确、最完整的 SBOM 生成器。
基于 [OWASP Software Component Verification Standard for Software Bill of Materials](https://scvs.owasp.org/scvs/v2-software-bill-of-materials/) 的
标准，此工具能够生成几乎通过 Level-2 的 SBOM 文档（只需在外部进行签名即可）。
生成的 SBOM 文档遵循 [官方规范和标准](https://github.com/CycloneDX/specification)，
并可能具有遵循 [`cdx:npm` Namespace Taxonomy](https://cyclonedx.github.io/cyclonedx-property-taxonomy/cdx/npm.html)
和 [`cdx` Namespace Taxonomy](https://cyclonedx.github.io/cyclonedx-property-taxonomy/cdx.html)
的属性。
## 要求
* `node >= 20.18.0`
* `npm >= 9`
不过，此工具的旧版本支持
* Node.js v14 或更高版本
* NPM v6 或更高版本
## 安装说明
有多种方法可以安装此工具：
* 作为类似 `npm` 的全局工具：
npm install --global @cyclonedx/cyclonedx-npm
* 作为类似 `npx` 的全局工具：
npx --package @cyclonedx/cyclonedx-npm --call exit
* 作为当前项目的开发依赖：
npm install --save-dev @cyclonedx/cyclonedx-npm
## 用法
根据安装方式的不同，以下是正确的用法说明：
* 如果作为类似 `npm` 的全局工具安装：
cyclonedx-npm --help
* 如果作为类似 `npx` 的全局工具安装：
— 或者 —
如果作为当前项目的开发依赖安装：
npx @cyclonedx/cyclonedx-npm --help
帮助页面：
```
Usage: cyclonedx-npm [options] [--] []
Create CycloneDX Software Bill of Materials (SBOM) from Node.js NPM projects.
Arguments:
Path to project's manifest file.
(default: "package.json" file in current working directory)
Options:
--ignore-npm-errors Whether to ignore errors of NPM.
This might be used, if "npm install" was run with "--force" or "--legacy-peer-deps".
(default: false)
--package-lock-only Whether to only use the lock file, ignoring "node_modules".
This means the output will be based only on the few details in and the tree described by the "npm-shrinkwrap.json" or "package-lock.json", rather than the contents of "node_modules" directory.
(default: false)
--omit Dependency types to omit from the installation tree.
(can be set multiple times)
(choices: "dev", "optional", "peer", default: "dev" if the NODE_ENV environment variable is set to "production", otherwise empty)
-w, --workspace Only include dependencies for specific workspaces.
(can be set multiple times)
This feature is experimental.
(default: empty)
--no-workspaces Do not include dependencies for workspaces.
Default behaviour is to include dependencies for all configured workspaces.
This cannot be used if workspaces have been explicitly defined using `--workspace`.
This feature is experimental.
--include-workspace-root Include workspace root dependencies along with explicitly defined workspaces' dependencies. This can only be used if you have explicitly defined workspaces using `--workspace`.
Default behaviour is to not include the workspace root when workspaces are explicitly defined using `--workspace`.
This feature is experimental.
--no-include-workspace-root Do not include workspace root dependencies. This only has an effect if you have one or more workspaces configured in your project.
This is useful if you want to include all dependencies for all workspaces without explicitly defining them with `--workspace` (default behaviour) but you do not want the workspace root dependencies included.
This feature is experimental.
--gather-license-texts Search for license files in components and include them as license evidence.
This feature is experimental.
(default: false)
--flatten-components Whether to flatten the components.
This means the actual nesting of node packages is not represented in the SBOM result.
(default: false)
--short-PURLs Omit all qualifiers from PackageURLs.
This causes information loss in trade-off shorter PURLs, which might improve ingesting these strings.
(default: false)
--sv, --spec-version Which version of CycloneDX spec to use.
(choices: "1.2", "1.3", "1.4", "1.5", "1.6", 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)
--of, --output-format Which output format to use.
(choices: "JSON", "XML", default: "JSON")
-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. See the README.
--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
```
## 演示
有关 _cyclonedx-npm_ 的演示，请参阅 [演示项目][demo_readme]。
## 工作原理
此工具利用 _[npm]_ 来收集已安装 packages/modules 的证据。
请阅读 [专门文档](https://github.com/CycloneDX/cyclonedx-node-npm/tree/main/docs/how.md) 了解更多。
适当的 _npm_ 可执行文件会被自动检测，但可以通过环境变量 `npm_execpath` 进行覆盖。
自动检测：如果从 `npm`/`npx` 上下文调用，则使用当前的 _npm_ 可执行文件，否则由 SHELL 和 PATH 进行管理。
此工具不进行人为的去重。
因此，如果一个 component 被安装了多次，它将在 SBOM 结果中出现多次。
请阅读 [专门文档“Component Deduplication”](https://github.com/CycloneDX/cyclonedx-node-npm/tree/main/docs/component_deduplication.md) 了解有关该主题的更多信息。
## 内部原理
此工具利用 [CycloneDX 库][cyclonedx-library] 生成实际的数据结构，并对它们进行序列化和验证。
验证需要 [transitive optional dependencies](https://github.com/CycloneDX/cyclonedx-javascript-library/blob/main/README.md#optional-dependencies)。
此工具**不**暴露任何额外的 _public_ 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-npm-cli.js',
'--output-format', 'JSON',
'--output-file', '-'
// additional CLI args
], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'buffer', maxBuffer: BUFFER_MAX_LENGTH }))
```
## 许可证
在 Apache 2.0 许可证的条款下，授予修改和重新分发的权限。
有关完整的许可证，请参阅 [LICENSE][license_file] 文件。
标签：CycloneDX, GNU通用公共许可证, LLM防护, MITM代理, Node.js, SBOM, 依赖管理, 安全合规, 数据可视化, 暗色界面, 硬件无关, 网络代理, 自定义脚本