valvur

状态：1.6.0，这是此代码树声明的版本；上方的 PyPI 徽章显示 pip install valvur 提供的版本，更新日志则记录了各版本的变更。

在 Claude Code 中：/plugin marketplace add MaverickHQ/valvur，然后运行 /plugin install valvur@valvur，并让它扫描项目。
**在终端中，**确保 Docker 或 Podman 正在运行，然后执行：uvx valvur scan。

为什么选择 valvur

• **七款扫描器，一份报告。**Gitleaks、Trivy、OSV-Scanner、Opengrep、Checkov、zizmor 和 Syft 均已固定版本、安装并在同一个容器中运行，同时 valvur 还会执行自身针对 AI 编写代码的检查。两个扫描器报告的同一个漏洞只会作为一条结果，而非两条， 并且所有结果都会统一排序。
• **有证据证明没有任何内容离开你的设备。**无需账号、API 密钥，也没有遥测数据。 扫描器在没有网络接口的容器中运行，源码会复制进去，而不会挂载。每次获取公开 数据都会记录在 run.json 中，文件还会说明有什么内容离开了设备：什么也没有。 运行一条命令即可验证。
• **专为 AI 生成代码的常见问题打造。**模型会编造攻击者随后注册的包名；Agent 指令 文件可能包含注入的指令和隐藏的 Unicode 字符；Agent 设置可能泄露令牌。valvur 会离线检查这些问题，同时检查传统的密钥、存在漏洞的依赖项和错误配置。
• **只呈现十条重要结果，而不是四百条。**根据攻击者是否正在利用这些问题对结果排序， 排序依据是 CISA KEV 和 FIRST EPSS，而非仅看 CVSS；结果会按规则和目录分组， 仅用于开发的依赖项则会降低优先级。
• **由你掌控。**valvur 会提出修复建议，但绝不会自行应用。被要求将结果清零的 Agent 可能会删除代码或添加抑制规则；而结果消失了并不等于漏洞已修复。

它能发现什么

范围	valvur 报告的内容	由谁发现
虚构的软件包	不存在的依赖项，或名称只差一次编辑就会变成热门名称的依赖项；离线对照 PyPI、npm、RubyGems、Packagist 和 crates.io 上的所有名称进行检查	valvur 的 dependency-reality Check
恶意软件包	被发布为恶意软件包的依赖项，来源为 OpenSSF 的 malicious-packages	OSV-Scanner，以及同一个 Check
Agent 配置	注入的指令、隐藏的 Unicode、未固定版本的 MCP 服务、全盘批准、会运行命令的钩子、可能泄露信息的设置	valvur 的 ai-artifact Check
存在漏洞的依赖项	根据锁文件发现已知 CVE，按可利用性排序，并指出需要升级的直接依赖包	Trivy、OSV-Scanner
机密信息	文件和 git 历史记录中的凭据	Gitleaks
代码	注入、路径遍历、SSRF、开放重定向、XXE 和不安全 Cookie，以及流入 eval、shell、查询或 DOM 的模型输出	Opengrep，使用 valvur 的规则
基础设施	Terraform、CloudFormation、Kubernetes 和 Dockerfile 的错误配置	Checkov
CI 工作流	未固定版本的操作、写入权限、模板注入	zizmor
许可证和 SBOM	缺失或相互矛盾的项目许可证；按需生成 CycloneDX SBOM	valvur 的 licence-file Check、Syft

逐条查看检查内容及其盲区：valvur 的工作原理。

工作原理

1. 一个小型主机垫片决定扫描读取哪些内容（git 会发布的文件，以及 .env* 文件和 Agent 配置），获取所需的公开数据，并记录 每次获取。
2. 一个扫描容器没有网络接口，会对通过 stdin 输入的这些文件副本运行所有扫描器。 容器中的任何内容都无法更改你的源代码。
3. 一个发现结果模型会对扫描器报告的内容进行规范化和排序，垫片会将 结果文件夹写入你的项目：

.security-scan/          ← ignores itself in git, so it is never committed
├── SUMMARY.md           ← start here: the verdict, anything that failed, the top groups
├── REMEDIATION.md       ← a ranked proposal: you choose what to apply
├── findings.json        ← every finding, normalised, secrets redacted
├── results.sarif        ← SARIF 2.1.0, for code scanning and IDEs
└── run.json             ← what ran, what was fetched, and what left the machine: nothing

扫描结束时会给出 findings、clean 或 inconclusive。如果数据过时、 某个生态系统未经检查，或扫描器未能完成，以致无法支持 clean 结论，它就不会报告 clean，并会说明原因。

以实测为准，而非空口声称

