anky2901/repo-xray

# Repo X-Ray [](https://github.com/anky2901/repo-xray/actions/workflows/ci.yml) 本地优先的代码仓库智能分析工具。将其指向某个 repo，它就会针对安全性、架构、依赖项、测试、CI、发布就绪度、可维护性、性能、git 健康、代码风格、业务上下文等方面生成可解释的、确定性的报告——此外还提供可直接复制粘贴的 AI 提示词和修复建议。 - **本地优先：** 克隆/复制 repo 并在你的机器上进行分析。默认情况下，不会对外发送任何数据。 - **确定性：** 相同的输入会产生字节完全一致的 `scan.json` 和报告。 - **可解释性：** 每一项发现都附带证据、置信度评分和通俗的英文推理说明。 - **离线可用：** 支持 `--offline` 从缓存运行；网络仅用于 CVE/registry 查询。 ## 环境要求 - Node.js >= 18（已在 22 上测试） - pnpm 10+ - PATH 中包含 git（用于扫描 GitHub URL 和分析 git-history） ## 设置说明 ``` pnpm install pnpm build ``` 你可以随时验证你的环境（以下两种形式均可——请参阅下文的“The `xray` command”）： ``` node apps/cli/dist/index.js doctor ``` ## 快速开始 扫描 GitHub repo（零配置）： ``` xray scan https://github.com/expressjs/express --mode=deep ``` 报告默认会写入 `.xray-reports/` 目录。在浏览器中打开 `.xray-reports/DASHBOARD.html` 即可查看交互式视图，或阅读 `REPORT.md` 获取摘要。 ## 使用指南 从安装到读取结果的完整操作流程。 ### 1. 安装与构建 ``` pnpm install pnpm build ``` ### 2. 检查你的环境 ``` node apps/cli/dist/index.js doctor ``` 这将检查 Node、pnpm、git、SQLite、缓存访问权限和磁盘空间。请在扫描前修复任何标记为 `FAIL` 的状态。 ### 3. 运行你的首次扫描 选择一个目标——本地文件夹、GitHub URL 或 `.zip` 归档文件——并选择一种模式。要进行完整审查，请使用 `deep` 模式： ``` # 本地项目 node apps/cli/dist/index.js scan ./path/to/project --mode=deep # 远程仓库 node apps/cli/dist/index.js scan https://github.com/expressjs/express --mode=deep # 当前目录 node apps/cli/dist/index.js scan . --mode=deep ``` 使用 `--output=` 可将报告写入 `.xray-reports/` 之外的其他位置。 ### 4. 读取分析结果 扫描完成后，请查看输出目录（默认为 `.xray-reports/`）： - **`DASHBOARD.html`** —— 在浏览器中打开以获取交互式视图：评分卡片、严重性摘要以及可过滤的发现列表。建议从这里开始。 - **`REPORT.md`** —— 包含健康评分卡和首要发现的文本摘要。 - **专项报告** —— 深入了解特定领域：`SECURITY.md`、`DEPENDENCY.md`、`ARCHITECTURE.md`、`TEST_PLAN.md`、`RELEASE.md` 等其他报告（完整列表请参阅 [Output files](#output-files-deep-mode)）。 - **`FIXES.md`** —— 按优先级排列且可直接复制粘贴的具体修复列表。 - **`scan.json`** —— 如果你需要通过脚本进行调用，可查看此完整的机器可读结果。 每一项发现都包含文件/行号证据、置信度评分以及通俗的英文原因说明。 ### 5. 根据任务选择合适的模式 - 快速筛选或 pre-commit 阶段：`--mode=quick`（仅检查安全性，速度最快）。 - 完整审查：`--mode=deep`（包含所有模块）。 - 深度审计：`--mode=paranoid`。 - 在 pipeline 中使用：`--ci --fail-on=HIGH`（机器输出 + 退出码）。 ### 6. 常见工作流 ``` # 拦截 CI 构建：发现 HIGH 或 CRITICAL 时以非零状态码退出 node apps/cli/dist/index.js scan . --ci --fail-on=HIGH # 快速 release-readiness 检查（仅限 release 和 CI 健康状态） node apps/cli/dist/index.js release-check . # 基于此仓库真实事实生成 AI 提示词 node apps/cli/dist/index.js prompts . # 使用缓存的 CVE/registry 数据重新扫描（无需网络访问） node apps/cli/dist/index.js scan . --mode=deep --offline # 从本地历史记录比较过去的两次扫描 node apps/cli/dist/index.js history node apps/cli/dist/index.js compare ``` ## `xray` 命令 CLI 包提供了一个名为 `xray` 的 `bin`。要将其作为全局命令使用： ``` pnpm --filter @repo-xray/cli build # ensure dist is built pnpm setup # one-time: creates pnpm's global bin dir (restart shell after) pnpm --filter @repo-xray/cli link --global xray --help ``` 如果你不想设置全局 bin，也可以通过以下方式运行所有命令： ``` node apps/cli/dist/index.js ``` 这两种形式是等效的；下文示例均使用 `xray`。 ## 命令说明 ### `scan ` 扫描本地路径、GitHub URL 或 `.zip` 归档文件。 | 选项 | 描述 | |---|---| | `--mode ` | `quick`（仅检查安全性，速度快）、`deep`（所有模块）、`paranoid`（所有模块 + 额外扫描）、`ci`（机器输出 + 退出码）。默认值：`quick`。 | | `--output ` | 报告的输出目录。默认值：`.xray-reports`。 | | `--offline` | 仅使用缓存数据；跳过实时的 CVE/registry 查询。 | | `--ci` | 适配机器读取的运行方式，附带 CI 退出码（包含 `ci` 模式）。 | | `--fail-on ` | 在 CI 模式下，当存在达到或超过此严重程度（如 `HIGH`）的发现时，以非零状态退出。 | 示例： ``` # 针对当前目录的快速安全检查 xray scan . --mode=quick # 将本地项目的完整分析输出到自定义文件夹 xray scan ./my-app --mode=deep --output=reports/ # CI 拦截：发现 HIGH+ 时使构建失败 xray scan . --ci --fail-on=HIGH # 使用缓存的 CVE/registry 数据进行离线重新扫描 xray scan https://github.com/user/repo --mode=deep --offline ``` CI 退出码：`0` 代表正常，`1` 代表存在低于阈值的发现，`2` 代表存在 HIGH 级别发现，`3` 代表存在 CRITICAL 级别发现。 ### `release-check ` 快速通道，仅运行发布就绪度（M17）+ CI 健康（M18）检查。生成 `RELEASE.md`、`RELEASE_CHECKLIST.md`、`CI_REPORT.md`。 ``` xray release-check . --output=reports/ ``` ### `prompts ` 基于 repo 的实际事实生成可直接复制粘贴的 AI 提示词。生成 `PROMPTS/{dev,bugfix,feature,audit,onboarding}.md`。 ``` xray prompts . ``` ### `history [repoId]`, `compare ` 查询并对存储在 SQLite 历史记录（`.xray-reports/xray.db`）中的过往扫描进行 diff 分析。 ``` xray history xray compare ``` ### `config`, `doctor` `config` 打印解析后的配置；`doctor` 运行环境诊断。 ## 扫描模式 | 模式 | 模块 | 用途 | |---|---|---| | `quick` | 仅安全性 | 快速 pre-commit / 筛选 | | `deep` | 所有模块 | 完整审查（默认推荐） | | `paranoid` | 所有模块 + 额外扫描 | 深度审计 | | `ci` | 所有模块，机器输出，附带退出码 | Pipelines | ## 输出文件 (deep 模式) | 文件 | 内容 | |---|---| | `REPORT.md` | 核心摘要 + 健康评分卡 + 徽章 | | `DASHBOARD.html` | 交互式、可过滤的 dashboard | | `SECURITY.md` | 密钥、危险 pattern、配置问题、CVE（密钥始终会被掩码处理） | | `ARCHITECTURE.md` / `ARCHITECTURE.html` | import 关系图、循环依赖、超大文件、分层结构、无效模块 | | `DEPENDENCY.md` | 存在漏洞/重复/被废弃/体积过大的依赖项，许可证冲突 | | `TEST_PLAN.md` | 测试覆盖率、测试盲区、不稳定测试 (flaky-test) 模式 | | `RELEASE.md` / `RELEASE_CHECKLIST.md` | 加权发布就绪度评分卡 + 检查清单 | | `CI_REPORT.md` | 工作流健康度：测试、版本固定的 actions、密钥、权限、超时时间 | | `MAINTAINABILITY.md` | 复杂度、文件大小、注释密度、热点模块 | | `PERFORMANCE.md` | 静态性能热点分析 | | `GIT.md` | Commit 频率、贡献者、巴士因子 (bus factor)、代码变动热点 | | `CODE_STYLE.md` | 缩进/引号一致性、行尾空格、长代码行 | | `BUSINESS.md` | 推断出的项目用途、领域、用户群、分发渠道 | | `VULN_REPORT.md` | 针对单个漏洞的修复方案（极简版 + 最佳实践 + AI 提示词 + 测试） | | `ADOPTION.md` | 带有置信区间的采用潜力评估 | | `FIXES.md` | 已整合并按严重程度分组的修复建议 | | `PROMPTS/*.md` | 基于提取到的 repo 事实生成的 AI 提示词 | | `scan.json` | 完整的结构化结果（schema 1.0），具备确定性 | | `scan.sarif` | 用于 GitHub Code Scanning 的 SARIF 2.1.0 | | `scan.pdf` | 当存在可用的 Chrome runtime 时进行渲染（否则自动优雅跳过） | ## 配置 开箱即用，无需任何配置。如需自定义，请在 repo 根目录添加 `.xrayrc.json` 文件，设置 `XRAY_*` 环境变量，或传递 CLI flags（优先级顺序为：CLI flags > 环境变量 > 配置文件 > 默认值）。常用设置包括：`output.dir`、`cache.dir`、`ignore.patterns`、`github.token`、`ai.provider`。遥测功能始终处于关闭状态。 忽略规则：默认遵循 `.gitignore` 配置；可在 `.xrayignore` 中添加针对特定 repo 的排除项。 ## 使用 SDK 所有功能均可通过 `@repo-xray/sdk` 进行编程调用： ``` import { XRayPipeline, FileCache, loadConfig, logger, renderDashboard } from '@repo-xray/sdk'; const config = loadConfig(); const result = await new XRayPipeline().run({ source: './my-app', mode: 'deep', modules: ['security', 'architecture', 'dependency', 'test-intelligence', 'release', 'ci-health'], config, cache: new FileCache(config.cache.dir), logger, }); console.log(result.scores); const html = renderDashboard(result); // self-contained dashboard HTML ``` ## 开发说明 ``` pnpm typecheck # strict TypeScript across all packages pnpm lint # eslint pnpm test # vitest pnpm build # lint + build all packages ``` 该 repo 是一个 pnpm workspace：包含 `apps/`（cli、web）、`packages/`（sdk、core、各模块 analyzers、cache、storage、export、reporting）以及 `shared/`。Apps 仅依赖于 SDK；analyzers 依赖于 `@repo-xray/types`。此边界由测试强制执行。

标签：DevSecOps, GNU通用公共许可证, MITM代理, Node.js, WebSocket, 上游代理, 云安全监控, 代码质量审查, 依赖分析, 自动化攻击, 静态分析