CycloneDX/cyclonedx-dotnet

# CycloneDX .NET 模块 [![shield_nuget-version]][link_nuget] [![shield_docker-version]][link_docker] [![shield_github_ci]][link_github_ci] [![shield_license]][License] [![shield_website]][link_website] [![shield_slack]][link_slack] [![shield_groups]][link_discussion] [![shield_twitter-follow]][link_twitter] CycloneDX .NET 模块用于创建一个包含所有项目依赖项聚合的有效 CycloneDX BOM 文档。CycloneDX 是一个轻量级的 BOM 规范，易于创建、人类可读且易于解析。 此模块运行于 * .NET 10.0 * .NET 9.0 * .NET 8.0 ## 用法 CycloneDX for .NET 通过 [NuGet][link_nuget] 和 [Docker Hub][link_docker] 分发。 #### 通过 NuGet 安装 ``` dotnet tool install --global CycloneDX ``` 如果您已经安装了旧版本的 **CycloneDX**，可以使用以下命令升级到最新版本： ``` dotnet tool update --global CycloneDX ``` #### 执行 ``` dotnet-CycloneDX -o ``` #### 通过 Docker 执行 ``` docker run --rm --user $(id -u):$(id -g) \ -v $(pwd):/work \ cyclonedx/cyclonedx-dotnet [OPTIONS] /work/ ``` #### 选项 ``` Usage: dotnet-CycloneDX [options] Arguments: The path to a .sln, .slnf, .slnx, .csproj, .fsproj, .vbproj, .xsproj, or packages.config file or the path to a directory which will be recursively analyzed for packages.config files. Options: -tfm, --framework The target framework to use. If not defined, all will be aggregated. -rt, --runtime The runtime to use. If not defined, all will be aggregated. -o, --output

