从 SCA 到 CI：OWASP Dependency-Check 依赖漏洞扫描

上次某个 Java 日志组件爆出远程代码执行漏洞的那晚，我在几个项目群里看到同一种场面：有人甩出一条链接，紧接着一群人开始 grep pom.xml、翻 package-lock.json、翻 build.gradle，挨个确认自己的服务有没有引到出问题的那个版本。人肉排查一次两次还能扛，但第三方依赖包的数量是逐年滚雪球式的增长，靠人盯迟早会漏。我现在比较固定的做法，是把 OWASP Dependency-Check 挂到构建链路里，让第三方依赖包的安全扫描变成一件自动发生的事——代码提交、流水线跑起来、报告自动生成、超阈值直接卡住构建。

这篇内容主要讲三件事：Dependency-Check 判定漏洞的底层逻辑到底是怎么回事，为什么它经常报出一堆看起来莫名其妙的漏洞；从零跑通一次扫描需要哪些环境和参数；以及在真实项目里治理误报、接入 CI、优化耗时的具体做法。适合已经在维护 Java/Node 项目的后端同学、做安全左移的安全工程师，也适合刚开始接触 SCA（软件成分分析）的测试和运维同学。哪怕你之前只用过 OWASP ZAP 这类动态扫描工具，这篇也能帮你把静态依赖扫描这一块补上。

1. 从一次供应链漏洞应急说起：依赖扫描凭什么该进构建流程

很多人对依赖漏洞的第一反应是"我引的包是社区主流版本，应该没事"。这个判断在十年前勉强成立，现在基本站不住脚。一个中等规模的微服务项目，直接声明的依赖可能只有三四十个，但把传递依赖展开，实际打进包里的 jar 动辄两三百个，Node 项目更夸张，node_modules 里上千个目录是常态。这些包来自不同的维护者、不同的仓库、不同的发布节奏，其中任何一个出问题，你的服务就跟着出问题。

1.1 第三方依赖包把风险面放大了多少

我做过一次粗略统计，在一个 Spring Boot 3 的项目里执行依赖树展开，直接写在 pom 里的依赖是 42 个，最终 runtime classpath 上的 jar 是 217 个。也就是说超过 80% 的代码不是你写的，也不在你的评审范围内。这些代码里有反序列化逻辑、有 XML 解析、有 HTTP 客户端、有模板引擎，全都在你的进程里跑，用的是你的权限，读的是你的数据。

风险主要来自三类场景。第一类是组件本身存在已知漏洞，比如某个版本的 JSON 解析库在特定输入下会栈溢出。第二类是组件本身没洞，但版本太老，间接阻塞了其他修复，你为了兼容它不得不把一个已经修好的包退回旧版本。第三类最隐蔽，是组件的依赖坐标被上游悄悄改过，或者内部仓库里被人重新传了一个同名但内容不同的包，扫描工具认坐标，人眼也认坐标，但字节流已经变了。

提示：依赖漏洞治理的难点从来不是"发现",而是"发现之后怎么快速判断影响范围并对齐修复节奏"。工具的价值在于把发现这一步自动化，把人的精力留给决策。

1.2 Dependency-Check 和 ZAP、代码扫描工具的分工边界

经常有人把 Dependency-Check 和 OWASP ZAP 混在一起问。这两个东西虽然都挂在 OWASP 名下，但解决的是完全不同的两类问题。ZAP 是动态应用安全测试工具，它的工作方式是拿着一个真实跑起来的站点，从外部发请求、爬页面、尝试各种攻击载荷，比如很多人搜 ZAP 是从文件上传这类功能测试开始的——上传一个畸形文件看服务端怎么处理。ZAP 看到的是运行时行为，它不知道你的服务里引了哪个版本的 jar。

Dependency-Check 是典型的静态成分分析工具，它压根不启动你的应用，只看代码仓库里能拿到的依赖清单和二进制文件。它不知道你的接口有没有做鉴权、有没有 SQL 注入，它只关心一件事：你用了哪些第三方组件，这些组件有没有已知漏洞。

