clwg/npm-git-history

# npm-git-history 从 npm 包的源仓库中提取提交历史，并可选择对其运行咨询性供应链风险启发式算法。 给定一个包名，该工具会从其 npm 元数据中解析出该包的源仓库，对其进行克隆，并分析最近的提交历史（作者、日期、主题）。它可以处理包的整个依赖树，从而一次性审计整个供应链。   ## 环境要求 - [Node.js](https://nodejs.org/) 18+ - `npm` 和 `git` 需要在你的 `PATH` 中可用 ## 安装说明 ``` git clone && cd npm-git-history npm install ``` 然后，该工具会通过 `tsx` 直接运行 TypeScript 代码 ### 可选：将 CLI 安装到你的 `PATH` 中 要将 `npm-git-history` 安装到你的 PATH 中 ``` npm run build # bundle source to dist/ via tsup npm install -g . # install to PATH ``` ## 用法 全局安装后： ``` npm-git-history [options] ``` 或者，通过 `tsx` 从源码运行： ``` npx tsx npm-git-history.ts [options] ``` ### 示例 如果已安装到你的 PATH 中，请将 `npm-git-history` 替换掉 `npx tsx npm-git-history.ts`。 ``` # 包的最近 commit 历史 npx tsx npm-git-history.ts left-pad # 更多 commit，包括写入到 JSON 的 monorepo-aware resolution npx tsx npm-git-history.ts @babel/core --limit 50 --json # 使用自定义 cooldown window 运行 supply-chain risk heuristics npx tsx npm-git-history.ts some-package --risk --cooldown 21 # 审计包及其 dependency tree 至 depth 2，使用 shallow clones 提升速度 npx tsx npm-git-history.ts express --deps --dep-depth 2 --depth 50 ``` ## 选项 | 选项 | 描述 | | --- | --- | | `--limit N` | 要显示的提交数量（默认为 `20`） | | `--all` | 显示所有提交（覆盖 `--limit`） | | `--full` | 包含完整的提交正文，而不仅仅是主题行 | | `--depth N` | `git clone` 深度（默认为：完整历史）。例如使用 `100` 来加快速度。 | | `--risk` | 运行防御性供应链启发式算法并打印风险报告 | | `--cooldown N` | cooldown 信号的新鲜度窗口（以天为单位）（默认为 `14`） | | `--deps` | 同时解析并分析依赖树（隐含 `--risk`） | | `--dep-depth N` | 最大传递依赖深度（默认为：无限制） | | `--max-deps N` | 分析的依赖项数量上限（默认为 `100`，`0` = 无上限） | | `--concurrency N` | 使用 `--deps` 时的并行包分析数量（默认为 `4`） | | `-v`, `--verbose` | 为每个依赖项输出按阶段（克隆/日志/风险）的进度流 | | `--json` | 将 JSON 写入到 `/.json`（而不是输出到 stdout） | | `--html` | 将自包含的 HTML 报告写入到 `/.html` | | `--out-dir DIR` | 写入 `--json`/`--html` 报告的目录（默认为 `output`） | | `-h`, `--help` | 显示帮助信息 | ## 输出格式 - **文本**（默认）- 输出到 stdout 的格式化报告。 - **JSON** (`--json`) - 完整的分析结果，包括依赖图（`dependencies`/`requiredBy` 边）以及每个包的风险发现。 - **HTML** (`--html`) - 一个可以在浏览器中打开的独立自包含文件。 ## 供应链风险分析 使用 `--risk`（或 `--deps`，它会隐含该选项）时，该工具会获取 npm 发布元数据，并在提交历史中运行一组启发式信号。每个信号都会对整体**得分**产生影响，该得分会映射到一个大致的风险级别： | 级别 | 得分 | | --- | --- | | `LOW` | `< 3` | | `ELEVATED` | `3–4` | | `HIGH` | `>= 5` | ### 信号 | 代码 | 等级 | 标记内容 | | --- | --- | --- | | `FRESH_PUBLISH` | warn | 最新版本在 cooldown 窗口内发布——即太新了，可能尚未经过审查。 | | `DORMANT_REVIVAL` | warn | 在最近一次提交之前有一段很长的静默期（发布前的突然恢复）。 | | `NEW_AUTHOR_IDENTITY` | high | 最近的提交作者未出现在较早的历史记录中。 | | `AUTHOR_NOT_MAINTAINER` | info | 最近的提交作者不是列出的 npm 维护者。 | | `CLUSTERED_TIMESTAMPS` | info | 许多提交之间的间隔在 ~2 秒内（可能是脚本生成/伪造的历史记录）。 | 当使用 `--deps` 时，该工具会克隆已解析依赖树中每个依赖项的仓库，这可能会很慢且占用大量磁盘空间。请使用 `--dep-depth`、`--max-deps` 以及较浅的 `--depth` 来限制审计范围。

标签：GNU通用公共许可证, MITM代理, Node.js, WebSocket, 依赖分析, 暗色界面, 网络安全研究, 自动化攻击