审计钩子

为了观察运行时（代表调用方）采取的操作，需要一个 API 来从某些操作内部发出消息。这些操作通常位于 Python 运行时或标准库的深处，例如动态代码编译、模块导入、DNS 解析或使用某些模块（如 ctypes）。

以下新的 C API 允许嵌入器和 CPython 实现者发送和接收审计钩子消息

# Add an auditing hook
typedef int (*hook_func)(const char *event, PyObject *args,
                         void *userData);
int PySys_AddAuditHook(hook_func hook, void *userData);

# Raise an event with all auditing hooks
int PySys_Audit(const char *event, PyObject *args);

接收和引发审计钩子的新 Python API 为

# Add an auditing hook
sys.addaudithook(hook: Callable[[str, tuple]])

# Raise an event with all auditing hooks
sys.audit(str, *args)

通过在任何时间从 C 调用 PySys_AddAuditHook()（包括在 Py_Initialize() 之前）或从 Python 代码调用 sys.addaudithook() 来添加钩子。钩子不能被删除或替换。对于 CPython，从 C 添加的钩子是全局的，而从 Python 添加的钩子仅适用于当前解释器。全局钩子在解释器钩子之前执行。

当感兴趣的事件发生时，代码可以从 C 调用 PySys_Audit()（在持有 GIL 时）或调用 sys.audit()。字符串参数是事件的名称，元组包含参数。给定的事件名称应该具有固定的参数模式，该模式应该被视为公共 API（对于每个 x.y 版本发布），因此应该只在具有更新文档的功能版本之间更改。为了最大程度地减少开销并简化本机代码钩子实现中的处理，不支持命名参数。

为了最大程度地兼容，使用与参考解释器 CPython 中的事件相同的名称的事件应尽一切努力使用兼容的参数。在特定于实现的事件名称中包含实现的名称或缩写也将有助于防止冲突。例如，pypy.jit_invoked 事件与 ipy.jit_invoked 事件明显不同。从 Python 模块引发的事件应在其事件名称中包含其模块或包名称。

虽然事件名称可以是任意的 UTF-8 字符串，但为了跨实现的一致性，建议使用有效的 Python 点分名称，并在名称中避免编码特定细节。例如，带有模块名称 spam 作为参数的 import 事件优于没有参数的 spam module imported 事件。避免使用嵌入的空字符，否则可能会惹恼那些使用 C 实现钩子的人。

当审计事件时，每个钩子都按添加顺序（尽可能地）调用，传递事件名称和参数。如果任何钩子返回时设置了异常，则忽略后面的钩子，并且通常Python 运行时应该终止 - 钩子的异常不应被处理或视为预期事件。这允许钩子实现决定如何响应任何特定事件。典型的响应是记录事件、使用异常中止操作或立即使用操作系统退出调用终止进程。

当审计事件但未设置任何钩子时，audit() 函数应该产生最小的开销。理想情况下，每个参数都是对现有数据的引用，而不是仅为审计调用计算的值。

由于钩子可能是 Python 对象，因此需要在解释器或运行时结束时释放它们。这些不应在任何其他时间触发，并且应该引发事件钩子以确保观察到任何意外调用。

在下面的 建议的审计钩子位置 中，我们建议了一些应该引发审计事件的重要操作。一般来说，事件应该在尽可能低的级别引发。在从 Python 代码或本机代码引发事件之间进行选择时，应优先从本机代码引发。

Python 实现应该记录哪些操作将引发审计事件，以及事件模式。有意地，sys.addaudithook(print) 是一种显示所有消息的简单方法。

已验证的打开钩子

大多数操作系统都有一种机制来区分可以执行的文件和不能执行的文件。例如，这可能是权限字段中的执行位、文件的验证哈希以检测潜在的代码篡改或文件系统路径限制。这些是确保仅执行已获准在给定环境中执行的代码的重要安全机制。

大多数内核都提供方法来限制或审计内核加载和执行的二进制文件。Python 拥有的文件类型显示为常规数据，并且这些功能不适用。此开放钩子允许 Python 嵌入器在启动脚本或导入 Python 代码时与操作系统支持集成。

已验证的打开钩子的新公共 C API 为

# Set the handler
typedef PyObject *(*hook_func)(PyObject *path, void *userData)
int PyFile_SetOpenCodeHook(hook_func handler, void *userData)

# Open a file using the handler
PyObject *PyFile_OpenCode(const char *path)

已验证的打开钩子的新公共 Python API 为

# Open a file using the handler
io.open_code(path : str) -> io.IOBase

io.open_code() 函数是 open(abspath(str(pathlike)), 'rb') 的替代品。它的默认行为是打开一个用于原始二进制访问的文件。要更改行为，应设置新的处理程序。处理程序函数仅接受 str 参数。C API PyFile_OpenCode 函数假定 UTF-8 编码。路径必须是绝对路径，并且调用者有责任确保正确解析完整路径。