两者是互补关系，不是替代关系。我的习惯是把依赖扫描放在提交阶段和构建阶段，把动态扫描放在测试环境的部署之后，两个环节各扫各的。另外提一句，OWASP 这两年也在把清单往 AI Agent 方向延伸，出了针对 Agentic Applications 的风险清单，思路和当年的 Top 10 一脉相承，但它关注的是智能体被诱导、被越权调用工具这类问题，和依赖包扫描完全是两条线，日常做供应链治理，落点还是 OWASP Top 10 里的"易受攻击和过时的组件"这一条。

1.3 SCA 工具那么多，为什么还留着 Dependency-Check

现在可选的 SCA 工具确实不少，Trivy、Grype 在容器镜像扫描里很流行，Syft 用来生成 SBOM，商业方案里 Snyk、Sonatype 也很成熟。我在不同项目里都用过，最后还是把 Dependency-Check 作为 Java 项目的主力，原因有几点。

第一，它对 Java 生态的识别做得非常细，jar 包里的 MANIFEST.MF、pom.properties、甚至类文件里的字符串都会被拿来当证据，识别率比只读锁文件的工具高一截。第二，它的报告颗粒度适合做流程卡点，支持 CVSS 阈值、抑制文件、多种输出格式，和 Maven、Gradle、Jenkins 都有现成插件。第三，它完全开源可离线部署，数据源缓存下来之后，内网环境也能跑。

代价也很明显：它慢，第一次全量扫描加数据下载可能要十几分钟甚至更久；它误报率不低，必须有配套的抑制规则维护机制。这两点如果没想清楚就贸然接入流水线，结果往往是构建天天红、团队开始无脑跳过扫描，比不接还糟糕。

2. 从 jar 包指纹到 CPE：Dependency-Check 判定漏洞的完整链路

理解判定链路是我觉得最值得花时间的一件事。搞懂之后，你看到一条误报，能立刻判断它是哪一环出的偏差，是证据不足导致认错了包，还是版本区间匹配过于宽松。单纯看报告里的红黄绿灯，永远只能被动接受结果。

2.1 证据收集：它凭什么认出这是哪个包

Dependency-Check 对一个文件的处理是分阶段流水线式的。第一阶段是"文件类型识别"，根据扩展名和文件头判断这是 jar、war、dll、还是 npm 的 package-lock.json。第二阶段是"信息收集"，也就是各个 Analyzer 各显神通。

以 jar 为例，比较关键的几个分析器会做这些事：读取 META-INF/MANIFEST.MF 里的 Implementation-Title、Implementation-Version；读取 META-INF/maven/groupId/artifactId/pom.properties 拿到精确的 Maven 坐标；扫描包路径结构，统计命名空间；甚至从类文件常量池里抽取版权字符串和版本号。对 Node 项目，它会解析 package-lock.json、npm-shrinkwrap.json 里的包名和版本；对 Python，会看 requirements.txt 和 site-packages 里的元数据。

这些信息汇总成一组"证据"（evidence），包括厂商名、产品名、版本号、文件路径。同一条信息可能来自不同分析器，置信度也不一样，pom.properties 里读到的坐标显然比文件名里猜出来的靠谱。

2.2 CPE 匹配：那些奇奇怪怪的标识符是怎么来的

收集完证据，下一步是把证据映射到 CPE（通用平台枚举）标识上。CPE 的格式长这样：cpe:2.3:a:apache:commons_text:*:*:*:*:*:*:*:*:*，里面包含厂商、产品名、版本、更新号等字段。NVD 的漏洞数据是按 CPE 组织的，所以必须先把你的 jar 翻译成 CPE，才能去问"这个组件有没有已知漏洞"。

这一步的实现方式是构建一个基于 NVD 数据的 Lucene 索引，然后用证据里的关键词去检索，取相似度最高的候选 CPE。所以你的包名越通用，越容易匹配错。一个叫common或者utils的内部工具包，很可能被匹配到某个同名开源项目上，然后你就凭空多了十几条高危漏洞。这就是误报的第一大来源，后面讲抑制规则时会重点展开。

