Trivy 仓库扫描全指南：使用 trivy repository 命令检测代码仓库中的漏洞、错误配置、密钥与许可证

Trivy 仓库扫描全指南使用 trivy repository 命令检测代码仓库中的漏洞、错误配置、密钥与许可证【免费下载链接】trivyFind vulnerabilities, misconfigurations, secrets, SBOM in containers, Kubernetes, code repositories, clouds and more项目地址: https://gitcode.com/GitHub_Trending/tr/trivy导读本文以 Trivy 官方 CLI 参考文档trivy repository别名trivy repo为核心系统讲解如何对本地或远程 Git 仓库执行安全扫描。你将掌握该子命令的完整参数体系Git 分支/提交/标签定位、扫描器选择、漏洞过滤、配置扫描、密钥与许可证扫描、缓存与认证等并通过仓库源码理解其底层实现原理——包括本地/远程仓库的自动判定、临时克隆流程、Git 元数据提取与基于 commit hash 的缓存机制从而能够在本地开发机与 CI 流水线中高效、精准地落地代码仓库安全扫描。命令概览扫描一个代码仓库trivy repository是 Trivy 统一安全扫描器面向Git 代码仓库的子命令用于扫描仓库中的漏洞Vulnerabilities错误配置Misconfigurations密钥Secrets许可证Licenses其基本语法为trivy repository [flags] (REPO_PATH | REPO_URL)其中参数可以是本地仓库路径REPO_PATH或远程仓库 URLREPO_URL。默认情况下漏洞扫描与密钥扫描处于启用状态可通过--scanners参数配置。从源码看该子命令在 pkg/commands/app.go 中通过NewRepositoryCommand构建注册了repository名称与repo别名声明为Use: repository [flags] (REPO_PATH | REPO_URL)并最终调用artifact.Run(cmd.Context(), options, artifact.TargetRepository)进入扫描主流程。与镜像/文件系统扫描的本质区别trivy repo专为代码仓库设计适用于本机或 CI 环境中的仓库扫描。与容器镜像、VM 镜像扫描不同它面向 lockfile如package-lock.json、Gemfile.lock而不面向 JAR、二进制等构建产物。这一设计在 pkg/commands/artifact/run.go 的ScanRepository中体现得十分直接将PkgTypes强制设为library不扫描 OS 包禁用 OS 分析器、独立包分析器与 SBOM 分析器。同时trivy repo子命令在构建时被去掉了--distro标志见 pkg/commands/app.go因为仓库扫描不涉及操作系统发行版。快速上手本地与远程仓库扫描示例原 CLI 参考文档给出的两个基础示例# 扫描远程 Git 仓库 $ trivy repo https://github.com/knqyf263/trivy-ci-test # 扫描本地 Git 仓库 $ trivy repo /path/to/your/repository结合目标指南 docs/guide/target/repository.md还有更多实用形态# 扫描当前目录作为 Git 仓库 $ trivy repo ./ # 扫描单个 lockfile 文件 $ trivy repo ./trivy-ci-test/Pipfile.lock # 仅做配置错误扫描 $ trivy repo --scanners misconfig (REPO_PATH | REPO_URL) # 启用许可证扫描 $ trivy repo --scanners license (REPO_PATH | REPO_URL) # 以 JSON 格式输出附带 Git 元数据 $ trivy repo --format json repo-name一次典型的漏洞扫描输出形如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)由于仓库扫描不检测 OS 包输出中的 WARN 提示属于预期行为可结合--skip-version-check、-q/--quiet等参数在 CI 中精简日志。参数详解按功能分类的完整选项表本节完整覆盖trivy repository参考页列出的全部选项并按用途分组说明方便按需查阅。Git 仓库定位分支、提交与标签这三个参数由 pkg/flag/repo_flags.go 定义对应配置键repository.branch、repository.commit、repository.tag用于指定扫描远程仓库的特定版本参数说明--branch string指定要扫描的分支名例如trivy repo --branch main repo--commit string指定要扫描的 commit hash例如trivy repo --commit hash repo--tag string指定要扫描的标签名例如trivy repo --tag v1.2.3 repo三者均可同时作用于远程 URL。底层实现在 pkg/fanal/artifact/repo/git.go 的cloneRepo函数中指定--branch或--tag时会设置ReferenceName与SingleBranchtrue做单分支浅克隆指定--commit时则会先完整克隆Depth1仅在没有 commit 参数时启用随后通过Worktree().Checkout检出对应提交。该文件的测试 pkg/fanal/artifact/repo/git_test.go 覆盖了有效/无效分支、标签、提交以及远程/本地仓库等场景。扫描器与扫描范围参数说明--scanners strings逗号分隔的扫描器列表可选vuln,misconfig,secret,license默认[vuln,secret]--skip-dirs strings跳过指定目录或 glob 模式--skip-files strings跳过指定文件或 glob 模式--file-patterns strings指定配置文件匹配模式--include-dev-deps在报告中包含开发依赖支持 npm、yarn、gradle--pkg-types strings包类型列表可选os,library默认[os,library]仓库扫描强制为 library--pkg-relationships strings包关系列表可选unknown,root,workspace,direct,indirect默认全选--list-all-pkgs在 JSON 报告中输出所有包无论是否有漏洞默认true--dependency-tree[EXPERIMENTAL] 展示存在漏洞包之间的依赖来源树--misconfig-scanners strings用于配置扫描的子扫描器默认[azure-arm,cloudformation,dockerfile,helm,kubernetes,terraform,terraformplan-json,terraformplan-snapshot,ansible]--raw-config-scanners strings指定同时扫描原始配置的扫描器类型可选terraform--include-non-failures在--scanners misconfig下包含成功项其中--skip-dirs、--skip-files最终会写入walker.Option控制文件遍历见 pkg/commands/artifact/run.go--parallel默认 5则决定并行分析文件的 goroutine 数量设置为 0 时自动探测并行度。漏洞扫描相关参数说明-s, --severity strings展示的漏洞等级可选UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL默认全部--ignore-unfixed只显示已提供修复版本的漏洞--ignore-status strings忽略指定漏洞状态unknown,not_affected,affected,fixed,under_investigation,will_not_fix,fix_deferred,end_of_life--ignore-policy string指定用于评估每个漏洞的 Rego 文件路径--ignorefile string指定.trivyignore文件默认.trivyignore--exit-code int发现安全问题时返回的退出码--detection-priority string检测优先级precise默认最小化误报或comprehensive追求更多发现可能引入误报--vuln-severity-source strings漏洞等级数据源优先级nvd、redhat、debian、ubuntu、ghsa、osv、auto 等默认[auto]--offline-scan不发 API 请求识别依赖--skip-db-update跳过漏洞数据库更新--download-db-only只下载/更新漏洞数据库而不执行扫描--db-repository strings获取 trivy-db 的 OCI 仓库按优先级默认[mirror.gcr.io/aquasec/trivy-db:2,ghcr.io/aquasecurity/trivy-db:2]--skip-java-db-update跳过 Java 索引数据库更新--download-java-db-only只下载/更新 Java 索引数据库而不执行扫描--java-db-repository strings获取 trivy-java-db 的 OCI 仓库按优先级默认[mirror.gcr.io/aquasec/trivy-java-db:1,ghcr.io/aquasecurity/trivy-java-db:1]--show-suppressed[EXPERIMENTAL] 展示被抑制的漏洞关于数据库初始化逻辑可参见 pkg/commands/artifact/run.go仅当启用漏洞扫描且非 client/server 模式时才下载漏洞数据库--download-db-only会触发SkipScan提前结束。检测优先级为comprehensive时还会禁用系统文件过滤的后处理器见 pkg/commands/artifact/run.go。配置Misconfiguration扫描相关参数说明--config-check strings指定 Rego 检查文件或目录的路径并应用配置文件--config-data strings指定递归加载 Rego 检查数据的路径--config-file-schemas strings指定 JSON 配置文件 schema 路径用于类型检查--check-namespaces stringsRego 命名空间--checks-bundle-repository string获取 checks bundle 的 OCI 仓库默认mirror.gcr.io/aquasec/trivy-checks:2--skip-check-update跳过获取 Rego 检查更新--include-deprecated-checks包含已弃用的检查--rego-error-limit intRego 策略评估期间允许的最大编译错误数默认 10--trace-rego为自定义查询启用更详细的 Rego trace 输出--helm-api-versions strings与helm template --api-versions相同的 API 版本列表--helm-kube-version string与helm template --kube-version相同的 K8s 版本--helm-set strings命令行指定 Helm valueskey1val1,key2val2--helm-set-file strings从文件指定 Helm valueskey1path1,key2path2--helm-set-string strings以字符串形式指定 Helm values--helm-values strings覆盖 Helm values.yaml 文件的路径--tf-vars strings覆盖 Terraform tfvars 文件的路径--tf-exclude-downloaded-modules排除已下载 Terraform 模块的错误配置--cf-params strings覆盖 CloudFormation 参数文件的路径--ansible-extra-vars strings以keyvalue或fileYAML/JSON形式设置额外变量--ansible-inventory strings指定 inventory 主机路径或逗号分隔的主机列表--ansible-playbook strings指定要扫描的 playbook 文件路径这些配置会在 pkg/commands/artifact/run.go 的initMisconfScannerOption中被组装进misconf.ScannerOption其中--ansible-extra-vars支持file前缀自动按 JSON/YAML 解析或keyvalue两种写法。配置扫描默认关闭需显式--scanners misconfig开启。密钥扫描相关参数说明--secret-config string指定密钥扫描的配置文件路径默认trivy-secret.yaml密钥扫描默认开启--scanners默认含secret。在 pkg/commands/artifact/run.go 中若未启用 secret 扫描器则清空SecretConfigPath启用时则会提示参考密钥扫描文档以加快检测。许可证扫描相关参数说明--license-full在源码文件头与许可证文件中主动查找许可证--license-confidence-level float许可证分类器的置信度阈值默认 0.9--ignored-licenses strings指定要忽略的许可证列表许可证扫描默认关闭需--scanners license开启。--license-full与许可证扫描器同时启用时才会启用昂贵的文件头分析见 pkg/commands/artifact/run.go。输出与报告参数说明-f, --format string输出格式可选table,json,template,sarif,cyclonedx,spdx,spdx-json,github,cosign-vuln默认table-t, --template string输出模板文件必须以.tpl结尾-o, --output string输出文件名--output-plugin-arg string[EXPERIMENTAL] 输出插件参数--table-mode strings[EXPERIMENTAL] table 格式展示的表格可选summary,detailed默认[summary,detailed]注意trivy repo子命令移除了--report、--compliance与--exit-on-eol标志见 pkg/commands/app.go。缓存、并行与远程模式参数说明--cache-backend string[EXPERIMENTAL] 缓存后端如redis://localhost:6379默认fs--cache-ttl duration使用 redis 缓存后端时的缓存 TTL--redis-ca stringredis 缓存后端的 CA 文件路径--redis-cert stringredis 证书文件路径--redis-key stringredis 密钥文件路径--redis-tls使用公共证书启用 redis TLS--parallel int并行扫描的 goroutine 数0 表示自动探测默认 5认证与私有仓库参数说明--username strings用户名支持逗号分隔--password strings密码支持逗号分隔出于安全考虑应使用TRIVY_PASSWORD环境变量--password-stdin从 stdin 读取密码不支持逗号分隔--registry-token stringregistry token--token stringclient/server 模式的认证 token--token-header stringclient/server 模式 token 的 header 名默认Trivy-Token--custom-headers stringsclient 模式下的自定义 header--server stringclient 模式下的 server 地址--insecure允许不安全的服务器连接模块、SBOM 与杂项参数说明--enable-modules strings[EXPERIMENTAL] 要启用的 WASM 模块名--module-dir stringWASM 模块加载目录默认$HOME/.trivy/modules--sbom-sources strings[EXPERIMENTAL] 从指定来源oci,rekor尝试获取 SBOM--rekor-url string[EXPERIMENTAL] rekor STL 服务器地址默认https://rekor.sigstore.dev--vex strings[EXPERIMENTAL] VEX 来源repo、oci或文件路径--skip-vex-repo-update[EXPERIMENTAL] 跳过 VEX 仓库更新--no-progress抑制进度条--skip-version-check抑制版本更新提示与 Trivy 公告--disable-telemetry禁用向 Aqua 发送匿名使用数据继承自父命令的选项以下选项为所有子命令共享见 docs/guide/references/configuration/cli/trivy.md参数说明--cacert stringPEM 编码的 CA 证书文件路径--cache-dir string缓存目录-c, --config string配置文件路径默认trivy.yaml-d, --debug调试模式--generate-default-config将默认配置写入trivy-default.yaml-q, --quiet抑制进度条与日志输出--timeout duration超时时间默认5m0s-v, --version显示版本-h, --help显示帮助源码实现剖析trivy repo是如何工作的本地 vs 远程仓库的自动判定NewArtifact 采用“先本地、后远程”的容错策略先通过tryLocalRepo检查参数是否为本机存在的路径os.Stat存在则直接用本地目录构造 artifact失败后再走tryRemoteRepo将参数解析为 URL省略 scheme 时自动补全https://见newURL因此github.com/aquasecurity/trivy这种写法也合法克隆到临时目录git-clone-*后按本地文件系统扫描并在结束时清理临时目录。对应到扫描服务装配pkg/commands/artifact/scanner.go 中的repositoryStandaloneScanService使用walker.NewFS()遍历仓库文件client/server 模式下则由 repositoryRemoteScanService 将仓库数据发往 Trivy Server 处理。私有仓库认证gitAuth()pkg/fanal/artifact/repo/git.go依次检查环境变量GITHUB_TOKEN与GITLAB_TOKEN并以固定用户名fanal-aquasecurity-scan构造 BasicAuth若均未设置则匿名访问。需要注意GITHUB_TOKEN优先于GITLAB_TOKEN因此扫描私有 GitLab 仓库前必须确保GITHUB_TOKEN未设置。此外git_test.go 中的认证测试 还验证了将凭据直接内嵌在 URLhttps://user:passhost/repo.git的用法。URL 内嵌凭据在报告元数据中会被sanitizeRemoteURL脱敏处理见 pkg/fanal/artifact/local/fs.go。Git 元数据与扫描缓存扫描 Git 仓库时extractGitInfo 会自动提取仓库元数据仓库 URL优先 upstream回退 origin分支名、指向 HEAD 的所有标签commit hash、提交信息、作者与提交者信息这些信息在 JSON 输出中位于Metadata字段RepoMetadata。缓存方面工作区干净的 Git 仓库以最新 commit hash 计算缓存键结合分析器版本、handler 版本与 artifact 选项命中后直接复用分析结果工作区 dirty时则改用随机 UUID 作为缓存键且不使用缓存——这是为了避免遗漏未提交的新文件见 pkg/fanal/artifact/local/fs.go。相关测试TestArtifact_Inspect覆盖了 remote/local/dirty/cache hit 四种场景pkg/fanal/artifact/repo/git_test.go。扫描主流程trivy repo与其余子命令共用 run 三阶段流程扫描Scan→ 过滤Filter应用--ignore-unfixed、--severity、.trivyignore等→ 报告Report按--format/--template输出并在结束时依据--exit-code返回退出码。WASM 模块--enable-modules/--module-dir与 VEX 仓库--vex/--skip-vex-repo-update的初始化同样发生在 runner 构建阶段pkg/commands/artifact/run.go。实战建议在 CI 中扫描仓库trivy repo --scanners vuln,secret,misconfig \ --severity HIGH,CRITICAL \ --ignore-unfixed \ --exit-code 1 \ --skip-db-update \ --no-progress \ https://github.com/your-org/your-repo--exit-code 1可在发现高危及以上问题时让流水线失败--skip-db-update适合配合定期预热缓存的流水线加快执行速度使用-q/--quiet或--no-progress精简日志避免污染 CI 输出。扫描私有仓库# GitHub 私有仓库 $ export GITHUB_TOKENyour_private_github_token $ trivy repo your private GitHub repo URL # GitLab 私有仓库注意先 unset GITHUB_TOKEN $ export GITLAB_TOKENyour_private_gitlab_token $ trivy repo your private GitLab repo URL生成 SBOM 与审计报告# 生成 CycloneDX SBOM $ trivy repo --format cyclonedx -o sbom.cdx.json repo # 输出 SARIF 供代码扫描平台消费 $ trivy repo --format sarif -o result.sarif repo # 使用自定义模板 $ trivy repo --format template --template contrib/html.tpl -o report.html repo仓库内置了可直接参考的模板示例如 contrib/html.tpl、contrib/junit.tpl、contrib/gitlab.tpl。SBOM 生成的更多细节见 docs/guide/supply-chain/sbom.md。相关文档子命令参考trivy repository、trivy目标指南Code Repository扫描器详解vulnerability、misconfiguration、secret、license缓存机制Cache【免费下载链接】trivyFind vulnerabilities, misconfigurations, secrets, SBOM in containers, Kubernetes, code repositories, clouds and more项目地址: https://gitcode.com/GitHub_Trending/tr/trivy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考