利用 PEP 517 构建后端钩子在 Python 依赖安装期执行任意代码
用户还没有运行目标包,包也未必已经安装完成,构建后端代码已经运行。
Python 依赖安装并不总是“把文件复制进 site-packages”。当安装对象是源码包、本地源码路径,或者当前平台没有可用 wheel 时,pip 需要先把源码构建成 wheel。PEP 517 把这个构建过程交给
pyproject.toml指定的构建后端。后端是一个 Python 模块,pip 会导入它,并调用约定钩子完成元数据生成和 wheel 构建。
0x00 运行环境
核对环境如下:

不同 Python 3 版本的临时路径、进程号和 pip 输出可能不同。判断重点不是某一行日志完全一致,而是源码构建阶段是否调用了后端钩子。
0x01 创建工程
先创建实验路径:
mkdir -p /tmp/pep517-backend-lab/build_backend
mkdir -p /tmp/pep517-backend-lab/src/pep517_lab_pkg
cd /tmp/pep517-backend-lab写入 pyproject.toml:
cat > pyproject.toml <<'EOF'
[build-system]
requires = []
build-backend = "lab_backend"
backend-path = ["build_backend"]
EOF这三个字段决定了构建入口:
requires = []表示不额外安装构建依赖,便于排除外部包影响。build-backend = "lab_backend"表示后端模块名是lab_backend。backend-path = ["build_backend"]表示 pip 导入后端前,会把build_backend加入后端导入路径。
再写一个目标包文件。它不是触发点,只是让生成的 wheel 有实际包内容:
cat > src/pep517_lab_pkg/__init__.py <<'PY'
VALUE = "installed from wheel"
PY写入构建后端 build_backend/lab_backend.py:
cat > build_backend/lab_backend.py <<'PY'
from __future__ import annotations
import base64
import hashlib
import json
import os
from pathlib import Path
import sys
import time
import zipfile
# wheel 内部使用下划线格式,包元数据中的 Name 保留分发名格式。
DIST_NAME = "pep517_lab_pkg"
PROJECT_NAME = "pep517-lab-pkg"
VERSION = "0.1.0"
DIST_INFO = f"{DIST_NAME}-{VERSION}.dist-info"
# 记录文件写在当前构建工作路径下,便于观察 pip 调用后端时的 cwd。
TRACE_FILE = Path("hook_trace.jsonl")
def record_hook(name: str, config_settings=None) -> None:
"""记录 PEP 517 钩子调用现场。"""
event = {
"hook": name,
"pid": os.getpid(),
"python": sys.executable,
"cwd": str(Path.cwd()),
"config_settings": config_settings or {},
"time_utc": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
}
with TRACE_FILE.open("a", encoding="utf-8") as f:
f.write(json.dumps(event, ensure_ascii=False, sort_keys=True) + "\n")
def metadata_bytes() -> bytes:
"""生成最小 METADATA 内容,满足 wheel 安装所需的包名和版本字段。"""
return (
"Metadata-Version: 2.1\n"
f"Name: {PROJECT_NAME}\n"
f"Version: {VERSION}\n"
"Summary: Local PEP 517 backend lab package\n"
"\n"
).encode("utf-8")
def wheel_bytes() -> bytes:
"""生成 WHEEL 元数据,声明这是一个纯 Python、跨平台 wheel。"""
return (
"Wheel-Version: 1.0\n"
"Generator: local-lab-backend\n"
"Root-Is-Purelib: true\n"
"Tag: py3-none-any\n"
"\n"
).encode("utf-8")
def hash_record(data: bytes) -> str:
"""按 wheel RECORD 规范写入 urlsafe-base64 的 sha256 摘要。"""
digest = hashlib.sha256(data).digest()
encoded = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
return f"sha256={encoded}"
def get_requires_for_build_wheel(config_settings=None):
# 构建隔离开启时,pip 会先询问后端是否需要额外构建依赖。
record_hook("get_requires_for_build_wheel", config_settings)
return []
def prepare_metadata_for_build_wheel(metadata_directory, config_settings=None):
# pip 可在完整构建 wheel 之前先调用该钩子获取包元数据。
record_hook("prepare_metadata_for_build_wheel", config_settings)
dist = Path(metadata_directory) / DIST_INFO
dist.mkdir(parents=True, exist_ok=True)
(dist / "METADATA").write_bytes(metadata_bytes())
(dist / "WHEEL").write_bytes(wheel_bytes())
return DIST_INFO
def build_wheel(wheel_directory, config_settings=None, metadata_directory=None):
# 生成最终 wheel 文件;metadata_directory 可由前一阶段传入,这里直接重写元数据。
record_hook("build_wheel", config_settings)
wheel_name = f"{DIST_NAME}-{VERSION}-py3-none-any.whl"
wheel_path = Path(wheel_directory) / wheel_name
files = {
f"{DIST_NAME}/__init__.py": b'VALUE = "installed from wheel"\n',
f"{DIST_INFO}/METADATA": metadata_bytes(),
f"{DIST_INFO}/WHEEL": wheel_bytes(),
}
# RECORD 列出 wheel 中每个文件的路径、哈希和长度;RECORD 自身不写哈希。
record_lines = []
for archive_name, data in files.items():
record_lines.append(f"{archive_name},{hash_record(data)},{len(data)}")
record_lines.append(f"{DIST_INFO}/RECORD,,")
files[f"{DIST_INFO}/RECORD"] = ("\n".join(record_lines) + "\n").encode("utf-8")
with zipfile.ZipFile(wheel_path, "w", compression=zipfile.ZIP_DEFLATED) as zf:
for archive_name, data in files.items():
zf.writestr(archive_name, data)
return wheel_name
PY这段代码做三件事:记录被调用的钩子、生成 wheel 元数据、写出一个合法的纯 Python wheel。RECORD 中写入文件哈希和长度,便于后续确认 wheel 结构。
建立完成后先核对文件位置:
find . -maxdepth 3 -type f | sort
pyproject.toml 决定 pip 去哪里找后端,build_backend/lab_backend.py 是实际会被导入的构建代码。目标包文件 src/pep517_lab_pkg/__init__.py 只进入最终 wheel,不负责触发构建钩子。
0x02 源码构建时的钩子调用
执行 wheel 构建:
python3 -m pip wheel . -w dist -v
查看后端写出的记录:
cat hook_trace.jsonl
这三行说明 pip 在构建阶段导入了 lab_backend,并按顺序调用了三个后端钩子。钩子顺序不是所有前端和所有后端的固定模板;它会受到 pip 版本、构建隔离状态、后端是否实现可选钩子等因素影响。
这里关注的是调用事实:源码构建过程中,后端 Python 代码已经运行。
get_requires_for_build_wheel用来询问后端是否还需要额外构建依赖。这里返回空数组,所以不会拉取任何依赖。prepare_metadata_for_build_wheel用来提前生成.dist-info元数据。pip 解析包名、版本和依赖时会用到这些信息。这个阶段常被误认为只是读取静态配置,但这里已经进入 Python 后端代码。build_wheel负责生成最终 wheel 文件。只要后端代码可以运行到这里,它就拥有当前构建用户的 Python 执行权限。
这三处连起来能说明“配置指定后端、pip 进入元数据阶段、后端代码实际运行”。
0x03 查看生成的 wheel 内容
运行:
python3 - <<'PY'
from pathlib import Path
import zipfile
whl = next(Path("dist").glob("*.whl"))
print("wheel:", whl.name)
with zipfile.ZipFile(whl) as z:
for name in z.namelist():
print(name)
PY输出:

这里可以看出,构建后端运行之后才产生 wheel。wheel 里没有 build_backend/lab_backend.py,因为后端文件属于源码构建输入,不必出现在最终运行包里。
只检查安装后的 site-packages,可能看不到安装期已经运行过的后端代码。
0x04 关闭构建隔离后的行为
删除旧记录并重新构建:
rm -f hook_trace.jsonl
rm -rf dist_noiso
python3 -m pip wheel --no-build-isolation . -w dist_noiso -v
cat hook_trace.jsonl输出:

--no-build-isolation 没有禁止后端运行。它改变的是构建环境处理方式:pip 不再为项目创建隔离构建环境,也不会按 [build-system].requires 自动安装构建依赖。
在这次本地运行中,get_requires_for_build_wheel 没有出现,但元数据钩子和 wheel 构建钩子仍然运行。
关闭构建隔离不是安全开关,不能把源码构建变成静态读取。相反,后端代码会运行在当前 Python 环境中,能接触到当前环境里已有的包和权限。
0x05 直接安装 wheel 不再调用源码后端
先创建虚拟环境,再安装前面生成的 wheel:
python3 -m venv .venv
./.venv/bin/python -m pip install --no-index --find-links dist pep517-lab-pkg -v
./.venv/bin/python - <<'PY'
import pep517_lab_pkg
print(pep517_lab_pkg.VALUE)
PY输出:

