Trivy Filesystem 扫描指南：对本地项目进行漏洞、错误配置、密钥与许可证检测

Trivy Filesystem 扫描指南：对本地项目进行漏洞、错误配置、密钥与许可证检测

【免费下载链接】trivyFind vulnerabilities, misconfigurations, secrets, SBOM in containers, Kubernetes, code repositories, clouds and more项目地址: https://gitcode.com/GitHub_Trending/tr/trivy

本篇技术指南围绕 Trivy 的trivy fs（filesystem）子命令展开，讲解如何对本地项目目录、单个文件乃至 Git 仓库执行安全扫描，覆盖漏洞（Vulnerabilities）、错误配置（Misconfigurations）、密钥（Secrets）与许可证（Licenses）四类检测能力的启用方式与适用场景，并结合仓库源码剖析扫描器的默认行为、分析器调度逻辑与基于 Git 提交哈希的扫描缓存机制。读完本文，你将掌握用一条命令对本地代码库做全方位安全检查的实战方法，并能按需裁剪扫描器、定制输出与缓存策略。

一、Filesystem 扫描概览

trivy fs面向本地文件系统，可以直接扫描一个项目目录，也可以只扫描单个文件。它支持检测四类安全问题：

• 漏洞（Vulnerabilities）
• 错误配置（Misconfigurations）
• 密钥（Secrets）
• 许可证（Licenses）

其中漏洞与密钥扫描默认启用，错误配置与许可证扫描默认关闭，可通过--scanners参数精确控制启用哪些扫描器。--scanners的合法取值与默认值在 trivy filesystem CLI 参考 中定义：vuln,misconfig,secret,license，默认值为vuln,secret。

最基本的用法是直接指定项目路径：

$ trivy fs /path/to/project

也可以只扫描单个文件，例如一个锁文件：

$ trivy fs ~/src/github.com/aquasecurity/trivy-ci-test/Pipfile.lock

该用法对应的完整命令签名是trivy filesystem [flags] PATH（fs是其别名），详见 trivy_filesystem.md 中的 Examples 一节。

从源码结构看，trivy fs在 Trivy 的命令层被映射为TargetFilesystem这一目标类型（见 pkg/commands/artifact/run.go），并经由run函数的分发表scans调用r.ScanFilesystem执行扫描、r.Filter过滤结果、r.Report输出报告（run.go）。

二、Scanners：四类扫描器的启用与配置

2.1 Vulnerabilities（默认启用）

漏洞扫描默认开启。Trivy 会基于锁文件（如Gemfile.lock、package-lock.json）等语言依赖清单来识别项目中的第三方组件并匹配已知漏洞。完整原理可参考 漏洞扫描文档，其中包含对 OS 包、语言包、非包管理软件（如内嵌模块信息的 Go/Rust 二进制）的检测说明，以及--detection-priority precise|comprehensive、--pkg-types、--pkg-relationships等控制检测精度与范围的参数。

$ trivy fs ~/src/github.com/aquasecurity/trivy-ci-test

对上面的示例项目，输出大致如下：

2020-06-01T17:06:58.652+0300 WARN OS is not detected and vulnerabilities in OS packages are not detected. 2020-06-01T17:06:58.652+0300 INFO Detecting pipenv vulnerabilities... 2020-06-01T17:06:58.691+0300 INFO Detecting cargo vulnerabilities... Pipfile.lock ============ Total: 10 (UNKNOWN: 2, LOW: 0, MEDIUM: 6, HIGH: 2, CRITICAL: 0) +---------------------+------------------+----------+-------------------+------------------------+------------------------------------+ | LIBRARY | VULNERABILITY ID | SEVERITY | INSTALLED VERSION | FIXED VERSION | TITLE | +---------------------+------------------+----------+-------------------+------------------------+------------------------------------+ | django | CVE-2020-7471 | HIGH | 2.0.9 | 3.0.3, 2.2.10, 1.11.28 | django: potential | | | | | | | SQL injection via | | | | | | | StringAgg(delimiter) | + +------------------+----------+ +------------------------+------------------------------------+ | | CVE-2019-19844 | MEDIUM | | 3.0.1, 2.2.9, 1.11.27 | Django: crafted email address | | | | | | | allows account takeover | ...

注意日志中的OS is not detected提示：trivy fs扫描普通项目目录时不会像容器镜像那样检测操作系统，因此 OS 级系统包漏洞不会被检测；它聚焦于语言生态的依赖漏洞。

从源码看，ScanFilesystem会显式禁用两类分析器，以避免与 filesystem 场景冲突（pkg/commands/artifact/run.go）：

