Snyk CLI `snyk test` 命令完全指南:漏洞扫描、参数详解与源码级原理剖析
Snyk CLI snyk test 命令完全指南:漏洞扫描、参数详解与源码级原理剖析
导读
test 是 Snyk CLI 最核心的子命令之一,用于对项目进行开源依赖(Open Source)漏洞与许可证问题扫描。本文以 Snyk CLI 官方命令文档 help/cli-commands/test.md 为骨架,完整覆盖 snyk test 的退出码语义、全部通用选项、各生态(Maven / Gradle / NuGet / .NET / npm / pnpm / Yarn / CocoaPods / Python / Go / C++ unmanaged)专属选项与实战示例,并结合当前开源仓库 cli 的 TypeScript 源码(如 src/cli/commands/test/index.ts、src/lib/snyk-test/run-test.ts、src/lib/detect.ts)深入解析其底层实现原理,帮助你在开发、CI 流水线乃至大规模 monorepo 场景中正确、高效地使用 snyk test。
一、命令用途与基本用法
1.1 命令做什么
snyk test 用于检查项目中存在的开源依赖漏洞(open-source vulnerabilities)与许可证问题(license issues)。它会自动检测受支持的 manifest 文件(如 package.json、pom.xml、requirements.txt、go.mod、Gemfile.lock、yarn.lock、pnpm-lock.yaml 等)并对其中的依赖进行扫描。
注意:针对 Snyk Code(SAST)、Container(容器镜像)与 IaC(基础设施即代码)三种扫描方式,分别有专门的子命令:
snyk code test、snyk container test与snyk iac test,本文不展开介绍这三者的专属行为。
1.2 基本语法
snyk test [<OPTIONS>]
在最简单的情况下,直接在项目根目录执行:
$ snyk test
Snyk 会自动探测当前目录下的受支持清单文件并开始扫描。
从源码角度看,命令入口在 src/cli/commands/test/index.ts 中的 test() 函数:它先通过 processCommandArgs 解析参数,随后调用 setDefaultTestOptions 补齐默认值,经过 validateTestOptions / validateCredentials 校验后,对每个传入路径(paths)依次调用 snyk.test(path, testOpts)(最终进入 src/lib/snyk-test/run-test.ts 的 runTest),再汇总所有扫描结果统一输出。
1.3 支持自动检测的清单文件
从 src/lib/detect.ts 中的 AUTO_DETECTABLE_FILES 常量可以看出,snyk test 在不指定 --file 时可以自动检测以下清单文件:
pnpm-lock.yaml、package-lock.json、yarn.lock、package.json、Gemfile、Gemfile.lock、pom.xml、packages.config、paket.dependencies、project.json、project.assets.json、Podfile、Podfile.lock、composer.lock、Gopkg.lock、go.mod、Pipfile、requirements.txt、build.sbt、build.gradle、build.gradle.kts、poetry.lock、mix.exs、mix.lock、Package.swift、uv.lock。
这些文件对应的包管理器映射定义在 src/lib/package-managers.ts 的 SUPPORTED_MANIFEST_FILES 枚举与 SUPPORTED_PACKAGE_MANAGER_NAME 常量中(如 RubyGems、npm、Yarn、pnpm、Maven、pip、SBT、Gradle、Go Modules、NuGet、Paket、Composer、CocoaPods、Poetry、Hex、Unmanaged C/C++、Swift、uv 等)。
二、退出码(Exit Codes)语义
test 命令执行完毕后可能返回以下退出码:
| 退出码 | 含义 |
|---|---|
| 0 | 成功(扫描完成),未发现漏洞 |
| 1 | action_needed(扫描完成),发现漏洞 |
| 2 | 失败,请尝试重新运行命令。可使用 -d 输出调试日志 |
| 3 | 失败,未检测到受支持的项目 |
这些退出码的常量定义在 src/cli/exit-codes.ts:
export const EXIT_CODES = {
VULNS_FOUND: 1,
ERROR: 2,
NO_SUPPORTED_PROJECTS_DETECTED: 3,
EX_UNAVAILABLE: 69,
EX_TEMPFAIL: 75,
EX_NOPERM: 77,
EX_TERMINATE: 44,
};
在 src/cli/main.ts 的异常处理逻辑中可以看到退出码的映射细节:
- 当错误消息中包含
'Could not detect supported target files in'(即未检测到受支持的 manifest)、或属于 SAST/IaC 的无文件可扫错误时,退出码被设为NO_SUPPORTED_PROJECTS_DETECTED (3); - 当
error.code === 'VULNS'(扫描完成但发现漏洞,见 src/cli/commands/test/index.ts 中err.code = 'VULNS'的赋值)时,退出码被设为VULNS_FOUND (1); - 其余失败场景默认取
ERROR (2)。
另外,在 CI 模式(SNYK_CI=1)下,401/403 会映射为 EX_NOPERM (77),其余 4xx 错误映射为 EX_UNAVAILABLE (69),可用于 CI 中对认证类错误做更精细的分支处理。
三、命令行通用选项详解
以下选项适用于大多数场景,部分选项仅在特定生态下生效(详见各生态小节)。
3.1 --reachability=<true|false>
扫描时执行可达性分析(reachability analysis)。该功能当前处于 Snyk Preview 阶段。
- 默认值:
false。 - 使用时通常配合
--source-dir=<PATH_TO_SOURCE_CODE>指定待分析源码目录。
3.2 --all-projects
自动检测工作目录下的所有项目,包括 Yarn workspaces。
- 适用于 monorepo 或多 manifest 文件场景:
snyk test --all-projects。 - 若遇到 "invalid string length" 错误,可参考仓库测试夹具
test/fixtures/npm-test-proj-with-vulns/等场景排查超长 JSON 输出问题。
从实现上看,--all-projects 会让插件系统对目录进行递归探测。底层文件发现逻辑在 src/lib/find-files.ts 的 find() 函数:默认搜索深度为 4 层(levelsDeep: 4),且始终忽略 node_modules、.build、.git 目录(ignoreFolders 常量)。同一个目录下同一包管理器出现多个 manifest 时,会通过 chooseBestManifest() 优先选择 lockfile(如 package-lock.json > yarn.lock > pnpm-lock.yaml > package.json,见 filterForDefaultManifests)。
3.3 --fail-fast
配合 --all-projects 使用:当某个项目扫描出错时立即中断扫描,并向用户报告这些错误。
- 发生错误时退出码为 2,扫描终止,不再报告其余未出错项目的漏洞信息。
- 若想恢复,需要先解决报错项目的问题后重新扫描。
- 注意:如果不加
--fail-fast,Snyk 会继续扫描所有项目,但对因配置错误等原因无法扫描的项目不报告漏洞。
源码中对应 src/lib/snyk-test/run-test.ts assembleLocalPayloads 中的处理:当 getDepsFromPlugin 返回 failedResults 且设置了 options['fail-fast'] 时,会抛出 FailedToRunTestError 立即终止整个流程。
3.4 --detection-depth=<DEPTH>
配合 --all-projects 或 --yarn-workspaces,指定向下搜索的子目录层级数。
DEPTH必须是大于等于 1 的数字;0表示仅当前目录。- 默认值:无限制。
- 示例:
--detection-depth=3表示在指定目录(若未指定<PATH>则为当前目录)及其三层子目录内搜索。
在 src/cli/args.ts 中,detection-depth 会被转换为数字类型(argv.detectionDepth = Number(argv.detectionDepth)),并作为 find-files 的 levelsDeep 参数控制递归深度。
3.5 --exclude=<NAME>[,<NAME>]...>
配合 --all-projects 与 --yarn-workspaces,指定要排除的目录名与文件名。
- 必须是逗号分隔的名称列表,不能包含路径。
- 示例:
$ snyk test --all-projects --exclude=dir1,file2会排除所有名为dir1与file2的目录/文件,例如./dir1、./src/dir1、./file2、./src/file2等。 - 注意:
--exclude=dir1能同时匹配./dir1与./src/dir1;而--exclude=./src/dir1会因为包含路径而报错。
底层实现在 src/lib/find-files.ts 的 isExcludedPath():对每个解析后的绝对路径与 excludePaths 列表做精确比对(Windows 平台会先转小写再比较)。解析时的排除规则错误会抛出 src/lib/errors/exclude-flag-bad-input.ts 或 src/lib/errors/exclude-flag-invalid-input.ts 中定义的错误。
3.6 --prune-repeated-subdependencies / -p
剪枝依赖树,移除重复的子依赖。
- 仍能发现全部漏洞,但可能无法列出全部漏洞路径。
- 当大型项目测试失败时建议使用该选项。
- 默认值:
false。
在 src/lib/snyk-test/run-test.ts 中,pruneIsRequired = options.pruneRepeatedSubdependencies 会作为参数传给 pruneGraph(depGraph, packageManager, pruneIsRequired)(实现见 src/lib/prune.ts)。
3.7 --print-deps
在发送依赖树进行分析之前,先在控制台打印依赖树。
3.8 --remote-repo-url=<URL>
设置或覆盖仓库的远程 URL,用于在 Snyk 平台上建立目标(target)关联。
- 示例:
--remote-repo-url=https://gitlab.com/example/project会在平台上创建一个目标,UI 中显示为/example/project/。 - 非法输入会抛出 src/lib/errors/invalid-remote-url-error.ts 定义的
Invalid argument provided for --remote-repo-url错误。 - 该值通过 src/lib/project-metadata/index.ts 的
getInfo注入到扫描目标元数据中。
3.9 --dev
包含仅开发环境的依赖。
- 仅对部分包管理器适用,例如 npm 的
devDependencies、Gemfile 的:development依赖。 - 该选项可用于 Maven、npm、Yarn 项目。
- 默认值:
false,即默认只扫描生产依赖。
3.10 --org=<ORG_ID>
指定运行 Snyk 命令所归属的 Snyk Organization。<ORG_ID> 会影响部分功能的可用性与私有测试额度。
- 多组织场景下可先用命令设置默认组织:
$ snyk config set org=<ORG_ID>,之后所有新测试的项目都会默认归属该组织;需要临时覆盖时再用--org=<ORG_ID>。 - 默认值:账号设置(Account settings)中当前首选的组织。
- 注意:也支持
--org=<orgslugname>(组织 slug 名)。ORG_ID在 CLI 与 API 中都可用;slug 名仅在 CLI 中可用,在 API 中不可用。orgslugname必须与 Snyk UI 中组织 URL(https://app.snyk.io/org/[orgslugname])显示的 slug 完全一致,组织显示名(orgname)无效。
从源码看,src/lib/snyk-test/common.ts 的 assembleQueryString() 会把 org(未指定时回退到 config.org)拼入 API 请求的 query string;src/cli/commands/test/set-default-test-options.ts 也会做 org: options.org || config.org 的默认值回退。
3.11 --file=<FILE>
指定要扫描的包清单文件。
- 本地测试或监控时,用它指定 Snyk 应检查的包信息文件;未指定时 Snyk 会尝试自动探测。
- 当文件名非标准时,需配合
--package-manager=<PACKAGE_MANAGER_NAME>使用(例如 Python 项目)。
3.12 --package-manager=<PACKAGE_MANAGER_NAME>
当 --file 指定的文件名不是标准名称时,通过它告知 Snyk 实际的包管理器,使 Snyk 能正确识别文件。
- 示例:
$ snyk test --file=req.txt --package-manager=pip - Python 项目使用自定义文件名时必须加
--package-manager=pip,否则测试会失败。
3.13 --source-dir=<PATH_TO_SOURCE_CODE>
指定要分析的源码目录。配合 --reachability 使用。
3.14 --unmanaged
仅用于 C++ 项目:扫描所有文件以查找已知的开源依赖。
- 相关专属选项见"扫描
--unmanaged的选项"一节。
3.15 --ignore-policy
忽略所有已配置的策略:.snyk 文件中的当前策略、Org 级忽略(ignores)、以及 snyk.io 上的项目策略全部忽略。
从实现看,src/lib/snyk-test/common.ts 的 assembleQueryString() 会在设置了 ignore-policy 时向 API 请求追加 ignorePolicy=true;本地侧 src/lib/snyk-test/run-test.ts 的 parseRes() 中,当 options['ignore-policy'] 未设置时才会用 snykPolicy.loadFromText() 加载并过滤策略。
3.16 --trust-policies
应用并采用依赖中 Snyk 策略文件(policy)里的 ignore 规则;否则依赖中的 ignore 规则仅作为建议展示。
3.17 --show-vulnerable-paths=<none|some|all>
展示从顶层依赖到易受攻击包的依赖路径。
- 默认值:
some(仅展示少量示例路径);false是none的别名。 - 示例:
--show-vulnerable-paths=none - 不支持与
--json-file-output同时使用。
该默认值逻辑在 src/cli/commands/test/set-default-test-options.ts 中实现:showVulnPathsMapping 将 false/none → 'none'、true/some → 'some'、all → 'all',未提供时默认 'some'。
3.18 --project-name=<PROJECT_NAME>
为项目指定自定义的 Snyk 项目名称。
3.19 --target-reference=<TARGET_REFERENCE>
指定一个用于区分该项目的引用,例如分支名或版本号。具有相同引用的项目可以据此分组。
- 适用于 Snyk Open Source,不支持与
--unmanaged搭配使用。 - 可在
snyk test时使用,以应用与某个已监控目标相同的 ignores 与策略。
在 src/lib/snyk-test/run-test.ts 中,targetReference: options['target-reference'] 会被写入请求 body 的目标元数据。
3.20 --policy-path=<PATH_TO_POLICY_FILE>
手动指定 .snyk 策略文件的路径。
3.21 --json
将结果以 JSON 数据结构打印到控制台。
- 示例:
$ snyk test --json
3.22 --json-file-output=<OUTPUT_FILE_PATH>
无论是否使用 --json,都会将测试输出以 JSON 格式直接保存到指定文件。
- 适合同时展示人类可读输出(stdout)并保存 JSON 结果。
- 对 Open Source 扫描:无论是否发现问题,Snyk 都会创建文件;对 SAST 扫描:若未发现问题,则不创建
json文件。 - 示例:
$ snyk test --json-file-output=vuln.json
3.23 --sarif
以 SARIF 格式返回结果。
3.24 --sarif-file-output=<OUTPUT_FILE_PATH>
无论是否使用 --sarif,都会将测试输出以 SARIF 格式保存到指定文件。
- 适合 stdout 展示人类可读输出、同时保存 SARIF 文件。
- 注意:当运行多个扫描(如 SCA 与 Code 扫描)时,SARIF 输出只包含最近一次完成的扫描数据;若多次扫描顺序执行并指定同一
--sarif-file-output路径,后一次会覆盖前一次文件。如需分别保留结果,请为每次扫描指定不同的 SARIF 输出文件。
3.25 --html
以 HTML 格式返回结果。需要 Snyk CLI v1.1308.0 或更高版本。
- 示例:
$ snyk test --html
3.26 --html-file-output=<OUTPUT_FILE_PATH>
无论是否使用 --html,都会将测试输出以 HTML 格式保存到指定文件。需要 Snyk CLI v1.1308.0 或更高版本。
- 示例:
$ snyk test --html-file-output=results.html
3.27 --severity-threshold=<low|medium|high|critical>
仅报告指定级别及以上的漏洞。
从源码看,src/cli/commands/test/validate-test-options.ts 会用 src/lib/snyk-test/common.ts 中的 SEVERITIES(low→1、medium→2、high→3、critical→4)校验该参数,非法取值会抛出 INVALID_SEVERITY_THRESHOLD。通过后,assembleQueryString() 会将其作为 severityThreshold 传给 API。
3.28 --fail-on=<all|upgradable|patchable>
仅当存在可被修复的漏洞时才让命令失败(退出码非 0)。取值含义:
-
all:存在至少一个可升级(upgrade)或可打补丁(patch)的漏洞时失败。 -
upgradable:存在至少一个 Snyk 已给出计算修复方案(remediation)的漏洞时失败。 -
patchable:存在至少一个可打补丁的漏洞时失败。注意:使用patchable时,只要存在至少一个可打补丁的漏洞,即便其他漏洞已有计算修复方案,测试也会失败。 -
若不使用
--fail-on,默认行为是:只要发现任何 Snyk 可检测到的漏洞即失败。若漏洞没有 Snyk 计算出的修复方案且使用了本选项,测试会通过。 -
注意:如果测试的代码受 Snyk 无法通过
snyk test遵守的元数据约束,为避免破坏你的代码,Snyk 不会提议修复方案;此时可能需要人工识别并应用修复。
该选项的实现同样位于 src/cli/commands/test/validate-test-options.ts:使用 FAIL_ON 枚举(定义于 src/lib/snyk-test/common.ts,值为 all / upgradable / patchable)校验参数,非法取值抛出 FailOnError。失败判定逻辑在 src/cli/commands/test/index.ts 的 shouldFail() 函数:
function shouldFail(vulnerableResults: any[], failOn: FailOn) {
if (failOn === 'all') {
return hasFixes(vulnerableResults);
}
if (failOn === 'upgradable') {
return hasUpgrades(vulnerableResults);
}
if (failOn === 'patchable') {
return hasPatches(vulnerableResults);
}
// 默认:存在漏洞即失败
return vulnerableResults.length > 0;
}
其中 hasFixes / hasUpgrades / hasPatches 定义于 src/lib/vuln-helpers.ts。
3.29 --reachability-filter=<reachable|no-info|not-applicable>
过滤结果,仅展示可达(reachable)、不可达(no-info)或无法执行可达性分析(not-applicable)的漏洞。
- 必须先设置
--reachability=true才可使用。
四、Maven 项目选项
提示:
--dev可用于 Maven 项目(见上文--dev说明)。
4.1 --maven-aggregate-project
扫描 Maven 聚合项目(即使用 modules 与 inheritance 的项目)时,用它替代 --all-projects。
- 该选项会指示 Snyk 执行一次编译步骤,确保项目内所有模块可被 Maven reactor 解析,从而完整覆盖所有子模块的依赖。
- 必须在根
pom.xml所在目录执行扫描。 - Snyk 会按聚合项目内的每个
pom.xml分别报告测试结果。 - 注意:可以用
--all-projects扫描 Maven 聚合项目,但--all-projects不能与--maven-aggregate-project同时使用。
4.2 --maven-skip-wrapper
强制使用全局安装的 mvn 命令,即使项目中存在 Maven wrapper(mvnw 或 mvnw.cmd)。
- 某些项目自带 wrapper,但用户或 CI 环境可能要求使用全局
mvn;该选项无需移除项目中的 wrapper 即可显式切换。
4.3 --scan-unmanaged
用于测试单个 JAR、WAR、AAR 文件:
--scan-unmanaged --file=<JAR_FILE_NAME>
4.4 --scan-all-unmanaged
从当前目录递归自动检测 Maven、JAR、WAR、AAR 文件:
--scan-all-unmanaged
注意:自定义构建的 JAR 文件(即使包含开源依赖)不受支持。
4.5 --include-provenance
实验性功能:在分析期间为 Maven 构件启用 provenance 生成,为扫描的构件生成加密指纹,以帮助漏洞匹配与供应链安全。
注意:需要依赖构件已存在于本地 Maven 仓库中(例如通过 mvn clean install 安装)。
4.6 Maven 专属透传选项
在完整 Snyk 命令后追加 --,再跟 Maven 选项,即可将额外参数直接传给 Maven:
- 示例:
-- -Dpkg_version=1.4;-- -Dprofile=my-profile;-- -s path/to/settings.xml
注意:不要把透传参数放在引号里当作单个参数传递(见下文"构建工具选项"一节)。
五、Gradle 项目选项
5.1 --sub-project=<NAME> / --gradle-sub-project=<NAME>
针对 Gradle 多项目(multi project)配置,测试特定的子项目。
5.2 --all-sub-projects
针对多项目配置,测试所有子项目。
- 当前目录下必须同时存在
build.gradle与settings.gradle(或对应等价文件)。
5.3 --all-projects(Gradle 场景)
用于 monorepo:检测所有受支持的 manifest。
- 对 Gradle monorepo,Snyk 只查找根级别的
build.gradle/build.gradle.kts文件,并在内部应用与--all-sub-projects相同的逻辑。 - 该选项设计为在 monorepo 根目录运行。
5.4 --configuration-matching=<CONFIGURATION_REGEX>
使用第一个匹配指定 Java 正则表达式的 configuration 来解析依赖。
- 示例:
^releaseRuntimeClasspath$
5.5 --configuration-attributes=<ATTRIBUTE>[,<ATTRIBUTE>]...
选择特定值的 configuration attributes 来安装并解析依赖。
- 示例:
buildtype:release,usage:java-runtime
5.6 --init-script=<FILE>
用于包含 Gradle 初始化脚本(init script)的项目。
六、NuGet 项目选项
6.1 --assets-project-name
监控使用 NuGet PackageReference 的 .NET 项目时,若找到 project.assets.json,则使用其中的项目名称。
6.2 --file=<filename>.sln
测试给定 .sln 文件包含的所有 .NET 项目。被引用的项目必须具有受支持的 manifest。
- 示例:
snyk test --file=myApp.sln
6.3 --file=packages.config
测试单个 .NET 项目。
6.4 --packages-folder
指定 packages 文件夹的自定义路径。
- 这是使用
packages.config时依赖被安装的文件夹。若你为该文件夹指定了唯一名称,Snyk 只有在你输入自定义路径时才能找到它。 - 使用包含依赖所在文件夹名称的绝对或相对路径。
- 示例:
- Unix:
snyk test --packages-folder=../location/to/packages - Windows:
snyk test --packages-folder=..\location\to\packages
- Unix:
6.5 --project-name-prefix=<PREFIX_STRING>
监控 .NET 项目时,为项目内文件名称添加自定义前缀及任意分隔符。
- 示例:
snyk monitor --file=my-project.sln --project-name-prefix=my-group/ - 当多个
.sln文件中有同名项目时非常有用。
七、.NET 项目选项
7.1 --dotnet-target-framework
可选。当解决方案包含多个 <TargetFramework> 指令时使用。不指定该选项时,会扫描所有受支持的 Target Framework。
- 指定的 Target Framework 需遵循标准命名约定。
- 示例:
snyk test --dotnet-runtime-resolution --dotnet-target-framework=net6.0
八、npm / pnpm / Yarn 项目选项
8.1 通用选项
npm、pnpm、Yarn 项目均支持以下通用选项:
--dev:包含开发依赖(见上文说明)。--all-projects:扫描并检测目录中的 npm/pnpm 项目及其他所有项目。--fail-on:见上文--fail-on说明。--prune-repeated-subdependencies, -p:见上文说明。
8.2 --strict-out-of-sync=true|false(npm / pnpm / Yarn)
防止测试不同步的 lockfile。
- 当项目存在不同步的 lockfile 且
--strict-out-of-sync=true时,test命令会失败。 - 默认值:
true。
在 src/cli/args.ts 中,strict-out-of-sync 字符串会被转换为布尔值('false' 之外的值一律视为 true)。
8.3 --yarn-workspaces(Yarn 专属)
当根目录存在 lockfile 时,仅检测并扫描 Yarn Workspaces。
- 可用
--detection-depth指定向下搜索的层数。 - 可用
--exclude排除目录与文件。 - 默认行为:
--all-projects会自动检测并扫描 Yarn Workspaces(与其他项目一起)。
九、CocoaPods 项目选项
9.1 --strict-out-of-sync=true|false
控制是否测试不同步的 lockfile。
- 默认值:
false(注意与 npm/pnpm/Yarn 的默认true不同)。
十、Python 项目选项
10.1 --command=<COMMAND>
根据 Python 版本指定具体使用的 Python 命令。
- Snyk 使用 Python 来扫描并发现依赖。若安装了多个 Python 版本,用此参数指定正确的 Python 命令。
- 默认值:
python(即默认 Python 版本;可用python -V查看)。 - 示例:
snyk test --command=python3
10.2 --skip-unresolved=true|false
跳过环境中无法找到的包,例如无法从运行扫描的机器访问的私有包。
- 在 src/cli/args.ts 中,该参数会被转换为内部
allowMissing标志:'false'对应allowMissing = false,其余情况为true。
10.3 --file=<FILE_for_Python>
针对 Python 项目,指定要测试的特定文件。
- 默认值:项目顶层目录的
requirements.txt。 - 重要:当
--file指定的不是默认文件时,必须同时添加--package-manager=pip,否则测试会失败。
snyk test --file=requirements-dev.txt --package-manager=pip
- 这样 Snyk 才能正确识别并扫描你指定的 manifest(例如重命名为
requirements-dev.txt的文件)。
10.4 --package-manager=pip
当文件名不是 requirements.txt 时,需在命令中添加 --package-manager=pip。
- 只要
--file指向非requirements.txt文件,此参数就是必填的;缺少时测试会失败。指定时取值必须为pip。
十一、Go 项目选项
Go 项目(Go Modules)不支持以下选项:
--fail-on=<all|upgradable|patchable>
十二、扫描 --unmanaged(C/C++)的选项
以下标准 snyk test 选项可与 --unmanaged 一起使用:
--org=<ORG_ID>--json--json-file-output=<OUTPUT_FILE_PATH>--remote-repo-url=<URL>--severity-threshold=<low|medium|high|critical>
另有专属选项:
12.1 --max-depth
指定归档(archive)解压的最大层级。
- 用法:
--max-depth=1 - 使用
0(零,也是默认值)可完全禁用归档解压。
12.2 --print-dep-paths
展示依赖(dependencies)。
- 使用该选项可查看每个被识别依赖由哪些文件贡献而来。
- 若想了解 Snyk 对识别出的依赖及其版本的置信程度,可使用
--print-deps或--print-dep-paths。
十三、构建工具选项(Build Tools)
13.1 -- [<CONTEXT-SPECIFIC_OPTIONS>]
在完整的 Snyk 命令后使用双横线(--),将后续参数(选项、标志)直接透传给构建工具(如 Gradle 或 Maven)。
- 格式:
snyk <command> -- [<context-specific_options>] - 示例:
snyk test -- --build-cache - 注意:
-- [<context-specific_options>]中不要使用双引号。- 正确:
snyk test --org=myorg -- -s settings.xml - 错误:
snyk test --org=myorg -- "-s settings.xml"
- 正确:
十四、典型使用示例
在当前文件夹测试项目是否存在已知漏洞:
$ snyk test
测试某个特定依赖(仅限 npm):
$ snyk test ionic@1.6.5
测试某个 npm 包的最新版本:
$ snyk test lodash
测试公开的 GitHub 仓库:
$ snyk test https://github.com/snyk-labs/nodejs-goof
十五、源码级流程全景:一次 snyk test 的完整执行链路
结合当前仓库源码,snyk test 的完整调用链大致如下:
- 参数解析与默认值补齐:src/cli/commands/test/index.ts 的
test()调用processCommandArgs解析 CLI 参数(转换逻辑见 src/cli/args.ts,包括detection-depth数字化、strict-out-of-sync/skip-unresolved布尔化、--all-projects/--fail-on等 dashed 参数转 camelCase),随后setDefaultTestOptions设置org与showVulnPaths默认值(src/cli/commands/test/set-default-test-options.ts)。 - 参数校验:
validateTestOptions校验--severity-threshold与--fail-on取值(src/cli/commands/test/validate-test-options.ts);validateCredentials校验认证凭据。 - 依赖解析(插件层):src/lib/snyk-test/run-test.ts 的
assembleLocalPayloads调用getDepsFromPlugin(src/lib/plugins/get-deps-from-plugin.ts),由各包管理器的插件生成依赖树/依赖图;若设置了--all-projects,则经由 src/lib/find-files.ts 递归发现所有 manifest。 - 策略加载:
findAndLoadPolicy(src/lib/policy/find-and-load-policy.ts)加载.snyk策略,除非使用--ignore-policy。 - 请求发送与重试:
sendAndParseResults通过pMap并发发送 API 请求,并发数由getRequestConcurrency()控制(src/lib/snyk-test/common.ts,默认 5,上限 50,可通过内部环境变量SNYK_INTERNAL_REQUEST_CONCURRENCY调整);对 500/502/503 错误会按RETRY_ATTEMPTS = 3、RETRY_DELAY = 500重试。 - 结果处理与输出:
parseRes应用策略过滤、统计漏洞;随后在 src/cli/commands/test/index.ts 中按--json/--sarif/ 人类可读三种方式输出,并按--fail-on/ 默认逻辑决定是否抛出VULNS错误。 - 退出码映射:src/cli/main.ts 将
VULNS映射为退出码 1、未检测到受支持项目映射为 3、其他错误映射为 2(详见本文第二节)。
十六、常见问题与调试建议
- 扫描失败(退出码 2):先用
-d输出 debug 日志定位原因(该选项会开启debug命名空间日志,见 src/cli/commands/test/index.ts 中的Debug('snyk-test')与 src/lib/snyk-test/run-test.ts 中的debugModule('snyk:run-test'))。 - 未检测到受支持项目(退出码 3):确认目标目录下存在 src/lib/detect.ts 中
AUTO_DETECTABLE_FILES列表内的 manifest 文件;或改用--all-projects/--file+--package-manager显式指定。 - 大型项目测试失败:尝试
--prune-repeated-subdependencies, -p剪枝依赖树。 - monorepo 扫描范围控制:组合使用
--all-projects、--detection-depth与--exclude精确控制搜索范围,注意--exclude不接受带路径的值。 - 超大输出导致的 "invalid string length" 错误:可改用
--json-file-output/--sarif-file-output将结果写入文件而非 stdout。 - 希望 CI 中断于可修复漏洞:按需选用
--fail-on=all/--fail-on=upgradable/--fail-on=patchable,配合--severity-threshold控制报告级别。
结语
snyk test 是 Snyk CLI 中覆盖面最广的漏洞扫描命令:从单项目快速扫描到 monorepo 全量检测,从人类可读输出到 JSON / SARIF / HTML 机器可读输出,从 Maven / Gradle / NuGet / .NET / npm / pnpm / Yarn / CocoaPods / Python / Go / C++ 等各生态的专属调优选项,再到与 .snyk 策略、Org 忽略规则和 --fail-on 门禁的深度集成,其行为均可通过本文列出的参数精细控制。理解退出码语义与底层实现(src/cli/exit-codes.ts、src/cli/commands/test/index.ts、src/lib/snyk-test/run-test.ts)后,你将能在本地开发与 CI 流水线中可靠地使用 snyk test 作为安全质量门禁。