osv-scanner 实战：pnpm 支持、忽略 CVE、离线模式与常见错误

适用对象：已经安装了 osv-scanner、在使用中遇到问题的人。这里讲的是装好之后才会遇到的问题，不讲安装。所有内容都依据官方文档。

指定锁文件

# a single lockfile
osv-scanner scan source -L pnpm-lock.yaml
 
# walk a directory
osv-scanner scan source -r ./my-project/

当无法从文件名推断格式时，在路径前加上要使用的解析器：

# parse an oddly named file as requirements.txt
osv-scanner scan source -L 'requirements.txt:/path/to/extra-requirements.txt'
 
# path containing a colon — lead with a bare ':' to keep filename inference
osv-scanner scan source -L ':/path/to/my:projects/package-lock.json'

如何检查自己的环境

结果看起来不对时，先做下面五项检查，再考虑添加参数。每一项都只检查你自己的项目。

退出码及 CI 中的处理

文档把 1–126 保留给与结果相关的情况，把 129–255 保留给与结果无关的错误。把 CI 的处理分成三类：0 通过、1 是检出结果、其他都是扫描故障，排查失败原因会快得多。

忽略特定漏洞

在被扫描的目录中放一个 osv-scanner.toml：

[[IgnoredVulns]]
id = "GHSA-xxxx-xxxx-xxxx"
ignoreUntil = 2026-12-31
reason = "Feature is not used and the code path is unreachable; re-evaluate at the December inventory"

• id（必填）：漏洞标识符
• ignoreUntil（可选）：过了这个日期会再次报告
• reason（可选）：也一定要写，给下一个看的人，而那个人通常就是你自己

--config=/path/to/config.toml 会覆盖各目录的文件并在所有地方生效。注意，忽略一个漏洞，也会同时忽略被视为其别名的漏洞。

离线模式：三个参数，三种作用

大部分困惑都出在这里。

v1 文章里的参数用不了时

很多搜索结果是为 v1 写的。官方迁移指南列出的主要变化：

osv-scanner <dir> 作为 osv-scanner scan source <dir> 的简写仍然可用。在脚本中写出 scan source，下一个读的人更容易看懂意图。

常见错误及修正方法

Maven 的 pom.xml 不像锁文件那样列出每个解析后的版本。默认情况下，osv-scanner 使用 deps.dev 解析器（加上 --data-source=native 时使用 Maven Central）计算传递依赖图。这需要网络，在 --offline 和 --no-resolve 下会被跳过。在完全隔离网络的运行中，要预期结果只覆盖 pom.xml 中直接写出的依赖。

真实案例：为什么 Log4Shell 难以回答

2021 年 12 月 Log4Shell（CVE-2021-44228） 出现时，很多组织无法迅速说清自己是否受影响。他们从未自己添加过 Log4j，它是通过框架和其他库进来的。CISA 的指南要求各组织全面列出已安装的软件，并与受影响软件的列表进行对照。

用到 osv-scanner 上，就是要确认两件事：

• 传递依赖确实被读取了：生态系统有锁文件的就用锁文件，Maven 则要在启用解析的状态下运行（不离线，不加 --no-resolve）
• 清单中确实包含间接引入的库：用 --format json --all-packages 输出并查看

在漏洞公开当天能否在几分钟内回答「我们是否受影响」，取决于事先是否把这份清单做对。

与相近工具的区别

只选一个才是错误。 数据库不同，发现的东西也不同。本站每天用 pnpm audit 做自动检查，用 osv-scanner 做跨锁文件的检查。

参考资料

• OSV-Scanner 文档 — Usage / Offline Mode / Configuration
• Supported Artifacts and Manifests
• OSV-Scanner 文档 — Output（输出格式与退出码） / Migration Guide（v1 到 v2）
• CISA — Apache Log4j Vulnerability Guidance

接下来阅读

• 入门：osv-scanner 的安装与使用
• 排优先级：决定先修补哪个（CVSS、EPSS、KEV）
• 事件：Log4Shell（传递依赖让人看不清用了什么）
• 实务：漏洞应对的实务 / 防御 npm 供应链蠕虫（英文）