anasm266/installsentry

# InstallSentry 查看 package 在安装时的行为。 InstallSentry 会在一个临时的沙箱中根据您的 lockfile 重现真实的安装过程，追踪生命周期脚本、文件系统访问、网络调用以及伪造的敏感信息诱饵暴露情况，随后生成一份 HTML 报告（并提供适用于 CI 的可选 JSON 或 SARIF 格式）。它会将这些行为映射回您的依赖关系图，并生成爆炸半径路径。 **支持的包管理器：** npm (`package-lock.json` v3)、**pnpm** (`pnpm-lock.yaml`)、**Yarn Berry** (包含 `__metadata` 的 `yarn.lock`)。支持自动检测，也可以通过 `--package-manager` 进行设置。 [](https://github.com/anasm266/installsentry/actions/workflows/ci.yml) [](https://www.npmjs.com/package/installsentry) [](https://www.npmjs.com/package/installsentry) [](https://nodejs.org/) [](LICENSE) ## 试用 demo 运行一个无害的、用于模拟安装阶段敏感信息窃取的生成式 demo： ``` npx installsentry@2 demo ``` 输出示例： ``` InstallSentry found 3 install-time risks CRITICAL packages/malice-local sent fake AWS secret canary to example.com MEDIUM Project install (npm) made POST request to registry.npmjs.org MEDIUM packages/malice-local made GET request to example.com Observed: 1 package with lifecycle scripts 2 outbound network hosts 1 secret canary hit Report: installsentry-demo-report.html ``` ## 在您的项目中运行 在包含 `package.json` 和受支持的 lockfile 的项目中执行： ``` npx installsentry@2 ``` 这会分析当前目录并生成 `installsentry-report.html`。可以通过 `--format json` 或 `--format both` 获取 JSON 输出。 ``` npx installsentry@2 --format both -o installsentry-report.html ``` ## 可检测的内容 - 在您的 lockfile 中声明的生命周期脚本（`preinstall`、`install`、`postinstall`、`prepare` 及相关钩子）。 - 安装期间对 Node 文件系统的读取和写入（包括常见的同步 API）。 - 安装期间的 Node HTTP(S) 和 `fetch` 流量。 - DNS 查询和 TCP/TLS 连接（为提高可见性而记录）。 - 从文件中读取或嵌入到出站 URL 中的伪造敏感信息诱饵值。 - 当安装代码探测 CI 或沙箱环境变量时，发现的低风险级别的**规避提示**。 - 从可疑行为回溯到您的依赖关系图的爆炸半径路径。 - 带有**置信度**标签的 package 归属信息（在可用时包含 cwd + npm 生命周期环境信息）。 ## 无法证明的内容 InstallSentry 是一个观察工具，而不是恶意软件扫描程序或安全保证。原生二进制文件、在没有 shim 的情况下生成非 Node 子进程的 shell、其他运行时以及刻意规避的代码仍然可能隐藏其活动。要获得更强的隔离性，请使用 Docker 模式，并在将其作为 CI 拦截条件之前，阅读[威胁模型](docs/THREAT-MODEL.md)。 ## 与其他工具的对比 | 工具 | 主要问题 | | --- | --- | | `npm audit` | 我解析的版本中是否存在已知的 CVE？ | | Socket / Snyk (metadata) | package 的源代码或元数据看起来是否有风险？ | | LavaMoat `allow-scripts` | 我愿意运行哪些生命周期脚本？ | | **InstallSentry** | **这次被追踪的安装**在执行我的 lockfile 时实际上做了什么？ | InstallSentry 起到的是补充作用，而非替代品。请参阅 [docs/COMPARISON.md](docs/COMPARISON.md)。 ## 安装 要求 **Node.js 20+**，并且您要分析的包管理器（`npm`、`pnpm` 或 `yarn`）已添加到 `PATH` 环境变量中。 ``` npm install -g installsentry ``` 或者在不进行全局安装的情况下运行： ``` npx installsentry@2 --version ``` Windows PowerShell： ``` npx.cmd --yes installsentry@2 --version ``` ## 命令 ``` # 分析当前项目（自动检测 package manager） installsentry # 带有模拟数据渗出的无害演示 installsentry demo # 列出声明 lifecycle scripts 的 lockfile 包 installsentry scan # 分析另一个路径 installsentry run /path/to/your-app -o report.html # 用于自动化的 JSON 报告 installsentry run . --format json -o report.json # 重放冻结安装（npm ci / pnpm frozen / yarn immutable） installsentry run . --npm-command ci installsentry ci # 显式 package manager installsentry run . --package-manager pnpm # 保存 baseline 并在下一次运行时进行 diff（PR workflows） installsentry run . --save-baseline installsentry diff . # Docker 隔离 installsentry run . --docker -o report.html installsentry run . --docker --docker-network none -o report.html ``` 在浏览器中打开 HTML 报告。它包含严重程度统计、发现结果表格、生命周期脚本预览、敏感信息诱饵警报、网络出站详情、爆炸半径路径以及交互式的依赖关系图。 ## 工作原理 1. **解析**您的 lockfile 以生成依赖关系图，并标记出包含生命周期脚本的 package。 2. **复制** manifest、lockfile、本地 `packages/` 以及 trace shim 到一个临时的工作区中。 3. **重现**安装过程（`npm install` / `npm ci`、`pnpm install` 或 `yarn install`），可以在宿主机上或 Docker 内部进行。 4. **检测**通过 `NODE_OPTIONS` 运行的 Node — 涵盖文件系统、HTTP(S)、`fetch`、DNS/TCP、子进程生成；子 `node` 进程在可能的情况下也会接收到 shim。 5. **注入**伪造的诱饵敏感信息到环境中（绝不使用您的真实 token）。 6. **分析**追踪事件，按严重程度排序生成带有归因置信度的发现结果。 7. **输出** HTML（默认），以及可选的 JSON 和可选的 SARIF 2.1.0。 ## 配置 可选的项目配置文件（按首个匹配项生效）：`.installsentry.yaml`、`.installsentry.yml`、`installsentry.json`、`.installsentry.json`。 示例（[docs/samples/example.installsentry.yaml](docs/samples/example.installsentry.yaml)）： ``` version: 1 ci: policy: balanced # balanced | strict | custom allowHosts: - registry.npmjs.org denyHosts: - example.com failOn: - secret-canary - denied-network runner: mode: host # host | docker dockerImage: node:20-bookworm-slim dockerNetwork: default # default | none report: output: installsentry-report.html format: both # html | json | both sarif: installsentry.sarif baseline: path: .installsentry/baseline.json ``` 在 `--help` 的说明中，CLI 参数会覆盖配置文件内的对应项。 ## CI、策略与 SARIF | 模式 | 敏感信息诱饵 | CI 中的网络请求 | | --- | --- | --- | | `strict` | 失败 | 除非主机在白名单中，否则失败（`installsentry ci` 的默认设置） | | `balanced` | 失败 | 仅在命中 `denyHosts` 时失败（`installsentry run --ci` 的推荐默认设置） | | `custom` | 依据配置中的 `failOn` | 依据配置中的 `failOn` | ``` installsentry ci ./my-app \ --allow-hosts registry.npmjs.org \ --policy strict \ -o report.html \ --sarif results.sarif \ --format both ``` - `--ci` — 当策略检查失败时以非零状态码退出。 - `--policy` — `balanced`、`strict` 或 `custom`。 - `--allow-hosts` / `--deny-hosts` — 网络允许/禁止列表。 - `--sarif ` — 用于 GitHub 代码扫描的 SARIF 2.1.0（包含 `helpUri` 和爆炸半径 `relatedLocations`）。 当 CI 检查失败时，CLI 会打印出具体的敏感信息命中记录、网络违规详情、允许的主机以及建议的修复方案。 ## Docker ``` installsentry run ./my-app --docker -o report.html installsentry run ./my-app --docker --docker-image node:20-bookworm-slim -o report.html installsentry run ./my-app --docker --docker-network none -o report.html ``` `--docker` 是 `--runner docker` 的简写。在 Windows 上，请使用 Docker Desktop，并确保如果安装失败，临时目录的卷是可以共享的。 ## GitHub Actions **推荐：** 结合固定主版本号的 `npx` 使用： ``` - uses: actions/setup-node@v4 with: node-version: 20 - run: npx --yes installsentry@2 ci . --allow-hosts registry.npmjs.org --sarif installsentry.sarif --format both - uses: github/codeql-action/upload-sarif@v3 if: always() with: sarif_file: installsentry.sarif ``` 本仓库中的**复合 action**（[`.github/actions/installsentry/action.yml`](.github/actions/installsentry/action.yml)）： ``` - uses: anasm266/installsentry/.github/actions/installsentry@v2 with: project-path: . command: ci policy: strict allow-hosts: registry.npmjs.org sarif-output: installsentry.sarif format: both ``` 对于基于 PowerShell 的 Windows 作业，请使用 `npx.cmd`。 ## 报告示例

