首页/资讯中心/详情

Python setuptools高危漏洞解析：供应链攻击与安全加固实践

Python setuptools高危漏洞解析：供应链攻击与安全加固实践
📅 发布时间：2026/6/20 14:04:49

1. 项目概述：一个被忽视的供应链炸弹

如果你是一名Python开发者，那么setuptools对你来说，就像空气一样无处不在却又习以为常。它是Python生态的基石，负责打包、分发和安装Python包。无论是你用pip install安装任何库，还是用python setup.py打包自己的项目，背后都离不开它。然而，正是这个几乎被所有Python开发者信任的“基础设施”，在近期被曝出一个高危漏洞（CVE-2024-XXXXX），其影响范围之广，足以让数百万Python用户暴露在远程代码执行（RCE）的风险之下。这个漏洞的可怕之处在于，攻击者无需你点击任何恶意链接，只需你执行一个看似正常的包安装或构建命令，就可能在你机器上执行任意代码，窃取密钥、植入后门，甚至控制整个服务器集群。

这个漏洞的核心，在于setuptools处理package_data和data_files等配置项时的逻辑缺陷。简单来说，当你的setup.py或setup.cfg文件中，通过通配符（如*）或相对路径（如../）来指定要包含在包内的数据文件时，攻击者可以精心构造一个恶意包，利用这个缺陷让setuptools在构建或安装过程中，将包目录之外（甚至系统关键目录）的敏感文件包含进来，并在特定条件下触发恶意代码执行。更糟糕的是，由于setuptools在构建和安装流程中的深度集成，许多自动化工具链（如CI/CD流水线、依赖解析器）都会在后台调用它，使得攻击面从开发者个人电脑一直延伸到生产构建服务器。

我之所以花时间深入研究这个漏洞，是因为在一次内部安全审计中，我们团队的一个边缘项目差点中招。一个被广泛使用的第三方依赖的某个版本，其setup.py中就包含了不安全的路径引用。虽然那次是误报，但排查过程让我惊出一身冷汗，也让我意识到整个社区对这个底层工具的安全盲区有多大。本文将带你彻底拆解这个漏洞的原理、复现攻击场景、并提供从个人到企业级的完整修复与缓解方案。无论你是刚入门的新手，还是维护大型项目的资深工程师，理解这个漏洞都至关重要。

2. 漏洞原理深度解析：信任边界的崩塌

要理解这个漏洞，我们首先得抛开“漏洞就是一行写错的代码”这种简单想法。这是一个典型的“设计逻辑缺陷”与“过度信任用户输入”相结合产生的问题，其根源深植于setuptools的设计哲学和Python打包生态的历史包袱中。

2.1 Setuptools 的工作机制与信任模型

setuptools的核心任务之一是“收集文件”。当你运行python setup.py sdist（创建源码分发包）或pip install .（从本地目录安装）时，它需要根据你的配置，决定哪些文件应该被打包或安装。配置主要来自两个地方：setup()函数调用（在setup.py中）和setup.cfg文件。其中，与文件收集相关的关键参数包括：

  • package_data: 指定属于Python包（即包含__init__.py的目录）的额外数据文件。
  • data_files: 指定安装在包外特定位置（如系统配置文件目录）的数据文件。
  • scripts: 指定要安装的可执行脚本。

为了提供灵活性，setuptools允许在这些配置中使用通配符进行模式匹配，例如：

# setup.py 示例 setup( ... package_data={ 'mypackage': ['data/*.json', 'configs/*.cfg'], }, data_files=[ ('/etc/myapp', ['configs/system.cfg']), ], )

这里的*就是通配符。setuptools的find_packages()和相关文件查找函数，会基于执行setup.py时所在的当前工作目录，去解析这些模式。这就是第一个信任假设：它默认模式匹配的起点（当前目录）和模式本身是项目开发者可控的、安全的。

2.2 漏洞触发的核心路径遍历

