pkgverdict

pkgverdict

在安装 npm 包之前检查它。一个命令，一个判定：GO、RISKY、FAKE 或 MISSING——用简单明了的文字呈现，你的 AI 编码 Agent 也能读懂。

pkgverdict 以容器镜像的形式发布在 GHCR 上（没有名为 pkgverdict 的 npm 包，所以 npx pkgverdict 会返回 404——请使用 Docker）：

docker run --rm ghcr.io/cloudcorprecords/pkgverdict check react-markdown
# [GO] [email protected]
#   - 5y old, 38.4M/wk, no install scripts, no advisories, no lookalike name.

docker run --rm ghcr.io/cloudcorprecords/pkgverdict check unused-imports
# [FAKE] [email protected]
#   - Flagged malicious: MAL-2025-48781. Do not install.
#   - Name rides on eslint-plugin-unused-imports (suffix of popular name) and the
#     package is barely downloaded — the classic typosquat shape.

docker run --rm ghcr.io/cloudcorprecords/pkgverdict check react-super-hooks-plus
# [MISSING] react-super-hooks-plus
#   - react-super-hooks-plus is not on the npm registry. If an AI assistant
#     suggested it, the name was hallucinated.

为什么

AI 助手现在会帮开发者选择一半要安装的包——它们还会幻觉出攻击者已经注册的名称（slopsquatting），而拼写仿冒包和遭劫持的版本则持续发布 postinstall 恶意软件。npm audit 只能发现已发布的安全公告，而且往往为时已晚。pkgverdict 会在安装之前进行检查：包是否存在、名称是否相似、包龄、安装脚本、维护者、下载量和 OSV 安全公告。

在 AI 编码工具中使用

只需一个命令即可完成设置。在项目目录中运行：

docker run --rm -v "$PWD":/work -w /work ghcr.io/cloudcorprecords/pkgverdict init --agent claude-code

这会安装 MCP 服务配置，以及一段指导 Agent 遵守一条行为规则的说明：**安装前先用 pkgverdict 检查。**支持的工具：claude-code、cursor、copilot（VS Code）、windsurf、cline 和 generic（init --list 会显示所有工具；--all 会设置所有工具；--dry-run 会预览但不写入）。重启工具，通过“列出你的 MCP 工具”提示词进行验证，pkgverdict 服务应会显示 2 个工具（check_package、scan_dependencies）。如果你更喜欢手动安装，底层安装包位于 integrations/。

CLI

# Verdict on one package (name or name@version)
docker run --rm ghcr.io/cloudcorprecords/pkgverdict check lodash

# Check every dependency in package.json, worst first
docker run --rm -v "$PWD":/work -w /work ghcr.io/cloudcorprecords/pkgverdict scan
docker run --rm -v "$PWD":/work -w /work ghcr.io/cloudcorprecords/pkgverdict scan ./my-app --no-dev

# Check your setup (Node version, registry + OSV reachability, cache)
docker run --rm ghcr.io/cloudcorprecords/pkgverdict doctor

# JSON output for scripting and CI
docker run --rm ghcr.io/cloudcorprecords/pkgverdict check left-pad --json

退出代码：一切均为 GO（或未使用 --strict 时为 RISKY）时返回 0；发现 FAKE 或 MISSING 包时返回 1；用法错误时返回 2。对于任何可疑项都应失败的 CI 门禁：pkgverdict scan --strict。

判定结果

判定	含义
GO	已确立的包，没有明显风险。放心安装。
RISKY	注意：存在安装脚本、包龄很短、知名度低、已弃用、没有仓库或许可证、存在已知安全公告，或者原本正常的包名称与其他包相似。安装前请仔细阅读。
FAKE	看起来明显有问题：新包或冷门包的名称像是拼写仿冒包、存在恶意安装脚本，或存在恶意安全公告（MAL- ID、MAL- 别名，或 OSV 记录详情将包标记为恶意或植入后门——例如 [email protected] 遭入侵事件，该事件以 GHSA ID 记录）。请勿安装。
MISSING	注册表中完全没有该包——名称可能拼错或是幻觉生成的名称；如果有合适的建议，还会显示“你是不是想找”。

信号来自 npm 注册表（元数据、下载量）、OSV 数据库（安全公告），以及用于检测名称相似包的内置知名包列表。响应缓存于 ~/.cache/pkgverdict（元数据缓存 6 小时，安全公告缓存 1 小时）；删除该目录即可强制重新检查。

发布渠道

pkgverdict 恰好有两个发布渠道，且二者都是有意为之：

1. GHCR：容器镜像 ghcr.io/cloudcorprecords/pkgverdict，在每次发布时由 Publish container 工作流构建并推送。
2. MCP Registry：条目 io.github.CloudCorpRecords/pkgverdict，其 server.json 只包含 OCI 包，并指向同一个 GHCR 镜像。

没有 npm 包，这是设计如此，并非遗漏步骤。npx pkgverdict 返回 404 是预期行为。package.json 中的无作用域名称用于构建镜像和标记 CLI 版本；该包被标记为 private，这样在检出目录中误运行 npm publish 会立即失败，而不会占用该名称。旧模板工作流曾在每次发布时运行 npm publish，现在已停用，位于 .github/workflows/publish.yml，只会打印这套发布模式，而不会发布到 npm。之后是否发布到 npm 将由维护者决定，并且需要使用带作用域的名称，以及拥有相应权限的令牌。这些事实由 test/distribution.test.ts 固定下来，因此相关残留不会悄然回归。

使用 Docker 运行

GHCR 镜像是主要的分发方式：ghcr.io/cloudcorprecords/pkgverdict。

将其用作 stdio MCP 服务：

docker run --rm -i ghcr.io/cloudcorprecords/pkgverdict

可以在镜像名称后传入任何 CLI 命令，以代替默认的 mcp 参数：

docker run --rm ghcr.io/cloudcorprecords/pkgverdict <command> [args]

MCP 服务

让 MCP 客户端通过 Docker（stdio）连接：

{
  "mcpServers": {
    "pkgverdict": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/cloudcorprecords/pkgverdict", "mcp"]
    }
  }
}

提供两个工具：check_package（对单个包给出判定）和 scan_dependencies（按风险从高到低给出项目 package.json 中各包的判定）。

开发

npm install
npm run build
npm test        # offline fixture corpus: every verdict rule pinned to a case

许可证

MIT。