npx-vibe

npx-vibe

在代码执行前，以证据为先审查 npm 软件包。适用于开发者、编码 Agent、MCP 客户端和 CI。

npx-vibe 会解析 registry 软件包，下载并验证其 tarball，但不会运行软件包代码；它会读取范围受限的安装时和可执行源代码，并根据证据报告 Proceed、Caution 或 Block。

3.0.0 是计划中的最终版本。主动维护已结束；后续不会再提供兼容性更新或安全补丁。 该软件包仍以 MIT 许可证提供。集成前请阅读维护政策和 3.0 迁移指南。

网站和演示 · npm 软件包 · 变更日志 · npm 12 指南

快速开始

需要 Node.js 20 或更高版本，并且能够访问 npm registry。默认扫描无需账户、AI 模型或 API 密钥。

# Review only — does not execute the target package
npx --yes [email protected] [email protected]

# Inspect install-time behavior
npx --yes [email protected] esbuild

# Review a project's locked production dependency tree
npx --yes [email protected] project

# Include development dependencies
npx --yes [email protected] project --include-dev

外层的 npx 会安装并运行 npx-vibe 本身；审查过程不会执行目标软件包。你也可以全局安装 CLI：

npm install --global [email protected]
npx-vibe [email protected]

扫描是默认操作。执行需要使用单独的 run 命令：

npx --yes [email protected] run cowsay -- hello
npx --yes [email protected] run --bin tsc typescript -- --version

Proceed 结果允许执行请求的操作；Caution 会在交互式终端中要求确认，否则会退出而不执行。除非有意使用 --force 覆盖，否则 Block 会阻止执行。默认忽略安装脚本。运行过程未经过沙盒隔离，并且可能安装未经审查的传递依赖；如果需要考虑更广的范围，请单独扫描项目。

审查哪些内容？

• 确切的软件包版本、registry 元数据和 tarball 完整性。
• 审查范围内的安装钩子、bin 入口点和可访问的相对源代码导入。
• 凭证读取与网络调用相结合、下载的负载执行、可疑写入和混淆等信号。
• 可用时来自 OSV 的已知漏洞公告。
• 仓库活动、维护者、软件包历史和下载量，作为背景信息——而非信任证明，也不用于降低评分。
• 可选的大模型解读，并对 AI 发现进行源码匹配。
• 基于本地完整性密钥的审查历史记录，不会跳过新一轮验证。

归档会在内存中解析，不会被解压或执行。文件选择和源代码分析都有范围限制；该工具不会审查每个源文件，也不会递归检查单个软件包的所有依赖项。

判定结果与自动化

退出码	含义	Agent 操作
0	Proceed：审查范围内没有阻断信号	continue
2	Caution：证据需要审查	review
3	Block：发现高风险问题	stop
1	错误或请求的审查未完成	retry

完整的 Proceed 扫描并非安全保证。OSV 查询不可用时会显示为不可用，而不是“未发现问题”；OSV 仅作补充，其服务中断本身不会导致软件包扫描失败。--no-advisories 会显式禁用该功能。

项目覆盖范围：不静默回退

对于非空项目，默认项目扫描需要包含带有 packages 映射的 package-lock.json（npm lockfile v2/v3）。生成 lockfile 时不要运行安装脚本：

npm install --package-lock-only --ignore-scripts
npx --yes [email protected] project

没有 lockfile？请明确选择范围更窄的审查：

npx --yes [email protected] project --direct-only

工作区/本地链接、Git 来源、别名和来自其他注册表的制品不在此仅限注册表的审查范围内。它们会被报告为跳过，而不会被替换成名称相似的公共包。存在跳过的包、达到包数量限制或扫描失败时，结果均为不完整（退出码 1）。默认限制为 500 个包；--max-packages 可将上限提高至 5,000 个。

注册表完整性校验值和 lockfile 中记录的完整性校验值都必须与下载的制品匹配。除非选择 --include-dev，否则不包含开发依赖。

npm 安装脚本权限

npx-vibe 可以审查 lockfile 标记为含有安装脚本的依赖，并建议 approve、review 或 deny：

npx --yes [email protected] approve-scripts
npx --yes [email protected] approve-scripts --all

对于可识别的本地构建命令，可以批准；涉及网络/ shell 行为、隐式原生构建和部分源代码读取时，则需要审查。高风险发现会被拒绝。建议并不保证构建工具或其读取的每个文件都是安全的。

若只记录明确无疑的决定：

npx --yes [email protected] approve-scripts --write

新的 allowScripts 条目始终会固定到经过审查的版本。需要人工审查的条目绝不会被静默批准；不完整的审查也无法写入权限。现有的宽泛权限会予以保留：使用 --all，并自行移除或缩小权限范围。--pin 仍是兼容性别名。

使用 npm 10/11 和 npm 12 均可读取并审查；allowScripts 的强制执行由兼容的 npm 版本负责。请参阅 npm 12 指南。

编码 Agent

--agent 会输出 schema 3 决策信封，禁用本地历史记录写入，并拒绝执行和写入权限的标志：

npx --yes [email protected] --agent [email protected]
npx --yes [email protected] project --agent --include-dev
npx --yes [email protected] approve-scripts --agent

精简示例（完整结果还包含报告）：