valvur 声称能发现的内容有多少，是通过分数来衡量的：共九项指标，按照 OWASP Benchmark 的公式评分，并设有护栏，任何变更的分数都不能低于基准两分以上。总分为 100 分中的 74.1，在 Linux 和 macOS 上结果相同。

指标	内容	分数
sast-python	Python 的 OWASP Benchmark	40.9
sast-js	valvur 的 JavaScript 双胞测试：十种弱点，各有易受攻击和已修复版本	55.0
secrets	十种格式，涵盖文件和历史记录	100.0
dependencies	锁定到存在漏洞版本的锁文件；已知恶意软件包	100.0
package-reality	不存在、近似名称和恶意名称	100.0
agent-configuration	针对真实文件植入的指令和隐藏 Unicode	94.3
infrastructure	Terraform、Kubernetes、Dockerfile 和 Actions 配置错误	95.0
real-code-precision	48 个维护中的项目，每条发现结果都经过人工标注	2.3
llm-output	流入代码、shell、查询或 DOM 的模型输出：生成的双胞测试和五份已发布的安全公告	79.0

第 8 项指标衡量维护中代码的精确率，此类代码中几乎没有漏洞：171 条发现结果里只有 3 条是真实问题。第 9 项指标衡量模型输出流入接收端的规则：这些规则在生成的测试流中捕获了 34 条中的 30 条，且没有误报；但在 LangChain、LlamaIndex 和 Vanna 发布的五份安全公告中，没有一条被捕获，因为其中的流都跨越了一个函数。每条规则的精确率见 docs/RULES.md，评估方法、门槛以及 valvur 不会声称的内容见 docs/EVALUATING.md。请带着怀疑阅读。

使用方法

在 AI 编码 Agent 中

Claude Code 插件包含 MCP 服务、负责运行工作流的技能，以及一个钩子：在 Agent 安装 valvur 标记的软件包前询问你。Kiro 将其作为一种扩展能力使用。任何 MCP 客户端都可以通过 uvx --from valvur valvur-mcp 运行该服务。 Agent 指南介绍了 11 个客户端的配置、7 个工具，以及“无需询问”模式所需的权限。

在命令行中

扫描器在容器中运行，因此机器需要 Docker 或 Podman；valvur doctor 会指出缺少什么。

pip install valvur          # or: uv tool install valvur
valvur scan                 # offline by default; --profile full adds the registries' answers
valvur check npm left-pad   # before an install: real, a near-miss, or malicious?
valvur gate . --fail-on high --no-inconclusive

命令行指南介绍了所有命令、首次扫描会获取的内容、结果文件夹以及设置文件。

在 CI 中

- uses: MaverickHQ/valvur-action@16b19e275f843419887873ed536a71f872607e24 # v0.2
  with: { fail-on: high, no-inconclusive: "true" }

该操作会执行扫描，将 results.sarif 上传到代码扫描，并设置作业门禁。 CI 指南介绍了门禁、作为独立步骤的镜像，以及 GitLab。

基于开源扫描器构建

valvur 不构建检测引擎。检测工作由 7 个开源扫描器完成，它们值得获得认可；valvur 则增加了一个文件集、一种发现项模型、考虑漏洞利用情况的优先级排序，以及 3 项自有检查。所有工具都在同一个容器中运行，输入为文件副本。run.json 会记录每个已运行工具的版本，raw/ 则保留各工具的输出。

扫描器	许可证	读取内容	运行条件
Gitleaks	MIT	已扫描文件中的秘密，以及 Git 历史中的秘密；最多读取最新的 5,000 次提交或 200 MB	始终
Trivy	Apache-2.0	根据锁文件检查依赖项中的已知漏洞，并与主机缓存中的数据库比对	始终
OSV-Scanner	Apache-2.0	根据 OSV 数据检查锁文件；该数据包含此处其他工具均未报告的已知恶意 MAL- 软件包。在 offline 模式下，使用针对每个已发现生态系统的 OSV 离线数据库，并将其获取到主机缓存；在 full 模式下，使用 OSV.dev API，该 API 会接收锁文件中的名称和版本	始终
Opengrep	LGPL-2.1	静态分析：固定版本规则、INFO 级别的汇点清单、从模型调用到汇点的污点规则，以及来自请求数据的污点规则	始终
Checkov	Apache-2.0	基础设施配置错误：Terraform、CloudFormation、Kubernetes、Dockerfile、其他 CI 系统	存在 GitHub 工作流以外的基础设施时
zizmor	MIT	GitHub Actions 工作流：未固定版本的操作、写入权限、模板注入	存在工作流时
Syft	Apache-2.0	SBOM，以及从中读取的依赖项许可证	按需运行：scan --sbom，或在 [scan] 下设置 sbom = true

