LamentXU123/secpipw

# secpipw

English | [简体中文](./README.zh-CN.md) [](https://github.com/LamentXU123/spip/actions/workflows/test.yml) [](LICENSE)   [](https://codecov.io/gh/LamentXU123/spip) 一个开源、免费、强大且轻量级的 pip 守护工具，用于防范供应链攻击。 通过使用它，你可以避免仅仅因为输入了 `pip install` 就被像 LiteLLM 这样被投毒的库所坑害。 尽管 `secpipw` 的设计初衷是降低学习成本，但我们依然建议你在将其应用于生产环境之前阅读我们的[文档](https://spip.lamentxu.top/docs)。 ## 是什么？ 当前，供应链攻击是全球最主要的安全隐患之一。`secpipw` 项目是一个专注于供应链风险控制的下一代 `pip` 包装器。 ## 等等，什么？ 你可以使用 ``` spip install requests ``` 来代替 ``` pip install requests ``` 以便在供应链安全的范围内更安全地安装包。 你不需要配置。你不需要学习。只需安装即可掌控。 换句话说，你可以完全用 `spip install` 替换 `pip install`，让你的安装过程更安全 :) Zsh (macOS): ``` pip install secpipw echo "alias pip='spip'" >> ~/.zshrc source ~/.zshrc ``` `secpipw` 项目会主动检查所有的供应链风险，防止你在输入 `spip install` 时安装了潜在的恶意包。 对于 `install` 命令，`secpipw` 会使用 pip 自身的 resolver，并在 pip 构建或安装已解析的分发包之前检查选定的安装计划。如果检查通过，会继续执行相同的 pip 安装流程；`secpipw` 不会对已经解析的包再次运行 `pip install`。 除了 `install` 命令外，该项目的行为与原版 `pip` 程序完全相同。也就是说，在任何情况下你都可以用 `spip` 代替 `pip` :) 对于 `pipx`、`poetry` 和 `uv`，secpipw 会在将控制权交给原工具之前，运行与 pip 兼容的预检解析和构件检查。原工具仍然会执行实际的环境更新。 有关更多详细信息，请查看我们的文档：https://spip.lamentxu.top/docs ## secpipw 解决了什么问题？ 供应链投毒一直是一个棘手的安全问题。现有的解决方案包括像 GuardDog 这样成熟但运行成本高昂的工具，以及像 sfw 这样完全依赖付费 Socket API 的轻量级工具。GuardDog 对于日常 CI 使用来说过于笨重，更适合安全研究人员进行静态分析。对 `pip install` 下载的每个构件（包括所有依赖项）运行 GuardDog 会拖慢安装速度。sfw 比较轻量，但它对付费 API 的依赖给日常开发者带来了额外的成本。 secpipw 通过挂钩到 pip 的安装程序并将安全检查直接合并到 pip install 的下载和安装流程中来解决这个问题。同时，它对性能的影响通常很小。secpipw 对所有人都是完全免费的。 如今，许多独立开发者都遭受过 CI 服务器被攻破的困扰，这会导致密钥泄露并造成严重损害。安装了 secpipw 后，这种风险会大大降低，而且不需要支付费用，不需要额外的性能开销，也不需要学习或配置。只需用 `pip install secpipw` 安装一次，设置一次 alias，就可以继续使用 pip，并在后台获得一层重要的保护。 ## 警告策略 ## TODO 欢迎贡献： - 框架 - [x] 支持受守护的 `uv pip install`、`uv add`、`uv tool install` 和 `uv tool run` - [x] 支持受守护的 `pipx install`、`pipx inject` 和 `pipx run` - [x] 支持受守护的 `poetry add` 和 `poetry self add` - [ ] 支持 `conda` - CI - [x] 在 github workflow 中编写基准测试 CI，以比较 `spip install` 和 `pip install` 的性能 - 文档 - [ ] 使用一些现代文档框架重构 /doc/docs 目录。 - [ ] 支持在手机上查看网站。@didongji91 - 检查 - [x] 记录并比较多次 `spip` 安装中已安装包的 entry-point 和 `.pth` 基线 - [x] 是否添加了新的或更改了 `.pth` 文件 - [x] entry-point 元数据或脚本文件是否发生更改 - [x] 从 pip 的已解析安装报告中检测 yanked 版本 - [x] 将归档哈希值与已有的 PyPI 发布元数据进行比较 - [ ] 增加对包的最后一个版本与待安装版本之间差异的检查，寻找恶意更改 - [ ] setup.py 是否已被更改 我们目前有三种安装警告策略： - `HIGH`：暂停安装并要求使用 `--spip-ignore-warning` - `MEDIUM`：在继续之前提示 `y/n` - `LOW`：警告并继续 默认灵敏度是 `low`，使用上述策略。你可以通过 `--sensitivity medium` 或 `--sensitivity high` 让检查变得更严格： - `--sensitivity medium`：`MEDIUM` 及以上级别会暂停安装；`LOW` 会进行提示。 - `--sensitivity high`：`LOW` 及以上级别会暂停安装。 使用 `--spip-ignore ` 可以完全忽略该严重级别及以下的警告。 例如，`--spip-ignore LOW` 会屏蔽 `LOW` 警告，而 `--spip-ignore MEDIUM` 会同时屏蔽 `LOW` 和 `MEDIUM` 警告。被忽略的警告不会被打印， 并且只能产生被忽略严重级别的检查将被跳过。 ## 缓存 secpipw 默认将 PyPI 名称、发布时间和维护者电子邮件历史缓存存储在 用户的缓存目录中，因此相同的缓存可以在不同项目中重复使用。 设置 `SPIP_CACHE_DIR` 可覆盖缓存目录。 ## 基准测试 使用以下命令运行本地基准测试： ``` python scripts/benchmark_install.py --runs 5 --warmups 0 ``` 添加 `--viztracer --viztracer-dir .tmp-perf/install-benchmark` 以生成 所测量的安装命令的每次运行的火焰图。 使用以下命令运行本地 VizTracer 热点路径基准测试： ``` python scripts/benchmark_viztracer.py --runs 3 ``` 默认基准测试比较 `pip install ruff` 和 `spip install ruff`， 同时对包下载和安装进行计时。它使用 `--no-cache-dir`、 `--no-deps`，并为每次测量的运行提供全新的 `--target` 目录，因此 结果侧重于重复安装一个众所周知的包主体，而不是 依赖树。Benchmark GitHub Actions 工作流会在相关的 `main` 分支更改时、按每周计划或通过手动触发运行。它将最新的 `benchmark.json` 发布到远程的 `benchmark-data` 分支，网站会根据该数据渲染出 `x1.0742` 样式的中位数比率。基准测试的更新不会推进 `main` 分支。 当 `secpipw` 检测到潜在风险时，会发出警告，警告级别取决于风险的严重程度。 目前，该项目包含几个主要检查点： - [x] 伪装拼写错误检查：黑客经常使用“伪装的拼写错误”将恶意依赖包注入被投毒的源文件中。`secpipw` 会首先解析 `pip install` 将要下载的所有包，然后将非热门的已解析包名与本地热门包列表进行比较来检测这种情况。警告级别： - 中等严重程度：`requsets` vs `requests` - 中等严重程度：`panda` vs `pandas` - 低严重程度：`sixth` vs `six` - [x] 直接 URL 依赖检查：如果安装目标或已解析的依赖项使用了直接 URL、VCS URL 或 PEP 508 直接引用，`secpipw` 将发出 `MEDIUM` 警告。 - [x] 全新发布检查：如果选定的 PyPI 版本发布时间不到 8 小时，`secpipw` 将发出 `MEDIUM` 警告；如果发布时间不到 48 小时，`secpipw` 将发出 `LOW` 警告。 - [x] Yanked 版本检查：如果 pip 解析出的版本被标记为 yanked，`secpipw` 将使用 pip 的安装报告发出 `MEDIUM` 警告。 - [x] 归档哈希检查：如果 PyPI 发布元数据已可用，且选定的 wheel/sdist 摘要与已解析的归档哈希不匹配，`secpipw` 将发出 `HIGH` 警告。 - [x] 空描述检查：如果选定的 PyPI 发布元数据没有摘要并且没有长描述，`secpipw` 将发出 `LOW` 警告。 - [x] 可疑元数据 URL 检查：如果 PyPI 元数据指向短链接、原始 IP、嵌入式凭据或类似的可疑 URL，`secpipw` 将发出 `LOW` 警告。 - [x] 代码库不匹配检查：如果 PyPI 元数据指向的 GitHub/GitLab 代码库名称似乎与包名无关，`secpipw` 将发出 `LOW` 警告。 - [x] 维护者电子邮件域名漂移检查：如果包的维护者电子邮件域名与本地 `secpipw` 历史缓存相比发生了变化，`secpipw` 将发出 `LOW` 警告。 - [x] 零版本检查：如果选定的包版本是 `0.0` 或 `0.0.0`，`secpipw` 将发出 `LOW` 警告。 - [x] `.pth` 文件检测：如今的黑客不再直接在包内部注入恶意代码，而是将他们的恶意内容放在 `.pth` 文件中，并以 `import` 开头。`secpipw` 仅在安装后检查已安装的文件系统差异。警告级别始终为 `MEDIUM`，并且 `secpipw` 会询问是否删除可疑的已安装 `.pth` 文件。 - [ ] TODO ...