Dependency-Check

Dependency-Check 是一个软件成分分析（SCA）工具，旨在检测项目依赖项中已公开披露的漏洞。它通过判断给定依赖项是否存在通用平台枚举（CPE）标识符来实现这一点。如果找到，它将生成一份报告，链接到相关的 CVE 条目。

文档以及生产二进制版本的链接可以在 GitHub Pages 上找到。此外，关于架构以及扩展 dependency-check 的方法的更多信息可以在 wiki 上找到。

声明

本产品使用 NVD API，但未经 NVD 认可或认证。

必须升级到 12.1.0+

由于 NVD API 的兼容性更改，升级是强制性的。有关更多信息，请参阅 #7463。

11.0.0 中的破坏性变更

运行 dependency-check 11.0.0 或更高版本现在需要 Java 11
H2 数据库升级

11.0.0 包含使用本地 H2 数据库的破坏性变更。将执行一次 NVD 数据的完整下载。请注意，如果您使用共享数据目录，h2 数据库文件与旧版本的 dependency-check 不兼容。如果遇到问题，您可能需要运行 purge：
- gradle：./gradlew dependencyCheckPurge
- maven：mvn org.owasp:dependency-check-maven:11.0.0:purge
- cli：dependency-check.sh --purge

其他声明

强烈建议使用 NVD API 密钥

自 9.0.0+（2024 年 1 月）起，dependency-check 已从使用 NVD data-feed 迁移到 NVD API。强烈鼓励 dependency-check 用户获取 NVD API 密钥；请参阅 https://nvd.nist.gov/developers/request-an-api-key 如果没有 NVD API 密钥，dependency-check 的更新将极其缓慢。有关如何设置 NVD API 密钥，请参阅 cli、maven、gradle 或 ant 集成的文档。

NVD API 密钥、CI 与速率限制

NVD API 已强制执行速率限制。如果您使用单个 API 密钥且发生多次构建，则可能会达到速率限制并收到 403 错误。在 CI 环境中，必须使用缓存策略。

Sonatype OSS Index 强制身份验证及迁移至 Sonatype Guide

2025 年 9 月，Sonatype OSS Index 开始强制使用 API 令牌进行身份验证。2026 年 4 月，随后开始了向 Sonatype Guide 的迁移，启动了使用 Sonatype Guide API 令牌的过渡，这些令牌计划在 2026 年底前取代传统的 OSS Index API 密钥/令牌。

如果没有凭据，Dependency Check 将自动禁用 OSS Index 分析器。有关如何设置分析器凭据以使用 Sonatype Guide 令牌或传统 OSS Index API 密钥，请参阅 CLI、Maven、Gradle 或 Ant 集成的文档。

如果您希望使用 Sonatype OSS Index（通过 Guide），则必须配置 Dependency-Check，并考虑迁移到 Sonatype Guide 的影响；其商业/使用模式已发生变化。有关更多信息，请参阅分析器文档。

Gradle 构建环境

使用 9.0.0+ 时，用户可能会遇到因依赖解析导致的 NoSuchMethodError 异常问题。如果遇到此问题，您需要将 dependency-check 的部分传递依赖固定到特定版本。例如：

/buildSrc/build.gradle

dependencies {
    constraints {
        // org.owasp.dependencycheck needs at least this version of jackson. Other plugins pull in older versions..
        add("implementation", "com.fasterxml.jackson:jackson-bom:2.21.2")

        // org.owasp.dependencycheck needs these versions. Other plugins pull in older versions..
        add("implementation", "org.apache.commons:commons-lang3:3.20.0")
        add("implementation", "org.apache.commons:commons-text:1.15.0")
    }
}

要求

Java 版本

最低 Java 版本：Java 11

互联网访问

OWASP dependency-check 需要访问多个外部托管的资源。有关更多信息，请参阅需要互联网访问。

构建工具

为了分析某些技术栈，dependency-check 可能需要安装其他开发工具。下面列出的一些分析可能是实验性的，需要启用实验性分析器。

要分析 .NET 程序集，必须安装 dotnet 8 运行时或 SDK。
- 可以分析针对其他运行时的程序集 - 但运行分析需要 8。
如果分析 GoLang 项目，必须安装 go。
分析 Elixir 项目需要 mix_audit。
分析 npm、pnpm 和 yarn 项目需要安装 npm、pnpm 或 yarn。
- 所执行的分析利用各自相应的 audit 功能。
对 Ruby 的分析是围绕 bundle-audit 的封装，因此必须安装 bundle-audit。

