import-guardian

import-guardian 🪝

在运行 npm install 之前，捕获生成代码中由 AI 幻觉（占位抢注）产生的 npm 导入。

大模型刚刚写了一些代码。它可能会 import 一个不存在的包——这是模型自信地凭空捏造的名称。攻击者会注册这些名称并植入恶意软件。这就是占位抢注，而在 2026 年，这已成为增长最快的供应链攻击之一：据观察，代码生成器引用了 205,000+ 个独一无二的不存在的包名；现实中也已经出现了真正由模型幻觉生成的包（react-codeshift、下载量超过 30k 的假冒 huggingface-cli）。

import-guardian 会读取生成的代码，提取其中导入的所有 npm 包，并告诉你哪些是真实存在的——这样 Agent 就不会安装模型凭空捏造的包名。

它是 guardian 系列工具的一员：npm-guardian 会审查你_已选定_的包，检查其中的 CVE 和恶意行为；license-guardian 会在你发布之前审查依赖项的_许可证_（识别 GPL/AGPL/BUSL 陷阱）；lockfile-guardian 会审查解析后的 package-lock.json，检查完整性篡改和有风险的安装脚本。import-guardian 比它们都更早一步，在代码及其依赖名称生成时就开始工作。

它能捕获哪些问题

👻 幻觉包	导入npm 上不存在的包——模型凭空捏造了名称。返回 BLOCK，并提供最接近的真实包作为“你是不是想找”。
🪤 新近抢注	确实存在但发布仅数日、没有源码仓库、下载量接近零，或与热门库仅有 1–2 处编辑差异的包。返回 REVIEW。
🧩 感知导入路径	将 import x from "@scope/pkg/sub" 解析为 @scope/pkg，将 lodash/fp 解析为 lodash；跳过 Node 内置模块（fs、node:path）和本地路径。使用普通正则表达式，无需 AST，除 MCP SDK 外零运行时依赖。

判定结果：🟢 CLEAN · 🟠 REVIEW · 🔴 BLOCK。

将它用作 MCP 服务（免费）

{
  "mcpServers": {
    "import-guardian": { "command": "npx", "args": ["-y", "import-guardian-mcp"] }
  }
}

工具：

• scan_code_imports — 提供一段生成的 JS/TS 代码；它会提取并检查所有 npm 导入。请在刚生成代码后、运行安装命令之前执行此检查。
• check_packages — 验证明确列出的包名。
• verify_package — 深入检查单个包名（是否存在、发布时间、版本、仓库、每周下载量、与热门包的编辑距离）。
• audit_lockfile 🔒 （高级版） — 深度审计工具。提供来自 npm（package-lock.json）、yarn（yarn.lock）、pnpm（pnpm-lock.yaml）、PyPI（requirements.txt / poetry.lock / Pipfile.lock）或 Go（go.mod / go.sum）的锁文件，它会解析整个传递依赖树，并审计每个包是否存在依赖混淆、传递依赖中的错别字抢注 / 同形字克隆、维护者接管特征、不存在的锁定项，以及安装脚本风险。详见下文。

深度锁文件审计（高级版）🔒

scan_code_imports 会检查你能看到的少数导入。audit_lockfile 会检查你看不到的数百个依赖——也就是锁文件中完全解析后的依赖关系图——并找出大模型仅凭源码无法推断的供应链攻击：