检查项	读取内容
ai-artifact	Agent 配置：注入的指令、隐藏的 Unicode、未固定版本的 MCP 服务、全局批准、运行命令的钩子，以及可能泄露信息的本地设置
dependency-reality	根据名称索引检查每个已声明的依赖项：是否存在；在 full 模式下，还会检查其年代和采用情况。根据已知恶意列表检查每个已声明或已锁定的依赖项；该列表每日根据 OpenSSF 的恶意软件包数据构建
licence-file	项目自身的许可证：是否缺失，或与清单声明的许可证相矛盾

漏洞利用情报来自 CISA KEV 和 FIRST EPSS：公开的一手来源，可审计，也可镜像。没有专有数据库，也不会让你受制于单一厂商。

它不会做什么

• 不进行可达性分析。 我们不会证明某个易受攻击的函数已被调用。
• 不自动修复。 修复方式由你选择。
• 不进行渗透测试。 不做 DAST、不利用漏洞，也不扫描已部署的系统。
• 不分析代码质量。 仅关注安全。
• 我们不会比商业 SAST 检测出更多问题。 我们的优势在于可信度、单一工件中的广泛覆盖和优先级排序，而非引擎深度。

平台

平台	支持情况
Linux、Docker 和 Podman	支持。每次提交都会在 amd64 上针对 Docker 和 Podman、在 arm64 上针对 Docker 运行端到端测试套件，并使用已发布的镜像进行扫描；验收测试集每晚在 GitHub 的 Linux 运行器上运行
macOS、Docker Desktop 或 Podman	支持，并且在每个阶段结束时，都会在 Apple 芯片 Mac 上通过 Docker Desktop 手动测试：运行验收测试集，以及针对由该提交构建的镜像运行端到端测试套件（docs/acceptance/）。不会在每次提交时测试：容器运行时需要嵌套虚拟化，而 GitHub 的 macOS 运行器不支持这一点
linux/amd64 和 linux/arm64	两种架构均支持：一个镜像索引，带签名，并为每种架构提供 SBOM
通过 WSL2 使用 Windows	支持：在 WSL 中，valvur 运行于 Linux 上
原生 Windows	**不作支持承诺。**未经测试，valvur 启动时也会明确说明
启用 SELinux 强制模式的主机（RHEL、Fedora）	支持。你的源代码会被复制到扫描环境中，绝不会挂载，因此其 SELinux 标签无关紧要；valvur 会为自己的缓存挂载点设置标签

无法联网？ 数据库、Name Index 及其恶意列表、KEV、EPSS 和 OSV 的数据库都位于镜像之外，并且每项都支持镜像源设置。参见 docs/AIR-GAPPED.md。

隐私

valvur 不收集任何信息：不需要账户或 API 密钥，不进行遥测，也不会以任何方式报告你的信息或代码。结果保存在 .security-scan/ 中，该目录会在 git 中忽略自身。主机获取的都是公开数据，每次获取都会记录在 run.json 中。 python3 scripts/verify-offline.py 会对其进行检查；在 Linux 上，unshare -rn valvur scan 可以证明这一点 （原理）。

文档

指南	适用内容
工作原理	离线证明、每项检查和排名
AI 编码 Agent	插件、权限、十一个 MCP 客户端和七种工具
命令行	命令、结果文件夹和设置
CI	门禁、GitHub Action 和流水线中的镜像
评估 valvur	审计：评分、门禁和限制
规则	每条静态分析规则经测量的精确率
隔离网络环境下使用	每个数据源的镜像源
所有文档	协议、决策、发布和记录

社区与支持

• 问题和想法：讨论区。
• **错误报告及 valvur 漏掉的问题：**https://github.com/MaverickHQ/valvur/issues，并附上 valvur doctor --bundle 生成的 tarball：其中包含版本信息和最近一次 run.json，绝不包含你的源代码、原始输出或发现的问题。
• **安全问题：**如果怀疑 valvur 存在漏洞，包括误报 clean 的情况，请通过 SECURITY.md 私下报告。
• 贡献：CONTRIBUTING.md 介绍了环境设置，以及原则上拒绝的事项清单。MAINTAINERS.md 说明了谁在维护 valvur，目前只有一人，以及你可以依赖哪些承诺。没有付费版本，也没有支持合同。

许可证

Apache-2.0，详见 LICENSE；选择它而非 MIT，是因为它明确授予专利许可。 捆绑的扫描器保留各自的许可证，已在上文和 NOTICE 中列出。valvur 不包含 GPL 或 AGPL 组件；与所有 Linux 容器一样，Alpine 基础镜像包含 GPL 用户空间组件，已发布的 SBOM 会披露全部内容 （ADR-0005）。