The directory to write the BOM -fn, --filename Optionally provide a filename for the BOM (default: bom.xml or bom.json) -ed, --exclude-dev Exclude development dependencies from the BOM (see https://github.com/NuGet/Home/wiki/DevelopmentDependency-support-for-PackageReference) -t, --exclude-test-projects Exclude test projects from the BOM -u, --url Alternative NuGet repository URL to https:///nuget//v3/index.json -us, --baseUrlUsername Alternative NuGet repository username (env: CYCLONEDX_NUGET_USERNAME) -usp, --baseUrlUserPassword Alternative NuGet repository username password/apikey (env: CYCLONEDX_NUGET_PASSWORD) -uspct, --isBaseUrlPasswordClearText Alternative NuGet repository password is cleartext -rs, --recursive To be used with a single project file, it will recursively scan project references of the supplied project file -ns, --no-serial-number Optionally omit the serial number from the resulting BOM -gu, --github-username Optionally provide a GitHub username for license resolution. If set you also need to provide a GitHub personal access token (env: CYCLONEDX_GITHUB_USERNAME) -gt, --github-token Optionally provide a GitHub personal access token for license resolution. If set you also need to provide a GitHub username (env: CYCLONEDX_GITHUB_TOKEN) -gbt, --github-bearer-token Optionally provide a GitHub bearer token for license resolution. This is useful in GitHub actions (env: CYCLONEDX_GITHUB_BEARER_TOKEN, GITHUB_TOKEN) -egl, --enable-github-licenses Enables GitHub license resolution -dpr, --disable-package-restore Optionally disable package restore -dhc, --disable-hash-computation Optionally disable hash computation for packages -dct, --dotnet-command-timeout dotnet command timeout in milliseconds (primarily used for long dotnet restore operations) [default: 300000] -biop, --base-intermediate-output-path Optionally provide a folder for customized build environment. Required if folder 'obj' is relocated. -imp, --import-metadata-path Optionally provide a metadata template which has project specific details. -ipr, --include-project-references Include project references as components (can only be used with project files). -sn, --set-name Override the autogenerated BOM metadata component name. -sv, --set-version Override the default BOM metadata component version (defaults to 0.0.0). -st, --set-type -ef, --exclude-filter A comma separated list of dependencies to exclude in form 'name1@version1,name2@version2' or 'name1,name2' (to exclude all versions). Transitive dependencies will also be removed. -F, --output-format Select the BOM output format: auto (default), xml, json, or unsafeJson (relaxed escaping). [default: Auto] --set-nuget-purl Override the default BOM metadata component bom ref and PURL as NuGet package. --version Show version information -?, -h, --help Show help and usage information ``` * `-ef, --exclude-filter` 排除过滤器可用于排除任何由 NuGet 解析但不存在于最终二进制输出中的包。例如，某个应用程序的目标框架是 .NET 8，但依赖的一个库仅支持 .NET Standard 1.6。如果不使用过滤器，生成的 SBOM 中将包含 .NET Standard 1.6 的库。但由于它们不存在于二进制输出文件夹中，因此不会被应用程序使用。 #### 示例 要运行 **CycloneDX** 工具，您需要指定一个解决方案或项目文件。如果您传递的是一个解决方案，该工具将聚合所有项目。 以下命令将从解决方案及其定义的所有项目创建一个 BOM： ``` dotnet-CycloneDX YourSolution.sln -o /output/path ``` 以下命令将递归扫描目录结构中的 packages.config 并创建一个 BOM： ``` dotnet-CycloneDX /path/to/project -o /output/path ``` 以下命令将递归扫描所提供项目文件的项目引用，并从所有包含的项目中创建包含所有包引用的 BOM： ``` dotnet-CycloneDX /path/to/project/MyProject.csproj -o /output/path -rs ``` 以下命令将从项目创建 BOM 并排除可传递依赖 .NET Standard： ``` dotnet-CycloneDX /path/to/project/MyProject.csproj -o /output/path -ef NETStandard.Library@1.6.0 ``` #### BOM 元数据 BOM `` 块按优先级顺序从三个来源填充： CLI 参数（`--set-name`、`--set-version`、`--set-type`）覆盖模板文件（`--import-metadata-path`），而模板文件又覆盖从扫描项目名称派生的自动回退值。 完整参考请参阅 **[docs/bom-metadata.md](docs/bom-metadata.md)**：模板文件格式、优先级规则和常见 CI 模式。 #### 通过环境变量设置凭据 所有凭据选项都可以通过环境变量而不是命令行参数提供。这可以避免在进程列表、Shell 历史记录和 CI 日志中暴露机密信息。 | 环境变量 | 等效 CLI 标志 | 描述 | |---|---|---| | `CYCLONEDX_NUGET_USERNAME` | `-us` / `--baseUrlUsername` | NuGet 源用户名 | | `CYCLONEDX_NUGET_PASSWORD` | `-usp` / `--baseUrlUserPassword` | NuGet 源密码或 API 密钥 | | `CYCLONEDX_GITHUB_USERNAME` | `-gu` / `--github-username` | 用于 Basic 认证的 GitHub 用户名 | | `CYCLONEDX_GITHUB_TOKEN` | `-gt` / `--github-token` | GitHub 个人访问令牌 | | `CYCLONEDX_GITHUB_BEARER_TOKEN` | `-gbt` / `--github-bearer-token` | GitHub bearer token | | `GITHUB_TOKEN` | `-gbt` / `--github-bearer-token` | GitHub bearer token（标准 Actions 变量，作为 `CYCLONEDX_GITHUB_BEARER_TOKEN` 的回退） | 当 CLI 参数和环境变量同时设置时，CLI 参数优先。 #### GitHub 许可证解析 对于引用 GitHub 仓库中受支持许可证文件的包，可以解析出 SPDX 许可证 ID。 GitHub 许可证 API 的未认证调用限制为每小时 60 次。为了确保超过速率限制时输出的一致性，BOM 生成将失败。如果您开始达到速率限制，则需要生成一个个人访问令牌，并在运行 CycloneDX 时提供该令牌和您的用户名。 要生成令牌，请转到 `Settings / Developer settings` 下的 [Personal access tokens](https://github.com/settings/tokens)。在那里，选择 [Generate new token](https://github.com/settings/tokens/new) 选项。不需要特殊的令牌权限。 由于 GitHub API 的当前限制，仅会解析 master 分支的许可证引用。 ## 许可证 在 Apache 2.0 许可证的条款下，授予修改和重新分发的权限。有关完整许可证，请参阅 [LICENSE] 文件。 ## 贡献 欢迎提交 Pull requests。但请先阅读 [CycloneDX 贡献指南](https://github.com/CycloneDX/.github/blob/master/CONTRIBUTING.md)。 要在本地构建和测试解决方案，您应该安装 .NET 8.0、.NET 9.0 或 .NET 10.0 SDK。诸如 `dotnet build` 和 `dotnet test` 之类的标准命令均可使用。 或者，您可以使用 VS Code 和包含的 devcontainer 配置在预配置的 docker 镜像中工作。（您还需要 "Remote - Containers" 扩展和 Docker） 通常期望 Pull requests 包含相关的测试。 测试会在每个 Pull request 中自动在 Windows、MacOS 和 Linux 上运行。 并且构建警告将导致构建中断。 如果您在调试某个您无法访问的平台上失败的测试时遇到困难，请告诉我们。 感谢 [Gitpod](https://gitpod.io/)，有一种非常简单的方法可以使用 VS Code 创建一个即用型的开发环境。您可以在浏览器中打开 Gitpod 托管的开发环境。 [](https://gitpod.io/#https://github.com/CycloneDX/cyclonedx-dotnet)

标签：CycloneDX, DevSecOps, Docker容器, GPT, LLM防护, LNA, NuGet, SBOM, WebSocket, 上游代理, 云安全监控, 依赖分析, 多人体追踪, 开源合规, 攻击面发现, 漏洞管理, 物料清单, 硬件无关, 组件管理, 请求拦截, 软件开发, 静态分析