知识库

Maven插件【漏扫工具】：dependency-check-maven

12/31/2025 后端开发构建工具Maven

目录

参考

# Maven插件【漏扫工具】：dependency-check-maven

# OWASP Dependency-Check Maven插件详解

OWASP Dependency-Check Maven插件是一个用于识别项目依赖项中已知安全漏洞的开源工具，属于OWASP(Open Web Application Security Project)项目的一部分。以下是该插件的全面解析：

# 一、基本概念与功能

Dependency-Check Maven插件是一款软件成分分析(SCA)工具，主要用于：

  1. 漏洞检测：通过比对国家漏洞数据库(NVD)和其他漏洞数据库，识别项目中使用的第三方库的已知安全漏洞
  2. 多语言支持：支持Java、.NET、Ruby、Node.js、Python等多种语言项目，对C/C++构建系统(autoconf和cmake)也提供有限支持
  3. 报告生成：可生成HTML、XML、JSON等多种格式的详细报告，展示已检测到的漏洞及修复建议

# 二、工作原理

该插件通过以下流程进行依赖项安全检查：

  1. 数据源准备：首次执行时会从NIST托管的NVD数据库下载漏洞数据到本地(约需20分钟)，后续每7天自动更新
  2. 依赖项分析：扫描项目的pom.xml、jar包等，识别所有直接和传递依赖
  3. 漏洞匹配：通过CPE(Common Platform Enumeration)标识符将依赖项与漏洞数据库比对
  4. 结果报告：生成包含CVE编号、严重程度、受影响版本等信息的详细报告

# 三、核心使用方式

在Maven项目中，通过pom.xml配置即可使用：

# 基础配置

<plugin>
    <groupId>org.owasp</groupId>
    <artifactId>dependency-check-maven</artifactId>
    <version>10.0.3</version>
    <executions>
        <execution>
            <goals>
                <goal>check</goal>
            </goals>
        </execution>
    </executions>
</plugin>
1
2
3
4
5
6
7
8
9
10
11
12

执行命令：mvn dependency-check:check

# 高级配置选项

  1. 设置风险阈值：当CVSS分数≥8时使构建失败
<configuration>
    <failBuildOnCVSS>8</failBuildOnCVSS>
</configuration>
1
2
3
  1. 仅更新漏洞库
<executions>
    <execution>
        <goals>
            <goal>update-only</goal>
        </goals>
    </execution>
</executions>
1
2
3
4
5
6
7
  1. 多模块项目聚合报告
<goal>aggregate</goal>
1
  1. 自定义报告输出
<configuration>
    <format>HTML</format>
    <outputDirectory>${project.build.directory}/security-reports</outputDirectory>
</configuration>
1
2
3
4

# 四、与其他工具对比

特性 Dependency-Check 普通Maven Dependency插件
主要目的 安全漏洞检测 依赖关系分析
数据库支持 NVD等漏洞数据库 无外部数据库
输出内容 CVE漏洞详细信息 依赖使用情况
集成复杂度 中等 简单
适用阶段 安全审查 开发优化

# 五、最佳实践建议

  1. CI/CD集成：建议在Jenkins等CI工具中定期执行，可结合Analysis Model API和OWASP Dependency-Check插件
  2. SonarQube整合：将报告路径传递给SonarQube实现集中管理
  3. 误报处理：通过suppression文件过滤已知误报
  4. 执行频率：至少每周执行一次以确保漏洞数据库最新
  5. 多模块项目：使用aggregate目标生成统一报告

该插件是OWASP Top 10解决方案的重要组成部分，能有效帮助开发团队识别和管理第三方依赖的安全风险。

以下是配置和使用 dependency-check-maven 插件的详细步骤及说明，基于您提供的简化配置（仅包含插件坐标）和搜索结果的补充信息：

# 一、基础配置与使用

  1. 完整插件配置示例 在 pom.xml 的 <build><plugins> 中添加以下配置（需指定版本和基本参数）：

    <plugin>
    <groupId>org.owasp</groupId>
    <artifactId>dependency-check-maven</artifactId>
    <version>9.0.9</version>  <!-- 推荐最新稳定版 -->
    <configuration>
        <autoUpdate>true</autoUpdate>  <!-- 自动更新漏洞数据库 -->
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>check</goal>  <!-- 绑定到默认生命周期阶段 -->
            </goals>
        </execution>
    </executions>
</plugin>
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    • 关键参数：
      • autoUpdate：设为 true 时，每次检查会自动更新漏洞数据库（首次需下载约20分钟）。
      • failBuildOnCVSS：可设置为阈值（如 8），当发现高危漏洞时中断构建。

  2. 运行扫描

    • 命令：执行 mvn dependency-check:check，或在IDE中右键运行插件目标。
    • 输出：在 target 目录生成 dependency-check-report.html，包含漏洞详情和建议修复措施。

