Meru143/reachable

# reachable    `reachable` 是一个针对 JavaScript 和 TypeScript 的本地优先 CLI 工具，用于回答开发者在运行 `npm audit` 后提出的问题：易受攻击的代码路径真的可以从我的应用程序访问到吗？ 它使用 tree-sitter 解析 JavaScript 和 TypeScript，构建项目调用图，查询 OSV 咨询，并报告易受攻击的符号从您的入口点是可达的、未知的还是不可达的。 在线页面：[merup.me/reachable](https://merup.me/reachable/) 其目的不是替代包级别的扫描器。而是通过询问那些工具无法独自回答的下一个问题，来确定真正重要的工作：您的代码是否访问了易受攻击的符号？  - 通过区分 `REACHABLE`（可达）、`UNKNOWN`（未知）和 `UNREACHABLE`（不可达）的结果，减少依赖项中的误报干扰。 - 仅在代码路径真正重要时使 CI 失败，而不是针对 lockfile 中的每个 Advisory。 - 在本地或 GitHub Actions 中运行，无需托管服务、账户或 API Key。 ## 为什么选择 reachable？ `npm audit` 报告包级别的风险。它不知道您的代码是否导入或调用了易受攻击的函数。这会导致 CI 失败嘈杂、依赖项升级范围广泛，以及团队忽略整个审计报告。 `reachable` 增加了源码感知的分类： - 它从入口点通过您的代码进行追踪，而不是同等标记每个已安装的易受攻击包。 - 它区分 `REACHABLE`、`UNKNOWN` 和 `UNREACHABLE` 结果，使真正的风险浮出水面。 - 它在 CI 中本地运行，无需托管服务、账户或 API Key。 ## 为什么不直接用 `npm audit`？ | 工具 | 标记易受攻击的包 | 检查代码是否访问易受攻击符号 | 本地优先 CLI | | --- | --- | --- | --- | | `reachable` | 是 | 是 | 是 | | `npm audit` | 是 | 否 | 是 | | Dependabot alerts | 是 | 否 | 否 | ## 安装 ``` npm install -g @merupatel/reachable ``` 运行而不全局安装： ``` npx @merupatel/reachable@latest scan ``` ## 快速开始 扫描当前项目： ``` reachable scan --format table ``` 终端输出示例： ``` REACHABLE +-----------+---------+----------------------+------------+-------------------+ | Severity | Package | GHSA ID | Status | Vulnerable Symbol | +-----------+---------+----------------------+------------+-------------------+ | HIGH | lodash | GHSA-xxxx-yyyy-zzzz | REACHABLE | trim | +-----------+---------+----------------------+------------+-------------------+ src/index.ts::module src/index.ts::call:lodash.trim:12 UNREACHABLE +-----------+---------+----------------------+--------------+-------------------+ | Severity | Package | GHSA ID | Status | Vulnerable Symbol | +-----------+---------+----------------------+--------------+-------------------+ | HIGH | lodash | GHSA-aaaa-bbbb-cccc | UNREACHABLE | trim | +-----------+---------+----------------------+--------------+-------------------+ ``` 从入口点追踪包： ``` reachable trace lodash ``` 检查单个文件的导入、导出和可达符号： ``` reachable graph src/index.ts ``` ## 配置 `reachable` 从 `.reachablerc.json` 或 `reachable.config.js` 加载项目配置。 示例： ``` { "entry": ["src/index.ts", "src/worker.ts"], "failOn": "high", "ignore": ["GHSA-xxxx-xxxx-xxxx"], "devPackages": ["vitest", "@types/node"], "cache": { "ttlHours": 24, "dir": ".reachable-cache" } } ``` 配置字段： | 字段 | 类型 | 描述 | | --- | --- | --- | | `entry` | `string[]` | 当自动检测不足时的显式入口点 | | `failOn` | `critical \| high \| moderate \| low \| all` | 设置失败退出代码的最低可达严重级别 | | `ignore` | `string[]` | 要屏蔽的 GHSA ID | | `devPackages` | `string[]` | 视为仅开发环境并从 lockfile 分析中排除的包 | | `cache.ttlHours` | `number` | 咨询缓存 TTL | | `cache.dir` | `string` | 咨询缓存目录 | ## 标志参考 ### reachable scan | 标志 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | `--entry ` | `string[]` | 自动检测 | 覆盖检测到的入口点 | | `--format ` | `table \| json \| sarif \| markdown` | `table` | 输出格式 | | `--fail-on ` | `critical \| high \| moderate \| low \| all` | `high` | 失败阈值 | | `--reachable-only` | `boolean` | `false` | 仅显示可达的 Advisory | | `--no-cache` | `boolean` | `false` | 忽略并清除本地咨询缓存 | | `--dry-run` | `boolean` | `false` | 跳过远程咨询获取并仅使用缓存 | | `--quiet` | `boolean` | `false` | 抑制格式化输出 | | `--depth ` | `number` | `20` | 最大遍历深度 | | `--ignore ` | `string[]` | `[]` | 忽略 GHSA 标识符 | | `--cwd ` | `string` | 当前目录 | 要分析的项目根目录 | | `--verbose` | `boolean` | `false` | 启用调试日志 | ### reachable trace ``` reachable trace [--cwd ] [--entry ] ``` ### reachable graph ``` reachable graph [--cwd ] [--entry ] ``` ## CI 集成 极简 GitHub Actions 用法： ``` name: Reachability on: pull_request: jobs: reachable: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 22 cache: npm - run: npm ci - run: npx @merupatel/reachable@latest scan --format markdown --fail-on high ``` 使用 `--format sarif` 以馈送给 GitHub 代码扫描，或使用 `--format markdown` 发布对 PR 友好的摘要。 ## 开发 ``` npm ci npm run lint npm run test npm run test-integration npm run build ``` 该项目使用： - tree-sitter 用于源码解析 - commander 用于 CLI - vitest 用于单元和集成测试 - semantic-release 用于发布自动化 有关贡献者工作流程，请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。

标签：CI/CD 集成, CLI 工具, CMS安全, GitHub Actions, IP 地址批量处理, Java RMI, JavaScript, LNA, MITM代理, npm audit, OSV, Tree-sitter, TypeScript, Vercel, 依赖安全, 函数级分析, 可达性分析, 安全插件, 数据可视化, 文档安全, 本地优先, 自动化攻击, 自动笔记, 误报消除, 调用图, 错误基检测, 静态代码分析