BjarneRentz/central-cyclone
GitHub: BjarneRentz/central-cyclone
围绕 cdxgen 构建的集中式 SBOM 生成与上传服务，通过统一配置文件批量管理多个仓库的软件物料清单，免除逐个仓库搭建流水线的繁琐工作。
Stars: 9 | Forks: 0
# 中心气旋 🌪️
Central Cyclone 是一个围绕 [cdxgen](https://github.com/CycloneDX/cdxgen) 构建的集中式 SBOM (软件物料清单) 生成服务。它可以被配置为分析和上传多个仓库及多个目标的结果，这样您就不必为每个仓库单独创建流水线。这类似于 Renovate 可以被配置为管理多个仓库的方式。
[
]()
## 目录
- [功能](#features)
- [用法](#usage)
- [配置](#configuration)
- [命令](#commands)
- [环境变量](#environment-variables)
- [示例](#example)
- [路线图](#roadmap)
- [贡献与支持](#contributing--support)
- [开发环境设置](#development-setup)
- [DevContainer](#devcontainer)
- [本地机器](#local-machine)
- [AI 免责声明](#ai-disclaimer)
## 功能
- 为多个仓库/项目提供集中式 SBOM 生成
- 上传至 [DependencyTrack](https://dependencytrack.org)
- 配置驱动：在单一配置文件中管理所有目标
- 提供用于轻松实现自动化的命令行界面
## 用法
### 配置
在一个 JSON 配置文件中定义您的目标和设置。有关配置示例，请参见 `exampleConfig.json`。它看起来像这样
```
{
"dependencyTrack": {
"url": "http://apiserver:8080"
},
"repositories": [
{
"url": "https://github.com/BjarneRentz/obsidian-gemini-generator.git",
"targets": [
{
"projectId": "2fbbfb99-132e-4e8d-b253-4aa8d58aa505",
"type": "node",
"directory": "web"
}, {
"projectId": "2fbbfb99-132e-3d8d-b253-4aa8d58aa505",
"type": "java"
}
]
}
],
"applications": [
{
"name": "My-App",
"type": "node",
"projects": [
{
"name": "My-App - Dev",
"version": "Dev",
"isLatest": true
},
{
"name": "My-App - Prod",
"version": "Prod",
"isLatest": false
}
]
}
]
}
```
配置文件中的 `dependencyTrack` 部分**是强制性的**，同时设置 `DEPENDENCYTRACK_API_KEY` 环境变量也是必须的。有关更多详细信息，请参阅 [环境变量](#environment-variables) 部分。
您可以为单个仓库配置多个*目标*。这对于 monorepo（单一仓库）非常有用，在这种情况下，不同的编程语言或项目在同一个仓库下进行管理。您可以在 [cdxgen 文档](https://cyclonedx.github.io/cdxgen/#/PROJECT_TYPES) 中找到所有支持的目标。
如果您的项目包含多个相同类型的子项目。您可以使用可选的 `directory` 属性指定仓库中的子目录。
新的 `applications` 块是可选的，可用于定义应用程序。一个应用程序可以包含多个*项目*。每个项目代表 DependencyTrack 中的一个项目。
这个概念将在未来的更新中使用，以启用 GitOps 模式，在该模式下，central cyclone 将监控您的 GitOps 仓库，并为您环境中部署的版本创建 SBOM。
### 命令
#### 全局参数
|参数| 快捷方式| 描述|
|-|-|-|
|`--config`| `-c`| 配置文件的路径|
#### 分析已配置的仓库
`analyze` 命令会克隆并分析所有已配置的仓库中定义的目标。生成的 SBOM 会被保存在 `~/.central-cyclone/workfolder/sboms` 路径下，或者直接上传。
```
analyze
```
- `-c path-to-config`：配置 JSON 文件的路径。
- `--upload`：可选，上传生成的 SBOM 而不是保存它们。
#### 上传
upload 命令可用于上传由 analyze 命令生成的 SBOM 文件。这在受限制的网络环境中非常有用。您可以使用两阶段流水线，首先在云端 Agent 上分析项目，然后使用自托管 Agent 上传生成的 SBOM。
需要注意的是，Central Cyclone 只能上传由相同版本的 Central Cyclone 创建的 SBOM。Central Cyclone 不会将*原始的* SBOM 保存为 JSON，而是将其与一些元数据（如 DependencyTrack Project Id）包装在一起保存。
```
upload
```
- `-c path-to-config`：配置 JSON 文件的路径。
- `--sboms-dir`：必填，包含所有待上传 SBOM 的目录路径。
`
#### 将项目与 DependencyTrack 同步
您可以使用 central cyclone 来创建和同步 DependencyTrack 项目。但是，此功能并非“配置即代码”解决方案。如配置中所述，它只会同步为应用程序定义的项目。这将在以后用于 central cyclone 的 GitOps 模式。
使用此命令触发同步：
```
dt projects sync
```
- `-c path-to-config`：配置 JSON 文件的路径
该命令只会在项目不存在时创建它们。现有项目既不会被删除也不会被更新。
### Docker 镜像
我们在 GitHub 的 Packages 部分提供了官方的 Docker 镜像。建议使用 Docker 镜像来运行 Central-Cyclone，因为它已经包含了所有依赖项，例如 `git` 和 `cdxgen`。
要使用它，请按照上述说明创建一个配置并将其挂载到容器中。只需确保传递给 analyze 命令的路径与挂载的路径相匹配：
```
docker run \
-v ./myConfig.json:/config/config.json \
-e DEPENDENCYTRACK_API_KEY=MY_API_KEY \
ghcr.io/bjarnerentz/central-cyclone:latest analyze -c /config/config.json
```
提取 `analyze` 命令生成的 SBOM 的最简单方法是挂载 central cyclone 的工作文件夹。
工作文件夹位于 home 目录下，对于当前的 Docker 镜像，此目录为 `\root`。
```
docker run \
-v ./myConfig.json:/config/config.json \
-v ./sboms:/root/.central-cyclone/workfolder/sboms \
-e DEPENDENCYTRACK_API_KEY=MY_API_KEY \
ghcr.io/bjarnerentz/central-cyclone:latest analyze -c /config/config.json
```
### 克隆私有仓库
**支持的平台：**
目前，此功能已在 GitHub 和 Azure DevOps 上进行了测试。如果您成功在其他平台上使用了它，请告诉我们！
**URL 转换示例：**
GitHub:
https://github.com//.git
⟶ https://@github.com//.git
Azure DevOps:
https://dev.azure.com///_git/
⟶ https://@dev.azure.com///_git/
**注意：**
对于 GitHub，请使用细粒度的个人访问令牌。选择您想要克隆的仓库，并添加 *Contents* 权限设为只读。
对于 Azure DevOps，请使用具有 "Code" 读取权限的 PAT。
如果您遇到任何问题或需要支持其他平台，请提出 Issue，以便我们在未来的版本中进行改进。
另请查阅文档中可用的流水线变量，例如 Azure Devops 中的 [`System.AccessToken`](https://learn.microsoft.com/de-de/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#systemaccesstoken)，以避免使用长期有效的令牌。
## 环境变量
- `DEPENDENCYTRACK_API_KEY`（必填）：用于与 Dependency-Track 进行身份验证的 API key。
- `GIT_TOKEN`（可选）可设置为用于克隆私有仓库。
该 API key 仅需要具有项目的 BOM-Upload 权限。Central Cyclone 不会在 DependencyTrack 中为您创建项目。
## 示例
有关最小可用的配置，请参见 `exampleConfig.json`。
## 路线图
- 支持 GitOps：自动为应用程序已部署的版本创建 SBOM。
## 贡献与支持
如有任何问题、议题或贡献，请在 GitHub 上提出 Issue 或 Pull Request。
### 开发环境设置
#### DevContainer
本项目附带了一个 DevContainer 设置，其中附带了所有必需的依赖项：
- git
- cdxgen
- DependencyTrack
首次启动时，您可以使用用户名 `admin` 和密码 `admin` 在 `http://localhost:8080` 登录 DependencyTrack。之后，系统会提示您更改 `admin` 用户的默认密码。DevContainer 配置为使用一个卷来保存 DependencyTrack 的数据，因此将会持久化保存新密码。
接下来，创建一个项目和一个供 Central Cyclone 使用的新团队及 API key。有关这方面的更多详细信息，请参阅官方的 [DependencyTrack 文档](https://docs.dependencytrack.org)。
#### 本地机器
如果您不想使用 DevContainer，请确保 Central Cyclone 可以通过您的 `PATH` 访问以下工具：
- git
- cdxgen
并且能够访问到 DependencyTrack 实例。
## AI 免责声明
本项目是在 AI 的辅助下创建的。您可以自由地让 AI 协助您处理 Pull Request，但请您务必自行审查更改。
]()
## 目录
- [功能](#features)
- [用法](#usage)
- [配置](#configuration)
- [命令](#commands)
- [环境变量](#environment-variables)
- [示例](#example)
- [路线图](#roadmap)
- [贡献与支持](#contributing--support)
- [开发环境设置](#development-setup)
- [DevContainer](#devcontainer)
- [本地机器](#local-machine)
- [AI 免责声明](#ai-disclaimer)
## 功能
- 为多个仓库/项目提供集中式 SBOM 生成
- 上传至 [DependencyTrack](https://dependencytrack.org)
- 配置驱动：在单一配置文件中管理所有目标
- 提供用于轻松实现自动化的命令行界面
## 用法
### 配置
在一个 JSON 配置文件中定义您的目标和设置。有关配置示例，请参见 `exampleConfig.json`。它看起来像这样
```
{
"dependencyTrack": {
"url": "http://apiserver:8080"
},
"repositories": [
{
"url": "https://github.com/BjarneRentz/obsidian-gemini-generator.git",
"targets": [
{
"projectId": "2fbbfb99-132e-4e8d-b253-4aa8d58aa505",
"type": "node",
"directory": "web"
}, {
"projectId": "2fbbfb99-132e-3d8d-b253-4aa8d58aa505",
"type": "java"
}
]
}
],
"applications": [
{
"name": "My-App",
"type": "node",
"projects": [
{
"name": "My-App - Dev",
"version": "Dev",
"isLatest": true
},
{
"name": "My-App - Prod",
"version": "Prod",
"isLatest": false
}
]
}
]
}
```
配置文件中的 `dependencyTrack` 部分**是强制性的**，同时设置 `DEPENDENCYTRACK_API_KEY` 环境变量也是必须的。有关更多详细信息，请参阅 [环境变量](#environment-variables) 部分。
您可以为单个仓库配置多个*目标*。这对于 monorepo（单一仓库）非常有用，在这种情况下，不同的编程语言或项目在同一个仓库下进行管理。您可以在 [cdxgen 文档](https://cyclonedx.github.io/cdxgen/#/PROJECT_TYPES) 中找到所有支持的目标。
如果您的项目包含多个相同类型的子项目。您可以使用可选的 `directory` 属性指定仓库中的子目录。
新的 `applications` 块是可选的，可用于定义应用程序。一个应用程序可以包含多个*项目*。每个项目代表 DependencyTrack 中的一个项目。
这个概念将在未来的更新中使用，以启用 GitOps 模式，在该模式下，central cyclone 将监控您的 GitOps 仓库，并为您环境中部署的版本创建 SBOM。
### 命令
#### 全局参数
|参数| 快捷方式| 描述|
|-|-|-|
|`--config`| `-c`| 配置文件的路径|
#### 分析已配置的仓库
`analyze` 命令会克隆并分析所有已配置的仓库中定义的目标。生成的 SBOM 会被保存在 `~/.central-cyclone/workfolder/sboms` 路径下，或者直接上传。
```
analyze
```
- `-c path-to-config`：配置 JSON 文件的路径。
- `--upload`：可选，上传生成的 SBOM 而不是保存它们。
#### 上传
upload 命令可用于上传由 analyze 命令生成的 SBOM 文件。这在受限制的网络环境中非常有用。您可以使用两阶段流水线，首先在云端 Agent 上分析项目，然后使用自托管 Agent 上传生成的 SBOM。
需要注意的是，Central Cyclone 只能上传由相同版本的 Central Cyclone 创建的 SBOM。Central Cyclone 不会将*原始的* SBOM 保存为 JSON，而是将其与一些元数据（如 DependencyTrack Project Id）包装在一起保存。
```
upload
```
- `-c path-to-config`：配置 JSON 文件的路径。
- `--sboms-dir`：必填，包含所有待上传 SBOM 的目录路径。
`
#### 将项目与 DependencyTrack 同步
您可以使用 central cyclone 来创建和同步 DependencyTrack 项目。但是，此功能并非“配置即代码”解决方案。如配置中所述，它只会同步为应用程序定义的项目。这将在以后用于 central cyclone 的 GitOps 模式。
使用此命令触发同步：
```
dt projects sync
```
- `-c path-to-config`：配置 JSON 文件的路径
该命令只会在项目不存在时创建它们。现有项目既不会被删除也不会被更新。
### Docker 镜像
我们在 GitHub 的 Packages 部分提供了官方的 Docker 镜像。建议使用 Docker 镜像来运行 Central-Cyclone，因为它已经包含了所有依赖项，例如 `git` 和 `cdxgen`。
要使用它，请按照上述说明创建一个配置并将其挂载到容器中。只需确保传递给 analyze 命令的路径与挂载的路径相匹配：
```
docker run \
-v ./myConfig.json:/config/config.json \
-e DEPENDENCYTRACK_API_KEY=MY_API_KEY \
ghcr.io/bjarnerentz/central-cyclone:latest analyze -c /config/config.json
```
提取 `analyze` 命令生成的 SBOM 的最简单方法是挂载 central cyclone 的工作文件夹。
工作文件夹位于 home 目录下，对于当前的 Docker 镜像，此目录为 `\root`。
```
docker run \
-v ./myConfig.json:/config/config.json \
-v ./sboms:/root/.central-cyclone/workfolder/sboms \
-e DEPENDENCYTRACK_API_KEY=MY_API_KEY \
ghcr.io/bjarnerentz/central-cyclone:latest analyze -c /config/config.json
```
### 克隆私有仓库
**支持的平台：**
目前，此功能已在 GitHub 和 Azure DevOps 上进行了测试。如果您成功在其他平台上使用了它，请告诉我们！
**URL 转换示例：**
GitHub:
https://github.com/标签：cdxgen, CycloneDX, DependencyTrack, DevSecOps, EVTX分析, GNU通用公共许可证, GPT, JSON配置, MITM代理, Node.js, SBOM, SBOM上传, SBOM生成, 上游代理, 代码分析, 凭证管理, 占用监测, 安全合规, 开源框架, 开源组件管理, 持续集成, 文档结构分析, 漏洞管理, 硬件无关, 网络代理, 网络安全研究, 网络调试, 自动化, 请求拦截, 资产管理, 跌倒检测, 软件物料清单, 集中化