npm 安装前安检 nisconder/npm-safe-forDSH

npm-safe for DeepSeek Harness

让 AI 智能体在选 npm 包之前先拿到证据。

14 个智能体工具 · 22 项安全检查 · 完整性校验的深度扫描 · 本地 SQLite 缓存

安装 · 能查出什么 · 工具目录 ·

npm-safe-forDSH 为 DeepSeek Harness 提供供应链安全检查工具。智能体可以在安装之前查看 npm 包的元数据和已发布的 tarball，然后在同一段对话里拿到证据、风险等级和可解释的评分。

插件注册一批工具，由智能体自行决定是否调用。它不拦截 shell 命令，也不会自动拦住每一次 npm、pnpm、yarn 或 DSH 插件安装。请在智能体工作流里配置成安装前必须检查确切版本；强制安装策略要另外在你的宿主或 CI 里落实。ci_scan 失败只是一个工具结果，调用方必须自己处理。

如果它让你的智能体工作流更安全，请给仓库点个 Star。这能帮其他 DSH 用户找到这个独立的安全工具。

30 秒安装

dsh plugin --profile tui add @npm-safe/dsh-tool-npm-safe --allow-build=better-sqlite3
dsh --profile tui

安装完成后重启正在运行的配置档。然后这样问：

Deep-scan fast-glob before installing it. Explain every finding.

只想快速查一下元数据：

Use check_package to check lodash.

插件声明为原生 DSH bundle，所以官方 dsh plugin 命令会安装包并激活它的 cordis.patch.yml 层。--allow-build=better-sqlite3 只给本地缓存用的 SQLite 驱动授予构建权限；pnpm 仍会拦截其他依赖的安装脚本。你选定的 DSH 模型服务商必须已经配置好；只有选中 DeepSeek 作为服务商时才需要 DeepSeek API key。

能查出什么

| 信号 | 元数据扫描 | 深度扫描 |
| 可疑的生命周期脚本和安装钩子 | ✅ | ✅ |
| 仿冒包名、废弃包、有风险维护者 | ✅ | ✅ |
| 非标准 registry 和远程二进制 | ✅ | ✅ |
| Tarball 完整性不匹配、归档路径不安全 | — | ✅ |
| 混淆代码、内嵌密钥、shell/网络执行 | — | ✅ |
| 原生二进制、WebAssembly、超大或截断内容 | — | ✅ |

元数据扫描速度快，仍是默认方式。设置 deep: true 后，会下载同源发布的 tarball，校验 npm 完整性元数据，并完全在内存中检查限定范围内的源码内容。

package: fast-glob@3.3.3
level: safe
score: 88/100
integrity: verified
files scanned: 91
findings: 1 low, 0 medium, 0 high, 0 critical

为什么在智能体里用它

| 典型智能体工作流 | 使用 npm-safe-forDSH 后 |
| 先安装，事后再审计 | 在决定安装之前先检查 |
| 信任包名和下载量 | 评估维护者、脚本、来源信号和内容 |
| 只返回通过/不通过，缺少上下文 | 返回发现项、证据、严重程度、评分和建议 |
| 反复请求 registry | 使用本地 SQLite 缓存和限流 |
| 手动检查单个包 | 支持批量检查、关注列表、刷新任务和 CI 门禁 |

14 个智能体工具

| 工具 | 用途 |
| check_package | 检查单个包，可选 version、forceRefresh 和 deep |
| check_packages | 限流的批量检查 |
| search_packages | 搜索 npm registry |
| watch_add / watch_remove / watch_list | 管理持久化关注列表 |
| rules_list / rule_enable / rule_disable | 查看和开关规则 |
| rule_set_severity | 覆盖规则严重程度 |
| settings_get / settings_set | 读取或更新引擎设置 |
| ci_scan | 把项目依赖当作安全门禁来扫描 |
| refresh_all | 作为后台 DSH 任务刷新关注列表 |

安全模型

- 核心检测是确定性的，且本地优先；默认不把包源码发送给外部 LLM。
- 深度扫描会拒绝跨源 tarball，并强制限制归档大小、文件数量、解压、路径和扫描文本范围。
- 发现项只是证据，不保证包一定安全。生产环境请审查高影响包并锁定版本。
- 完整规则见 scanner rules 和 security policy。

直接使用引擎

pnpm add @npm-safe/core-dsh

import { NpmSafeEngine } from "@npm-safe/core-dsh";

const engine = new NpmSafeEngine();
const report = await engine.checkPackage("lodash", { version: "4.17.21", deep: true });
console.log(report.latestVersion, report.security.overallLevel, report.security.overallScore);
await engine.close();

从源码开发

需要 Node.js 24.9+ 和 Corepack。

git clone https://github.com/nisconder/npm-safe-forDSH.git
cd npm-safe-forDSH
corepack enable
corepack prepare pnpm@11.7.0 --activate
pnpm install
pnpm run build
pnpm run typecheck
pnpm run test

仓库在 vendor/ 下固定了 @npm-safe/core@1.1.2 的发布 tarball 通过工作区覆盖实现。扫描器源码只在 nisconder/npm-safe 维护。packages/core 是一层很小的兼容门面，没有复制扫描器、数据库或注册表实现。可复现的 --core-tarball 工作流和发布顺序见更新共享核心。

在线注册表冒烟测试：

node scripts/smoke.mjs lodash
node scripts/smoke-facade.mjs

工作区包含 @npm-safe/core-dsh 和 @npm-safe/dsh-tool-npm-safe 插件包。DSH 对等包统一对齐到 0.2.1-rc.5 系列，插件包把 engines.dsh 声明为 >=0.2.1-rc.5 <0.3.0；DeepSeek Harness 处于开发者预览阶段时，升级必须让对等包和这个范围保持一致。

文档

- 插件包与示例
- 引擎 API
- 架构
- 扫描器规则
- 贡献指南

本项目依赖 nisconder/npm-safe 提供的共享引擎，用于 DeepSeek Harness。本项目是独立的社区项目，与 DeepSeek 没有隶属关系，也未获其认可。

许可证

Apache-2.0 — Copyright 2026 Nisconder, InfiniteScope, Escap1ng, StoryBegins。