2.3 版本区间比对：为什么同一个 CVE 有时报有时不报

拿到 CPE 之后，Dependency-Check 会去查这个 CPE 关联的所有 CVE，然后用版本号做区间判断。NVD 的漏洞配置里会写成类似"影响 2.0.0 到 2.8.1（不含）的所有版本"这样的区间，工具需要把你实际的版本号映射到这个区间里做比较。

版本比较是个脏活。语义化版本还好办，但现实里存在大量非标准版本号：1.2.3-SNAPSHOT、2.0.1.Final、3.1.0-rc2、1.0.0-jdk8、4.5.6-20240101。这些后缀会让比较结果出现偏差，常见的后果是要么漏报（明明在受影响区间里，因为后缀没被正确处理而判定为安全），要么误报（明明已经升到修复版本，因为版本字符串没被识别而对上了旧区间）。内部做过定制改造的包尤其容易踩这个坑，因为你的版本号上游根本不认识。

2.4 数据从哪来：NVD、CVE 与 CVSS 的关系

Dependency-Check 的漏洞数据来自 NVD（美国国家漏洞数据库），NVD 收录的是 CVE 条目，每条 CVE 会带一个或多个 CVSS 评分。CVSS 是打分体系，不是严重等级本身，常见的是 0.1 到 10 的分数段，映射到低危、中危、高危、严重四档。工具里配阈值用的就是这个分数，比如failBuildOnCVSS=7的意思是发现了 7.0 及以上的漏洞就让构建失败。

数据更新方式这几年有过一次大变动。早期版本走的是 NVD 提供的离线数据文件，后来那套数据源被退役，新版本改走 NVD API 2.0。这个变化影响挺大：走 API 就必须处理限流和网络问题，没有 API Key 的情况下请求额度很低，全量同步一次数据能跑到让人怀疑人生。所以第一步环境准备里，申请 API Key 基本是必选项。

3. 第一次跑通：CLI、Maven 与 Gradle 三种落地方式

讲完原理，来说怎么让它在自己机器上先跑起来。我建议的路径是先用 CLI 扫一个目录，确认数据能正常下载、报告能正常打开，再去改构建脚本。直接从 Maven 插件上手的话，如果数据下载卡住，你很难分清是插件配置的问题还是网络的问题。

3.1 环境准备：JDK、API Key 与数据目录

前置条件不复杂：JDK 11 以上（新版本工具链对 JDK 版本有要求，我一般直接用 17），一个能访问 NVD 的网络出口，以及一个 API Key。API Key 在 NVD 官网注册后可以自助申请，免费，申请完会收到一封邮件里的字符串。

数据目录是另一个容易忽略的点。工具会把 NVD 的漏洞数据和 CPE 索引缓存在本地，默认在用户目录下的一个隐藏文件夹里。首次运行会下载几百 MB 的数据，耗时取决于网络。如果多人共用一个构建机，建议把这个目录固定到一个共享路径，避免每个用户、每个流水线任务都重新拉一遍。

# 指定数据目录和 API Key 的典型调用形式 export NVD_API_KEY="你的key" export DC_DATA_DIR="$HOME/.dependency-check-data"

有个版本选择的坑必须提醒：早期 8.x 之前的版本依赖的离线数据源已经停用，跑起来会一直报更新失败。直接上 9.x 以上的版本，写这篇的时候最新稳定版已经在 12.x 这一档了。别在旧版本上浪费时间排查网络。

3.2 CLI 扫描：最直观的一次试跑

CLI 是最适合做验证的方式。下载发行包解压，进 bin 目录执行脚本就行。

./dependency-check.sh \ --project "order-service" \ --scan ./libs \ --format HTML \ --format JSON \ --out ./dc-report \ --nvdApiKey "$NVD_API_KEY" \ --data "$DC_DATA_DIR" \ --failOnCVSS 7 \ --suppression ./suppression.xml \ --exclude "**/test/**"

