What does sys.addaudithook install in CPython, and which operations raise audit events?

## The two halves of the mechanism PEP 578, "Runtime Audit Hooks", shipped in Python 3.8 and is unchanged in shape on 3.14. It adds a *raise* side and a *listen* side. The raise side is `sys.audit(event, *args)`. It takes an event name -- by convention a dotted string namespaced to whoever raises it, such as `"subprocess.Popen"` or `"etl.export.start"` -- and any number of positional arguments describing the operation. It returns `None`; there is no result to inspect. The listen side is `sys.addaudithook(hook)`. The hook is any callable taking two positional parameters: the event name as a `str`, and a `tuple` of the arguments. It is invoked synchronously, in the thread that raised the event, before the audited operation completes, and hooks are invoked in the order they were installed. The return value is discarded, so a hook cannot approve or veto by returning; the only way it can influence the operation is by raising, and an exception raised inside a hook propagates out of the audited call and aborts it. ## Where the events come from Most interesting events are raised by CPython itself, from C, at points chosen for security relevance rather than for performance instrumentation: * `"compile"` with the source and filename, and `"exec"` with the code object -- so `exec`, `eval` and `compile` are all visible, including code assembled at runtime. * `"import"` with the module name, the resolved filename, and the import machinery's own search state (`sys.path`, `sys.meta_path`, `sys.path_hooks`). * `"open"` with the path, the mode and the OS flags, raised by both the builtin `open` and `os.open`. * `"subprocess.Popen"` with the executable, the fully resolved argument list, the working directory and the environment, plus `"os.system"` for the shell entry point. * Networking, `ctypes` and other sensitive stdlib surfaces raise their own events, and on 3.14 the new remote-execution entry point `sys.remote_exec` raises `"sys.remote_exec"`. Stdlib modules written in Python raise events by calling `sys.audit` directly, and application code can do the same. Because the namespace is a flat string space, prefix your own events with something you own so that a hook can filter them cheaply with `str.startswith`. ## What a hook can and cannot do A hook is an observer with one weapon. It sees the operation's *semantic* arguments -- an argv list before the process is spawned, a module name before it is loaded, a path before the file is opened -- which is strictly more informative than what an operating-system-level tracer sees after the fact. Raising from the hook is how a "deny subprocess launches in this service" policy is written, and it genuinely aborts the specific call. What it is not is a sandbox, and PEP 578 says so explicitly. The audit points exist where CPython chose to put them; native code that calls the C library directly, rather than going through the interpreter's own entry points, raises nothing. Treat the stream as high-quality detection and defence in depth, not as an isolation boundary -- isolation belongs to the process, container or operating-system layer. ## Cost, filtering and discovery There is deliberately no way to subscribe to a subset of events. Every installed hook is called for every event, and filtering happens in Python inside your hook. That is the single most important consequence for the shape of hook code: the first line should be the cheapest possible test -- membership of the event name in a `set`, or a prefix test -- with an immediate return for everything else. When no hook is installed at all, the audit points are close to free: the C-level audit call checks a flag and skips building the argument tuple. Installing one hook turns every audit point in the process into a Python-level call plus tuple construction. Discovering the event names is done empirically. A hook that counts event names into a `collections.Counter` and prints the totals at the end tells you exactly which events your workload actually raises and how often -- which is the right first step before writing any policy. Be careful what the hook itself does: writing to a file from inside a hook raises `"open"` again, so any I/O in a hook needs a re-entrancy guard or it will amplify. ## Installing it early enough A hook only sees events raised after it is installed, so the imports and file opens that happen during your own startup are invisible to a hook installed in `main()`. Installing as early as possible means a path-configuration file or a startup module picked up by the `site` machinery in the base image; an embedder can install a hook from C before the interpreter is initialised, which is the only way to catch everything.