vcian/project-inspector

# @vcian/project-inspector [](https://www.npmjs.com/package/@vcian/project-inspector) [](LICENSE) [](https://github.com/vcian/project-inspector/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@vcian/project-inspector) **您的代码永远不会离开您的本地机器。** `project-inspector` 是一个完全离线、确定性的静态分析 CLI —— 无需上传源码，无需远程服务器，不使用 LLM，不收集遥测数据。每次扫描均在本地运行，且对于相同的输入会产生完全一致的输出，因此它适用于气隙环境、受监管的代码库，以及禁止将专有源码发送至云服务的 CI 门禁。 它会扫描源代码、锁定文件（lockfile）和项目结构，从而生成专注于生产环境的报告，涵盖安全性、架构、依赖项、API 暴露面、性能和发布就绪情况 —— 交付物为一个独立的交互式 HTML 仪表板以及机器可读的产物（`json`、`sarif`）。 ## 为什么选择它 - 为工程和 AppSec 审查提供快速的本地反馈。 - 稳定、确定性的输出，适用于 CI 门禁和趋势跟踪。 - 零 LLM 依赖；可在受限或断网环境中运行。 - 生成交互式 HTML 仪表板、Markdown 报告和机器可读的产物（`json`、`sarif`）。 - 无 CDN 依赖 —— HTML 报告完全独立，可离线使用。 ## 与 SonarQube 和 Semgrep 的对比 `project-inspector` **并非** SonarQube 或 Semgrep 的替代品 —— 它服务于工作流中的不同环节，认清这一点很重要： - **对比 SonarQube** —— SonarQube 是一个服务器托管的质量平台，具有深度的多语言覆盖、历史仪表板和丰富的规则引擎，但它需要运行（或付费使用）服务器并将您的代码/指标推送至其中。`project-inspector` 作为一个独立的离线 CLI 运行，无需任何基础设施，并提供独立的 HTML 报告。如果需要跨多种语言进行组织级、长期的质量治理，请选择 SonarQube；如果需要对 Node.js/TypeScript 项目进行快速、私密且无需基础设施的分析，请选择 `project-inspector`。 - **对比 Semgrep** —— Semgrep 拥有更为庞大、由社区维护的规则库，以及强大的自定义模式语言，可进行跨语言的污点和数据流分析。`project-inspector` 则提供了一套专注于 Node.js/TS 生态系统且经过精心挑选的规则集，并结合了架构、依赖项、API 表面以及数据库/ER 分析，外加一个工具内的生产就绪判定。当您需要广泛的规则覆盖或自定义数据流查询时，请选择 Semgrep；当您无需编写规则，希望获得一份带有强烈主观色彩的一体化就绪报告时，请选择 `project-inspector`。 在实际应用中，这些工具是互补的：许多团队将 `project-inspector` 用作快速的本地/CI 门禁，同时保留 Semgrep 或 SonarQube 进行更深入的、语言无关的覆盖。 ## 核心功能 - 静态代码分析（AST + 规则启发式）。 - 与 OWASP 风格分类保持一致的安全信号。 - 依赖项和迁移风险情报（离线 + 可选的 `npm audit`）。 - API 表面发现（HTTP + CLI 命令启发式）。 - 性能和内存反模式检测。 - 清单和项目拓扑映射。 - 数据库 schema 智能 —— 带有实体/关系可视化的 ER 图。 - 通过 `check` 进行 CI 门禁判定。 ## 交互式 HTML 仪表板 每次扫描都会生成 `project-report/index.html` —— 一个单文件、完全离线的 HTML 报告。 ### 仪表板预览 **Overview** —— 生产就绪度仪表、各维度得分和严重性细分：  **Performance** —— 包含严重性、源码位置和标题的引擎检查结果：  **Bundle** —— 包含所有生成的报告文件，可本地打开且无任何 CDN 调用：  报告包含以下标签页： | 标签页 | 内容 | |-----|---------| | **Issues** | 完整的检查结果表，包含严重性徽章、过滤器、所有者、修复指南和合规性标签 | | **Bundle** | 所有生成的报告文件，带有内联 Markdown 和 JSON 预览，支持语法高亮 | | **Architecture** | 数据流管道图、框架检测、架构问题列表 | | **Database** | 自动检测的 ER 图（Mongoose 对应 Collections，SQL/Prisma/TypeORM/Drizzle/Sequelize 对应 Tables）、关系、索引提示、schema 模型卡片 | 该仪表板无需服务器 —— 直接在浏览器中打开即可。 ## 支持的生态系统 - Node.js / TypeScript / JavaScript - React / Next.js - Express / Fastify - 启发式的 NestJS 支持 - MongoDB / Mongoose（Collection 级别的 ER 图和关系检测） - 通过 Prisma、TypeORM、Drizzle ORM、Sequelize 或原生 `.sql` DDL 支持的 SQL 数据库 - Monorepo 和多项目工作区检测（启发式） ## 安装 ### 全局安装（推荐用于 CI runner 和本地 CLI 使用） ``` npm install -g @vcian/project-inspector ``` ### 验证安装 ``` project-inspector --help ``` ## 快速开始 ``` cd your-project project-inspector scan ``` 默认输出目录：`./project-report` 打开报告： ``` # macOS open project-report/index.html # Windows start project-report/index.html # Linux xdg-open project-report/index.html ``` ## CLI 命令 | 命令 | 用途 | |--------|---------| | `scan` | 运行所有已配置的引擎并写入报告 | | `check` | 运行 `scan`，评估就绪度门禁，并在失败时以非零状态码退出 | | `watch` | 在文件更改时重新运行扫描（防抖动，单次执行队列） | | `chat` | 对先前生成的报告进行离线关键字搜索（不使用 LLM） | | `clear` | 删除报告目录（包括 `.cache`） | | `update-vuln-db` | 从 `VULN_DB_URL` (HTTPS) 刷新可选的漏洞覆盖数据库 | ## 命令用法 ### `scan` ``` project-inspector scan [options] ``` | 选项 | 说明 | |--------|-------------| | `-c, --cwd ` | 项目根目录。默认值：当前工作目录 | | `-o, --out ` | 输出目录。默认值：`/project-report` | | `-j, --concurrency ` | 文件级任务的并行度（`1-32`；默认值为 `max(2, cpuCount - 1)`） | | `--mode ` | 扫描策略。`diff` 会强制限定为 git 变更范围 | | `--online` | 在支持的条件下启用在线依赖审计（`npm audit`） | | `--incremental` | 优先处理 git 变更文件 | | `--no-cache` | 忽略缓存的文件哈希 / 合并后的扫描复用 | | `--rescan` | 强制进行完整的工作区扫描（禁用缓存 + 增量优化） | | `--offline` | 禁用漏洞数据库过期提醒和自动刷新行为 | | `--auto-update-db` | 在依赖引擎运行前，尽力通过 HTTPS 刷新漏洞覆盖数据库 | | `--format ` | 生成额外的机器可读输出（`results.json` 和/或 `results.sarif`） | ### `check` ``` project-inspector check [options] ``` 选项与 `scan` 相同。 `check` 会写入 `ci-result.json`，并在门禁标准未通过时以退出码 `1` 退出。 ### `watch` ``` project-inspector watch [options] ``` 选项与 `scan` 相同。使用 `1500ms` 的防抖和单次执行调度来防止扫描重叠。 ### `chat` ``` project-inspector chat [options] ``` | 选项 | 说明 | |--------|-------------| | `-c, --cwd ` | 用于查找最新报告的根目录 | ### `clear` ``` project-inspector clear [options] ``` | 选项 | 说明 | |--------|-------------| | `-c, --cwd ` | 项目根目录 | | `-o, --out ` | 要删除的报告目录 | ### `update-vuln-db` ``` project-inspector update-vuln-db [options] ``` | 选项 | 说明 | |--------|-------------| | `-c, --cwd ` | 项目根目录 | | `-o, --out ` | 报告目录 | ## 推荐的生产工作流 ### 本地开发者循环 ``` project-inspector scan --mode quick --incremental ``` ### 合并前验证 ``` project-inspector check --mode deep --format json --format sarif ``` ### 大型重构或分支基线刷新 ``` project-inspector scan --rescan --mode deep ``` ### 气隙 / 严格的离线环境 ``` project-inspector scan --offline ``` ## 输出文件 安全检查结果、性能信号、依赖项分析和热点都已嵌入到 `audit-summary.md`、`action-plan.md` 和 `index.html` 仪表板中 —— 没有单独的 `security.md` / `performance.md` 文件。 | 路径 | 内容 | |------|---------| | `project-report/index.html` | **交互式 HTML 仪表板**（Issues、Bundle、Architecture、Database 标签页） | | `project-report/action-plan.md` | 带有所有者分配和 ETA 的优先修复清单 | | `project-report/audit-summary.md` | GitHub 风格的 Markdown 摘要，适用于 PR 评论和 Job 摘要 | | `project-report/api.md` | API 表面审查 —— 路由矩阵、身份验证/验证覆盖率、端点访问权限 | | `project-report/architecture.md` | 架构分析、模块到数据存储的映射、API 到数据库的流程、结构性问题 | | `project-report/database.md` | 数据库 schema 分析、ER 关系、索引提示、ORM 检查结果 | | `project-report/decision.json` | 用于 CI 自动化的机器可读生产判定和门禁状态 | | `project-report/scores.json` | 所有维度的数字得分以及细分汇总 | | `project-report/openapi.json` | 根据检测到的 HTTP 路由自动生成的 OpenAPI **3.1** 导出文件 | | `project-report/sbom.cdx.json` | 从 npm lockfile 生成的 CycloneDX **1.5** SBOM | | `project-report/governance-suppressions.json` | 活动的治理抑制规则快照 | | `project-report/results.sarif` | SARIF **2.1.0** 报告（始终会写入） | | `project-report/results.json` | JSON 格式的完整扫描结果 —— 仅在使用 `--format json` 时写入 | | `project-report/ci-result.json` | 由 `check` 命令写入的门禁判定结果 | | `project-report/.cache/merged-scan.json` | 缓存的完整扫描 payload，用于部分/增量刷新 | | `project-report/.cache/file-hashes.json` | 用于增量文件变更检测的 SHA-256 哈希映射 | | `project-report/.cache/dependency-snapshot.json` | 依赖项和 lockfile 指纹（包含漏洞数据库哈希） | | `project-report/.cache/scan-meta.json` | 扫描元数据和各引擎的耗时 | | `project-report/.cache/vuln-db-meta.json` | 关于上次漏洞数据库获取和过期状态的元数据 | | `project-report/.cache/env-snapshot.json` | 用于偏差检测的环境变量键快照 | | `docs/rules-catalog.md` | 生成的规则目录 —— 运行 `npm run docs:catalog` 进行刷新 | ## CI 集成 ### GitHub Actions 示例 ``` name: Static Analysis Gate on: pull_request: push: branches: [main] jobs: inspect: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' - run: npm install -g @vcian/project-inspector - name: Run production gate run: project-inspector check --cwd . --mode deep --format sarif --format json - name: Upload SARIF if: always() uses: github/codeql-action/upload-sarif@v3 with: sarif_file: project-report/results.sarif ``` ## 配置参考 | 键 / 标志 | 类型 | 用途 | |------------|------|---------| | `LOG_LEVEL` | env | Pino 日志级别（`fatal`、`error`、`warn`、`info`、`debug` 等） | | `--mode` | cli | `quick`、`deep`、`diff` | | `--concurrency` | cli | 控制并行度（`1-32`） | | `--format` | cli | 额外的机器可读输出（`json`、`sarif`） | | `--auto-update-db` | cli | 依赖扫描前使用 `VULN_DB_URL` 进行尽力刷新 | | `--offline` | cli | 禁用远程漏洞数据库过期流程和自动刷新 | | `VULN_DB_URL` | env | 用于覆盖漏洞规则数据库 HTTPS URL | | `policyPack` | `project-inspector.config.json` | 命名的覆盖配置（`packs/.json`），合并额外的忽略 glob / 抑制字符串（`packs/` 下附带了 HIPAA、SOC2、PCI、OWASP ASVS 示例） | ### `VULN_DB_URL` payload 结构 ``` { "version": "string", "updated": "ISO-8601 timestamp", "rules": [] } ``` ## 可靠性与安全模型 ### 本工具的优势 - 确定性的静态风险发现。 - 工程治理和 CI 门禁标准化。 - 在运行时测试之前进行早期问题检测。 ### 本工具做不到的事情 - 无法替代渗透测试或动态分析。 - 不是完整的过程间污点分析。 - 不是完整的框架语义模型。 请将检查结果视为高信号的审查输入，然后在代码审查或针对性测试中进行确认。 ## 局限性 - 安全引擎使用 AST + 模式启发式（无完整的跨函数数据流）。 - `chat` 是针对本地报告文本的离线关键字搜索，而不是 AI 助手。 - NestJS 路由/身份验证/验证分类是基于装饰器的启发式分析。 - 供应链洞察结合了离线规则和 `--online` 模式下的可选 `npm audit`。 - 当不存在显式工作区配置时，多项目自动检测是启发式的。 - Mongoose schema 检测涵盖 `mongoose.Schema`、`new Schema()` 和 `mongoose.model()` 模式；非标准的 schema 工厂包装器可能无法被捕获。 ## 性能与确定性说明 - 默认启用缓存以提高速度。 - 在代码库发生重大变动后应使用 `--rescan`。 - `--mode diff` 和 `--incremental` 针对变更文件的工作流进行了优化。 - 机器输出契约（`decision.json`、`ci-result.json`、`results.sarif`）适用于自动化。 ## 开发与维护 ### 本地开发脚本 | 脚本 | 说明 | |--------|-------------| | `npm run build` | 将 TypeScript 编译到 `dist/`（运行构建验证后置步骤） | | `npm run dev` | 使用 `tsx` 在开发模式下运行 CLI 入口 | | `npm run typecheck` | TypeScript 严格类型检查（不输出文件） | | `npm run lint` | ESLint，零警告 | | `npm test` | 用于所有已配置测试文件的 Node 测试运行器 | | `npm run test:coverage` | 通过 `c8` 进行带有 lcov + 文本覆盖率的测试套件 | | `npm run ci` | 完整的本地 CI 门禁：类型检查 + lint + 测试 | | `npm run clean` | 删除 `dist/` 目录 | | `npm run refresh-majors` | 刷新精选的包主要版本元数据（需要网络） | | `npm run docs:catalog` | 根据引擎规则定义生成 `docs/rules-catalog.md` | ### Node 版本 - 运行时要求：`node >= 18.0.0` - CI 推荐版本：Node.js `20.x` LTS ## 生产环境采用清单 - 在 CI 中对每个 PR 和受保护分支的推送运行 `check`。 - 将 `results.sarif` 上传到您的安全平台（兼容 GitHub Advanced Security）。 - 随着时间的推移跟踪 `scores.json` 和 `decision.json` 以建立趋势基线。 - 对于发布分支和重大重构，使用 `--rescan`。 - 如果使用私有覆盖情报，请保持 `VULN_DB_URL` 最新。 - 在本地打开 `project-report/index.html` 以获取完整的交互式仪表板视图。 ## 编程 API `project-inspector` 也可以作为库在您自己的脚本或工具中使用。 ``` import { runScan, writeScanArtifacts, computeScores } from '@vcian/project-inspector'; const result = await runScan({ cwd: process.cwd(), outDir: './project-report', mode: 'deep', }); await writeScanArtifacts(result, './project-report'); console.log(result.scores.productionReadiness); ``` 所有公共导出都有 JSDoc 文档记录，并随附 TypeScript 声明文件（`dist/index.d.ts`）。核心导出包括： | 导出 | 说明 | |--------|-------------| | `runScan(options)` | 运行完整的项目扫描并返回 `ScanResult` | | `writeScanArtifacts(result, outDir)` | 写入所有报告文件（HTML、Markdown、SARIF、SBOM、OpenAPI、JSON） | | `computeScores(result)` | 计算所有分析维度的数字得分 | | `buildScoreDiagnostics(result)` | 用于人类可读解释的各维度命中数 | | `computeHotspots(result)` | 根据可利用性启发式排名的前 10 大问题 | | `evaluateCheckGates(result)` | 根据门禁阈值评估 ScanResult | | `writeSarifReport(result, outDir)` | 仅写入 SARIF 2.1.0 报告 | ## 开源治理 - 贡献指南：`CONTRIBUTING.md` - 行为准则：`CODE_OF_CONDUCT.md` - 安全政策：`SECURITY.md` - 支持指南：`SUPPORT.md` - 变更历史：`CHANGELOG.md` - 发布流程：`RELEASING.md` ## 许可证 MIT ## 关于 ViitorCloud [ViitorCloud Technologies](https://viitorcloud.com/?utm_source=github&utm_medium=readme&utm_campaign=project-inspector) 是一家全球技术公司，提供 AI、云和企业软件工程解决方案。我们开发像 `project-inspector` 这样的开发者工具，帮助团队交付安全、生产就绪的软件。 - 🌐 网站：[viitorcloud.com](https://viitorcloud.com/?utm_source=github&utm_medium=readme&utm_campaign=project-inspector) - 📧 联系方式：[support@viitorcloud.com](mailto:support@viitorcloud.com) - 💼 服务：[viitorcloud.com/services](https://viitorcloud.com/services/?utm_source=github&utm_medium=readme&utm_campaign=project-inspector) 由 ViitorCloud 团队倾注 ❤️ 构建并维护。

标签：DevSecOps, DNS 反向解析, GNU通用公共许可证, MITM代理, Node.js, Web报告查看器, 上游代理, 云安全监控, 文档结构分析, 自动化payload嵌入, 自动化攻击, 静态分析