几个参数值得单独说。--scan可以指向单个文件、目录或多个路径，指向目录时会递归。--format可以重复指定，我习惯同时出 HTML 和 JSON，HTML 给人看，JSON 给后续系统消费。--data指定缓存目录，第二次跑的时候数据更新会快很多。--exclude支持通配符，用来排除测试资源目录，能明显减少噪音。

--noupdate是个很实用的参数，意思是跳过数据更新直接用本地缓存。离线环境或者只是想验证扫描配置的时候非常有用，但它也是个隐患——如果流水线里长期带着这个参数，你的漏洞库就永远停在某个时间点上，新披露的漏洞一条都收不到。我的做法是只在调试阶段用，正式流水线必须走更新。

3.3 Maven 插件配置模板

Java 项目接入插件是最顺的路径，因为插件能直接拿到 Maven 解析出来的依赖树，比扫 class 文件准确得多。下面这套配置我在多个项目里复用，重点看注释里标出的几个参数。

<plugin> <groupId>org.owasp</groupId> <artifactId>dependency-check-maven</artifactId> <version>12.1.0</version> <configuration> <!-- API Key 从环境变量注入，不要硬编码进仓库 --> <nvdApiKey>${env.NVD_API_KEY}</nvdApiKey> <!-- 发现 7.0 及以上漏洞时构建失败 --> <failBuildOnCVSS>7</failBuildOnCVSS> <suppressionFiles> <suppressionFile>${project.basedir}/config/suppression.xml</suppressionFile> </suppressionFiles> <!-- 缓存目录放在仓库外部，避免被清理任务误删 --> <dataDirectory>${user.home}/.dependency-check-data</dataDirectory> <formats> <format>HTML</format> <format>JSON</format> </formats> <outputDirectory>${project.build.directory}/dc-report</outputDirectory> <!-- 测试范围的依赖通常不进生产包，可以跳过 --> <skipTestScope>true</skipTestScope> </configuration> <executions> <execution> <phase>verify</phase> <goals> <goal>check</goal> </goals> </execution> </executions> </plugin>

把执行阶段绑在verify而不是compile是个有意的选择。放在verify意味着单元测试都跑完了才做依赖扫描，避免因为一个依赖问题打断开发者最频繁的编译循环。真正要卡构建的时候，用mvn verify或者流水线里单独调mvn dependency-check:check都行。

3.4 Gradle 项目与多模块聚合

Gradle 用的是官方插件，配置写法更简洁一些，但有个关键项必须显式指定。