针对本仓库中包含的 canary demo 场景进行的参考运行。 ## 局限性 | 领域 | 说明 | | --- | --- | | Lockfile | npm lockfile v3；pnpm `pnpm-lock.yaml`；仅支持 Yarn Berry（不支持 Yarn Classic v1）。 | | 追踪 | 仅限 Node shim；原生二进制文件和未应用 shim 的子进程属于监测盲区。 | | 归属 | cwd + npm 生命周期环境变量包含置信度标签；但在发生 `chdir` 或特殊的 spawn 之后仍然不够完美。 | | 信任 | 提供可见性和策略拦截条件 —— 但并非安全证明。 | 详情：[docs/THREAT-MODEL.md](docs/THREAT-MODEL.md)。从 0.x 迁移：[docs/MIGRATION-v1-to-v2.md](docs/MIGRATION-v1-to-v2.md)。 ## 文档 | 文档 | 用途 | | --- | --- | | [docs/THREAT-MODEL.md](docs/THREAT-MODEL.md) | 该工具能证明和不能证明的内容 | | [docs/PACKAGE-MANAGERS.md](docs/PACKAGE-MANAGERS.md) | npm、pnpm 和 Yarn Berry 支持 | | [docs/COMPARISON.md](docs/COMPARISON.md) | 对比 audit、Socket、LavaMoat | | [docs/JSON-REPORT-SCHEMA.md](docs/JSON-REPORT-SCHEMA.md) | 机器可读的报告格式 | | [docs/MIGRATION-v1-to-v2.md](docs/MIGRATION-v1-to-v2.md) | 升级至 2.0 | | [docs/samples/](docs/samples/) | 配置和报告示例 | | [CHANGELOG.md](CHANGELOG.md) | 发布历史 | ## 贡献 欢迎提交 Pull request 和 issue 报告。有关如何在本地进行构建和测试，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 MIT

标签：GNU通用公共许可证, MITM代理, Node.js, StruQ, 依赖审计, 文档安全, 暗色界面, 沙箱, 网络信息收集, 自动化攻击, 请求拦截