{
  "schemaVersion": 3,
  "kind": "package-scan",
  "status": "complete",
  "decision": {
    "verdict": "proceed",
    "riskScore": 0,
    "action": "continue",
    "exitCode": 0,
    "mayContinue": true
  },
  "coverage": {
    "scope": "package",
    "complete": true,
    "requested": 1,
    "scanned": 1,
    "skipped": 0,
    "failed": 0,
    "reasons": []
  }
}

继续已获授权的工作流之前，请确认 schema 为 3、status === "complete"、coverage.complete === true 且 decision.action === "continue"。遇到 review 时，请咨询人员；遇到 stop 时，不要执行；遇到 retry 时，请先解决覆盖范围缺失或错误。主题覆盖数量不代表已穷尽所有源文件。

已移除的 decision.safeToExecute 字段不会被其他安全承诺取代。

安装可移植的 Agent Skill：

npx skills add Devrajsinh-Jhala/NPM-Vibe-check --skill npx-vibe -g

Agent Skill · 面向 Agent 的文档

MCP 支持

运行本地、零依赖的 stdio MCP 服务：

npx --yes [email protected] npx-vibe-mcp

客户端配置示例（你的客户端配置格式可能有所不同）：

{
  "mcpServers": {
    "npx-vibe": {
      "command": "npx",
      "args": ["--yes", "[email protected]", "npx-vibe-mcp"]
    }
  }
}

工具：

工具	用途
scan_package	审查一个公开的 npm 包规格
scan_project	审查已锁定的依赖树；directOnly 可明确缩小范围
approve_scripts	提供只读的安装脚本权限建议
list_providers	列出支持的提供方及其配置；不进行实时模型发现

这些工具为只读工具，基于 schema，并同时返回 JSON 文本和结构化内容。不完整或出错的结果会设置 MCP isError: true。协议支持包括 2025-11-25；工具结果使用 schema 3。凭据通过服务环境提供，绝不会通过工具参数传递。

规范的 MCP Registry 标识为 io.github.Devrajsinh-Jhala/npx-vibe。npm 和 MCP Registry 的发布相互独立；请查看 Registry 条目，了解其可用版本。

此动画展示了一个 Caution 审查流程。结果经过了简化，并非实时调用提供方所得。

可选的 AI 审查

默认情况下，AI 处于禁用状态，即使环境中存在特定提供方的密钥也是如此。明确选择启用后，只有在启发式检测发现问题时才会进行审查。

在线提供方包括 Gemini、OpenAI、Anthropic、OpenRouter、Groq、Together，以及自定义的 OpenAI 兼容端点。这里没有固定不变的“最新模型”列表：请选择一个你的账户可用的确切模型 ID。

npx --yes [email protected] --models
npx --yes [email protected] --ai online --provider gemini --model <model-id> esbuild
npx --yes [email protected] --ai ollama --model <installed-model> esbuild

请替换尖括号占位符；它们不是实际的 shell 参数。在环境中配置特定提供方的密钥，例如 GEMINI_API_KEY、OPENAI_API_KEY 或 ANTHROPIC_API_KEY。显式设置 --ai off 的优先级高于密钥快捷方式。专用的 NPX_VIBE_API_KEY 和 --api-key 会明确启用 AI；建议使用环境变量，以免密钥进入 shell 历史记录。

有歧义的直接密钥必须通过 --provider 指定提供方；它们不会被悄悄转发给其他提供方。自定义端点还需要 --api-url（完整的 chat-completions 端点）和准确的 --model。提供方错误会经过脱敏并予以报告，不会取代确定性审查。

在线审查会将选定的包源码和有限的元数据发送给指定提供方。它不会上传你的环境或本地项目文件。本地 Ollama 审查会将这些内容保留在你配置的本地端点上。AI 仅提供建议，不是信任权威。

GitHub Actions

固定 Action 和扫描器版本：

- uses: actions/checkout@v6
- uses: actions/setup-node@v6
  with:
    node-version: 24
- uses: Devrajsinh-Jhala/[email protected]
  with:
    version: '3.0.0'
    command: project
    include-dev: 'true'
    fail-on: caution

该 Action 使用隔离的临时安装，生成注释和作业摘要，并提供 verdict 和 exit-code。fail-on 可接受 block（默认值）、caution 或 never；错误和覆盖不完整的情况始终会导致失败。该 Action 禁用了 AI 和本地历史记录写入。与可变标签相比，提交 SHA 能提供更可靠的固定版本。

Marketplace 列表 · Action 输入项

限制与支持

npx-vibe 不是沙箱、杀毒引擎或详尽的审计工具，也无法替代依赖项控制。它可能会遗漏条件触发、仅在运行时出现、延迟执行、混淆处理或传递性行为，也可能产生误报。归档检查受到大小、文件数量和源码选择方面的限制。网络元数据和安全公告服务可能不可用或信息过时。

如果你在扫描后运行某个包，npm 会单独执行安装；审查并非原子化安装，也不保证所有执行内容都经过检查。提供方 API、模型可用性、npm 行为和 MCP 生态可能会在此固定版本发布后发生变化。

安全边界 · 维护与分支 · 迁移

开发

npm install --ignore-scripts
npm run verify
npm run smoke:pack
npm run site:preview

测试套件涵盖判定结果、归档限制、提供方路由与脱敏、锁定依赖项扫描、脚本权限、Agent 架构以及 MCP 传输。打包产物检查会测试 CLI 和 MCP 入口。

许可证

MIT · 由 Devrajsinh Jhala 构建。