plugins { id 'org.owasp.dependencycheck' version '12.1.0' } dependencyCheck { nvd { apiKey = System.getenv('NVD_API_KEY') } failBuildOnCVSS = 7 suppressionFile = 'config/suppression.xml' formats = ['HTML', 'JSON'] outputDirectory = "$buildDir/reports/dependency-check" // 只扫运行时依赖，避免把编译期工具链也扫一遍 scanConfigurations = ['runtimeClasspath'] // 多模块项目里只让根工程出报告 skipConfigurations = ['annotationProcessor'] }

scanConfigurations这个设置我强烈建议加上。默认行为可能把compileClasspath、testCompileClasspath、annotationProcessor全都扫一遍，结果就是同一个 jar 被扫四次，报告里出现四条一模一样的漏洞，耗时的增长也相当可观。只扫runtimeClasspath基本上覆盖了真正会打进制品的内容。

多模块项目的另一个常见问题是报告合并。每个子模块都出一份 HTML，最后十几个报告没人看。可行的做法是在根工程用聚合任务收集，或者干脆把报告统一输出到根目录的同一个outputDirectory下，用--project名字区分。如果团队有平台能力，更好的路径是把各模块的 JSON 报告汇总推到 Dependency-Track 这类专门的管理平台上，做统一的漏洞看板和趋势追踪。

3.5 报告怎么读：先看哪一栏

第一次打开 HTML 报告的人基本都会被满屏的红色吓到。我的阅读顺序是这样的。先看顶部的摘要统计，了解严重、高危、中危各多少条。然后按 CVSS 分数降序排，从最高分往下看。每条记录里，重点看三处：Evidence告诉我工具是根据什么判定这个组件身份的，References给出 CVE 链接和修复版本，CPE则告诉你它把这个包匹配成了哪个上游项目。

如果 Evidence 里的产品和版本跟你实际用的对不上，恭喜，多半是条误报，处理方式在下一节。如果对得上，那就该安排升级了。JSON 报告适合做二次消费，字段结构稳定，写个脚本抽出"组件名 + 版本 + CVE + CVSS + 修复版本"四元组推到工单系统里，比人工截图高效得多。

4. 误报治理：suppression 规则怎么写才不失控

这是整个实践里最费精力、也最能体现功力的部分。任何声称"接入后零误报"的说法都不值得信，真实的做法是建立一套可维护、可评审、可追溯的抑制机制。

4.1 误报的四种典型来源

我把遇到过的误报归了四类，处理方式各不相同。

第一类是组件身份识别错误。内部自研包名字起得太通用，被匹配到了同名开源项目上。典型症状是 Evidence 里的厂商名和你知道的完全不符，但产品名拼写一样。

第二类是版本区间判断偏差。你的版本号带了自定义后缀，或者你用的是某个分支上的定制版，上游的受影响区间套用过来就不准了。

第三类是传递依赖误伤。你依赖的 A 组件内部打包了一份旧版 B，但你自己在 pom 里已经把 B 显式升级到新版本了。打进制品的那份旧 B 确实存在风险，但如果它根本没被加载，实际影响可能为零。

第四类是漏洞本身有争议。有些 CVE 是配置问题或者需要特定条件才能触发，在你的使用方式下不构成实际风险。这类判断需要人来做，工具做不了。

4.2 suppression.xml 的编写规范

抑制文件是 XML 格式，核心是"匹配条件 + 漏洞编号"的组合。写得太宽会让抑制规则变成黑洞，把真漏洞也一起吞掉，所以匹配条件一定要收窄。

<?xml version="1.0" encoding="UTF-8"?> <suppressions xmlns="https://jeremylong.github.io/DependencyCheck/dependency-suppression.1.3.xsd"> <!-- 示例一：内部组件被误匹配到同名开源项目 --> <suppress> <notes><![CDATA[ 内部包 com.acme:common-utils 被误判为 apache 的 commons-utils。 评估人：张三 评估日期：2025-03-12 复查日期：2025-09-12 ]]></notes> <gav regex="true">^com\.acme:common-utils:.*$</gav> <cve>CVE-2021-XXXXX</cve> </suppress> <!-- 示例二：打包进制品但运行时不会加载的旧版传递依赖 --> <suppress> <notes><![CDATA[ 该版本由 A 组件 shade 打包进来，运行时类加载不会走到，已在依赖收敛计划中。 ]]></notes> <packageUrl regex="true">^pkg:maven/org\.example/legacy-lib@1\.2\.3.*$</packageUrl> <cve>CVE-2022-YYYYY</cve> </suppress> <!-- 示例三：只要低于某个分数就整体不报，慎用 --> <suppress> <notes>CVSS 5.0 以下且无远程触发路径的条目，统一不作为卡点</notes> <gav regex="true">^com\.acme:internal-.*$</gav> <cvssBelow>5.0</cvssBelow> </suppress> </suppressions>

几个写法细节值得强调。regex="true"表示后面的字符串按正则处理，不加就是精确匹配。匹配维度可以选 GAV（groupId:artifactId:version）、purl、CPE、文件路径，我一般优先用 GAV 或 purl，因为这两个和依赖坐标强绑定，不会因为包名相似而误伤别的组件。每一条抑制都必须写<notes>，把误报原因、评估人、评估日期、复查日期都记上，这不是形式主义，等半年后有人问"这条为什么被压掉了"，答案就在这儿。

4.3 让抑制规则不变成技术债的三个机制

第一，抑制文件纳入版本管理并走评审。任何新增条目都要有人在合并请求里看一眼，确认不是随手加的一行。我在 code review 里见过最离谱的一条是把整个 groupId 前缀都抑制了，等于把这个组织的所有漏洞全部静默。

第二，设定复查日期。过滤规则里可以带时间维度的说明，定期清理已经修复的条目。一个健康的抑制文件应该是有进有出的，只进不出说明没人管。

第三，数量做监控。抑制条目总数是个很好的健康指标。如果它在半年里从 20 条涨到 200 条，说明依赖治理已经 go wrong，要么是升级流程堵住了，要么是有人在用抑制规则逃避真正的修复工作。

5. 接进 CI/CD：阈值、离线数据与耗时控制

本地跑通只是第一步，真正产生价值是在流水线上自动跑。这一节讲的都是接入过程中必须做决策的几个点。

5.1 failBuildOnCVSS 阈值该怎么定

阈值定低了构建天天红，定高了等于没卡。我的一般建议是分阶段推进，不要一上来就用最严的标准。

观察期这一步千万别省。刚接入的时候存量漏洞动辄几百条，这时候直接卡构建，结果只有一个：有人往配置里加一行跳过扫描的参数，然后这件事就再也没人提起了。先用报告模式跑一两个月，把存量消化掉，再开卡点，推行阻力会小很多。

还有一个细节是要区分"新增"和"存量"。理想的状态是只对新引入的漏洞卡构建，存量走单独的修复计划。实现方式各家不同，一种可行的做法是把上次的 JSON 报告存下来做差分，只比对新增条目。

5.2 内网环境怎么解决数据同步

很多公司的构建机没有公网出口，这是接入时最现实的障碍。解决办法是在一台能出网的机器上定期同步数据缓存目录，然后打包同步到内网，构建时用--noupdate加指定的--data目录。

同步周期建议每天一次，最低一周一次。漏洞披露是持续发生的，如果数据停在三个月前，这个扫描的意义就大打折扣了。有个折中方案是用国内可访问的镜像源同步，或者在 DMZ 区放一台专门的同步机，只允许它访问 NVD，其他构建机从它这里拉数据。

提示：数据目录的版本要和工具版本大致匹配。大版本升级后，索引结构可能变化，旧的缓存目录不兼容会导致重建，同步时最好连带工具版本一起管理。

5.3 扫描耗时优化：从二十分钟压到三分钟

首次全量扫描慢是正常的，但流水线里每次构建都跑二十分钟没人受得了。我做过几轮优化，效果比较明显的几个手段如下。

裁剪扫描范围是第一优先级。只扫runtimeClasspath，排除测试资源目录，排除前端 node_modules（前端项目单独走自己的工具链）。这一项通常能砍掉一半以上的时间。

复用数据目录是第二项。把--data指向构建机上固定的持久化路径，让数据更新变成增量行为。注意如果多个任务并行跑，同一个数据目录会有锁竞争，这时候可以给每个任务分配独立的目录，但首次填充的成本要提前规划好。

扫描结果的缓存是第三项，也是最有效的一项。如果本次提交没有改动任何依赖文件（pom.xml、build.gradle、package-lock.json 等），直接复用上次的报告，跳过整个扫描。这一步能覆盖绝大多数提交，因为大部分提交改的都是业务代码。

关闭用不上的分析器也能省时间。项目里没有 Node 依赖，就把相关分析器关掉；没有 Ruby 依赖同理。工具提供了对应的开关参数，具体取值用--help查一下，按自己项目的技术栈裁剪。

5.4 和其他安全环节怎么分工

一个完整的安全左移链路里，依赖扫描只是其中一环，不要指望它包打天下。我的分工习惯是这样：Dependency-Check 负责源码仓库层面的依赖成分分析，输出 SBOM 和漏洞报告；镜像扫描工具负责制品层面的操作系统包和系统库漏洞，因为容器基础镜像里的漏洞它才看得见；SAST 工具负责自己写的代码里的问题；DAST 工具在测试环境部署后跑一轮。

这四类工具的漏洞数据源经常有重叠，同一个 CVE 可能被报两三次，团队容易产生"怎么到处都是漏洞"的疲劳感。可行的做法是统一收口到一个平台，做去重和状态流转，让人看到的是"待处理的 N 个问题"而不是"四份互不相干的报告"。

6. 踩坑实录：限流、shaded jar 与识别失败

前面讲的是方法论，这一节是我实际踩过的几个坑，按排查过程写出来，方便你遇到类似现象时对照。

6.1 NVD API 限流导致扫描中断

现象是扫描跑到一半报连接错误或者超时，日志里能看到 403 或者请求被拒的提示。原因是没有配 API Key，走了最低的请求额度，全量同步数据的时候请求太密集被限。

排查路径很简单，先确认环境变量有没有正确传到构建进程里。我踩过一次是 Jenkins 里配了凭据，但插件的配置项引用错了变量名，结果传进去的是空值，等于没配。确认方式是在报告或者日志开头看有没有打印出 API Key 已加载的信息（不会打印明文）。

另一个坑是并发。多个流水线任务同时触发数据更新，请求量叠加起来同样会触发限流。解决办法是把数据更新从每个任务里剥离出来，做成定时任务统一更新，业务流水线只读不写。

6.2 shaded jar 带来的重复与错判

现象是报告里同一个组件出现在不同路径下，版本还都不一样，一个高版本一个低版本，低版本上挂着一堆高危漏洞，但你明明已经在 pom 里锁定了高版本。

根因是有组件在打包时把依赖重新 relocate 并 shade 进了自己的 jar 里。这种内嵌的 class 文件会带着原始的包路径和元数据，Dependency-Check 扫到就会当成一个独立组件。排查方式是看报告里的文件路径，如果它出现在某个第三方 jar 的内部，基本可以确认是 shade 的结果。

处理顺序是先做依赖收敛，用 dependencyManagement 统一版本，用 maven-enforcer 的依赖收敛规则把冲突挡在构建期。真的收敛不了、且确定运行时不会加载那份旧代码的，再考虑用抑制规则处理，并在 notes 里写清楚判断依据。

6.3 版本号被改写导致漏报

这个坑比误报更危险，因为它是静默的。内部仓库里有人为了修一个兼容问题，拿上游 2.3.4 的源码改了几行，然后把版本号写成2.3.4-patched。Dependency-Check 拿到这个版本字符串，做区间比较时可能既匹配不上受影响区间，也匹配不上修复区间，最后判定为无漏洞。而实际上，你这份代码是基于有漏洞的 2.3.4 改的，漏洞大概率还在。

我的应对方式是两条。一是内部定制版的版本号规范要定死，比如统一用2.3.4.acme.1这种带独立段落的格式，并且在内部仓库里维护一份"定制版与上游版本对应关系"的清单。二是在扫描之外，对内部定制组件单独做一次人工评估，工具解决不了的问题就得靠流程兜底。

6.4 内存与并发问题

扫描大项目时遇到的另一个现象是进程被 OOM Killer 干掉，或者卡在某个分析阶段不动。默认堆大小在依赖数量多的时候不够用，需要在启动时通过 JVM 参数把最大堆调大，CLI 脚本支持通过环境变量传入 JVM 参数。

并发扫描多个项目时，我的做法是串行执行，或者给每个任务分配独立的 data 目录和输出目录，避免文件锁冲突。时间上串行确实更慢，但稳定性比追求并行重要得多——一次莫名其妙的构建失败，团队对工具的信任就要掉一截。

提示：任何一次"扫描器自己挂了"的事故，处理完都要顺手看一眼是不是资源问题。工具类故障里，配置错误和资源不足占的比例远高于工具本身的缺陷。

我个人在实际操作中的体会是，Dependency-Check 这类工具的价值上限，取决于团队对它的定位。如果只是想在安全合规检查表上打个勾，那装完跑一次就够了；如果想让它真正降低供应链风险，就必须配套三样东西：一份有人维护的抑制规则、一条独立的漏洞数据同步链路、一套把新增漏洞和存量漏洞分开处理的策略。这三样都比装工具本身麻烦，但它们决定了你半年后是在看一份持续更新的风险清单，还是在看一份没人打开的报告。