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 fsfilesystem子命令展开讲解如何对本地项目目录、单个文件乃至 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] PATHfs是其别名详见 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.6520300 WARN OS is not detected and vulnerabilities in OS packages are not detected. 2020-06-01T17:06:58.6520300 INFO Detecting pipenv vulnerabilities... 2020-06-01T17:06:58.6910300 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.gofunc (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/projectTrivy 会扫描目录中的明文文件按内置规则检测 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.TypeSecretrun.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 CacheGit 仓库场景下的缓存行为与容器镜像扫描不同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.goNewArtifact会调用extractGitInfo打开 Git 仓库并提取 HEAD 提交哈希、分支、标签、提交信息与远端地址等元数据同时通过worktree.Status().IsClean()判断仓库是否干净fs.go、fs.gocalcCacheKey中若是干净的 Git 仓库则以commit hash analyzer 版本 handler 版本 artifact 选项计算缓存键否则非 Git 仓库或脏仓库生成随机 UUID 作为键——这意味着每次扫描都不会命中缓存fs.goInspect在命中缓存时直接返回已有的 BlobID跳过文件遍历与分析fs.go。由于缓存键还包含了分析器版本等信息升级 Trivy 后即使 commit 未变缓存也会自动失效重建避免旧版本分析结果污染新版本报告。另外Trivy 针对文件系统遍历做了优化当所有启用的分析器都实现了静态路径StaticPath时会直接按静态路径分析目标文件如锁文件、清单文件而不必递归遍历整个目录树从而提升扫描速度fs.go。文件遍历还支持--skip-dirs/--skip-files支持 glob 模式与--parallel并发数控制默认 5。六、实用参数速查以下参数在trivy fs场景中高频使用均出自 trivy filesystem CLI 参考参数作用默认值--scanners启用哪些扫描器vuln,misconfig,secret,licensevuln,secret-f, --format输出格式table、json、template、sarif、cyclonedx、spdx、spdx-json、github、cosign-vulntable-o, --output输出文件路径--s, --severity展示的严重级别UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL全部--exit-code发现安全问题时进程退出码便于 CI 集成---skip-dirs/--skip-files跳过指定目录/文件支持 glob---ignore-unfixed只显示有修复版本的漏洞---ignorefile指定.trivyignore文件路径.trivyignore--cache-backend缓存后端memory、fs、redis://[HOST]:[PORT]memory--cache-dir缓存目录---cache-ttlRedis 缓存 TTL---detection-priorityprecise低误报或comprehensive更全但可能有误报precise--pkg-types包类型过滤os,libraryos,library--pkg-relationships依赖关系过滤unknown,root,workspace,direct,indirect全部--secret-config密钥扫描配置文件trivy-secret.yaml--misconfig-scannersmisconfig 扫描器列表见上文默认值--parallel并行扫描 goroutine 数0表示自动检测5--timeout扫描超时时间5m0s-c, --config全局配置文件路径trivy.yaml--skip-db-update/--skip-check-update跳过漏洞库/检查包更新-七、典型实战场景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/projectSARIF 格式可对接 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考