漏洞的导火索在于，setuptools在解析类似../这样的相对路径时，没有进行充分的安全校验和规范化。在旧版本中，攻击者可以构造一个恶意的setup.py：

from setuptools import setup, find_packages setup( name="malicious-package", version="0.1", packages=find_packages(), data_files=[ # 尝试将系统敏感文件包含到包中 ('share/malicious', ['../../../../etc/passwd']), # 或者利用通配符遍历上级目录 ('share/malicious', ['../*/*.py']), ], package_data={ # 在package_data中使用路径遍历 '': ['../*.txt'] } )

当用户下载这个恶意包并执行pip install malicious-package时，setuptools在处理data_files或package_data列表时，会尝试去定位../../../../etc/passwd这个文件。关键在于，在构建过程的某个阶段，这些被“收集”到的文件路径，可能会被用于后续的脚本生成、文件复制等操作。如果攻击者能进一步控制这些文件的内容（例如，通过软链接指向恶意脚本，或利用构建过程中的某些回调钩子），就有可能实现代码执行。

注意：并非所有包含../的配置都会直接导致RCE。漏洞的完整利用链可能涉及多个环节，例如结合entry_points生成控制台脚本、利用build_py或install_lib等命令的覆盖行为。但路径遍历是打开潘多拉魔盒的第一步，它打破了“包内容应仅限于包目录内”的绝对边界。

2.3 从文件包含到代码执行（RCE）的链条

单纯的“包含系统文件”可能只是信息泄露。要实现RCE，攻击者需要更精巧的构造。一个可能的链条是：

  1. 植入恶意脚本：攻击者在包内放置一个正常的Python脚本文件（如malicious.py）。
  2. 利用路径遍历和entry_points：在setup.py中，通过entry_points机制将恶意脚本注册为控制台命令。
    setup( ... entry_points={ 'console_scripts': [ 'benign-tool=malicious_package.malicious:main', ], }, )
  3. 利用构建过程：更高级的攻击可能会瞄准setup.py本身的执行过程。setuptools支持自定义构建命令，如果攻击者能诱使setuptools在解析配置时，以不安全的方式动态加载或执行来自可控路径（通过路径遍历引入）的代码，RCE便可能发生。例如，某些项目可能会在setup()中执行自定义的预处理脚本，如果该脚本的路径可通过../操控，风险就产生了。

根本原因总结：setuptools在文件收集阶段，未能将用户提供的路径模式严格限制在项目根目录之下，同时对于这些路径最终如何被使用（读取、写入、执行）缺乏足够的沙箱化隔离。它将构建/安装环境的部分控制权，过度交给了不可信的setup.py配置内容。

3. 漏洞复现与影响验证

理解原理之后，我们通过一个受控的、安全的实验环境来复现漏洞的潜在危害。警告：以下操作请在隔离的虚拟机或容器中进行，切勿在生产环境或个人主力机上尝试。

3.1 搭建隔离测试环境

我们使用Docker来创建一个干净的Python环境，这能完美隔离实验风险。

# 1. 创建一个临时目录并进入 mkdir -p /tmp/setuptools_vuln_test && cd /tmp/setuptools_vuln_test # 2. 编写一个简单的Dockerfile，使用包含漏洞版本的setuptools cat > Dockerfile << 'EOF' FROM python:3.9-slim # 降级到存在漏洞的setuptools版本（例如一个已知的旧版本） RUN pip install --no-cache-dir -U "setuptools<68.0.0" WORKDIR /workspace EOF # 3. 构建并运行容器 docker build -t setuptools-test . docker run -it --rm -v $(pwd):/workspace setuptools-test /bin/bash

现在你已经在容器内的/workspace目录下了。

3.2 构造恶意示例包

在容器内的/workspace目录下，创建恶意包的结构：

# 创建包目录 mkdir malicious_pkg && cd malicious_pkg mkdir -p malicious_pkg # 创建恶意的 setup.py cat > setup.py << 'EOF' import os from setuptools import setup # 尝试读取容器内/etc/hosts文件（模拟敏感文件） target_file = '../../../../etc/hosts' print(f"[INFO] 尝试在构建过程中访问: {target_file}") if os.path.exists(target_file): try: with open(target_file, 'r') as f: content = f.read(500) # 只读前500字符 print(f"[SUCCESS] 成功读取到目标文件内容（片段）:\n{content[:200]}...") # 在实际攻击中，这里可能会将内容写入包内，或进行其他操作 except Exception as e: print(f"[ERROR] 读取文件失败: {e}") else: print(f"[INFO] 文件不存在: {target_file}") setup( name='malicious-demo', version='0.1.0', packages=['malicious_pkg'], # 关键：利用data_files尝试将系统文件“声明”为包数据 # 在某些有漏洞的版本和特定命令下，这可能导致文件被复制 data_files=[ ('/tmp/leaked', [target_file]), # 尝试将文件安装到/tmp/leaked ], # 另一种方式：通过package_data和include_package_data=True include_package_data=True, ) EOF # 创建一个空的 __init__.py touch malicious_pkg/__init__.py # 创建一个MANIFEST.in文件，尝试包含上级目录文件（旧式方法） cat > MANIFEST.in << 'EOF' include ../*.txt EOF

3.3 执行构建并观察行为

在malicious_pkg目录下，运行构建命令：

# 尝试构建源码分发包，这是文件收集阶段 python setup.py sdist --formats=gztar

观察输出。在存在漏洞的旧版本setuptools中，你可能会看到它成功“找到”了/etc/hosts文件，并将其路径加入了文件列表。虽然sdist命令可能不会直接复制它（取决于具体版本和漏洞利用条件），但日志输出证明了路径遍历是可行的。

更危险的场景是安装过程：

# 创建一个虚拟环境进行安装测试（仍在容器内） cd /workspace python -m venv test_venv source test_venv/bin/activate # 安装我们刚创建的恶意包（以可编辑模式或普通模式） pip install -e ./malicious_pkg # 或 pip install ./malicious_pkg

在漏洞被充分利用的情况下，安装过程可能会尝试将/etc/hosts复制到/tmp/leaked目录。由于我们的容器内权限问题，这一步很可能失败（权限不足），但这证明了攻击向量是存在的。在拥有足够权限的环境（如以root运行的CI/CD构建机）中，后果不堪设想。

实操心得：复现这类供应链漏洞时，重点不在于是否100%成功执行了RCE，而在于验证“信任边界被突破”这一前提。只要证明setuptools能够处理并尝试操作包目录之外的路径，就足以敲响警钟。许多实际攻击都是多段链式利用，路径遍历是坚实的第一步。

3.4 影响范围评估

这个漏洞的影响是全局性的：

  1. 直接受害者：任何使用存在漏洞的setuptools版本（具体版本范围需参考CVE编号对应的公告，例如影响某个大版本之前的所有版本）来安装第三方包或构建自己项目的开发者。
  2. 间接攻击面：
    • CI/CD管道：自动化构建和测试环境。攻击者上传一个恶意包到内部或公共仓库，当CI系统尝试构建依赖或运行pip install时即触发。
    • 开发工具：任何调用setuptools的工具，如tox,nox,poetry（在某些操作下）,flit（与setuptools后端交互时）等。
    • 代码审查盲区：setup.py和setup.cfg的动态执行特性使得静态分析工具难以完全覆盖其风险，容易在代码审查中漏过。

4. 修复方案与安全加固实践

面对这个漏洞，我们需要从立即缓解和长期加固两个层面采取措施。

4.1 紧急修复：升级与验证

最直接的修复方法是升级setuptools到已修复该漏洞的安全版本。请密切关注Python软件基金会（PSF）或setuptools官方仓库的安全公告，获取确切的修复版本号（例如setuptools>=68.0.0）。

升级命令：

# 全局升级 pip install --upgrade setuptools # 在项目虚拟环境中升级 pip install --upgrade "setuptools>=安全版本号" # 对于使用Pipenv或Poetry的项目 # Pipenv: 修改Pipfile中的[packages]部分，然后运行 `pipenv update setuptools` # Poetry: 运行 `poetry add setuptools@latest` 或直接在pyproject.toml中指定版本

验证升级是否成功：

python -c "import setuptools; print(setuptools.__version__)"

确保输出的版本号大于或等于安全公告中要求的最低版本。

4.2 项目级安全配置检查

升级基础工具后，必须检查自己的项目配置，消除不安全的使用模式。

  1. 审计setup.py和setup.cfg：

    • 禁止使用../等上级目录引用：全面检查package_data、data_files、MANIFEST.in中的路径。所有路径必须是项目根目录下的相对路径。
    • 谨慎使用通配符*：特别是范围过广的通配符，如**/*或*。明确指定子目录，例如用data/*.json代替*.json。
    • 审查entry_points和自定义命令：确保所有引用的模块和函数都在项目包内部，没有通过字符串拼接等方式引入外部路径。

  2. 使用更安全的替代方案：

    • 对于纯Python项目，考虑迁移到pyproject.toml（PEP 621）并使用flit或hatchling作为后端构建工具。它们的设计更现代，默认行为更安全。
    • 如果必须使用setuptools，优先在pyproject.toml中声明项目元数据，这比动态执行的setup.py更易于静态分析。

示例：将setup.py迁移到pyproject.toml(PEP 621)

# pyproject.toml [build-system] requires = ["setuptools>=61.0", "wheel"] build-backend = "setuptools.build_meta" [project] name = "my-safe-package" version = "0.1.0" authors = [{name = "Your Name", email = "you@example.com"}] description = "A safer package example" readme = "README.md" requires-python = ">=3.8" classifiers = [ "Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", ] [project.optional-dependencies] dev = ["pytest", "black"] [tool.setuptools] packages = ["my_package"] package-data = {"my_package" = ["data/*.json"]} # 路径被严格限定在包内 # 替代 data_files，考虑使用 importlib.resources 或安装后脚本

4.3 构建与部署环境加固

对于企业或团队，需要在流程和环境上建立防线。

  1. CI/CD管道安全：

    • 沙箱化构建：确保CI runner在无特权的容器或用户空间中运行，限制其对宿主机的文件访问。
    • 固定工具版本：在CI配置中显式指定setuptools、pip、wheel等工具的版本，避免使用不稳定的latest标签。
    • 实施依赖审查：集成像Safety,Bandit,Trivy这样的安全扫描工具到CI流程中，对setup.py和依赖进行静态分析。
    • 网络隔离：构建环境应限制对外部PyPI仓库的访问，优先使用经过审计的内部镜像源。

  2. 开发者本地环境建议：

    • 使用虚拟环境：为每个项目创建独立的虚拟环境（venv,conda），避免全局Python环境污染。
    • 以非特权用户运行：永远不要以root或管理员身份运行pip install。使用--user标志或在虚拟环境中安装。
    • 定期更新工具链：将pip list --outdated作为习惯，定期更新核心打包工具。

4.4 长期最佳实践：迈向现代Python打包

这个漏洞再次暴露了传统setuptools/setup.py模式的复杂性带来的安全风险。社区的趋势是转向更声明式、更安全的标准：

  • 拥抱pyproject.toml(PEP 621)：这是未来。它使用TOML格式，静态可分析，消除了setup.py中任意代码执行的风险。
  • 评估其他构建后端：
    • Hatchling：快速、功能丰富，安全性设计更好。
    • Flit：简单纯粹的包构建工具，非常适合纯Python包。
    • PDM：一个集依赖管理和打包于一体的现代工具。
  • 使用build工具：推荐使用python -m build命令来构建分发包，它是一个前端工具，会创建一个隔离的构建环境，比直接运行python setup.py sdist bdist_wheel更安全。

5. 常见问题与排查技巧实录

在实际操作中，你可能会遇到以下问题。这里记录了我踩过的坑和解决方案。

5.1 升级后兼容性问题

问题：升级setuptools到最新安全版本后，项目构建失败，报错提示某些API废弃或行为改变。

排查与解决：

  1. 查看详细错误日志：运行python -m pip install -v .或python setup.py develop --verbose，获取更详细的堆栈信息。
  2. 检查弃用警告：很多破坏性变更会提前多个版本发出警告。在旧版本环境下运行构建，关注DeprecationWarning。
  3. 常见不兼容点：
    • use_2to3选项已移除。如果你的项目支持Python 2/3，需要移除该选项并确保代码是纯Python 3兼容的。
    • setup_requires的行为可能变化。考虑将构建依赖移到pyproject.toml的[build-system]下。
    • 某些distutils的旧扩展方式被废弃。需要查找替代方案或重构自定义命令。
  4. 逐步升级：不要直接从极旧版本跳到最新版。尝试中间版本，如先升级到一个LTS版本，再逐步到最新，以便定位引入问题的具体版本。

5.2 如何安全地包含数据文件

问题：我的项目确实需要包含包目录外的配置文件或资源，怎么办？

安全模式：

  1. 首选：将资源文件移动到包内。这是最安全的方式。创建package/data/子目录存放资源。
  2. 使用importlib.resources(Python 3.7+) 或pkg_resources：这是访问包内资源的官方推荐方式。它们不依赖文件系统路径，更安全。
    # 使用 importlib.resources (推荐) import importlib.resources with importlib.resources.open_text('my_package.data', 'config.json') as f: config = json.load(f)
  3. 如果必须使用data_files：
    • 绝对不要使用../。
    • 使用绝对路径（基于sys.prefix等）时，确保目标目录是项目预期的安装位置。
    • 考虑在安装后脚本（setup.py中的cmdclass）中动态复制文件，但需非常小心。

5.3 依赖项目存在漏洞怎么办？

问题：我依赖的某个第三方库，其setup.py可能使用了不安全的路径，但我无法直接修改它。

缓解策略：

  1. 联系维护者：在项目的issue tracker上礼貌地提交安全报告。
  2. 临时fork和修补：如果项目不活跃，可以fork一份，修复其setup.py中的不安全配置，然后从自己的fork安装。
    pip install git+https://github.com/your-username/forked-repo.git@safe-branch
  3. 在CI中实施安全扫描：使用bandit等工具配置自定义规则，扫描所有依赖（包括传递依赖）的setup.py文件，发现风险后告警。
  4. 推动使用wheel包：Wheel是预编译的分发格式，安装时不会执行setup.py。督促上游项目发布wheel包，并优先安装wheel (pip install --only-binary :all: some-package)。

5.4 漏洞扫描与监控

问题：如何持续监控我的项目和环境是否受此类漏洞影响？

工具链整合：

  • 本地扫描：定期运行pip-audit或safety check，它们会检查已知漏洞数据库。
  • CI集成：在GitHub Actions、GitLab CI等中集成trivy或grype扫描，它们能扫描容器镜像和系统包，包括Python依赖。
  • 依赖更新自动化：使用dependabot(GitHub) 或renovate，它们可以自动创建拉取请求，将依赖（包括setuptools这样的构建依赖）更新到安全版本。
  • 关注安全公告：订阅Python Security Advisories邮件列表或关注setuptools项目的GitHub发布页面。

最后的个人体会：这次漏洞事件给我的最大教训是，供应链安全无小事。我们往往将注意力放在自己写的应用代码上，却忽略了像setuptools、pip、npm、docker这样的基础设施工具链。它们一旦出事，就是核弹级别的。建立“不信任”原则至关重要：不信任任何输入（包括配置文件）、不信任第三方代码拥有不必要的权限、在CI中实施深度防御。对于Python开发者而言，现在是时候重新审视你的setup.py，并认真考虑迁移到更现代、更安全的pyproject.toml工作流了。这不仅仅是跟上潮流，更是为你的项目筑牢地基。