pmg v0.26.0
PMG 通过代理、沙箱和 SafeDep 的威胁情报源保护开发者和 AI 代理免受恶意开源包的侵害。
包管理器守卫（PMG）
在恶意 npm 和 pip 包安装之前将其拦截。
为您已在使用的包管理器提供深度防御。
为什么选择 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 包装了
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
# 重启终端以应用更改
提示： 升级 PMG 后重新运行
pmg setup install，以获取新的配置选项。Linux 全用户/黄金镜像：
sudo pmg setup install --system— 参见 docs/system-install.md。
验证安装并确认保护生效：
pmg setup doctor
可选： PMG 通过一个即时注入到包管理器的 CA 来检查 HTTPS 流量。若要让单个 CA 在多次运行间持久化并在操作系统信任存储中信任它（对于忽略 CA 环境变量的工具，如 macOS 和 Windows 上的 Go），请一次性安装：
pmg setup cert install # 用户范围，无需 sudo pmg setup cert status # 检查信任状态和过期时间有关范围、轮换和移除，请参见 证书颁发机构。
3. 使用
查看 PMG 如何拦截威胁。
npm install --no-cache --prefer-online [email protected]
注意：
safedep-test-pkg是一个良性测试包，在 SafeDep 数据库中被标记为恶意，用于测试和验证目的。
继续像往常一样使用您的包管理器，或者让您的 AI 编码代理运行它们。PMG 驻留在路径中，拦截恶意包。
npm install express
# 或
pip install requests
支持的包管理器
PMG 支持您已在使用的工具：
| 生态系统 | 工具 | 命令示例 |
|---|---|---|
| Node.js | npm | npm install <pkg> |
pnpm | pnpm add <pkg> | |
yarn | yarn add <pkg> | |
bun | bun add <pkg> | |
npx | npx <pkg> | |
pnpx | pnpx <pkg> | |
| 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二进制路径会随当前 Node 版本变化，因此切换版本可能导致pmg在PATH中不可用（或指向旧安装）。对于此类环境，建议使用安装脚本或 Homebrew。
Go（从源码构建）
# 确保 $(go env GOPATH)/bin 位于 $PATH 中
go install github.com/safedep/pmg@latest
二进制下载
从 发布页面 下载适用于您平台的最新二进制文件。
容器镜像（GHCR）
预构建的多架构（linux/amd64、linux/arm64）镜像会在每次发布时推送到 GitHub Container Registry。镜像入口点为 pmg。
# 拉取最新镜像（或固定版本标签，例如 :v1.2.3）
docker pull ghcr.io/safedep/pmg:latest
# 运行任意 pmg 命令
docker run --rm ghcr.io/safedep/pmg:latest version
GitHub Actions
使用一个步骤保护 CI 工作流。PMG 会分析作业中的每次 npm install、pip install 等。
- uses: safedep/pmg@v1
with:
server-mode: true
# 通过 HTTP_PROXY 自动拦截
- run: npm ci
- name: 执行 PMG 策略
if: always()
run: pmg proxy stop --fail-on-violation # 停止守护进程，若发生拦截则标记作业失败
默认情况下，您会获得恶意软件拦截和依赖冷却。沙箱隔离通过 sandbox 输入可选启用。通过输入（paranoid、sandbox、cooldown-days 等）调整行为，或通过 config-file 指向仓库中的 YAML 文件。请参见 docs/github-action.md 获取完整参考。
卸载
移除 Shell 集成：
pmg setup remove
若同时移除 PMG 配置文件：
pmg setup remove --config-file
然后卸载 PMG 本身：
# Homebrew
brew uninstall safedep/tap/pmg
# NPM
npm uninstall -g @safedep/pmg
信任与安全
PMG 构建是可复现的且已签名。
- 证明：GitHub 和 npm 证明保证工件完整性。
- 验证：您可以加密证明二进制文件与源代码匹配。
- 验证步骤请参见 信任 PMG。
用户指南
支持
如果 PMG 帮您避开了恶意包，请给本仓库加星。这有助于他人发现它。
Star 历史
贡献
欢迎贡献。构建和测试说明请参见 CONTRIBUTING.md。
感谢所有贡献者 ❤️
遥测
PMG 会收集匿名使用数据。如需禁用，请执行以下任一操作：
- 在 PMG 配置文件中设置
disable_telemetry: true，或 - 导出环境变量
PMG_DISABLE_TELEMETRY=true。