Snyk CLI `snyk test` 命令完全指南:漏洞扫描、参数详解与源码级原理剖析

原创2026-10-11 22:51:091,687 阅读
文章标签:应用安全漏洞扫描CLI开发工具供应链安全

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)关联。

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

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 的完整调用链大致如下:

  1. 参数解析与默认值补齐: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)。
  2. 参数校验:validateTestOptions 校验 --severity-threshold 与 --fail-on 取值(src/cli/commands/test/validate-test-options.ts);validateCredentials 校验认证凭据。
  3. 依赖解析(插件层):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。
  4. 策略加载:findAndLoadPolicy(src/lib/policy/find-and-load-policy.ts)加载 .snyk 策略,除非使用 --ignore-policy。
  5. 请求发送与重试: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 重试。
  6. 结果处理与输出:parseRes 应用策略过滤、统计漏洞;随后在 src/cli/commands/test/index.ts 中按 --json / --sarif / 人类可读三种方式输出,并按 --fail-on / 默认逻辑决定是否抛出 VULNS 错误。
  7. 退出码映射: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 作为安全质量门禁。

登录后查看全文
cli