当前版本

Jenkins 插件

有关 Jenkins 插件使用说明，请参阅 OWASP Dependency-Check 插件页面。

命令行

更详细的说明可以在 dependency-check GitHub Pages 上找到。最新的 CLI 可以从 GitHub 的 Releases 部分下载。

下载最新版本：

$ VERSION=$(curl -s https://dependency-check.github.io/DependencyCheck/current.txt)
$ curl -Ls "https://github.com/dependency-check/DependencyCheck/releases/download/v$VERSION/dependency-check-$VERSION-release.zip" --output dependency-check.zip

在 *nix 上

$ ./bin/dependency-check.sh -h
$ ./bin/dependency-check.sh --out . --scan [path to jar files to be scanned]

在 Windows 上

> .\bin\dependency-check.bat -h
> .\bin\dependency-check.bat --out . --scan [path to jar files to be scanned]

在 Mac 上使用 Homebrew 注意 - 从 5.x 升级到 6.0.0 的 homebrew 用户需要运行 dependency-check.sh --purge。

$ brew update && brew install dependency-check
$ dependency-check -h
$ dependency-check --out . --scan [path to jar files to be scanned]

Maven 插件

更详细的说明可以在 dependency-check-maven GitHub Pages 上找到。默认情况下，该插件绑定到 verify 阶段（即 mvn verify）。或者，也可以通过 mvn org.owasp:dependency-check-maven:check 直接调用该插件。

dependency-check 插件可以通过以下方式进行配置：

<project>
    <build>
        <plugins>
            ...
            <plugin>
              <groupId>org.owasp</groupId>
              <artifactId>dependency-check-maven</artifactId>
              <executions>
                  <execution>
                      <goals>
                          <goal>check</goal>
                      </goals>
                  </execution>
              </executions>
            </plugin>
            ...
        </plugins>
        ...
    </build>
    ...
</project>

Gradle 插件

有关 Gradle 插件使用说明，请参阅 dependency-check-gradle GitHub 页面。

Ant 任务

有关 Ant 任务使用说明，请参阅 dependency-check-ant GitHub 页面。

开发先决条件

要成功安装，您必须安装以下组件：

Java：java -version 25.0
Maven：mvn -version 3.6.3 及更高版本

测试用例需要：

dotnet core 版本 8.0
Go：go version 1.12 及更高版本
Ruby bundler-audit
Yarn
pnpm

开发用法

以下说明概述了如何编译和使用当前的快照版本。尽管我们尽可能保持快照的稳定，但仍建议使用上面列出的发布版本。

由于测试资源的原因，该仓库包含一些大文件。团队已尽可能清理提交历史。不过，建议您执行浅克隆以节省时间：

git clone --depth 1 https://github.com/dependency-check/DependencyCheck.git

在 *nix 上

$ mvn -s settings.xml install
$ ./cli/target/release/bin/dependency-check.sh -h
$ ./cli/target/release/bin/dependency-check.sh --out . --scan ./src/test/resources

在 Windows 上

> mvn -s settings.xml install
> .\cli\target\release\bin\dependency-check.bat -h
> .\cli\target\release\bin\dependency-check.bat --out . --scan ./src/test/resources

然后将生成的 'dependency-check-report.html' 加载到您常用的浏览器中。

不运行测试进行构建

为了加快迭代周期，您也可以每次不运行测试就进行编译：
mvn -s settings.xml install -DskipTests=true

请记住在提交 PR 之前至少运行一次测试。:)

IntelliJ Idea

为了能够在 IntelliJ Idea 中调试测试，您可以引入一个 Maven 配置来执行测试并启用断点等调试功能。
基本上，您按照 https://www.jetbrains.com/help/idea/work-with-tests-in-maven.html#run_single_test 中描述的操作，并将 forkCount 设置为 0，否则调试将无法工作。

逐步操作：

Run -> Edit Configurations
+ (Add new configuration) -> Maven
为配置命名，例如 Run tests
选择工作目录，例如 core
在 command line 中，输入 -DforkCount=0 -f pom.xml -s ../settings.xml test
按 OK
Run -> Debug，然后选择新创建的运行配置

IntelliJ 现在将在启用调试的情况下对 core 子项目执行测试。在代码任何位置设置的断点都应该有效。

仅测试一个函数或一个类