🎯 依赖混淆	锁文件从私有 / 内部注册表解析出的包，其名称在公共索引上尚未被占用——攻击者可以在公共索引上发布同名包并进行替换。这是影响最大的供应链漏洞，没有解析后的锁文件和实时公共注册表交叉检查就无法检测。在 PyPI 上情况更严重：pip install --extra-index-url 会合并你的私有索引和公共 PyPI，并安装两者中版本最高的包（2021 年影响 Microsoft / Apple / Tesla 的攻击就是如此）。返回 critical。
🪞 传递依赖拼写仿冒	同形 / Unicode 易混淆克隆（rеact 中的 e 是西里尔字母）、字母换位（axois→axios），以及特定注册表中的仿冒包（PyPI 上的 python3-dateutil 与 python-dateutil，根据 PEP 503 进行规范化），覆盖整棵依赖树——并与各生态系统中包含高流量包的大型语料库进行匹配。
🕳️ 维护者账号接管	受入侵维护者的特征：休眠包突然重新发布、由单一维护者维护的项目，或短时间内密集重新发布——这是 event-stream、ua-parser-js、node-ipc 以及 PyPI 的 ctx 劫持事件中出现的模式。
💉 安装脚本版本差异检测	最敏锐的注入信号：某个包的最新版本新增了 postinstall/preinstall/install/prepare 钩子，而前一版本没有。原本干净的依赖突然获得安装时执行代码的能力，正是 event-stream 和 ua-parser-js 攻击中采用的方式——通过比较实时注册表上两个版本的元数据即可捕获。返回 critical，并告知你可固定的最后一个安全版本。
🔬 安装脚本载荷分析	不只检查是否存在钩子，还会分析钩子的行为：下载包的 tarball，在内存中解压 gzip 并 untar（无依赖），将生命周期命令解析到入口文件，并对实际代码进行静态分析，查找恶意软件行为——网络外传、凭据 / 环境变量窃取、子进程执行、下载并运行、混淆。抗混淆 AST / 令牌分析器会解码 \x/\u/八进制转义，并合并拆分的字符串拼接，因此即使危险调用藏在 require("child-pro"+"cess") 或 global["ev"+"al"](…) 中也能捕获。载荷藏在买方的 Agent 从不获取的二进制工件中——这就是访问权限与计算能力构成的护城河。
🐍 PyPI sdist setup.py 载荷分析	这是 PyPI 对 npm tarball 扫描的对应方案，也是 PyPI 风险最高的入口：源代码分发包会在 pip install 时、执行你的任何代码之前运行 setup.py——任意 Python 代码。我们会下载 sdist（设有反 DoS 大小上限），在内存中解压，并对 setup.py / setup.cfg / pyproject.toml 进行静态分析，查找窃取器 / 加载器模式——os.environ 外传、os.system/subprocess 执行、.pypirc/AWS/SSH 凭据窃取、urllib/requests 外连、exec/eval/__import__ 混淆、下载并运行，以及非标准构建后端。Python AST 反混淆器会解码 \x/\u/八进制转义，并合并拆分字符串与隐式相邻字符串，因此 getattr(__import__("o"+"s"),"sys"+"tem")(…) 仍能被解析。可从买方的 Agent 从不获取的工件中捕获 ctx / jeIlyfish / colourama 这一类攻击。只有出现恶意软件的组合特征（外传 / 下载并执行 / 打包加载器）时才会触发 BLOCK，因此仅调用编译器的合法 C/Cython 构建只会被报告为信息提示，不会误报并阻止。
🦠 已知恶意软件 / 已知漏洞（实时交叉查询 OSV）	每个已解析的包都会以其确切固定版本与实时 OSV.dev 安全公告数据库交叉查询（该数据库收录了 OpenSSF Malicious Packages 源中的 MAL-*，以及 GitHub/PyPI/Go/crates/Maven/Packagist 的安全公告）。如果锁文件固定的版本已被记录为恶意软件（例如 [email protected]、[email protected]），这就是 critical / BLOCK——可能是最强的信号。映射关系是特定于版本的：[email protected] 是恶意软件，3.3.4 则是安全的，只有查询实时数据库才能区分两者。这与上述静态扫描的护城河属于不同类型——买方的模型不包含安全公告语料库，也无法解析版本与安全公告之间的对应关系。查询会进行批量处理、缓存（TTL）并发数设上限，且当 OSV 无法访问时会按安全处理（绝不会将安全包误报为问题包）。
🏗️ 本地构建后端跟进一跳（PyPI）	当 pyproject.toml 声明了一个包含在 sdist 内部的非标准构建后端（backend-path = ["."]）时，每次构建 / 安装都会将包自身的代码作为 PEP 517 后端运行。我们会在 sdist 中将该模块解析到对应文件并分析其实际源码（并跟进 setup.py 的本地导入一跳），而不只是标记后端名称——从而弥补载荷藏在 setup.py 之外一层间接调用中的检测缺口。
🔀 Go replace 劫持	go.mod 中指向外部主机的 replace … => host/path，并通过 Go 模块代理进行实时验证。如果替换目标无法解析（例如私有主机 / 攻击者主机），那么构建实际编译的代码就不是你审核过的模块，也不是 go.sum 能为之背书的内容。
💣 安装脚本与来源风险	已解析依赖树中会运行安装脚本的包、新近固定的版本、缺失仓库的包，以及实际下载量几乎为零的包（通过 npm / pypistats / crates.io 验证）。
七大生态系统。 同一个已解析依赖图引擎可用于 npm / yarn / pnpm、PyPI（requirements.txt、poetry.lock、Pipfile.lock）、Go 模块（go.mod、go.sum）、Rust / Cargo（Cargo.lock、Cargo.toml）、Java（Maven pom.xml、Gradle build.gradle / .kts / gradle.lockfile）和 PHP / Composer（composer.json、composer.lock），并分别与对应的公开索引交叉核验（npm registry、PyPI、Go 模块代理、crates.io、Maven Central、Packagist）。在 crates.io 上，匹配器了解 -/_ 的等价关系（rustdecimal 与 rust_decimal）；在 Maven 上，Central 未被认领的内部 groupId:artifactId 是依赖混淆目标；在 Composer 上，未在 Packagist 注册、但私有仓库与公共索引合并时的内部 vendor/package 是混淆目标；Packagist 上被标记为 abandoned 的包则会被标记为接管风险。大型锁文件会受到限制：始终先实时检查直接依赖和私有来源的包，然后再检查数量不超过上限的传递依赖，因此单次调用不会触发数万次请求。

