Niki-1337/secure-build-maven-extension

# Secure Build Maven Extension 用于 Java 安全分析工作流的 Maven 核心扩展。它会自动将通用的安全和质量插件注入到 Maven 构建中，从而让应用仓库自身的 `pom.xml` 文件变得更精简、更一致。 ## 它配置了什么 - 针对单模块和多模块构建的 SonarQube 扫描器属性。 - 用于生成 SCA 报告的 OWASP Dependency-Check 执行配置。 - CycloneDX SBOM 生成。 - JaCoCo 覆盖率报告。 - 用于 SonarQube 的 GitLab CI 分支和合并请求元数据。 - 针对大型多模块项目的可选模块过滤。 ## 要求 - Java 17+ - Maven 3.9+ - 运行 SonarQube 分析时需要 SonarQube 服务器和令牌 - 需要互联网访问或内部 Maven 代理来解析插件依赖 ## 本地构建 ``` ./mvnw clean package ``` 安装到本地 Maven 缓存： ``` ./mvnw clean install ``` ## 为什么不直接使用原生 CI/CD？ 你可以直接在 CI/CD YAML 中配置 SonarQube、Dependency-Check、CycloneDX 和覆盖率。这对于单一仓库是可行的，但很难在多个服务之间保持一致性。此扩展将安全构建逻辑移入一个带版本控制的 Maven 扩展中，而不是在每个流水线中重复编写。 与原生 CI/CD 脚本相比，此方法为你带来以下优势： - 为安全扫描行为提供一个单一且带版本控制的信息源。 - 减少各个服务仓库中重复的 YAML 配置。 - 在本地和 CI/CD 中使用相同的 Maven goals，以便开发人员在推送前运行检查。 - 统一 SAST、SCA、SBOM 和覆盖率输出的报告位置和格式。 - 内置对单模块和多模块的处理。 - 集中管理排除项、分支命名、基线分支检测以及受保护分支护栏的默认设置。 - 通过发布新版本的扩展来更轻松地推广扫描器升级，而无需修改每条流水线。 - 在 GitLab CI、GitHub Actions、Jenkins 和本地开发机器之间具有更好的可移植性。 CI/CD 仍然负责执行把关。该扩展使构建时的安全逻辑保持可重用、可测试且更易于演进。 ## 示例 可在 [`examples`](./examples) 中查看可运行的示例： | 示例 | 目的 | | --- | --- | | [`examples/single-module`](./examples/single-module) | 使用此 Maven 扩展的最小化 Java 服务 | | [`examples/multi-module`](./examples/multi-module) | 用于多模块 Java 构建的父 POM 设置 | 首先将扩展安装到你的本地 Maven 仓库： ``` ./mvnw clean install ``` 然后运行示例： ``` cd examples/single-module ../../mvnw -Dmaven.multiModuleProjectDirectory="$PWD" clean package cd ../multi-module ../../mvnw -Dmaven.multiModuleProjectDirectory="$PWD" clean package ``` 仅当从嵌套的示例目录使用仓库根目录的 Maven Wrapper 时，才需要 `maven.multiModuleProjectDirectory` 标志。它会让 Maven 加载示例自身的 `.mvn/extensions.xml`。如果你在示例目录中运行已安装的 `mvn`，只需执行 `mvn clean package` 即可。 ## 在其他 Maven 项目中使用 安装或发布该扩展工件，然后将其添加到目标项目的 `.mvn/extensions.xml` 中： ``` io.github.niki1337.securebuild secure-maven-extension 0.1.0 ``` 运行标准的 Maven goals。该扩展会在读取项目后配置安全插件： ``` mvn verify mvn sonar:sonar ``` ## 配置 该扩展首先读取环境变量，然后是 Maven 用户属性（`-D...`）、项目属性和系统属性。 | 环境变量 | Maven 属性 | 目的 | | --- | --- | --- | | `SERVICE_NAME` | `secure.serviceName` | 用于报告和 SBOM 输出的服务名称 | | `DT_API_URL` | `dt.api.url` | Dependency-Track API URL，用作可选的 NVD 镜像源 | | `SONAR_HOST_URL` | `sonar.host.url` | SonarQube 服务器 URL | | `SONAR_PROJECT_KEY` | `sonar.projectKey` | SonarQube 项目密钥 | | `SONAR_PROJECT_NAME` | `sonar.projectName` | SonarQube 项目名称 | | `SONAR_TOKEN` | `sonar.token` | SonarQube 分析令牌 | | `SONAR_REFERENCE_BRANCH` | `sonar.referenceBranch` | 显式的新代码参考分支 | | `SONAR_BASELINE_BRANCH` | `sonar.baselineBranch` | 备选的新代码参考分支 | | `SONAR_BASELINE_REMOTE` | `sonar.baselineRemote` | 用于基线自动检测的远程仓库，默认为 `origin` | 其他 Maven 属性： | 属性 | 目的 | | --- | --- | | `secure.allowLocalSonar` | 设置为 `true` 时允许本地 SonarQube 分析 | | `secure.forceSimpleMode` | 强制使用单模块行为 | | `secure.includedModules` | 以逗号分隔的模块白名单 | | `secure.excludedModules` | 以逗号分隔的模块黑名单 | | `secure.sonarExclusions` | 覆盖 SonarQube 源码排除项 | | `secure.sonarTestExclusions` | 覆盖 SonarQube 测试排除项 | | `secure.sonarCpdExclusions` | 覆盖 SonarQube 重复代码排除项 | | `secure.sonarCoverageExclusions` | 覆盖 SonarQube 覆盖率排除项 | | `secure.enableRetireJs` | 启用 Dependency-Check RetireJS 分析器 | | `secure.enableKnownExploited` | 启用 Dependency-Check KEV 分析器 | | `secure.enableHostedSuppressions` | 启用 Dependency-Check 托管抑制 | 示例： ``` SONAR_HOST_URL=https://sonarqube.example.com \ SONAR_PROJECT_KEY=my-service \ SONAR_TOKEN=token-value \ mvn verify sonar:sonar -Dsecure.allowLocalSonar=true ``` ## 多模块行为 对于多模块项目，该扩展会执行以下操作： - 在根项目上配置 SonarQube 属性。 - 为 Java 模块添加 JaCoCo 和模块级的 SonarQube 属性。 - 在根项目上运行聚合 Dependency-Check。 - 当存在 Spring Boot 模块时，从中生成 CycloneDX 输出，否则回退到聚合 SBOM 生成。 使用 `secure.includedModules` 和 `secure.excludedModules` 可以缩小大型构建的范围。 ## 许可证 Apache License 2.0。详见 [LICENSE](./LICENSE)。

标签：AppSec, CycloneDX, DevSecOps, GHAS, GitHub Actions, GitLab CI, JaCoCo, Java 17, Java安全, Jenkins, JS文件枚举, Maven扩展, OWASP Dependency-Check, SAST, SBOM, SonarQube, 上游代理, 人体姿态估计, 代码覆盖率, 域名枚举, 多模块构建, 安全构建, 开源框架, 持续集成, 数据集, 盲注攻击, 硬件无关, 自动笔记, 错误基检测, 静态代码分析