SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场pypi-security-best-practices

pypi-security-best-practices

安全与审计

查看项目

更新于 10-15 13:53

技能介绍

PyPI Security Best Practices 是一个安全技能，属于 ara.so 的 Security Skills 集合。它提供在从 PyPI 安装 Python 包时保障安全的全面指导，覆盖供应链攻击缓解、依赖校验以及针对 uv 和 pip 两种包管理器的安全开发实践。

用途 该指南用于防范供应链攻击（例如 LiteLLM/Telnyx 事件在不到 3 小时内出现 11.9 万次以上恶意下载）以及其他被入侵包的场景，内容涵盖安全安装包、依赖管理以及开发环境加固。

主要安全原则

  • 优先采用仅二进制安装，避免任意代码执行
  • 实施依赖冷却期，避开新发布的恶意包
  • 使用加密哈希固定依赖
  • 使用确定性安装，防止依赖混淆
  • 扫描漏洞并核验包健康状况

安装 uv（推荐）： curl -LsSf https://astral.sh/uv/install.sh | sh powershell -c "irm https://astral.sh/uv/install.ps1 | iex" uv --version

pip： python -m pip --version python -m pip install --upgrade pip

安全工具： python -m pip install pip-audit uv tool install uv-secure

核心安全实践

  1. 仅二进制安装：源码分发可通过 setup.py 执行任意代码，应强制只安装二进制包。uv 可使用 uv pip install --only-binary :all: requests，或在 pyproject.toml 的 [tool.uv.pip] 中设置 only-binary = [":all:"]，或在 uv.toml 的 [pip] 中设置；pip 可使用 pip install --only-binary :all:，或环境变量 PIP_ONLY_BINARY=:all:，或在 pip.conf 的 [install] 中设置 only-binary = :all:。

  2. 依赖冷却期：避免新发布的恶意包。uv 可在 pyproject.toml 的 [tool.uv] 设置 exclude-newer = "7 days" 或 "30 days"，也可命令行 uv lock --exclude-newer、uv sync --exclude-newer，或环境变量 UV_EXCLUDE_NEWER。可按包覆盖：exclude-newer-package = { requests = "1 day" }。pip（v26.1+）可在 pip.conf 设置 uploaded-prior-to = P7D，或命令行 --uploaded-prior-to。Dependabot 与 Renovate 也支持冷却配置。

  3. 哈希校验：使用加密哈希验证完整性。uv 在 lockfile 中自动生成哈希并用 uv sync 校验；requirements.txt 流程可用 uv pip compile --generate-hashes。pip 可用 pip-compile --generate-hashes 与 pip install --require-hashes。

  4. 确定性安装：uv 用 uv lock 与 uv sync（可加 --frozen）；pip 用 pip freeze 或 pip-compile 固定版本。

  5. 防止依赖混淆：为 uv 配置 [[tool.uv.index]] 并设置 explicit = true；pip 在 pip.conf 中配置 index-url、extra-index-url 与 trusted-host。

  6. 漏洞扫描：pip-audit 可扫描已安装包、requirements 文件、输出 JSON、自动修复、忽略特定漏洞；uv-secure 可扫描 uv lockfile、CI 失败退出、生成 SARIF。示例 CI 使用 astral-sh/setup-uv 和 uv-secure scan --exit-code。

  7. 使用安全工具加固安装：Socket.dev（npm install -g @socketsecurity/cli，socket python scan requirements.txt）与 Phylum（curl -sSL https://sh.phylum.io/ | sh，phylum analyze/check）。

安全本地开发 8. 不在 .env 中使用明文密钥：可用 1Password（op item create、op inject、op run）或 Doppler（doppler login/setup/run），并在 .env.template 中使用 op:// 引用。

  1. 在 Dev Container 中工作：devcontainer.json 使用 Python 镜像与 uv 特性，设置 postCreateCommand 与 remoteEnv UV_EXCLUDE_NEWER；也可用 Docker Compose 隔离。

维护者安全实践 10. 为 PyPI 账户启用 2FA（TOTP 应用或安全密钥）。 11. 使用 Trusted Publishing（OIDC）发布：GitHub Actions 设置 permissions id-token: write，使用 pypa/gh-action-pypi-publish，无需 API token。 12. 使用包证明（attestations）发布：actions/attest-build-provenance 生成，publish 时设置 attestations: true，并可用 gh attestation verify 核验。 13. 加固 CI/CD 发布流水线：验证签名提交、漏洞扫描、SBOM 生成与上传。 14. 减少依赖树：uv tree、检查未使用依赖、使用可选依赖 extras。

包健康状况实践 15. 生成与跟踪 SBOM：uv export 配合 cyclonedx-py 或 syft 生成，上传到 Dependency-Track。 16. 查阅漏洞数据库：使用 pypistats、PyPI JSON API、osv-scanner、OSV API 查询。 17. 核验已发布包内容：pip download 不安装、解压查看文件、检查可疑可执行文件，或在隔离环境使用脚本检查 wheel。

配置示例 提供完整的 pyproject.toml（含依赖冷却、仅二进制、索引、ruff 安全检查）与全局 uv.toml 示例。

故障排除 涵盖冷却期阻止所需包、平台无二进制包、哈希校验失败、依赖混淆攻击等问题的解决方案。