POST /pro/audit   { "lockfile": "<contents of package-lock.json>", "filename": "package-lock.json" }

通过 x402（Base 上的 USDC）或预付费 Stripe 密钥按次付费。免费接口 POST /audit 会返回判定结果和按严重程度统计的问题数量，但不会透露哪些包受到影响以及原因——这些内容包含在付费报告中。此深度引擎仅在服务端运行，绝不会随 npm 包一同发布。

示例

scan_code_imports({ code: 'import shift from "react-codeshift";\nimport React from "react";' })

🟠 REVIEW — 1 referenced package(s) look risky.
🟠 react-codeshift  (risk 57/100)
    • No source repository linked.
    • Only 1 published version.
    • Only 3 downloads in the last week despite being 158 days old.
🟢 react  (ok) — established package.

免费 HTTP API

POST /scan        { "code": "import x from 'reqeusts'\nimport y from 'lodash'" }
GET  /verify?name=express

托管于 https://import-guardian.vercel.app · 试试 /verify?name=express 和 /verify?name=reqeusts。

按次付费（x402）

/pro/* 路由受 x402 保护。你的 Agent 会自动为每次调用支付 $0.02 USDC，无需注册，也无需 API 密钥。款项通过链上结算（Base 上的 USDC）。服务端不持有私钥；它只声明一个公开收款地址。

POST /pro/scan    { "code": "…" }   # 402 → pay → result, no rate limit

工作原理（及其局限）

• 包是否存在及其新鲜度数据直接来自 npm 实时 registry（registry.npmjs.org）和下载统计 API——这些都是事实，而非猜测，这正是其核心优势：Agent 无法仅凭自身可靠地判断它生成的名称是否真实可信。
• “你是否想查”会基于一份精选的高影响力包列表，使用 Levenshtein 距离来匹配攻击者冒充的包。
• 它不会执行或安装任何内容（只读），并且会有意倾向于标记为 REVIEW，而不是默默放行一个新出现的仿冒包。它是一道防护措施，而非保证——请搭配 npm-guardian，对你决定保留的包进行行为和 CVE 审计。

许可证

MIT。