可以通过在 C 中调用 PyFile_SetOpenCodeHook() 来设置自定义处理程序，这可以在任何时间进行，包括在 Py_Initialize() 之前。但是，如果已经设置了钩子，则调用将失败。当 open_code() 被调用且已设置钩子时，钩子将被传递路径，并且其返回值将被直接返回。返回的对象应为支持读取原始字节的打开的文件类对象。如果打开处理程序已将整个文件读入内存，则明确地允许 BytesIO 实例。

请注意，这些钩子可以在 CPython 上导入并调用 _io.open() 函数，而不会触发自身。它们还可以使用 _io.BytesIO 使用内存缓冲区返回兼容的结果。

如果钩子确定文件不应加载，则应根据需要引发异常，并执行任何其他日志记录。

所有涉及从文件加载代码的导入和执行功能都将无条件地更改为使用 open_code()。需要注意的是，对 compile()、exec() 和 eval() 的调用不会经过此函数 - 包括来自这些调用的代码的审计钩子是验证从文件读取的代码的最佳机会。鉴于 Python 中导入和执行之间的当前解耦，大多数导入的代码将同时经过 open_code() 和 compile 的日志钩子，因此应注意避免重复验证步骤。

不打算执行代码的文件访问预计不会使用此函数。这包括加载 pickle、XML 或 YAML 文件，其中代码执行通常被认为是恶意的而不是故意的。这些操作应提供自己的审计事件，最好是在正常功能（例如，Unpickler.load）和代码执行（Unpickler.find_class）之间进行区分。

一些示例：如果文件类型通常需要执行位（在 POSIX 上）或在标记为从互联网下载时发出警告（在 Windows 上），则它可能应该使用 open_code() 而不是普通的 open()。使用 ZipFile 类打开 ZIP 文件应使用 open()，而通过 zipimport 打开它们应使用 open_code() 来表示正确的意图。在特定上下文中对特定函数使用错误的代码可能会绕过钩子，在 CPython 和标准库中，这应被视为错误。需要结合使用 open_code 钩子和审计钩子来跟踪存在任意代码时所有执行的源代码。

没有为更改打开钩子提供的 Python API。要从 Python 代码修改导入行为，请使用 importlib 提供的现有功能。

API 可用性

虽然此处添加的所有函数都被视为公共且稳定的 API，但函数的行为是特定于实现的。此处的大多数描述都指的是 CPython 实现，虽然其他实现应该提供这些函数，但没有要求它们的行为相同。

例如，sys.addaudithook() 和 sys.audit() 应该存在，但可能什么也不做。这允许代码调用 sys.audit() 而无需测试是否存在，但它不应该假设其调用会产生任何影响。（在安全关键代码中包含存在测试会允许另一个绕过审计的途径，因此最好是函数始终存在。）

io.open_code(path) 至少应始终返回 _io.open(path, 'rb')。使用该函数的代码不应对可能发生的情况做出进一步的假设，并且除 CPython 之外的实现不需要让开发人员使用钩子覆盖此函数的行为。

用于审计钩子的单独模块

建议为审计钩子添加一个新的模块，假设为 audit。这将使 API 和实现与 sys 模块分离，并允许将 C 函数命名为 PyAudit_AddHook 和 PyAudit_Audit，而不是当前的变体。

任何此类模块都需要是一个内置模块，并且保证始终存在。这些钩子的本质是它们必须能够无条件调用，因为任何条件导入或调用都提供了拦截和抑制或修改事件的机会。

鉴于它是最重要的核心模块之一，sys 模块在一定程度上受到保护，防止模块隐藏攻击。用一个足够功能的模块替换 sys 以便应用程序仍然能够运行是一项比替换一个只有一个感兴趣函数的模块复杂得多的任务。能够隐藏 sys 模块的攻击者已经能够从文件运行任意代码，而 audit 模块可以通过搜索路径上的任何位置的 .pth 文件中的一行代码替换。

import sys; sys.modules['audit'] = type('audit', (object,),
    {'audit': lambda *a: None, 'addhook': lambda *a: None})

针对 sys 或 audit 的猴子补丁攻击已经存在多层保护，但对 sys.modules 的赋值或插入不会被审计。

此想法被拒绝，因为它使抑制对 audit 的所有调用变得微不足道。

sys.flags 中的标志以指示“已审计”模式

建议在 sys.flags 中添加一个值，以指示 Python 是否在“安全”或“已审计”模式下运行。这将允许应用程序检测某些功能何时启用或何时添加了钩子，并相应地修改其行为。

目前，我们不知道程序在存在审计钩子的情况下以不同方式运行的任何合法理由。

应用程序级 API sys.audit 和 io.open_code 始终存在且功能齐全，无论使用常规 python 入口点还是某些替代入口点。调用者无法确定是否添加了任何钩子（除非执行侧信道分析），他们也不需要这样做。这些调用应该足够快，以至于调用者不需要避免它们，并且程序负责确保任何添加的钩子都足够快，以至于不会影响应用程序性能。

认为这是“安全通过模糊”的说法是有效的，但无关紧要。安全通过模糊只有在没有其他保护机制时才成为问题；将模糊作为避免攻击的第一步是强烈推荐的（有关讨论，请参阅 这篇文章）。

此想法被拒绝，因为应用程序没有合适的理由根据这些 API 是否正在使用来更改其行为。