如果您想加快迭代周期，也可以只测试一个函数或一个测试类。
这可以通过将 -Dtest=MyTestClass 或 -Dtest=MyTestClass#myTestFunction 添加到运行配置来实现。运行配置中的完整命令行将是：

-Dtest=MyTestClass#myTestFunction -DforkCount=0 -f pom.xml -s ../settings.xml test

Docker

在以下示例中，假设要检查的源代码位于当前工作目录中，报告将写入 $(pwd)/odc-reports。使用持久化的数据和缓存目录，这样您可以在运行后销毁容器。

对于 Linux：

#!/bin/sh

DC_VERSION="latest"
DC_DIRECTORY=$HOME/OWASP-Dependency-Check
DC_PROJECT="dependency-check scan: $(pwd)"
DATA_DIRECTORY="$DC_DIRECTORY/data"
CACHE_DIRECTORY="$DC_DIRECTORY/data/cache"

if [ ! -d "$DATA_DIRECTORY" ]; then
    echo "Initially creating persistent directory: $DATA_DIRECTORY"
    mkdir -p "$DATA_DIRECTORY"
fi
if [ ! -d "$CACHE_DIRECTORY" ]; then
    echo "Initially creating persistent directory: $CACHE_DIRECTORY"
    mkdir -p "$CACHE_DIRECTORY"
fi

# Make sure we are using the latest version
docker pull owasp/dependency-check:$DC_VERSION

docker run --rm \
    -e user=$USER \
    -u $(id -u ${USER}):$(id -g ${USER}) \
    --volume $(pwd):/src:z \
    --volume "$DATA_DIRECTORY":/usr/share/dependency-check/data:z \
    --volume $(pwd)/odc-reports:/report:z \
    owasp/dependency-check:$DC_VERSION \
    --scan /src \
    --format "ALL" \
    --project "$DC_PROJECT" \
    --out /report
    # Use suppression like this: (where /src == $pwd)
    # --suppression "/src/security/dependency-check-suppression.xml"

对于 Windows：

@echo off

set DC_VERSION="latest"
set DC_DIRECTORY=%USERPROFILE%\OWASP-Dependency-Check
SET DC_PROJECT="dependency-check scan: %CD%"
set DATA_DIRECTORY="%DC_DIRECTORY%\data"
set CACHE_DIRECTORY="%DC_DIRECTORY%\data\cache"

IF NOT EXIST %DATA_DIRECTORY% (
    echo Initially creating persistent directory: %DATA_DIRECTORY%
    mkdir %DATA_DIRECTORY%
)
IF NOT EXIST %CACHE_DIRECTORY% (
    echo Initially creating persistent directory: %CACHE_DIRECTORY%
    mkdir %CACHE_DIRECTORY%
)

rem Make sure we are using the latest version
docker pull owasp/dependency-check:%DC_VERSION%

docker run --rm ^
    --volume %CD%:/src ^
    --volume %DATA_DIRECTORY%:/usr/share/dependency-check/data ^
    --volume %CD%/odc-reports:/report ^
    owasp/dependency-check:%DC_VERSION% ^
    --scan /src ^
    --format "ALL" ^
    --project "%DC_PROJECT%" ^
    --out /report
    rem Use suppression like this: (where /src == %CD%)
    rem --suppression "/src/security/dependency-check-suppression.xml"

从源码构建

要构建 dependency-check（使用 Java 11），请运行命令：

mvn -s settings.xml install

对 dependency-check 自身运行 dependency-check

Dependency-check 引用了一些易受攻击的依赖项，这些依赖项除作为测试资源外从未被使用。所有这些可选测试依赖项都包含在 test-dependencies profile 中。要对 dependency-check 自身运行 dependency-check，只需排除 test-dependencies profile：

mvn org.owasp:dependency-check-maven:aggregate -P-test-dependencies -DskipProvidedScope=true

构建文档

GitHub Pages 上的文档由该仓库生成：

mvn -s settings.xml site site:stage

完成后，用浏览器打开 ./target/staging/index.html。

构建 Docker 镜像

要构建 dependency-check Docker 镜像，请运行命令：

mvn -s settings.xml install
./docker-build.sh

许可证

根据 Apache 2.0 许可证的条款，授予修改和重新分发的权限。完整许可证请参阅 LICENSE.txt 文件。

Dependency-Check 使用了其他几个开源库。有关更多信息，请参阅 NOTICE.txt 文件。