func (r *runner) ScanFilesystem(ctx context.Context, opts flag.Options) (types.Report, error) { // Disable scanning of individual package and SBOM files opts.DisabledAnalyzers = append(opts.DisabledAnalyzers, analyzer.TypeIndividualPkgs...) opts.DisabledAnalyzers = append(opts.DisabledAnalyzers, analyzer.TypeSBOM) return r.scanFS(ctx, opts) }

也就是说，filesystem 扫描不把单个 RPM/DEB 包文件或 SBOM 文件当作独立扫描目标，而是专注于锁文件、清单文件等依赖描述文件。与此同时，disabledAnalyzers会根据--scanners、--pkg-types、--license-full等选项动态裁剪分析器集合（run.go）。

2.2 Misconfigurations（默认禁用）

错误配置扫描默认关闭，通过--scanners misconfig启用：

$ trivy fs --scanners misconfig /path/to/project

它适用于 IaC 文件，例如 Terraform、CloudFormation、Dockerfile、Helm、Kubernetes YAML、Ansible 等。--misconfig-scanners参数可以指定要使用的错误配置扫描器类型，默认值为azure-arm,cloudformation,dockerfile,helm,kubernetes,terraform,terraformplan-json,terraformplan-snapshot,ansible（见 trivy_filesystem.md）。此外还有--include-non-failures（配合--scanners misconfig展示通过项）、--checks-bundle-repository（默认拉取mirror.gcr.io/aquasec/trivy-checks:2的检查包）、--config-check/--config-data（加载自定义 Rego 检查与数据）、--file-patterns（指定配置文件匹配模式）等进阶参数。

底层实现方面，当启用 misconfig 扫描时，initMisconfScannerOption会初始化检查客户端并调用operation.InitBuiltinChecks下载/加载内置检查策略，同时支持自定义 Rego 命名空间、Helm 变量覆盖、Terraform tfvars 与 CloudFormation 参数文件等（pkg/commands/artifact/run.go）。更详细的说明可参考 错误配置扫描文档。

2.3 Secrets（默认启用）

密钥扫描默认开启：

$ trivy fs /path/to/project

Trivy 会扫描目录中的明文文件，按内置规则检测 AWS Access Key、GCP Service Account、GitHub/GitLab Personal Access Token、Slack Token、私钥等，并支持通过trivy-secret.yaml配置文件自定义规则、allow-rules、启用/禁用内置规则以及 skip-patterns（详见 密钥扫描文档）。--secret-config可指定自定义配置文件路径。

针对 filesystem 扫描的性能，官方文档建议用--skip-dirs或--skip-files跳过不需要扫描的目录与文件（如**/vendor/**），以显著加速密钥扫描；配置文件中的skip-patterns会整体替换默认跳过列表而非合并，需要注意。

2.4 Licenses（默认禁用）

许可证扫描默认关闭，通过--scanners license启用：

$ trivy fs --scanners license /path/to/project

它用于检测依赖与源码中的开源许可证信息，相关参数包括：

• --license-confidence-level：许可证分类器置信度阈值（默认0.9）；
• --license-full：额外扫描源码文件头部与许可证文件（该模式开销较大，源码中disabledAnalyzers只有在--scanners license与--license-full同时出现时才保留许可证文件分析器，见 run.go）；
• --ignored-licenses：指定要忽略的许可证列表。

详细说明可参考 许可证扫描文档。

三、按需组合扫描器

--scanners支持逗号分隔的多个取值，你可以按需组合。例如同时启用四类扫描：

$ trivy fs --scanners vuln,misconfig,secret,license /path/to/project

只扫描错误配置与许可证：

$ trivy fs --scanners misconfig,license /path/to/project

注意：关闭密钥扫描还能提升扫描速度，源码中当未启用 secret scanner 时会禁用analyzer.TypeSecret（run.go），从而跳过整个密钥分析流程。

四、SBOM 生成

trivy fs还可以为本地项目生成 SBOM（软件物料清单）。通过--format指定输出格式即可，例如：

$ trivy fs --format cyclonedx --output result.cdx.json /path/to/project

支持的 SBOM 格式包括cyclonedx、spdx、spdx-json（完整格式列表见 trivy_filesystem.md 的--format选项）。生成的 SBOM 会完整列出检测到的依赖包清单。源码中，当输出格式为 SPDX/CycloneDX 时，会为包文件计算校验和（fileChecksum = true，见 run.go），以保证 SBOM 中包条目的可验证性。更多细节可参考 SBOM 文档。

五、Scan Cache：Git 仓库场景下的缓存行为

与容器镜像扫描不同，trivy fs默认不使用扫描缓存（即内存后端），每次扫描都会重新分析文件。但存在一个重要例外：

当本地项目是一个状态干净的 Git 仓库（clean status），并且启用了内存之外的其他缓存后端（如fs或redis）时，Trivy 会以最新提交哈希（latest commit hash）作为缓存键存储分析结果。

$ trivy fs --cache-backend fs /path/to/git/repo

也就是说：在同一个 Git commit 上重复扫描会命中缓存、跳过重复分析；而一旦有了新的提交，缓存键变化，就会重新分析。这与 缓存文档 中描述的一致：filesystem 与 SBOM 扫描默认使用 memory 后端（进程结束后缓存即丢弃），而 fs/redis 后端才具备持久化能力。

从源码可以印证这一机制（pkg/fanal/artifact/local/fs.go）：

• NewArtifact会调用extractGitInfo打开 Git 仓库并提取 HEAD 提交哈希、分支、标签、提交信息与远端地址等元数据，同时通过worktree.Status().IsClean()判断仓库是否干净（fs.go、fs.go）；
• calcCacheKey中，若是干净的 Git 仓库则以commit hash + analyzer 版本 + handler 版本 + artifact 选项计算缓存键；否则（非 Git 仓库或脏仓库）生成随机 UUID 作为键——这意味着每次扫描都不会命中缓存（fs.go）；
• Inspect在命中缓存时直接返回已有的 BlobID，跳过文件遍历与分析（fs.go）。

由于缓存键还包含了分析器版本等信息，升级 Trivy 后即使 commit 未变，缓存也会自动失效重建，避免旧版本分析结果污染新版本报告。

另外，Trivy 针对文件系统遍历做了优化：当所有启用的分析器都实现了静态路径（StaticPath）时，会直接按静态路径分析目标文件（如锁文件、清单文件），而不必递归遍历整个目录树，从而提升扫描速度（fs.go）。文件遍历还支持--skip-dirs/--skip-files（支持 glob 模式）与--parallel并发数控制（默认 5）。

六、实用参数速查

以下参数在trivy fs场景中高频使用，均出自 trivy filesystem CLI 参考：

七、典型实战场景

7.1 CI 中门禁式漏洞检查

$ trivy fs --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed /path/to/project

发现 HIGH/CRITICAL 级且已有修复版本的漏洞时进程返回 1，从而让 CI 流水线失败；--ignore-unfixed可避免因厂商尚未发布补丁的漏洞阻塞发布。

7.2 输出 SARIF 对接代码平台

$ trivy fs --format sarif --output result.sarif /path/to/project

SARIF 格式可对接 GitHub、GitLab 等平台的代码扫描告警展示（参考 reporting.md 与 gitlab.tpl、gitlab-codequality.tpl 等模板）。

7.3 大规模仓库加速

• 用--skip-dirs node_modules,vendor --skip-files "**/*.min.js"跳过无关文件；
• 对 Git 仓库使用--cache-backend fs --cache-dir /tmp/trivy-cache复用跨次扫描的分析结果；
• 用--parallel调整并发度平衡 CPU 占用与扫描速度。

7.4 通过配置文件统一扫描参数

除了命令行参数，还可以使用trivy.yaml配置文件固化上述选项（默认加载，可用-c指定路径）。文件系统扫描相关配置与 CLI 标志一一对应，例如：

scanners: - vuln - secret format: table severity: - HIGH - CRITICAL exit-code: 1 skip-dirs: - node_modules - vendor skip-files: - "**/*.min.js"

完整配置字段定义可参考 config-file.md 与 schema/trivy-config.json。

八、小结

trivy fs是 Trivy 对本地项目进行安全体检的入口：默认启用漏洞与密钥扫描，按需开启错误配置与许可证扫描，并支持 SBOM 生成与可配置的扫描缓存。其默认行为与底层分析器调度逻辑可以在 pkg/commands/artifact/run.go 与 pkg/fanal/artifact/local/fs.go 中直接验证；配合 CLI 参考 中的完整参数表，可以针对 CI 门禁、SARIF 对接、大规模仓库提速等场景快速落地。相关主题还可进一步阅读 漏洞扫描、密钥扫描、错误配置扫描、许可证扫描 与 缓存配置 等文档。

【免费下载链接】trivyFind vulnerabilities, misconfigurations, secrets, SBOM in containers, Kubernetes, code repositories, clouds and more项目地址: https://gitcode.com/GitHub_Trending/tr/trivy