CycloneDX/cyclonedx-gradle-plugin
GitHub: CycloneDX/cyclonedx-gradle-plugin
CycloneDX 官方 Gradle 插件，用于从 Gradle 项目自动生成符合 CycloneDX 标准的软件物料清单（SBOM），覆盖直接和传递依赖的完整分析。
Stars: 221 | Forks: 94
# CycloneDX Gradle 插件
[](https://github.com/CycloneDX/cyclonedx-gradle-plugin/actions?workflow=Build+CI)
[](https://plugins.gradle.org/plugin/org.cyclonedx.bom)
[](LICENSE)
[](https://cyclonedx.org/)
[](https://cyclonedx.org/slack/invite)
[](https://groups.io/g/CycloneDX)
[](https://twitter.com/CycloneDX_Spec)
CycloneDX Gradle 插件会汇总项目的所有直接和传递依赖，
并生成有效的 CycloneDX SBOM。CycloneDX 是一个轻量级的软件物料清单
(SBOM) 规范，专为应用程序安全上下文和供应链组件分析而设计。
## 目录
- [功能特性](#features)
- [安装](#installation)
- [快速开始](#quick-start)
- [用法](#usage)
- [按项目生成 SBOM](#per-project-sbom-generation)
- [多项目聚合](#multi-project-aggregation)
- [结合初始化脚本使用](#usage-with-initialization-script)
- [配置](#configuration)
- [配置属性](#configuration-properties)
- [输出配置](#output-configuration)
- [高级配置](#advanced-configuration)
- [任务](#tasks)
- [示例](#examples)
- [Gradle 支持](#gradle-support)
- [CycloneDX Schema 支持](#cyclonedx-schema-support)
- [版权与许可](#copyright--license)
## 功能特性
- ✅ **按项目生成 SBOM**：为每个项目生成独立的 SBOM 文档
- ✅ **多项目聚合**：为整个项目层级创建统一的 SBOM
- ✅ **多种输出格式**：支持 JSON 和 XML 格式并符合 CycloneDX 规范
- ✅ **灵活配置**：包含/排除特定的依赖、配置和项目
- ✅ **元数据增强**：包含许可证信息、构建系统详情和组织数据
- ✅ **Gradle 集成**：原生 Gradle 任务集成，提供适当的增量构建支持
- ✅ **依赖分析**：分析所有直接和传递的已解析依赖（不仅仅是已声明的依赖）
## 安装
将此插件应用到您的项目中：
**Groovy DSL:**
```
plugins {
id 'org.cyclonedx.bom' version '3.2.4'
}
```
**Kotlin DSL:**
```
plugins {
id("org.cyclonedx.bom") version "3.2.4"
}
```
## 快速开始
1. 将此插件应用到您的根项目中
2. 运行 SBOM 生成任务：
```
# 生成每个项目的 SBOM
./gradlew cyclonedxDirectBom
# 生成聚合 SBOM（用于多项目构建）
./gradlew cyclonedxBom
```
3. 查找您的 SBOM 文件：
- 按项目：`build/reports/cyclonedx-direct/bom.{json,xml}`
- 已聚合：`build/reports/cyclonedx/bom.{json,xml}`
## 用法
### 按项目生成 SBOM
`cyclonedxDirectBom` 任务会为构建中的每个项目生成独立的 SBOM 文档。如果您希望
以更细粒度的级别分析依赖项，这将会非常有用。
```
# 生成所有项目的 SBOM
./gradlew cyclonedxDirectBom
# 使用 verbose 日志记录生成
./gradlew cyclonedxDirectBom --info
# 仅为特定项目生成
./gradlew :subproject:cyclonedxDirectBom
```
**输出位置：**
- JSON: `{project}/build/reports/cyclonedx-direct/bom.json`
- XML: `{project}/build/reports/cyclonedx-direct/bom.xml`
### 多项目聚合
`cyclonedxBom` 任务会创建一个包含构建中所有项目依赖的统一 SBOM。
这提供了应用程序供应链的完整视图。
```
# 生成聚合 SBOM
./gradlew cyclonedxBom
```
**输出位置：**
- JSON: `build/reports/cyclonedx/bom.json`
- XML: `build/reports/cyclonedx/bom.xml`
### 结合初始化脚本使用
无需修改项目的构建脚本即可使用此插件。这对于 CI/CD 流水线，或者您想为您不拥有或无法修改的项目生成 SBOM 时非常有用。
1. 创建一个名为 `init.gradle.kts` 的文件，内容如下：
```
import org.cyclonedx.gradle.CyclonedxPlugin
initscript {
repositories {
gradlePluginPortal()
}
dependencies {
classpath("org.cyclonedx.bom:org.cyclonedx.bom.gradle.plugin:3.2.4")
}
}
rootProject {
apply()
}
```
2. 使用 `--init-script` 参数运行 SBOM 生成任务：
```
./gradlew cyclonedxBom --init-script init.gradle.kts
```
## 配置
要配置 `cyclonedxDirectBom` 任务，您必须在每个项目中单独进行配置。要配置
`cyclonedxBom` 任务，您必须在放置该插件的项目（通常是根项目）中进行配置。
对于多项目构建，您还可以通过在根项目中使用 `allprojects` 或 `subprojects` 块配置
`cyclonedxDirectBom` 任务，来为所有项目设置通用配置选项。
```
allprojects {
tasks.cyclonedxDirectBom {
// Configuration properties here
}
}
tasks.cyclonedxBom {
// Configuration properties here
}
```
### 配置属性
#### `cyclonedxDirectBom`
| 属性 | 类型 | 默认值 | 描述 |
|----------------------------------|---------------------------|---------------------------|-------------------------------------------------------------------------------------|
| `includeConfigs` | `List` | `[]` (所有配置) | 包含在 SBOM 生成中的配置。支持正则表达式匹配 |
| `skipConfigs` | `List` | `[]` | 从 SBOM 生成中排除的配置。支持正则表达式匹配 |
| `projectType` | `Component.Type` | `"library"` | 项目类型 (`"application"`, `"library"`, `"framework"`, `"container"` 等) |
| `schemaVersion` | `SchemaVersion` | `VERSION_16` | 要使用的 CycloneDX schema 版本 |
| `includeBomSerialNumber` | `boolean` | `true` | 包含唯一的 BOM 序列号 |
| `includeLicenseText` | `boolean` | `false` | 在组件中包含完整的许可证文本 |
| `includeMetadataResolution` | `boolean` | `true` | 包含组件的完整元数据解析 |
| `includeBuildEnvironment` | `boolean` | `false` | 包含构建环境依赖（例如来自构建脚本的依赖） |
| `includeBuildSystem` | `boolean` | `true` | 包含来自 CI 环境的构建系统 URL |
| `buildSystemEnvironmentVariable` | `String` | - | 用于构建系统 URL 的自定义环境变量 |
| `componentVersion` | `String` | 项目版本 | 覆盖主组件版本 |
| `componentName` | `String` | 项目名称 | 覆盖主组件名称 |
| `componentGroup` | `String` | 项目组 | 覆盖主组件组 |
| `organizationalEntity` | `OrganizationalEntity` | - | 项目的组织元数据，包括名称、URL 和联系人 |
| `externalReferences` | `List` | Git remote URL | 项目的外部参考，例如文档或问题跟踪系统 |
| `licenseChoice` | `LicenseChoice` | - | 主组件的许可证信息 |
#### `cyclonedxBom`
| 属性 | 类型 | 默认值 | 描述 |
|----------------------------------|---------------------------|---------------------------|-------------------------------------------------------------------------------------|
| `projectType` | `Component.Type` | `"library"` | 项目类型 (`"application"`, `"library"`, `"framework"`, `"container"` 等) |
| `schemaVersion` | `SchemaVersion` | `VERSION_16` | 要使用的 CycloneDX schema 版本 |
| `includeBomSerialNumber` | `boolean` | `true` | 包含唯一的 BOM 序列号 |
| `includeLicenseText` | `boolean` | `false` | 在组件中包含完整的许可证文本 |
| `includeBuildSystem` | `boolean` | `true` | 包含来自 CI 环境的构建系统 URL |
| `buildSystemEnvironmentVariable` | `String` | - | 用于构建系统 URL 的自定义环境变量 |
| `componentVersion` | `String` | 项目版本 | 覆盖主组件版本 |
| `componentName` | `String` | 项目名称 | 覆盖主组件名称 |
| `componentGroup` | `String` | 项目组 | 覆盖主组件组 |
| `organizationalEntity` | `OrganizationalEntity` | - | 项目的组织元数据，包括名称、URL 和联系人 |
| `externalReferences` | `List` | Git remote URL | 项目的外部参考，例如文档或问题跟踪系统 |
| `licenseChoice` | `LicenseChoice` | - | 主组件的许可证信息 |
### 输出配置
使用每个任务的显式属性配置输出文件。该插件支持同时或单独输出 JSON 和 XML 格式：
```
allprojects {
tasks.cyclonedxDirectBom {
// Configure JSON output (default: build/reports/cyclonedx/bom.json)
jsonOutput.set(file("build/reports/cyclonedx/${project.name}-bom.json"))
// Configure XML output (default: build/reports/cyclonedx/bom.xml)
xmlOutput.set(file("build/reports/cyclonedx/${project.name}-bom.xml"))
}
tasks.cyclonedxBom {
// Configure JSON output (default: build/reports/cyclonedx-aggregate/bom.json)
jsonOutput.set(file("build/reports/cyclonedx-aggregate/${project.name}-bom.json"))
// Configure XML output (default: build/reports/cyclonedx-aggregate/bom.xml)
xmlOutput.set(file("build/reports/cyclonedx-aggregate/${project.name}-bom.xml"))
}
}
```
#### 禁用输出格式
要仅生成一种格式，您可以通过取消设置其约定来禁用另一种格式：
```
tasks.cyclonedxDirectBom {
// Generate only JSON format
xmlOutput.unsetConvention()
// Or generate only XML format
jsonOutput.unsetConvention()
}
tasks.cyclonedxBom {
// Generate only JSON format
xmlOutput.unsetConvention()
// Or generate only XML format
jsonOutput.unsetConvention()
}
```
### 高级配置
#### 完整配置示例
```
tasks.cyclonedxDirectBom {
// Include only runtime dependencies
includeConfigs = ["runtimeClasspath", "compileClasspath"]
// Exclude all test-related configurations using regex
skipConfigs = [".*test.*", ".*Test.*"]
// Set application metadata
projectType = "application"
componentName = "my-microservice"
componentVersion = "2.0.0-SNAPSHOT"
// Schema configuration
schemaVersion = org.cyclonedx.model.schema.SchemaVersion.VERSION_16
// Metadata options
includeBomSerialNumber = true
includeLicenseText = true
includeMetadataResolution = true
includeBuildEnvironment = false
includeBuildSystem = true
// Custom build system URL template
buildSystemEnvironmentVariable = '${CI_PIPELINE_URL}/jobs/${CI_JOB_ID}'
// Custom output locations
jsonOutput = file("build/reports/sbom/${project.name}-sbom.json")
xmlOutput = file("build/reports/sbom/${project.name}-sbom.xml")
}
```
#### 从聚合中排除项目
要从 SBOM 生成中排除特定项目（包括直接和聚合任务），请禁用该任务：
```
subprojects {
tasks.cyclonedxDirectBom.enabled = false // Skip SBOM generation for this project
}
// Or in a specific project's build.gradle.kts:
tasks.cyclonedxDirectBom.enabled = false
```
## 任务
| 任务 | 描述 | 范围 | 类型 | 输出位置 |
|----------------------|---------------------------------------------|--------------------------|--------------------------|-----------------------------------|
| `cyclonedxDirectBom` | 为每个项目生成 SBOM 文档 | 单个项目 | `CyclonedxDirectTask` | `build/reports/cyclonedx-direct/` |
| `cyclonedxBom` | 为多项目构建生成聚合的 SBOM | 整个项目层级 | `CyclonedxAggregateTask` | `build/reports/cyclonedx/` |
这两个任务均支持：
- 增量构建
- 并行执行
- 配置缓存
- 构建缓存
## 示例
#### 简单的 Java 应用程序
```
plugins {
id("org.cyclonedx.bom") version "3.2.4"
id("application")
}
tasks.cyclonedxDirectBom {
projectType = "application"
includeConfigs = listOf("runtimeClasspath")
}
```
#### 带过滤的多项目构建
根 `/build.gradle.kts`:
```
plugins {
id("org.cyclonedx.bom") version "3.2.4"
}
allprojects {
tasks.cyclonedxDirectBom {
// Include only production dependencies
includeConfigs = listOf("runtimeClasspath", "compileClasspath")
skipConfigs = listOf("testRuntimeClasspath", "testCompileClasspath")
// Application metadata
projectType = "application"
componentGroup = "com.example"
// Enable build system tracking
includeBuildSystem = true
}
}
tasks.cyclonedxBom {
// Aggregated SBOM configuration
projectType = "application"
componentName = "my-enterprise-app"
componentVersion = "1.0.0"
includeBuildSystem = true
}
```
子项目 `/test-utils/build.gradle.kts`:
```
// Disable SBOM generation for test utility projects
tasks.cyclonedxDirectBom.enabled = false
```
#### 组织实体
```
import org.cyclonedx.model.*
import org.cyclonedx.model.schema.*
plugins {
id("org.cyclonedx.bom") version "3.2.4"
id("java")
}
tasks.cyclonedxDirectBom {
// Project configuration
projectType = "application"
schemaVersion = SchemaVersion.VERSION_16
// Component details
componentName = "acme-payment-service"
componentVersion = "3.2.4"
// Dependency filtering
includeConfigs = listOf("runtimeClasspath", "compileClasspath")
skipConfigs = listOf(".*test.*", ".*benchmark.*")
// Metadata options
includeBomSerialNumber = true
includeLicenseText = true
includeMetadataResolution = true
includeBuildSystem = true
buildSystemEnvironmentVariable = "\${BUILD_URL}"
// Organizational metadata
organizationalEntity = OrganizationalEntity().apply {
name = "ACME Corporation"
urls = listOf("https://www.acme.com", "https://security.acme.com")
addContact(OrganizationalContact().apply {
name = "Security Team"
email = "security@acme.com"
phone = "+1-555-SECURITY"
})
}
}
```
#### 外部参考示例
```
import org.cyclonedx.model.*
plugins {
id("org.cyclonedx.bom") version "3.2.4"
id("java")
}
tasks.cyclonedxDirectBom {
externalReferences = listOf(
ExternalReference().apply {
url = "https://cyclonedx.org/"
type = ExternalReference.Type.WEBSITE
}
)
}
```
#### 许可证示例
```
import org.cyclonedx.model.*
plugins {
id("org.cyclonedx.bom") version "3.2.4"
id("java")
}
tasks.cyclonedxDirectBom {
// Specify licenses for the main component
licenseChoice = LicenseChoice().apply {
addLicense(License().apply {
name = "Apache-2.0"
url = "https://www.apache.org/licenses/LICENSE-2.0.txt"
})
}
}
```
#### CI 元数据示例
```
plugins {
id("org.cyclonedx.bom") version "3.2.4"
id("java")
}
tasks.cyclonedxDirectBom {
projectType = "application"
// Dynamic versioning for CI/CD
componentVersion = System.getenv("BUILD_VERSION") ?: project.version.toString()
// Build system integration
includeBuildSystem = true
buildSystemEnvironmentVariable = "\${BUILD_URL}"
// Conditional configuration based on environment
if (System.getenv("CI") == "true") {
// CI environment - include all runtime dependencies
includeConfigs = listOf("runtimeClasspath", "compileClasspath")
skipConfigs = listOf("testRuntimeClasspath")
} else {
// Local development - lighter analysis
includeConfigs = listOf("runtimeClasspath")
}
}
tasks.cyclonedxBom {
// Timestamped output artifacts (WARNING: will disable Gradle cache)
jsonOutput = file("build/artifacts/sbom-${Instant.now()}.json")
xmlOutput.unsetConvention()
}
```
有关详细的元数据结构信息，请参阅
[CycloneDX 规范](https://cyclonedx.org/docs/1.6/json/#metadata)。
## Gradle 支持
下表提供了有关此 Gradle 插件的版本以及所支持的 Gradle 版本的信息。
| 版本 | Gradle 版本 |
|---------|----------------|
| 3.0.x | Gradle 8.4+ |
| 2.x.x | Gradle 8.0+ |
| 1.x.x | Gradle <8.0 |
## CycloneDX Schema 支持
下表提供了有关此 Gradle 插件的版本、所支持的 CycloneDX schema 版本
以及输出格式选项的信息。请使用与目标系统支持的 CycloneDX 版本兼容的
本插件最新版本。
| 版本 | Schema 版本 | 格式 |
|---------|----------------|-----------|
| 3.x.x | CycloneDX v1.6 | XML/JSON |
| 2.x.x | CycloneDX v1.6 | XML/JSON |
| 1.10.x | CycloneDX v1.6 | XML/JSON |
| 1.9.x | CycloneDX v1.6 | XML/JSON |
| 1.8.x | CycloneDX v1.5 | XML/JSON |
| 1.7.x | CycloneDX v1.4 | XML/JSON |
| 1.6.x | CycloneDX v1.4 | XML/JSON |
| 1.5.x | CycloneDX v1.3 | XML/JSON |
| 1.4.x | CycloneDX v1.3 | XML/JSON |
| 1.2.x | CycloneDX v1.2 | XML/JSON |
| 1.1.x | CycloneDX v1.1 | XML |
| 1.0x | CycloneDX v1.0 | XML |
## 版权与许可
CycloneDX Gradle 插件的版权归 (c) OWASP Foundation 所有。保留所有权利。
在 Apache 2.0 许可证的条款下授予修改和重新分发的权限。有关完整的许可证内容，请参见 [LICENSE] 文件。
标签：CycloneDX, GPT, Gradle插件, JS文件枚举, SBOM, WebSocket, 人工智能安全, 传递依赖, 依赖分析, 合规性, 后台面板检测, 域名枚举, 开源组件管理, 漏洞管理, 硬件无关, 组件分析, 跌倒检测, 软件物料清单