pmg v0.27.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 的安装可能不稳定。全局npmbin 路径会随当前 Node 版本变化，因此切换版本可能导致pmg在PATH中不可用（或指向旧安装）。对于这些环境，建议使用安装脚本或 Homebrew。
Go（从源码构建）
# 确保 $(go env GOPATH)/bin 在您的 $PATH 中
go install github.com/safedep/pmg@latest
二进制下载
从 发布页面 下载适用于您平台的最新二进制文件。
容器镜像（GHCR）
每次发布时，预构建的多架构（linux/amd64、linux/arm64）镜像都会发布到 GitHub 容器注册表。镜像入口点为 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 帮您避免了一个恶意软件包，请给此仓库加星。这有助于其他人发现它。
贡献
欢迎贡献。构建和测试说明请参阅 CONTRIBUTING.md。
感谢所有贡献者 ❤️
遥测
PMG 会收集匿名使用数据。要禁用，请执行以下任一操作：
- 在您的 PMG 配置文件中设置
disable_telemetry: true，或 - 导出
PMG_DISABLE_TELEMETRY=true。