# 二、高级配置选项

  1. 多模块项目聚合报告 在父POM中配置：

    <plugin>
    <groupId>org.owasp</groupId>
    <artifactId>dependency-check-maven</artifactId>
    <version>9.0.9</version>
    <executions>
        <execution>
            <goals>
                <goal>aggregate</goal>  <!-- 生成聚合报告 -->
            </goals>
        </execution>
    </executions>
</plugin>
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    • 运行 mvn dependency-check:aggregate，报告会汇总所有子模块的依赖漏洞。

  2. 自定义报告格式与路径

    <configuration>
    <formats>HTML,JSON</formats>  <!-- 支持HTML/JSON/XML等 -->
    <outputDirectory>./reports</outputDirectory>  <!-- 自定义输出目录 -->
</configuration>
    1
    2
    3
    4
    • JSON/XML格式便于集成到CI工具（如Jenkins、SonarQube）。

  3. 漏洞数据库配置

    • 离线模式：设置 autoUpdate=false，并手动指定本地数据库路径：

      <configuration>
    <dataDirectory>/path/to/nvd-data</dataDirectory>
</configuration>
      1
      2
      3

    • API Key：申请NVD API Key以减少下载限制：

      <configuration>
    <nvdApiKey>your-api-key</nvdApiKey>
</configuration>
      1
      2
      3

# 三、常见问题解决

  1. 网络问题导致失败

    • 错误：Failed to initialize the RetireJS repo 或 SocketTimeoutException。
    • 解决方案：
      1. 手动下载 jsrepository.json 并放到本地Maven仓库的 dependency-check-data 目录。
      2. 配置Hosts解析 raw.githubusercontent.com 的IP。

  2. 证书错误

    • 若出现HTTPS证书验证失败，可通过生成证书并导入Java信任库解决（参考代码示例）。

  3. 误报抑制 创建 suppression.xml 文件忽略误报漏洞：

    <suppressions>
    <suppress>
        <cpe>cpe:/a:apache:log4j:1.2.17</cpe>  <!-- 忽略特定CPE -->
    </suppress>
</suppressions>
    1
    2
    3
    4
    5

    在插件中引用：

    <configuration>
    <suppressionFile>path/to/suppression.xml</suppressionFile>
</configuration>
    1
    2
    3

# 四、集成到CI/CD流程

  1. Jenkins集成

    • 安装 OWASP Dependency-Check Plugin，在流水线中添加扫描阶段：

      stage('Security Scan') {
    steps {
        dependencyCheck additionalArguments: '--format ALL', odcInstallation: 'Dependency-Check'
        dependencyCheckPublisher pattern: '**/dependency-check-report.xml'
    }
}
      1
      2
      3
      4
      5
      6

  2. SonarQube集成 在Sonar扫描命令中传递报告路径：

    mvn sonar:sonar -Dsonar.dependencyCheck.reportPath=target/dependency-check-report.xml
    1

# 五、总结

场景 配置/命令 输出
单项目扫描 mvn dependency-check:check HTML报告（target目录）
多模块聚合报告 mvn dependency-check:aggregate 聚合报告（父项目target目录）
CI/CD集成 Jenkins插件或SonarQube参数 可视化漏洞趋势与告警
离线扫描 配置 dataDirectory 和 autoUpdate 本地数据库支持的报告

完整参数参考：官方文档 (opens new window)。

以下是：dependency-check-maven插件如何配置才能只扫描特定的依赖项？

在 Maven 项目中，可以通过 dependency-check-maven 插件的配置来 限定扫描范围，只检查特定的依赖项。以下是具体配置方法和相关参数说明：

# 一、通过 <excludes> 排除不需要扫描的依赖

在插件配置中，使用 <excludes> 标签指定要跳过的依赖项（支持正则表达式或精确匹配）：

<plugin>
    <groupId>org.owasp</groupId>
    <artifactId>dependency-check-maven</artifactId>
    <version>9.0.9</version>
    <configuration>
        <excludes>
            <!-- 格式：groupId:artifactId:version（版本可选） -->
            <exclude>org.example:legacy-lib</exclude>  <!-- 排除指定artifact -->
            <exclude>com.old.*:*:1.0</exclude>         <!-- 通配符排除一组依赖 -->
        </excludes>
    </configuration>
</plugin>
1
2
3
4
5
6
7
8
9
10
11
12

效果：插件会跳过 org.example:legacy-lib 和所有 com.old 组下版本为 1.0 的依赖项。

# 二、通过 <skipProvidedScope> 跳过特定作用域的依赖

如果只想扫描实际打包的依赖（如 compile 范围），忽略 provided 或 test 范围的依赖：

<configuration>
    <skipProvidedScope>true</skipProvidedScope>  <!-- 跳过provided范围 -->
    <skipTestScope>true</skipTestScope>          <!-- 跳过test范围 -->
