审计钩子

为了观察运行时（代表调用者）执行的操作，需要一个 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 点分名称，并避免在名称中编码特定细节。例如，一个 import 事件，其中模块名称 spam 作为参数，优于一个没有参数的 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 何时在“安全”或“审计”模式下运行。这将允许应用程序检测何时启用了某些功能或何时添加了钩子，并相应地修改其行为。

目前，我们不知道程序在存在审计钩子时表现不同的任何正当理由。

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

“这是靠模糊实现安全”的论点是有效的，但无关紧要。靠模糊实现安全只有在没有其他保护机制时才是个问题；将模糊作为避免攻击的第一步是强烈推荐的（请参阅本文进行讨论）。

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