vuln-check

vuln-check

为 AI Agent 提供准确的漏洞信息。在本地运行 grype，合并 OSV 时效性补充数据，并返回带有具体升级目标的优先级建议，而不是 40 KB 的 JSON 转储。

• 支持任何带锁文件的语言（npm、PyPI、Go、Maven、Cargo、RubyGems、Composer、NuGet、Hex、Pub、Swift、R、Conan……），以及操作系统软件包、容器镜像和 SBOM。
• 每个发现项一个评分：CVSS + EPSS + CISA KEV + 修复可用性。
• 每个软件包提供修复计划：能够解决所有发现项的最低版本，并标记 breaking。
• CLEAN 约占 20 个 token。不会在服务器上运行任何程序；除可选的 OSV 查询外，任何内容都不会离开你的设备。

安装

# grype is required
brew install grype            # or: curl -sSfL https://get.anchore.io/grype | sh -s -- -b /usr/local/bin

go install github.com/ciloops/vuln-check/cmd/vuln-check@latest
# or
brew install ciloops/tap/vuln-check      # macOS cask
# or
npx @ciloops/vuln-check scan .

Linux/macOS/Windows 二进制文件可在 Releases 页面获取。Docker：ghcr.io/ciloops/vuln-check（包含 grype）。

CLI

vuln-check scan .                               # agent format, OSV overlay on
vuln-check scan python:3.12-slim                # image, pulled from the registry
vuln-check scan sbom:bom.cdx.json
vuln-check scan --format sarif --sarif-out out.sarif .
vuln-check scan --fail-above 69 --no-osv .      # CI gate, exit 2 above threshold
vuln-check vuln CVE-2024-3094
vuln-check db update

输出（--format agent）：

{"status":"ACTION_REQUIRED","target":"dir:.","packages":412,"findings":17,"shown":5,"sources":["grype","osv"],
 "actions":[{"package":"pkg:npm/minimist","current":"1.2.5","target":"1.2.6","breaking":false,"fixes":["CVE-2021-44906"],"score":59}],
 "top":[{"id":"CVE-2021-44906","package":"[email protected]","severity":"CRITICAL","score":59,"epss":0.015,"fixed_in":["1.2.6"]}],
 "unfixable":3}

status：CLEAN | REVIEW（所有发现项均 < 40）| ACTION_REQUIRED。fresh: true 表示这些公告在 grype-db 收录之前已由 OSV 提供。unfixable 统计当前发布分支中没有修复方案的发现项。

MCP

工具：scan_dir、scan_image、scan_sbom、vuln_lookup、db_update。

Claude Code：

claude mcp add vuln-check -- vuln-check mcp
# or the plugin (adds a skill that tells Claude when to scan):
claude plugin marketplace add ciloops/vuln-check && claude plugin install vuln-check

Cursor / Windsurf / VS Code（.cursor/mcp.json、~/.codeium/windsurf/mcp_config.json、.vscode/mcp.json）：

{ "mcpServers": { "vuln-check": { "command": "vuln-check", "args": ["mcp"] } } }

Codex（~/.codex/config.toml）：

[mcp_servers.vuln-check]
command = "vuln-check"
args = ["mcp"]

在参数中添加 --no-osv，即可避免将依赖列表发送到网络。

GitHub Action

- uses: ciloops/vuln-check@v1
  with:
    target: .            # or an image ref
    fail-above: 69
    sarif: vuln.sarif
- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with: { sarif_file: vuln.sarif }

评分

severity = CVSS 基础分 × 6（标签回退值） · exploit = EPSS × 30 · KEV：+10，最低 85 · 无修复方案：× 0.85。分数限制在 0–100 之间。参见 internal/score。

时效性

grype-db 每天构建，grype 最多每 2 h 刷新一次。OSV 补充数据会使用 grype 清点出的 purl 查询 api.osv.dev（仅限语言生态系统），并添加 grype-db 尚未收录的所有内容，通常在 GHSA 发布后几分钟内即可获取。使用 --no-osv 禁用。

限制

• 没有锁文件 → 无法发现传递依赖。这与所有扫描器的情况相同。
• 修复计划假定每个软件包都沿线性发布分支演进；目前无法区分直接依赖和传递依赖。
• 版本比较使用通用分词器，而非各生态系统专用解析器。对于“高于当前版本的最低修复版本”这一需求足够适用，但仍存在边缘情况（PEP 440 的 post-release 版本、Maven 的特殊限定符）。

开发

go test ./...
go build ./cmd/vuln-check

测试使用伪造的 grype（cmd/vuln-check/testdata/fake-grype.sh）和 internal/grype/testdata 中的测试数据。CI 会运行真实 grype 的端到端测试。

发布：打上 vX.Y.Z 标签 → goreleaser 发布二进制文件、校验和、ghcr 镜像、适用于 macOS 的 Homebrew cask（需要 HOMEBREW_TAP_GITHUB_TOKEN 和 ciloops/homebrew-tap 仓库），以及通过可信发布（OIDC，无需令牌）发布的 npm 包：在 npmjs.com 上为 @ciloops/vuln-check 配置 GitHub Actions 可信发布方，工作流为 release.yml。

许可证

Apache-2.0。grype 和 syft 由 Anchore 按 Apache-2.0 许可发布。漏洞数据：NVD（公有领域）、GHSA（CC-BY 4.0）、OSV（依各来源而定）、CISA KEV、FIRST EPSS。