reachvuln

reachvuln

包含两百条发现项的扫描报告并不是待办清单。其中大多数软件包可能根本不会被你的代码加载；即使被加载，其中的易受攻击导出项也可能不是你导入的那个。reachvuln 会围绕这个问题重新排列报告：给定发现项、模块及其导入项，以及入口点，哪些发现项实际上可以被触达？

可达性基于你提供的导入图计算。若某个导入项的 package 与另一个模块的 path 相同，则它是本地边；其他情况都是外部软件包导入项。可达模块包括入口点，以及沿本地边从入口点到达的所有模块——采用广度优先遍历，并能安全处理循环，因此循环导入链既不会无限循环，也不会隐藏其后的模块。

如果某个可达模块导入了该发现项的软件包，并且该发现项未列出 vulnerable_exports（导入该软件包的任何内容都算），或该导入项的 names 与 vulnerable_exports 至少有一项相同，则该发现项为 reachable。如果某个模块导入了该软件包，但不满足可达条件，则该发现项为 imported_unreachable——该软件包位于导入树中，但没有可达模块以触及易受攻击导出项的方式导入它。如果没有任何模块导入该软件包，则该发现项为 not_imported。对于可达发现项，reached_via 会列出满足条件的可达模块路径（去重并排序）；否则该字段为空。

排名采用固定算法，而非启发式计算：严重性权重分别为 critical 40、high 30、medium 20、low 10；对于可达发现项，权重乘以 3；对于已导入但不可达的发现项，乘以 1；对于未导入的发现项，乘以 0。发现项按排名分数降序、严重性权重降序、id 升序排列，结果还会包含这三类发现项的计数。

验证严格，并会指出出错路径：vulnerabilities、modules 或 entry_points 缺失或类型不正确；发现项的 id 缺失、为空或重复，package 缺失或为空，severity 不属于枚举值，或 vulnerable_exports 类型不正确；模块的 path 缺失、为空或重复，imports 缺失，或导入项的 package 或 names 不正确；以及不属于模块路径的入口点。请注意，导入项 names 中的条目可以是空字符串——它们只会与易受攻击导出项不匹配，而易受攻击导出项本身必须非空。未知的额外字段会被忽略；输入无效时不会生成部分结果。计算是纯本地操作：不访问网络、不读取配置，也不读取任何代码仓库。

命令行

npx @reneturcios/reachvuln rank --input args.json
npx @reneturcios/reachvuln --version

args.json 包含完整的参数对象：

{
  "vulnerabilities": [
    {
      "id": "CVE-1",
      "package": "lodash",
      "severity": "high",
      "vulnerable_exports": ["merge"]
    }
  ],
  "modules": [
    {
      "path": "src/app.ts",
      "imports": [{ "package": "lodash", "names": ["merge"] }]
    }
  ],
  "entry_points": ["src/app.ts"]
}

结果以 JSON 格式打印：

{
  "ranked": [
    {
      "id": "CVE-1",
      "package": "lodash",
      "severity": "high",
      "reachability": "reachable",
      "rank_score": 90,
      "reached_via": ["src/app.ts"]
    }
  ],
  "counts": {
    "reachable": 1,
    "imported_unreachable": 0,
    "not_imported": 0
  }
}

退出代码：成功时为 0；发生运行时错误时为 1（包括输入文件无法读取或无效，以及输入无效）；使用方式错误时为 2。

MCP 服务

npx -y @reneturcios/reachvuln mcp

MCP 客户端配置：

{
  "mcpServers": {
    "reachvuln": {
      "command": "npx",
      "args": ["-y", "@reneturcios/reachvuln", "mcp"]
    }
  }
}

工具

• rank_vulns_by_reach — 根据易受攻击的软件包及其导出项能否从入口点访问，对漏洞发现进行排序。

  • vulnerabilities（数组，必填，可为空）— 发现项，每项为 {id, package, severity, vulnerable_exports}；id 是非空且唯一的字符串， package 是非空字符串，severity 是 critical、high、medium、low 之一，而 vulnerable_exports 是非空字符串数组，可选（默认为 []）
  • modules（数组，必填，可为空）— 模块， 每项为 {path, imports}；path 是非空且唯一的 字符串，imports 是 {package, names} 数组， 其中 package 是非空字符串，names 是必填字符串数组（条目可为空）
  • entry_points（数组，必填，可为空）— 作为入口点的模块路径；每个条目都必须 与某个模块的 path 相同

  返回 {ranked, counts}，其中每个排序条目为 {id, package, severity, reachability, rank_score, reached_via}，顺序固定；counts 为 {reachable, imported_unreachable, not_imported}。

Docker

docker run -i ghcr.io/cloudcorprecords/reachvuln
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/reachvuln rank --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios