enomoto11/vuln-symtrace-ts

# vuln-symtrace-ts 一个基于 OSV 的漏洞扫描器，它增加了一个分流步骤：它能告诉你你的代码实际使用了哪些易受攻击的依赖项——精确到单个导出（exports）——并将它们与每个安全公告（advisory）标记的内容进行交叉比对，让你能专注于代表真实风险的警报。 ## 问题所在 `npm audit` 和 Dependabot 会以相同的紧迫程度标记依赖树中的每一个易受攻击的包。在实际操作中，大多数警报来自你的代码从未触及的传递依赖项。团队要么追查每一个警报（浪费时间），要么完全忽略它们（错失真正的风险）。这两种结果都会造成损害。 ## symtrace 的作用 symtrace 会扫描你的依赖树，自行查询 OSV 数据库以获取已知漏洞，然后使用 TypeScript AST 分析 (ts-morph) 将每个易受攻击的包与你的实际源代码进行交叉比对，从而对其进行分类： | 级别 | 含义 | | -------------- | --------------------------------------------------------------- | | `needs-review` | 你的代码导入了的直接依赖项 | | `not-affected` | 从未被导入的直接依赖项 | | `transitive` | 间接依赖项；报告会显示是哪个直接依赖项引入了它 | 这让你能专注于少数代表真实风险的警报，而不是对所有警报一视同仁。 ## 工作原理 1. 检测并解析项目的 lockfile（`pnpm-lock.yaml`、`package-lock.json` 或 `yarn.lock`） 2. 通过 OSV API 查询每一个直接和间接依赖项 3. 对于每个易受攻击的包，使用 ts-morph 解析你的代码使用了它的哪些导出，以及在哪里使用的 4. 将使用的导出与每个安全公告指出的 API 进行交叉比对，对影响进行分类并生成报告 导入检测涵盖了静态导入、动态 `import()`、`require()` 以及重新导出（`export ... from`），包括像 `lodash/get` 这样的子路径导入和像 `@scope/pkg/sub` 这样的作用域子路径——这些都会被解析回它们所属的包。纯类型导入（Type-only imports）会被忽略，因为它们在编译时会被擦除。 ## 用法 ### 安装 无需安装直接运行： ``` npx vuln-symtrace-ts scan -p . ``` 或者全局安装 `symtrace` CLI： ``` npm install -g vuln-symtrace-ts ``` ### 扫描项目 ``` symtrace scan -p ./my-project ``` 选项： - `-p, --path ` — 要扫描的项目目录（默认：`.`） - `-t, --tsconfig ` — tsconfig 路径，相对于 `--path`（默认：`tsconfig.json`） - `-s, --severity ` — 触发非零退出代码的最低严重级别：`low` | `moderate` | `high` | `critical`（默认：`moderate`） - `--json` — 输出 JSON 而不是人类可读的文本 当 `needs-review` 包存在达到或超过严重性阈值的漏洞时，将以代码 `1` 退出，使其可用作 CI 门禁。 ### 抑制警报 要阻止特定漏洞导致 CI 门禁失败——例如你已经审查并接受的漏洞——请在扫描的项目目录中添加一个 `.symtracerc.json` 文件： ``` { "ignore": [ { "id": "GHSA-jf85-cpcp-j695", "reason": "not reachable — only the unaffected API is used", "expires": "2026-12-31" } ] } ``` - `id` — 要抑制的漏洞的 OSV id、GHSA id 或 CVE 别名。 - `reason` — 必填项，以确保每次抑制都有文档记录。 - `expires` — 可选的 ISO 日期（`YYYY-MM-DD`）。过期后，该规则将停止抑制，并且 symtrace 会打印警告，从而强制进行定期重新审查。 被抑制的漏洞仍会列在报告中（并附注其原因）；它们只是被排除在退出代码判断之外。 ### 检查单个包 ``` symtrace check -p lodash symtrace check -p lodash -v 4.17.20 ``` 在不进行代码分析的情况下通过 OSV API 查询包。 ## 严重性 漏洞的严重性取自 GitHub Advisory Database 的标签（如果存在），否则根据 CVSS 向量计算。支持 CVSS v3 和 v4 向量；v4 分数是近似值，GitHub Advisory 标签始终优先于它。 ## 公告交叉比对 对于每个 `needs-review` 漏洞，symtrace 会读取安全公告文本中指出的 API 名称，并将它们与你的代码使用的导出进行比较： - **审查优先级 (review priority)** — 你的代码使用了公告指出存在漏洞的导出 - **可能较低风险 (likely low)** — 公告指出了具体的导出，而你的代码没有使用其中任何一个 - _（无提示）_ — 公告未指出具体的 API，因此没有可比较的内容 这些提示指导你首先应该查看哪里；它们不是最终定论。它们永远不会改变退出代码——当满足严重性阈值时，`likely low` 结果仍然会导致 CI 门禁失败。公告匹配是一种保守的文本启发式方法（它读取反引号标注的 API 名称），因此请手动确认结果。 ## 支持的包管理器 pnpm、npm 和 yarn v1 (classic)。尚不支持 Yarn Berry (v2+)。 ## 环境要求 Node.js >= 20。 ## 范围与限制 symtrace 不能替代 `npm audit` 或 Dependabot——它只是增加了一个分流步骤。当前的限制： - 会解析你的代码使用了易受攻击包的哪些导出，并将它们与公告文本进行交叉比对，但公告匹配是一种保守的文本启发式方法，而且许多公告根本没有指出任何 API。提示仅作为指导，而非定论——请手动确认 `review priority` 和 `needs-review` 结果。参数级别的数据流分析已在计划中。 - 间接依赖项会被标记，但不会进行代码使用情况分析，因为你的代码通常不会直接导入它们。报告会显示引入每个间接依赖项的依赖链。 - 尚不支持 Workspaces / monorepos。symtrace 会根据一个 `tsconfig` 分析单个包，因此在包含多个包的 pnpm/npm/yarn workspace 中，直接/间接依赖的分类和导入分析可能不准确。建议改为在每个包目录中分别运行一次 symtrace。 - 通过 `allowJs` 支持纯 JavaScript（非 TypeScript）项目，但在缺少类型信息的情况下，符号解析的准确性会较低。 ## 状态 Beta (0.1.x)。仅支持单仓库扫描。 ## 许可证 MIT

标签：MITM代理, TypeScript, WebSocket, 依赖分析, 安全插件, 漏洞分诊, 自动化攻击, 错误基检测, 静态代码分析