</configuration>
1
2
3
4

适用场景：例如，Tomcat 提供的 servlet-api（provided 范围）无需扫描。

# 三、通过 <suppressionFile> 抑制误报（间接限定扫描范围）

通过抑制文件忽略已知的误报依赖（即使它们被扫描，也不会出现在报告中）：

  1. 创建抑制文件（如 suppression.xml）：

    <suppressions>
    <suppress>
        <notes>忽略旧版本的log4j</notes>
        <gav regex="true">org\.apache\.logging\.log4j:.*:1\.2\.17</gav>
    </suppress>
</suppressions>
    1
    2
    3
    4
    5
    6

  2. 在插件中引用：

    <configuration>
    <suppressionFile>path/to/suppression.xml</suppressionFile>
</configuration>
    1
    2
    3

优势：支持正则匹配和更精细的漏洞抑制（如按CVE ID过滤）。

# 四、命令行临时指定扫描范围

如果仅需临时扫描特定依赖，可通过命令行参数动态指定：

mvn dependency-check:check -DdependencyCheck.includes=org.example:safe-lib
1

注意：此方式需插件版本 ≥ 7.0.0，且会覆盖POM中的配置。

# 五、结合 <dependency> 标签显式声明目标依赖

通过项目依赖配置间接控制扫描范围（推荐与上述方法联用）：

<dependencies>
    <!-- 只保留需要扫描的依赖 -->
    <dependency>
        <groupId>org.example</groupId>
        <artifactId>target-lib</artifactId>
        <version>1.0</version>
    </dependency>
</dependencies>
1
2
3
4
5
6
7
8

# 总结：选择合适的方法

方法 适用场景 灵活性 引用来源
<excludes> 精确排除特定依赖 高
<skipProvidedScope> 按作用域过滤（如跳过provided/test） 中
<suppressionFile> 复杂场景（如按CVE或正则匹配） 极高
命令行参数 临时调试或CI/CD动态调整 低

推荐组合： 日常开发中，建议使用 <excludes> + <suppressionFile> 组合，兼顾灵活性和可维护性。若需进一步优化扫描性能，可关闭不必要的分析器（如 .NET 或 JS 分析器）。

以下是：dependency-check-maven插件支持哪些自定义漏洞数据库？

dependency-check-maven 插件支持多种自定义漏洞数据库的集成，以下是其支持的主要数据源及配置方式：

# 一、官方默认支持的漏洞数据库

  1. NVD（National Vulnerability Database）

    • 美国国家漏洞数据库，插件默认从NIST镜像下载数据，支持自动更新。

    • 配置示例：

      <configuration>
    <autoUpdate>true</autoUpdate>  <!-- 默认启用NVD更新 -->
    <dataDirectory>/path/to/nvd-data</dataDirectory>  <!-- 自定义本地存储路径 -->
</configuration>
      1
      2
      3
      4

  2. NPM Public Advisories

    • 针对Node.js生态的漏洞库，自动集成到扫描中。

# 二、自定义或第三方漏洞数据库

  1. CNNVD（中国国家信息安全漏洞库）

    • 支持通过本地文件或API集成中文漏洞数据，需手动下载并转换为插件兼容格式（如JSON或XML）。

    • 配置步骤：

      • 从CNNVD官网下载漏洞数据文件。

      • 通过脚本将数据转换为NVD兼容格式，存放到本地目录。

      • 在插件中指定该目录为附加数据源：

        <configuration>
    <cveUrlBase>file:/path/to/cnnvd-json/</cveUrlBase>
</configuration>
        1
        2
        3

  2. 本地自建漏洞库

    • 使用工具如 nist-data-mirror.jar 同步NVD数据到本地数据库（如MySQL），再通过插件读取。

    • 示例：

      java -jar nist-data-mirror.jar /path/to/nvdcache  # 同步数据到本地
      1

  3. 企业私有漏洞库

    • 支持通过HTTP接口或文件系统集成私有漏洞数据，需符合NVD JSON格式。

# 三、其他扩展数据源

  1. RetireJS

    • 用于检测JavaScript库漏洞，需配置 jsrepository.json 文件路径：

      <configuration>
    <retireJsUrl>file:/path/to/jsrepository.json</retireJsUrl>
</configuration>
      1
      2
      3

  2. OSS Index

    • 需通过API Key访问，配置如下：

      <configuration>
    <ossIndexUsername>your-username</ossIndexUsername>
    <ossIndexToken>your-token</ossIndexToken>
</configuration>
      1
      2
      3
      4

# 四、关键配置参数

参数 作用 示例值
cveUrlBase 指定NVD或自定义漏洞库的URL/文件路径 file:/data/nvd/
cveUrlModified 增量更新的漏洞数据文件路径 file:/data/nvd/nvdcve-1.1-modified.json
retireJsUrl RetireJS数据库路径 file:/data/retirejs.json
suppressionFile 漏洞抑制文件（忽略误报） suppression.xml

# 五、注意事项

  1. NVD API Key

    • 若使用NVD官方数据源，建议申请API Key以加速更新（避免限速）：

      <configuration>
    <nvdApiKey>your-api-key</nvdApiKey>
</configuration>
      1
      2
      3

  2. 离线模式

    • 若网络受限，可完全禁用自动更新，仅依赖本地数据：

      <configuration>
    <autoUpdate>false</autoUpdate>
</configuration>
      1
      2
      3

  3. 多数据源优先级

    • 插件会按顺序合并多个数据源的结果，冲突时以NVD数据为准。

通过以上配置，用户可根据需求灵活集成企业私有或地区性漏洞数据库，增强扫描的覆盖率和准确性。详细参数见官方文档 (opens new window)。

以下是：dependency-check-maven插件支持哪些分析器？如何关闭不需要的分析器

dependency-check-maven 插件通过内置的多种分析器（Analyzers）来识别不同技术栈的依赖项及其漏洞。以下是支持的主要分析器类型及关闭不需要的分析器的配置方法：

# 一、支持的分析器类型

  1. 核心分析器
    • CPE Analyzer：匹配依赖项的 CPE（通用平台枚举）标识符，关联 NVD 漏洞数据。
    • CPE Suppression Analyzer：处理抑制文件中指定的 CPE 排除规则。
    • Central Analyzer：从 Maven Central 仓库获取依赖的元数据（如版本、发布日期）。
  2. 语言/技术特定分析器
    • Jar Analyzer：解析 Java JAR 文件的 Manifest、包名等证据。
    • Node.js Analyzer：扫描 package.json 和 node_modules 中的 npm 依赖。
    • Python Analyzer：检查 requirements.txt 或 setup.py 中的 Python 包。
    • Ruby Gemspec Analyzer：分析 Ruby 的 Gemfile.lock 或 .gemspec 文件。
    • .NET NuGet Analyzer：识别 NuGet 包依赖（如 packages.config）。
    • OSS Index Analyzer：通过 OSS Index API 查询漏洞（需配置 API Key）。
  3. 辅助分析器
    • Archive Analyzer：解压并扫描 ZIP、TAR 等压缩文件中的依赖。
    • Assembly Analyzer：分析 .NET 程序集（DLL）的元数据。
    • RetireJS Analyzer：检测 JavaScript 库的已知漏洞（基于 RetireJS 数据库）。

# 二、关闭不需要的分析器

在插件配置中通过 <disabledAnalyzer> 标签关闭特定分析器，例如：

<plugin>
    <groupId>org.owasp</groupId>
    <artifactId>dependency-check-maven</artifactId>
    <version>9.0.9</version>
    <configuration>
        <!-- 关闭非Java相关的分析器以提升扫描速度 -->
        <disabledAnalyzers>
            <analyzer>Node.js</analyzer>
            <analyzer>Python</analyzer>
            <analyzer>Ruby Gemspec</analyzer>
            <analyzer>NuGet</analyzer>
        </disabledAnalyzers>
    </configuration>
</plugin>
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 常用可关闭的分析器名称：

  • Node.js
  • Python
  • Ruby Gemspec
  • NuGet
  • RetireJS（若项目无前端代码）
  • Archive（若无需扫描压缩包）

# 三、高级配置建议

  1. 性能优化 对于纯 Java 项目，可仅保留 Jar、CPE 和 Central 分析器，关闭其他分析器以加速扫描。

  2. 动态排除结合 <skip> 参数按条件跳过分析（如跳过测试依赖）：

    <configuration>
    <skipTestScope>true</skipTestScope>
</configuration>
    1
    2
    3

  3. 自定义数据源 若使用私有漏洞库，可通过 <cveUrlBase> 指定本地路径或 API 端点。

# 四、完整分析器列表与作用

分析器名称 功能 适用场景
Jar 解析 Java JAR 文件 Java 项目必选
Node.js 扫描 npm 依赖 前端或全栈项目
OSS Index 查询 OSS Index 漏洞库 需额外 API Key
RetireJS 检测 JavaScript 漏洞 前端项目
Archive 解压并扫描压缩包内容 需检查嵌套依赖时启用

# 五、注意事项

  1. 首次运行延迟 关闭分析器后，首次扫描仍需下载基础漏洞数据库（如 NVD）。
  2. 误报风险 过度关闭分析器可能导致漏报，建议根据项目技术栈选择性禁用。

通过合理配置分析器，可以显著提升扫描效率并减少无关结果。更多参数参考官方文档 (opens new window)。

上次更新时间: 8/3/2025, 10:09:53 AM

Maven插件【版本发布】：maven-release-plugin