Niki-1337/secure-build-gradle-plugin
GitHub: Niki-1337/secure-build-gradle-plugin
将 Java 项目常见的安全构建检查（SAST、SCA、SBOM、覆盖率）封装为可复用的 Gradle 约定插件，解决多服务仓库间安全扫描配置重复和不一致的问题。
Stars: 1 | Forks: 0
# Secure Build Gradle 插件
用于 Java 安全分析工作流的 Gradle 约定插件。它将常见的应用程序安全检查整合到可重复的本地和 CI/CD 流程中，而无需每个服务存储库都复制相同的 Gradle 配置。
## 它配置了什么
- 针对单模块和多模块 Java 项目的 SonarQube 分析。
- 用于 SCA 和依赖项漏洞报告的 OWASP Dependency-Check。
- CycloneDX SBOM 生成。
- JaCoCo 覆盖率报告，以及对 Kotlin 项目的 Kover 检测。
- 用于 SonarQube 的 GitLab CI 分支和合并请求元数据。
- 受保护发布分支的本地扫描防护机制。
## 要求
- Java 17+
- Gradle 8+
- 运行 SonarQube 分析时需要 SonarQube 服务器和令牌
- 需要访问互联网或内部 Maven 代理来解析插件依赖项
## 本地构建
```
./gradlew clean build
```
发布到你的本地 Maven 缓存：
```
./gradlew publishToMavenLocal
```
## 为什么不直接使用原生 CI/CD？
你可以直接在 CI/CD YAML 中接入 SonarQube、Dependency-Check、CycloneDX 和覆盖率工具。这对于单个存储库是可行的，但很难在众多服务之间保持一致性。此插件将安全构建逻辑转移到版本化的 Gradle 约定中，而不是在每个流水线中重复编写。
与原生 CI/CD 脚本相比，这种方法为你提供了：
- 安全扫描行为的单一版本化事实来源。
- 减少了服务存储库中重复的 YAML。
- 本地和 CI/CD 中运行的任务相同，因此开发者可以在推送之前运行检查。
- SAST、SCA、SBOM 和覆盖率输出具有一致的报告位置和格式。
- 内置的单模块和多模块处理机制。
- 集中管理排除项、分支命名、基线分支检测和受保护分支防护的默认配置。
- 通过发布新的插件版本更轻松地推出扫描器升级，而无需修改每个流水线。
- 在 GitLab CI、GitHub Actions、Jenkins 和本地开发者机器之间具有更好的可移植性。
CI/CD 仍然负责执行关卡。该插件使构建时的安全逻辑可重用、可测试，并且更易于演进。
## 示例
可运行的示例可在 [`examples`](./examples) 中找到：
| 示例 | 目的 |
| --- | --- |
| [`examples/single-module`](./examples/single-module) | 使用此仓库中插件的最小化 Java 服务 |
| [`examples/multi-module`](./examples/multi-module) | 多模块 Java 构建的根级别插件设置 |
运行轻量级的冒烟测试：
```
./gradlew -p examples/single-module clean build --no-daemon
./gradlew -p examples/multi-module clean build --no-daemon
```
## 在其他 Gradle 项目中使用
在本地发布后，将插件存储库添加到目标项目的 `settings.gradle` 中：
```
pluginManagement {
repositories {
mavenLocal()
gradlePluginPortal()
mavenCentral()
}
}
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
mavenLocal()
mavenCentral()
}
}
```
在根目录的 `build.gradle` 中应用该插件：
```
plugins {
id "java"
id "io.github.niki1337.securebuild.gradle-java" version "0.1.0"
}
```
对于多模块项目，只需在根构建文件中应用即可。该插件会检测 Java 子项目，并配置模块感知的 SonarQube、JaCoCo、Dependency-Check 和 SBOM 任务。
## 配置
```
securityConventions {
serviceName = "payments-api"
sonarHostUrl = "https://sonarqube.example.com"
sonarProjectKey = "payments-api"
sonarProjectName = "Payments API"
baselineBranch = "main"
dtApiUrl = "https://dependency-track.example.com"
includedModules = ["api", "service"]
excludedModules = ["generated-client"]
allowLocalSonar = false
coverageProvider = "auto"
enableRetireJs = false
enableKnownExploited = false
enableHostedSuppressions = false
}
```
支持的环境变量：
| 变量 | 目的 |
| --- | --- |
| `SONAR_HOST_URL` | SonarQube 服务器 URL |
| `SONAR_PROJECT_KEY` | SonarQube 项目密钥 |
| `SONAR_PROJECT_NAME` | SonarQube 项目名称 |
| `SONAR_TOKEN` | SonarQube 分析令牌 |
| `SONAR_REFERENCE_BRANCH` | 显式 New Code 参考分支 |
| `SONAR_BASELINE_BRANCH` | 备用 New Code 参考分支变量 |
| `SONAR_BASELINE_REMOTE` | 用于基线自动检测的远程仓库，默认为 `origin` |
| `DT_API_URL` | Dependency-Track API URL，用作可选的 NVD 镜像源 |
| `NEXUS_MAVEN_PUBLIC_URL` | 用于隔离 CI 环境的可选 Maven 代理 |
| `NEXUS_USER` / `NEXUS_USERNAME` | 可选 Maven 代理用户名 |
| `NEXUS_PASS` / `NEXUS_PASSWORD` | 可选 Maven 代理密码 |
也支持使用匹配的驼峰命名形式的 Gradle 属性，例如 `sonarHostUrl`、`sonarProjectKey`、`sonarToken`、`baselineBranch` 和 `dtApiUrl`。
## 任务
| 任务 | 描述 |
| --- | --- |
| `sonar` | 当令牌和分支规则允许时运行 SonarQube 分析 |
| `sonarHelp` | 打印本地 SonarQube 运行说明 |
| `dependencyCheckAnalyze` | 在单模块项目中运行 OWASP Dependency-Check |
| `dependencyCheckAggregate` | 在多模块项目中运行聚合 Dependency-Check |
| `cyclonedxBom` / `cyclonedxDirectBom` | 生成 CycloneDX SBOM 输出 |
| `securityAnalyze` | 运行可用的安全分析任务 |
报告将写入 `build/reports/` 目录下。
## 本地 SonarQube 运行
本地 SonarQube 分析是选择性启用的。可以使用命令行标志：
```
SONAR_HOST_URL=https://sonarqube.example.com \
SONAR_PROJECT_KEY=my-service \
SONAR_TOKEN=token-value \
./gradlew sonar -PsonarLocal
```
或者通过扩展配置启用：
```
securityConventions {
allowLocalSonar = true
}
```
默认情况下，本地分析在 `staging` 和 `release/*` 分支上会被阻止。CI 流水线仍然可以在这些分支上运行分析。
## 基线分支选择
该插件按以下顺序选择 SonarQube New Code 参考分支：
1. `securityConventions.baselineBranch`
2. `SONAR_REFERENCE_BRANCH`
3. `SONAR_BASELINE_BRANCH`
4. `baselineBranch` 或 `sonarBaselineBranch` Gradle 属性
5. 从 `staging`、`dev`、`develop`、`main`、`master` 自动检测
## 发布
发布到 Maven Local：
```
./gradlew publishToMavenLocal
```
发布到私有 Maven 仓库：
```
NEXUS_URL=https://repo.example.com/repository/releases \
NEXUS_USER=username \
NEXUS_PASS=password \
./gradlew publish
```
只能通过 CI/CD 变量或本地密钥存储来使用仓库凭据。请勿提交凭据。
## 许可证
Apache License 2.0。请参阅 [LICENSE](./LICENSE)。
标签：CycloneDX, DevSecOps, GHAS, GitHub Actions, GitLab CI, Gradle插件, JaCoCo, Java安全, Jenkins, JS文件枚举, Kotlin, SAST, SBOM生成, SonarQube, 上游代理, 人体姿态估计, 代码覆盖率, 分支保护, 后台面板检测, 安全基线, 安全工具链, 安全扫描, 教学环境, 数据集, 时序注入, 构建安全, 盲注攻击, 自动笔记, 静态应用安全测试