Package Manager Guard (PMG)

在恶意 npm 和 pip 包安装之前将其拦截。
为你已在使用的包管理器提供纵深防御。

License Release

为什么选择 PMG？

开发者和 AI 编码代理每天都在安装软件包。每一次 npm install 或 pip install 都会执行数千行无人审查的代码。

近期热门生态系统中发生的入侵事件：

Mini Shai-Hulud - 300 多个热门软件包被入侵
litellm 1.82.8 - 一个流行的 AI 代理库被入侵以窃取凭据
telnyx 4.87.2 - 一个合法的电信 SDK 在 PyPI 上被劫持
pino-sdk-v2 - 一个伪装成流行 pino 日志库的仿冒包

PMG 免费、开源（Apache 2.0），无需账户或 API 密钥。 它会拦截每一次软件包安装，并在代码执行之前对照 SafeDep 的免费社区 API 检查已知恶意软件。安装一次，此后它便会覆盖每一次 npm install、pip install 和 poetry add。

PMG 的工作原理

PMG 采用纵深防御策略。零配置，兼容 Zsh、Bash 和 Fish，每次安装都会在代码运行前经过已启用的各层保护，并在之后留下审计记录。

PMG defense in depth: install command intercepted by PMG, passed through Layer 1 Threat Intel, Layer 2 Cooldown, Layer 3 Sandbox, then run with an audit log entry

各层详情

透明拦截 - PMG 包装 npm、pip 及其他包管理器。开发者和 AI 代理使用相同的命令。无需改变工作流程。
第 1 层：威胁情报 - PMG 在安装前对照 SafeDep 的实时威胁情报检查每个软件包。已知恶意的软件包会被拦截。无需密钥，无需登录。
第 2 层：策略（依赖冷却） - PMG 会拦截在可配置冷却窗口内发布的软件包版本，因此近期被入侵的版本会在该窗口期内被跳过。
第 3 层：可选沙箱 - 当沙箱功能启用并配置后，PMG 会在操作系统原生沙箱（默认 macOS Seatbelt、Linux Landlock，或 Bubblewrap 作为后备）内运行安装，因此即使威胁突破了前两层，安装脚本的系统访问权限也受到限制。
审计日志 - PMG 记录每一次安装（安装了什么、何时、来自何处），形成可验证的审计轨迹。

PMG 的对比优势

PMG 是唯一免费、开源、安装时生效的软件包防火墙，同时覆盖开发者和 AI 代理，并开箱即用地提供沙箱和冷却功能。

能力	PMG	Socket	safe-chain	Snyk	Dependabot
开源 / 公开构建	✓	✗	✓	✗	✗
无需账户或 API 密钥	✓	✓	✓	✗	✗
安装时拦截恶意软件包	✓	✓	✓	✗	✗
依赖冷却策略	✓	✗	✓	✗	✗
运行时沙箱	✓	✗	✗	✗	✗
透明保护 AI 编码代理	✓	✗	✗	✗	✗
本地审计日志	✓	✗	✗	✗	✗
已知 CVE 修复 PR	✗	✗	✗	✓	✓

快速开始

1. 安装

curl -fsSL https://raw.githubusercontent.com/safedep/pmg/main/install.sh | sh

有关 Homebrew、npm 及其他安装方式，请参阅安装。

2. 设置

将 PMG 接入你的 shell，使其能够拦截包管理器。

pmg setup install
# Restart your terminal to apply changes

提示： 升级 PMG 后请重新运行 pmg setup install，以应用新的配置选项。

全用户 / 黄金镜像：在 Linux 上使用 sudo pmg setup install --system，在 Windows 上以管理员身份运行 pmg setup install --system — 参见 docs/system-install.md。

验证你的安装并确认保护正在生效：

pmg setup doctor

可选： PMG 使用一个即时生成的 CA 来检查 HTTPS 流量，并在每次运行时将其注入包管理器。若要在多次运行间持久保留同一个 CA 并将其信任到操作系统的信任存储中（对于忽略 CA 环境变量的工具是必需的，例如 macOS 和 Windows 上的 Go），请安装一次：
pmg setup cert install          # user scope, no sudo
pmg setup cert status           # check trust state and expiry
有关作用域、轮换和移除，请参阅证书颁发机构。

3. 使用

查看 PMG 拦截威胁。

npm install --no-cache --prefer-online [email protected]

注意： safedep-test-pkg 是一个良性测试包，在 SafeDep 数据库中被标记为恶意，用于测试和验证目的。

像往常一样继续使用你的包管理器，或让你的 AI 编码代理运行它们。PMG 位于执行路径中，拦截恶意软件包。

npm install express
# or
pip install requests

支持的包管理器

PMG 支持你已经在使用的工具：

生态系统	工具	命令示例
Node.js	`npm`	`npm install <pkg>`
	`pnpm`	`pnpm add <pkg>`
	`yarn`	`yarn add <pkg>`
	`bun`	`bun add <pkg>`
	`aube`	`aube add <pkg>`
	`npx`	`npx <pkg>`
	`pnpx`	`pnpx <pkg>`
	`aubx`	`aubx <pkg>`
	`aubr`	`aubr <script>`
Python	`pip`	`pip install <pkg>`
	`pipx`	`pipx run <pkg>`
	`poetry`	`poetry add <pkg>`
	`uv`	`uv add <pkg>`
	`uvx`	`uvx <pkg>`

安装

安装脚本（MacOS/Linux）

从 GitHub 下载最新版本，验证其 SHA-256 校验和，并安装到 $HOME/.local/bin（如果该路径在 PATH 中）或 /usr/local/bin。

curl -fsSL https://raw.githubusercontent.com/safedep/pmg/main/install.sh | sh

Homebrew（MacOS/Linux）

brew tap safedep/tap
brew install safedep/tap/pmg

NPM（跨平台）

npm install -g @safedep/pmg

注意： 当 Node.js 由 mise 或 asdf 等版本管理器管理时，基于 NPM 的安装可能较为脆弱。全局 npm bin 路径会随当前激活的 Node 版本而变化，因此切换版本可能导致 pmg 在 PATH 中不可用（或指向旧安装）。对于这类环境，建议使用安装脚本或 Homebrew。

Go（从源码构建）

# Ensure $(go env GOPATH)/bin is in your $PATH
go install github.com/safedep/pmg@latest

二进制下载

从发布页面下载适用于你平台的最新二进制文件。

容器镜像（GHCR）

预构建的多架构（linux/amd64、linux/arm64）镜像会在每次发布时推送到 GitHub Container Registry。镜像入口点为 pmg。

# Pull the latest image (or pin a version tag, e.g. :v1.2.3)
docker pull ghcr.io/safedep/pmg:latest

# Run any pmg command
docker run --rm ghcr.io/safedep/pmg:latest version

GitHub Actions

用一个步骤保护 CI 工作流。PMG 会分析作业中的每一次 npm install、pip install 等。

pmg v0.26.0