再明确安装 wheel 文件,并确认没有新的钩子记录:
rm -f hook_trace.jsonl
./.venv/bin/python -m pip install --force-reinstall --no-deps --no-index dist/pep517_lab_pkg-0.1.0-py3-none-any.whl -v
if [ -f hook_trace.jsonl ]; then cat hook_trace.jsonl; else echo 'no hook trace generated'; fi
这说明已构建好的 wheel 安装路径没有回到源码后端。这里不能推导出“wheel 一定安全”。wheel 里的包代码、入口脚本和元数据仍然需要信任;但从 PEP 517 角度看,直接安装 wheel 不会执行源码包里的 build_backend/lab_backend.py。
0x06 安装后反查 site-packages
安装完成后再看虚拟环境中的 site-packages:
SITE=$(./.venv/bin/python - <<'PY'
import sysconfig
print(sysconfig.get_path('purelib'))
PY
)
printf 'site=%s\n' "$SITE"
find "$SITE" -maxdepth 2 -type f | grep -E 'pep517_lab_pkg|lab_backend' | sort || true
再用 Python 查询模块:
./.venv/bin/python - <<'PY'
import importlib.util
print('package_spec:', importlib.util.find_spec('pep517_lab_pkg') is not None)
print('backend_spec:', importlib.util.find_spec('lab_backend'))
PY
构建后端已经在安装期运行,但安装后的环境里不一定保留后端模块。pep517_lab_pkg 能被导入,因为它进入了 wheel;lab_backend 不能被导入,因为它只是源码构建输入。只检查安装后的包文件,很容易错过已经发生过的构建期行为。
0x07 从源码安装时的实际触发点
很多真实场景不是手动运行 pip wheel,而是直接安装源码路径或源码分发包。继续在同一个虚拟环境中运行:
rm -f hook_trace.jsonl
./.venv/bin/python -m pip install --force-reinstall --no-deps --no-build-isolation . -v
cat hook_trace.jsonl输出:

pip 日志尾部包含:
Building wheel for pep517-lab-pkg (pyproject.toml)....done
Successfully built pep517-lab-pkg
Installing collected packages: pep517-lab-pkg
Successfully installed pep517-lab-pkg-0.1.0这段结果更贴近实际依赖安装:pip install . 并不是直接复制源码,而是先构建 wheel,再安装 wheel。后端代码运行在安装完成之前。
如果这一步发生在 CI 中,后端进程使用的是 CI runner 的 Python 解释器。从记录中的 python 字段可以看到,源码安装时后端运行在虚拟环境解释器 /tmp/pep517-backend-lab/.venv/bin/python 下。实际项目中,这意味着后端可以使用该环境里已有的 Python 包,也能继承进程已有权限。
0x08 源码压缩包安装时保留临时构建路径
真实依赖更常见的形态不是本地源码路径,而是 .tar.gz 形式的源码分发包。可以把同一个工程打成源码压缩包,再用 --no-clean 保留 pip 的临时构建路径:
rm -rf /tmp/pep517-sdist-src /tmp/pep517-pip-tmp
mkdir -p /tmp/pep517-sdist-src/pep517-lab-pkg-0.1.0/build_backend
mkdir -p /tmp/pep517-sdist-src/pep517-lab-pkg-0.1.0/src/pep517_lab_pkg
mkdir -p /tmp/pep517-pip-tmp
cp pyproject.toml /tmp/pep517-sdist-src/pep517-lab-pkg-0.1.0/pyproject.toml
cp build_backend/lab_backend.py /tmp/pep517-sdist-src/pep517-lab-pkg-0.1.0/build_backend/lab_backend.py
cp src/pep517_lab_pkg/__init__.py /tmp/pep517-sdist-src/pep517-lab-pkg-0.1.0/src/pep517_lab_pkg/__init__.py
tar -czf /tmp/pep517-lab-pkg-0.1.0.tar.gz -C /tmp/pep517-sdist-src pep517-lab-pkg-0.1.0![]()
TMPDIR=/tmp/pep517-pip-tmp ./.venv/bin/python -m pip install \
--force-reinstall \
--no-deps \
--no-build-isolation \
--no-clean \
/tmp/pep517-lab-pkg-0.1.0.tar.gz \
-v \
> /tmp/pep517_sdist_install.log 2>&1
find /tmp/pep517-pip-tmp -name hook_trace.jsonl -print -exec cat {} \;
再看 pip 日志中的构建阶段:
grep -E 'Preparing metadata|Building wheel|Successfully built' /tmp/pep517_sdist_install.log
源码压缩包会先被 pip 解包到临时构建路径,再从该路径执行 PEP 517 后端。--no-clean 的价值在于保留 pip-req-build-*,方便回看解包后的源码、后端文件和钩子记录。没有这个参数,pip 正常结束后通常会清理临时构建路径,很多安装期证据会随之消失。
0x09 config_settings 会进入后端钩子
PEP 517 后端钩子可以接收前端传入的 config_settings。pip 中可以通过 -C 或 --config-settings 传入键值。继续运行:
rm -f hook_trace.jsonl
python3 -m pip wheel . -w dist_cfg -C audit_marker=visible-in-hook -v
cat hook_trace.jsonl
这段结果说明,构建前端传入的配置会直接到达后端钩子。正常项目可以用它控制构建选项,例如打开某个扩展或切换编译参数。
命令行参数进入 pip,pip 再把它交给构建后端。
0x0A 后端代码能接触到的内容
构建后端是当前构建用户权限下的 Python 代码。它通常能接触到以下对象:
- 当前源码路径中的文件;
- 当前进程继承的环境变量;
- pip 传给后端的
config_settings; - 构建环境中已安装的 Python 包;
- 当前用户有权限读取或写入的路径;
- 本机可用的编译器、解释器和命令行工具。
该后端记录了 pid、python、cwd、config_settings 和 UTC 时间。真实项目中,风险大小取决于构建环境本身。如果 CI 把发布令牌、私有源认证信息、云平台临时凭据或代理配置注入到同一个构建进程,构建后端就处在能接触这些数据的位置。
这里需要分清两个概念:PEP 517 允许后端执行代码,这是协议层面的事实;后端代码能造成多大影响,取决于运行它的用户权限和环境暴露程度。
0x0B backend-path 为什么值得单独看
常见项目会使用第三方构建后端,例如:
[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"这种配置下,后端代码来自构建依赖。审查重点在构建依赖是否来自可信索引、版本是否固定、是否被内部镜像替换。
实验工程使用的是另一种形式:
[build-system]
requires = []
build-backend = "lab_backend"
backend-path = ["build_backend"]这里的后端文件随源码一起提交。只看 src/pep517_lab_pkg 不能发现它,因为真正被 pip 导入的是 build_backend/lab_backend.py。这类配置适合做自定义构建,但也会把安全审查范围从运行时代码扩展到构建代码。
实际排查时,至少要看这些文件和路径:
pyproject.toml
setup.py
setup.cfg
MANIFEST.in
build_backend/lab_backend.py如果 backend-path 指向其他名称,就沿着该路径继续找 build-backend 对应的模块。模块名不要求叫 backend,路径名也不要求叫 build_backend。
0x0C 构建依赖也是提前运行的代码来源
即使没有 backend-path,[build-system].requires 仍然不能忽略。例如:
[build-system]
requires = ["custom-build-core>=1.0"]
build-backend = "custom_build_core.backend"pip 需要先准备 custom-build-core,再导入 custom_build_core.backend。如果构建依赖来自外部索引、内部镜像或本地包缓存,运行时依赖干净并不代表构建阶段干净。
requirements.txt和 wheel 元数据更多描述运行依赖;pyproject.toml的[build-system]描述构建依赖。构建依赖执行得更早,接触构建环境也更早。
0x0D 几个参数的真实边界
--no-deps 只是不安装依赖,不会跳过当前目标包的构建。如果当前目标是源码路径,后端仍可能运行。
--no-build-isolation 只是不使用隔离构建环境,不会禁止导入后端,也不会禁止调用后端钩子。
pip wheel 虽然不把包安装进业务环境,但它本身就是构建动作。只要输入是源码,后端仍会运行。
--only-binary=:all: 可以阻止 pip 在安装阶段回退到源码包。它适合和固定哈希、内部 wheel 仓库配合使用,但前提是目标平台确实有可用 wheel。
这些参数的差异可以用一句话概括:依赖解析、构建隔离、源码构建、wheel 安装是不同阶段。关掉某个阶段的功能,不等于禁止其他阶段执行代码。
0x0E 更稳妥的落地方式
高敏感环境不应直接从不透明源码临时构建依赖。更合理的方式是把源码构建放进权限较低、输入可控的构建环境,生成 wheel 后再进入业务安装链路。
业务环境中可以使用类似命令:
python3 -m pip install --only-binary=:all: --require-hashes -r requirements.txt这条命令的作用是要求依赖来自 wheel,并且哈希必须匹配锁定文件。它不能把不可信 wheel 变可信,但能避免安装过程临时执行源码构建后端。
构建环境本身也要降权。构建任务只注入必须使用的凭据;发布令牌、生产云凭据、长期私钥不应默认出现在普通依赖构建任务中。日志中保留
pip -v输出,能帮助后续确认是否出现了非预期源码构建。
0x0F 结论
PEP 517 的构建后端不是静态配置项,而是 pip 在源码构建阶段会导入和调用的 Python 模块。prepare_metadata_for_build_wheel 发生在元数据准备阶段,build_wheel 发生在 wheel 生成阶段;这两个阶段都早于最终包安装完成。
源码构建会产生钩子记录,关闭构建隔离仍会执行后端钩子,直接安装已生成 wheel 不会再调用源码后端。安全重点不是否定 PEP 517,而是把源码构建放在权限合适的环境中,把业务环境安装输入尽量收敛到已审查、已固定哈希的 wheel。