# Changelog All notable changes to this project will be documented in this file. Each version listed corresponds to a release published on [PyPI](). The format is based on [Keep a Changelog](), and this project adheres to [Semantic Versioning](). ## [1.0.0]() — 2026-10-13 Everything below is relative to 0.5.3. Most of this release closes cases in which a policy was in place and not applied: an event loop or a resolver that tethered does not see, a Python child or an interpreter that started without the policy, a rule that was read otherwise than it was written. Where 0.5.3 went on unenforced, 1.0.0 refuses, when the policy is set or at the call, and says what to change. A deployment that ran on 0.5.3 can therefore stop at start-up after the upgrade with no change of its own. Every change that can do that is under **Breaking changes**, whatever kind of change it is, a security fix included. No function, parameter or exception was renamed or removed. ### Upgrading from 0.5.x Read the [1.0.0 migration guide]() before upgrading. It takes the breaking changes below by what a deployment uses (an asyncio server, child processes and `external_subprocess_policy="block"`, locked mode, a log-only rollout), with the message each one shows and the change that puts it right, and it lists the fixes that are not breaking but refuse something 0.5.3 let through. ### Breaking changes Each entry can break a configuration or calling code that worked on 0.5.3, and ends with what to do. An entry that is a security fix as well is here and not under Security. #### Python version - **Breaking: Python 3.10 is no longer supported.** tethered now requires Python 3.11 or later, and no wheels are built for 3.10, which reached the end of its security support in October 2026. `pip` keeps an environment on Python 3.10 at 0.5.3, without the fixes listed under Security. What to do: move to Python 3.11 or later. #### Event loops and resolvers - **Breaking: tethered no longer runs next to uvloop.** Nothing that goes through a uvloop event loop raises an audit event, so a policy was applied to none of the asynchronous networking of a process that ran on one, and uvicorn picks uvloop whenever it is installed (`uvicorn[standard]`, `fastapi[standard]`). Two things changed. While a policy that is not `log_only` is active, `import uvloop` raises `ImportError`; a server that takes uvloop only when the import works (uvicorn, gunicorn's `UvicornWorker`) then runs on the standard asyncio event loop, where the policy is enforced, and tethered logs one warning. And when uvloop is already loaded, `activate()` raises `RuntimeError`, logs the same message as an error, and changes nothing: the server does not start. Before, the policy was activated and silently not applied to anything that went through the loop. A `log_only` policy and a `scope()` with no policy under it are not affected: they refuse nothing and warn once. Nothing is said or refused where uvloop is not installed. Which of the two a deployment meets depends on whether the server imports the application before it picks its loop: with uvicorn 0.54 a plain `uvicorn main:app` falls back and works, while `--workers`, `--reload`, older uvicorn releases, hypercorn's uvloop worker, the `sanic` command and granian with uvloop installed do not start. What to do: name the standard loop in the server's configuration (`uvicorn main:app --loop asyncio`, `UVICORN_LOOP=asyncio` for the `uvicorn` command, `loop="asyncio"` in `uvicorn.run()`), or call `activate()` in a launcher script before the server is imported, or uninstall uvloop ([`docs/COOKBOOK.md`]() has each server). - **Breaking: pycares, and with it aiodns, is not loaded while a policy is active.** c-ares looks names up in C, where tethered sees neither the lookup nor which host an address belongs to. With it, every host that the allow list names was refused by its address, while the lookup of a forbidden name still left the process; aiohttp resolves that way whenever aiodns is installed (`aiohttp[speedups]`). While a policy that is not `log_only` is active, `import pycares` and `import aiodns` now raise `ImportError`, logged once at info level. aiohttp falls back to its threaded resolver on its own, and is then enforced like any other client. A pycares that was imported before `activate()` is left alone, and `activate()` is not refused because of it. What to do: nothing for aiohttp, as long as `activate()` comes before aiohttp is imported; where it cannot (`python -m aiohttp.web`, gunicorn's aiohttp worker class), pass `aiohttp.TCPConnector(resolver=aiohttp.ThreadedResolver())`; and code that needs pycares or aiodns itself has to import it before `activate()` and allow the addresses it connects to. #### Allow rules - **Breaking: malformed allow rules raise `ValueError`** at `activate()` / `scope()`. Before, they were accepted and either never matched or allowed more than was written. Affected: a non-numeric, empty, negative or out-of-range port (`host:abc`, `host:`, `host:-1`); text or a bad port after the `]` of a bracketed IP address (`[2001:db8::1]:abc` used to allow the address on every port); an invalid network prefix; a rule with no host (`:443`); a hostname containing `:`, which includes wildcards over IPv6 text such as `fe80::*` (use CIDR); a dot after the port (`host:443.`) or after a bracketed IP (`[::1].`); and a `*` pattern whose only other content is a character set (`*[!/]`), which matched every destination. What to do: correct the rule; for an IPv6 range use CIDR notation (`fe80::/10`). #### Child processes - **Breaking: more launches are treated as external**, so they are warned about or, under `external_subprocess_policy="block"`, refused. These are: any Python launch when no `tethered.pth` is in a directory `site.py` processes (an editable install, or `pip install --target` + `PYTHONPATH`), or when the file there is not tethered's own or, from Python 3.15, has a `tethered.start` file beside it (both under Security); on POSIX, a launch whose `argv[0]` is not `sys.executable` (`["python", ...]` with `executable=sys.executable`); a launch whose interpreter options cannot be parsed; `-s` / `-I` launches when tethered is installed in the per-user site-packages; and a Python launch through `os.spawn*` / `os.posix_spawn` with an explicit environment that lacks the policy variable (an `os.exec*` with such an environment is carried out with the variable added, see Fixed). Under uWSGI started without `--py-sys-executable`, where `sys.executable` is the uwsgi binary and not an interpreter, every launch counts as external (see Security). `multiprocessing` workers started after `multiprocessing.set_executable()` named another interpreter, and direct `_winapi.CreateProcess` calls, are now subject to the policy as well (Windows; `multiprocessing` on POSIX from Python 3.14). What to do: install tethered into site-packages (a regular install, not editable and not `--target`) so that Python children inherit the policy, and under uWSGI name the interpreter with `--py-sys-executable`; `external_subprocess_policy` then decides whether the launches that remain external are logged (`"warn"`), ignored (`"allow"`) or refused (`"block"`). - **Breaking: a child process refuses to start when it cannot establish a locked or fail-closed policy.** When the inherited policy has `locked` or `fail_closed` set and the child's bootstrap cannot establish it (an invalid payload, a rule the child rejects, the C extension missing), the interpreter exits at startup with status 1. Before, it logged a warning and ran without the policy, or fell back to unlocked enforcement. Without either flag nothing changes: a warning is logged and the child continues. An interpreter created inside the process (a subinterpreter) is the one exception for `locked`: it joins the lock of its process or, where none is held, enforces the policy unlocked, and one that cannot join starts all the same and stays outside the lock (see Locked mode below, and Security). What to do: give child interpreters the same tethered installation as the parent, C extension included. #### Locked mode - **Breaking: under a locked policy, an interpreter that has not joined the lock gets no network.** The lock is held once per process, by the interpreter that took it. An interpreter created while it is held joins it as it starts, through the `tethered.pth` bootstrap: it gets its own locked copy of the policy, checked for tampering like the lock holder's, reaches what the policy allows and is refused the rest, and can neither deactivate nor replace the policy nor change `_TETHERED_CHILD_POLICY`. `concurrent.futures.InterpreterPoolExecutor` workers join the same way. Every other interpreter gets no connections, lookups or process launches and cannot change `tethered.pth`, `tethered.start` or the policy variable for as long as the lock is held, whatever the allow list says: one that existed before the lock was taken, one that started without the bootstrap (tethered not installed in site-packages, the variable missing from the environment, a process started with `-S`), and one whose join failed. Such an interpreter can still be created and can compute. Before, a subinterpreter was limited only by its own unlocked copy of the policy, which it could switch off with `tethered.deactivate()`, and by nothing once the variable had been removed. A locked `log_only` policy lets every interpreter's connections and lookups pass. What to do: take the lock before creating subinterpreters or interpreter pools (for a pool, before its first task is submitted: workers are started on demand), and install tethered into site-packages (a regular install, not editable and not `--target`) so that the bootstrap runs in each new interpreter. Under mod\_wsgi, which creates an application group's interpreter at that group's first request, give each application its own daemon process, or take the lock in the main interpreter at process start with a script of its own (`WSGIImportScript ... application-group=%{GLOBAL}`); uWSGI with several mounted applications needs the same policy locked by the first one ([`docs/COOKBOOK.md`]()). - **Breaking: under a locked policy, no Python child is launched once the hook is lost.** When `tethered.pth` no longer holds tethered's line at the launch of a Python child (it was emptied, removed or replaced after the policy was locked), the launch raises `SubprocessBlocked`, whatever `external_subprocess_policy` says. The lock promises that no Python child of the interpreter starts without the policy, and it already refused a launch whose process environment had lost the policy variable; a lost hook has the same result for the child. This is also what answers for the routes the file guard cannot see: on Linux, `/proc/self/fd/N` and `os.open(..., dir_fd=...)` still empty the hook under a lock, and the launch that follows is refused. What to do: restart a locked process after tethered was upgraded or removed in its environment, and keep doing both from outside the processes that hold a locked policy. - **Breaking: lock tokens of more types are rejected, and a tampered policy stays locked.** `lock_token` now also rejects `complex`, `tuple` and `frozenset` values and the singletons `Ellipsis` and `NotImplemented` (`TypeError`), in addition to `str`, `int`, `float`, `bytes` and `bool`. A locked policy that has failed its integrity check can be neither replaced nor deactivated, even with the correct token: `activate()` and `deactivate()` raise `TetheredLocked` until the original objects are restored or the process is restarted. What to do: pass `object()`, or an instance of a class of your own, as the token. - **Breaking: in locked mode, a failed integrity check on a process launch raises `SubprocessBlocked`**, where it raised `EgressBlocked`. The same check now also refuses the guarded `tethered.pth` operations and `os.putenv` / `os.unsetenv` of the policy variable. What to do: catch `SubprocessBlocked`, or `RuntimeError` (the base class of both exceptions), around process launches. #### `activate()` and `scope()` - **Breaking: `activate()` and `scope()` raise `RuntimeError` when another audit hook in the process refuses tethered's hook.** `sys.addaudithook` drops a new hook without an error when an existing hook raises on its event. Before, tethered then reported success with nothing enforced, in locked mode too. What to do: install tethered's hook first, by calling `activate()` or entering a scope before the other hook is added, or have that hook let tethered's through. - **Breaking: `activate()` raises `ValueError` and changes nothing when the policy is too large to publish to child processes.** Windows limits an environment variable to 32,767 characters, which is roughly 1,500 short rules. Before, the call raised with the new policy already enforcing and nothing published to children. What to do: shorten the allow list, for example by merging addresses into CIDR ranges; a caller that ignored the error no longer ends up with the new policy enforcing in the parent. #### Log lines - **Breaking: a log-only policy or scope logs `would block`, where it logged `blocked`.** Under `log_only=True` the call goes ahead, and a line such as `tethered: blocked connect to evil.test:443` read, to whoever looked at the log later, like a connection that was stopped. It is now `tethered: would block connect to evil.test:443`, and the same for lookups and scopes. The lines of an enforcing policy are unchanged. What to do: a log filter or an alert that matches `tethered: blocked` for a log-only policy has to match `tethered: would block`. ### Added - Python 3.15 support: the test matrix runs on 3.15 and wheels are built for it. The `tethered.pth` bootstrap keeps working there; [PEP 829]() deprecates `import` lines in `.pth` files but Python 3.15–3.17 still run them. - A warning for address-shaped wildcard rules (`10.*`, `192.0.2.*`). Such a rule is a text pattern, so it also allows every hostname that fits it, such as `10.attacker.example`. Matching is unchanged; the warning is logged once per rule per process and points to CIDR notation (`10.0.0.0/8`). - A one-time warning on Windows when a policy or scope is active and a socket is created under asyncio's default `ProactorEventLoop`. That loop connects through calls that raise no audit event, so raw-IP destinations, port rules and scope connect checks are not enforced on it; run the loop as `asyncio.SelectorEventLoop`. The gap is not new; it is now reported at run time and documented in [`docs/security.md`](). - A one-time warning when uvloop is loaded next to a `log_only` policy or a `scope()` that has no policy under it: logged when the policy is activated, when a scope is entered, or at the first socket created under either. In those two cases tethered runs next to uvloop and reports nothing that goes through its event loop. Every other policy keeps uvloop out (see Breaking changes). - A one-time warning from `activate()` when multiprocessing's fork server was started before the policy. A worker of the `forkserver` start method (the default on Linux from Python 3.14) is a copy of the fork server, so such workers hold no policy, under a locked policy either, and tethered can neither refuse nor complete them. The gap is not new; it is now reported at run time. Call `activate()` before the first pool or process is started. - A one-time hint when a connection is refused to an IP address that no hostname is known for, under a policy that has hostname rules: `tethered: no hostname is known for the refused address ...`. That is what a library produces that resolves names outside Python's `socket` module (aiodns / c-ares imported before the policy, dnspython, eventlet's greendns, gevent's ares resolver): a host the allow list names is then refused by its address. The line says what to change. - A documentation site, [tethered.shcherbak.ai](), built from the pages under `docs/`: a home page and a quick start, the cookbook, the subprocess page, the API reference, the compatibility and architecture pages, the security model, this changelog, and the [1.0.0 migration guide](). The site sets no cookie and asks no third party for anything, and the pages read the same on GitHub. For language models and coding agents it has an index at [`llms.txt`](), with a Markdown version of every page it lists. - [`docs/COMPATIBILITY.md`](): what is enforced, what needs a particular configuration, what tethered refuses at start-up and what it does not see at all, under the servers, task queues and client libraries people deploy: uvicorn, FastAPI, gunicorn and its worker classes, hypercorn, Quart, granian, sanic, aiohttp, daphne and Twisted, tornado, uWSGI, waitress, mod\_wsgi, Flask, Django; Celery, RQ, Dramatiq, Huey, arq, the standard library's process and interpreter pools, supervisord; and 72 arrangements of client libraries. Each row names the version it was measured with and the test suite that asserts it. - Container test suites (`tests_containers/`): a harness that installs tethered into the official Python Docker images the way a user does, starts real servers, task queues and client libraries in a container without a network, and checks from the outside, by counting what arrives, that the policy holds in every process. 28 suites besides the harness's own, on Python 3.11 to 3.15; they run in CI on pull requests that touch the package, and weekly against the latest release of every server. Run them with `uv run python tests_containers/run.py`. - [`docs/COOKBOOK.md`](): a FastAPI exception handler, and a section on what each server and task queue needs for the policy to be enforced in every worker, written from the container suites: the launcher pattern, uvicorn and FastAPI, gunicorn, hypercorn, granian, sanic, aiohttp, daphne and Twisted, tornado, uWSGI, waitress, mod\_wsgi, Flask and Django, Celery, RQ, Dramatiq, Huey and arq, process pools and the fork server, and `InterpreterPoolExecutor`. The FastAPI handler also catches a refusal that arrives inside an `ExceptionGroup`: `httpx.AsyncClient` delivers a refused connection (a port rule, or a URL with a raw IP address) that way, and neither `except tethered.EgressBlocked` nor a handler registered for `EgressBlocked` alone catches it. The connection is blocked either way; `except* tethered.EgressBlocked` catches both shapes. - The container suites cover `scope()` under real servers: a scope around one request under gunicorn's sync, gthread and gevent workers and under uvicorn on the standard loop, and around one Celery task in the prefork, threads, solo, gevent and eventlet pools. The scope narrows the policy for that request or task only, also while other requests run in the same process on other threads, tasks or greenlets, and a Python child launched inside it inherits it. Two limits are now measured and stated in [`docs/COMPATIBILITY.md`](): a thread started inside a scope and `loop.run_in_executor` run without it; and a name lookup that asyncio or gevent makes in a pool thread is not checked against the scope, so the DNS query leaves although the connection is refused. ### Changed - The message of `EgressBlocked` writes an IPv6 address with a port the way an allow rule does, `[2001:db8::1]:443`, where it was `2001:db8::1:443`, which did not say where the address ends. The attributes and the log lines are unchanged. - `activate()` and `deactivate()` are all-or-nothing and serialized across threads and across the interpreters of a process: when either raises, the previous policy, the lock and the policy published to child processes are exactly as they were. - The C extension keeps its state per interpreter and loads in interpreters that have their own GIL (Python 3.12+), where it could not be imported before. It still does not declare free-threading support. - The `activate()` warning about a missing `tethered.pth` now says what it means: no directory this interpreter's `site.py` processes holds the file, so Python children will not inherit the policy and `sys.executable` launches are treated as external. - Performance: `with tethered.scope(...)` enter + exit costs about 1 µs (was about 0.5 µs). `activate(locked=True)` takes longer (still under a millisecond) because it generates a larger integrity snapshot; verifying the snapshot on each event is faster than before. Under a locked policy, an `open`, `os.remove` or `os.chmod` of a file that is not tethered's costs about 0.4 µs on Linux and 0.5 µs on Windows (0.6 µs and 1.4 µs in 0.5.3), and an `os.rename` 0.4 µs and 0.7 µs (0.9 µs and 2.6 µs). - The security model (the threat model, what tethered does not protect against, what locked mode does and does not do) moved from `SECURITY.md` to [`docs/security.md`](). `SECURITY.md` keeps how to report a vulnerability, a summary of the model and links to its sections. - The README is cut to the pitch, the quick start and the limits, and PyPI shows a description of its own (`PYPI.md`), short and without images. What the README no longer holds has moved: the full allow list syntax to [`docs/API.md`](), the overhead measurements to [`docs/ARCHITECTURE.md`](), and the table of examples to [`examples/README.md`](). The header image of the READMEs up to 0.5.3 is gone from the repository, so the PyPI pages of those releases show no header. ### Fixed - `EgressBlocked` and `SubprocessBlocked` can be pickled and copied with all their attributes. A blocked call in a `ProcessPoolExecutor` or `multiprocessing.Pool` worker now reaches the parent as `EgressBlocked`; before, the pool broke (`BrokenProcessPool`) or the result never arrived. - `EgressBlocked` and `SubprocessBlocked` can be rebuilt from their message alone, `tethered.EgressBlocked(*exc.args)`, which is what a transport does that keeps the class and `args` of an exception without pickling it. With Celery's default JSON result serializer, `result.get()` for a refused task raised a bare `Exception` in a producer that had tethered loaded, so `except tethered.EgressBlocked` did not match; it now raises `tethered.EgressBlocked`, with `host`, `port`, `resolved_from`, `scope_label` and `scope_hint` read back out of the message. The constructors are otherwise as they were: a call that leaves out a field is still a `TypeError`. - A forked child no longer hangs behind one of tethered's locks. `os.fork()` copies one thread, and a lock that another thread held at that moment stayed locked in the child for ever: the child's next lookup, connection or `activate()` did not return. tethered now resets its locks in the child, as `logging` and `threading` do with theirs. - The warning and the `SubprocessBlocked` for a launch of this interpreter that is treated as external say why: `tethered: external subprocess launch detected: subprocess.Popen(/usr/local/bin/python) — -S skips site.py and the tethered.pth bootstrap with it: the child holds no policy`. Before, the line named the interpreter tethered runs in and nothing else. The other reasons are an `argv[0]` that is not `sys.executable`, interpreter options that cannot be parsed, `-s` / `-I` with tethered in the per-user site-packages, and no `tethered.pth` in a processed site directory. - A rule that begins with a character set (`[ab].example.com:443`) is a hostname pattern. Before, every rule starting with `[` was read as a bracketed IP address, which dropped the port and the rest of the pattern. - A trailing FQDN dot in front of a port (`api.example.com.:443`, `*.example.com.:443`) is ignored, as it already was without a port. Such rules never matched before. - `scope()` used on its own under asyncio no longer blocks the hosts it allows. `loop.getaddrinfo` runs in an executor thread that does not carry the scope, so the lookup was not recorded and the connection was judged as a bare IP. - Two allowed hostnames that share an address (CDNs, load balancers) no longer block each other. tethered remembers up to 8 hostnames per address instead of the last one, and a connection is allowed if any of them, or the raw IP, is allowed. Addresses are matched in canonical form, so a dual-stack connect to `::ffff:a.b.c.d` finds the name recorded for `a.b.c.d`. - `socket.gethostbyname()` followed by a connect to the returned address now works for an allowed host, as the same sequence through `getaddrinfo` did. - Calling `activate()` with the policy that is already active no longer drops the addresses recorded for hostnames. Every `activate()` used to empty that map, so a thread that had just looked a name up and was about to connect was refused a host the policy allows whenever another thread activated the same policy again. In a test with four threads connecting to an allowed host while a fifth re-activated, 1,493 to 2,872 of 6,000 connections were refused; now none is. The map is still dropped when the policy changes, and by `deactivate()`. - A hostname-only scope combined with an IP-only scope no longer blocks a connection that each of them allows. - Under a locked policy, a `subprocess` launch whose explicit environment lacks `_TETHERED_CHILD_POLICY` is given the variable instead of being refused, for a Python child and for an external program alike. An environment built from a list of its own is what ordinary code passes, CPython included: on Linux `ctypes.util.find_library()` runs `ldconfig` with one, so under a locked policy `find_library()` raised `SubprocessBlocked`, and with it `import trio` (hence anyio on trio, and httpx wherever trio is installed), `import asyncssh` and psycopg 3 in its Python implementation. The lock still keeps its promise that no Python starts without the policy, by adding the variable. An environment that carries a different policy, an invalid value or two spellings of the variable is refused as before, and so is `os.posix_spawn` / `os.spawn*` with an environment that lacks the variable, which cannot be completed. `external_subprocess_policy="block"` still refuses the `ldconfig` launch like any external program: import such libraries before `activate()` there. - An `os.exec*` of the same interpreter with an explicit environment that lacks the policy variable is carried out with the variable added, with or without a lock, and logged under a lock. Before, a locked policy refused it. Whoever calls `os.exec*` has usually just forked, and the refusal left a second copy of the parent running the parent's code: gunicorn's binary upgrade (`SIGUSR2`) under `--preload` with a locked policy stopped the workers and removed the unix socket of the server it was to replace. The upgrade now completes with no `pre_exec` hook. - A scope reaches a Python child that is started with `os.exec*`. Before, a scope travelled to a child only through `subprocess.Popen`, so under gevent, whose `Popen` forks and calls `os.exec*` from Python, a child launched inside `with tethered.scope(...)` held the policy of the process and not the scope: in gunicorn's gevent workers and in Celery's gevent pool it reached what the scope refuses, and with no `activate()` under the scope it was not restricted at all. tethered's hook now carries such an exec out itself with the scope in the environment, as it already did to add a missing policy variable. A hand-written `os.fork()` and `os.exec*` inside a scope is covered in the same way. `os.spawn*`, `os.posix_spawn` and `os.system` still carry no scope. - [`docs/COOKBOOK.md`](): the Django middleware it printed did not work. Django turns a view's exception into a 500 response before `get_response()` returns, so a `try` / `except tethered.EgressBlocked` around it never saw the refusal: the connection was blocked, but the request ended as a 500 and the middleware logged nothing. The recipe now uses `process_exception()`. If you copied the earlier middleware, replace it. - `with tethered.scope():` inside a generator no longer removes the caller's scope or leaves its own behind when scopes exit out of order. A scope exited in a context that never entered it logs a warning instead of raising `ValueError`. - tethered no longer resolves a hostname that a scope has just refused: the connect-time fallback search only considers names whose lookup every enforcing layer let through. It also skips that search when the address is already allowed by IP (loopback, an IP or CIDR rule), where it could cost up to 30 DNS lookups per connect. - Interpreter options of a Python launch are read the way CPython reads them. A script argument `-S`, a joined `-cCODE` and `-Wignore::SyntaxWarning` are no longer mistaken for the `-S` flag and treated as external. - Inside a scope, a child launched with an explicit `env=` that is not a `dict` (`UserDict`, `MappingProxyType`) receives a copy of that mapping. Before, it received the parent's environment instead. - On Windows, log messages and `SubprocessBlocked.description` for an external launch name the program instead of `subprocess.Popen(None)`. - `_normalize_host` re-strips whitespace hidden behind a trailing dot (`"host\r."`). - Under a locked policy, a file named `tethered.pth` in another directory can be removed, renamed and have its mode changed relative to that directory's descriptor while the working directory is the one that holds the hook. Before, such a call was taken for the hook and refused. On POSIX it is the call `shutil.rmtree()` makes for a tree that holds such a file. - `scope()` overlap warnings judge each rule the way the policy parses it. A scope rule identical to a rule of the global policy no longer draws "has no overlap with global policy" when it starts with or contains a character set (`[ab].example.com:443`), is an unbracketed IPv6 address whose last group is numeric (`2001:db8::1`, `::1`), or is a wildcard with a trailing dot. Also no longer reported as broader: a port-specific rule inside an any-port rule of the same pattern or of a containing network, a wildcard inside a `*`-suffix wildcard (`*.s3.amazonaws.com` under `*.amazonaws.com`), and `localhost` or a loopback address without a port when localhost is allowed. A hostname rule containing `/` is now reported like any other hostname rule; it used to be skipped. A warning is logged only when the overlap is certain. Where it cannot be told from the rule text, nothing is reported; such rules used to be reported as never matching or as broader, sometimes wrongly. That covers two wildcards of which the global one is not `*` + text (`*.example.com` under `*.example.*`, `[ab].example.com` next to `??.example.com`), a wildcard over address text next to a network rule (`10.0.0.*` under `10.0.0.0/24`, or the reverse), and a wildcard or range that may reach localhost while localhost is allowed (`local*`, `127.0.0.0/8`). ### Security The security fixes that can stop a setup that ran on 0.5.3 are under Breaking changes: uvloop and pycares, the launches that now count as external, a child that cannot establish a locked or fail-closed policy, interpreters outside a lock, a lost hook under a lock, and an audit hook that refuses tethered's. The fixes below also refuse things 0.5.3 let through. - Socket addresses are checked in every form CPython accepts. `bytes` / `bytearray` hosts and ports given through `__index__` (`numpy.int64` and the like) used to skip the policy entirely, including under `fail_closed` and `locked`. An address on an IP-family socket that tethered cannot read is now refused. `sendmsg()` called without an address is not such a case and passes, as it always did: it is a write on a connected socket, whose destination was checked when it connected, and from Python 3.12 asyncio writes that way. - A log-only layer no longer switches off an enforcing one. An outer `scope(log_only=True)` used to disable an inner enforcing scope, and a log-only global denial used to skip the scope checks for the lookup. - Under uWSGI the uwsgi binary is no longer taken for a Python interpreter. There `sys.executable` is the program that embeds Python, and tethered counted a launch of it as a Python child that inherits the policy: `external_subprocess_policy="block"` did not refuse `[sys.executable, "file.ini"]`, and uWSGI ran a command from that file which reached a forbidden destination under a locked policy, with nothing logged. Where Python is embedded and `sys.executable` is not named like an interpreter, every launch now counts as external (warned about, refused under `"block"`), and `activate()` logs a warning that says so and names uWSGI's `--py-sys-executable`. With that option, and under every other server, nothing changes. - A Python child launched with an explicit `env=` that lacks `_TETHERED_CHILD_POLICY`, or after the variable was cleaned out of `os.environ`, now receives the policy: tethered establishes the payload in the launch environment. Before, such a child ran with no policy and neither `"warn"` nor `"block"` noticed. Locked mode, which refused these launches, now gives them the variable as well where it can (see Fixed), and still refuses an environment that carries a different policy. This holds for the launches tethered sees: `multiprocessing` launches on POSIX before Python 3.14 raise no audit event. - `-S` is detected when it is quoted inside a Windows command line, when `executable=` is passed on Windows, and after `-X -c`; these forms used to get through `external_subprocess_policy="block"`. - An editable or `--target` install no longer counts as having the bootstrap. Before, the mere existence of a `tethered.pth` next to the package made tethered trust `sys.executable` children that never ran it. - `multiprocessing` / `ProcessPoolExecutor` launches are seen by tethered on Windows and, from Python 3.14, on POSIX: `external_subprocess_policy`, the locked-mode payload check and the repair of a cleaned environment now apply to them. Workers started inside a virtual environment by third-party copies of the Windows spawner (joblib's loky, billiard) are recognized as children of `sys.executable`. On POSIX with Python 3.11–3.13 these launches raise no audit event and remain out of reach. - Locked mode, launch environments: the payload check reads an explicit environment of any mapping type (a `UserDict` without the variable used to pass unnoticed, and the child ran with no policy; it is now given the variable, see Fixed), compares type-exactly (`"log_only": 0` used to pass and leave the child with no policy), refuses more than one spelling of the variable name (a case-variant duplicate won on Windows), and detects changes made through `os.putenv()` / `os.unsetenv()`. The earlier claim that libc `setenv` / `unsetenv` called through `ctypes` is caught was wrong: `os.environ` does not show such a change. The next entry says what is checked now. - Locked mode, process environment: a launch that inherits the environment is checked against the environment of the process itself, not only against `os.environ`. `os.environ` is a copy each interpreter makes when it starts, so it shows neither a change made from another interpreter of the process nor one made below Python (`ctypes` calling libc `setenv` / `unsetenv`); 0.5.3 saw neither. Such a launch is now refused with `SubprocessBlocked` when the process no longer carries the locked policy. The check is made at the launches tethered sees and does not stop native code from starting a process itself. The interpreters of a process also take turns at `activate()` and `deactivate()`, so that no interpreter's write of the variable is under way while another one publishes a policy and locks it: a call waits while another interpreter is in the middle of one. When interpreters with their own GILs race to take the first lock of a process, the variable carries the winner's policy, and each of the others gets `TetheredLocked` before it has written anything. A call made from inside an `activate()` or `deactivate()` that the same thread is running in another interpreter raises `RuntimeError` instead of waiting. The bootstrap of a new interpreter waits in the same way, so an interpreter created while a locked policy is being replaced joins the new policy. - Locked mode, integrity: the snapshot now covers every module-level name (runtime flags and counters aside), class attribute and function of `tethered._core` and `tethered._policy` instead of sixteen hand-picked handlers, so rebinding a helper no longer disables enforcement silently. It is also verified on the guarded `tethered.pth` and policy-variable events, not only on socket and launch events. Allow rules are immutable tuples of strings and integers and can no longer be edited in place. - Locked mode, token: the lock token is held only by the C extension and can no longer be read back from tethered's module state. - Locked mode, interpreters outside the lock (Breaking changes says which those are): `activate()` and `deactivate()` raise `TetheredLocked` there whatever policy and token are passed, an `activate()` with the identical policy included, because such an interpreter has no locked policy of its own to compare with. The message says what the situation is and what avoids it: a policy is locked by another interpreter of the process, this interpreter is outside that lock and can neither change nor release the policy, and the lock has to be taken before the other interpreters of the process are created. It does not ask for the lock token, which only the interpreter that took the lock can pass. The connections, lookups and launches refused in such an interpreter are not logged. - Locked mode, joined interpreters: a join is accepted only while an interpreter starts, and only once; code that is already running in an interpreter cannot join. Tampering inside a joined interpreter is detected there and refuses that interpreter everything guarded, while the lock holder and the other interpreters are unaffected. When the lock holder replaces the locked policy with a different one, the interpreters that had joined are outside the lock for good and new ones join the new policy; replacing it with an identical policy keeps them joined. When the lock is released, a formerly joined interpreter keeps enforcing its copy from Python and may deactivate it. If the interpreter that holds the lock is destroyed, the process stays locked: no other interpreter, existing or created later, takes the lock over, joined interpreters keep working, new ones still join, and nothing can release it. A joined interpreter is protected like a locked child process, which means that its startup files are trusted; [`docs/security.md`]() states the rules and the limits. - Locked mode: `os.truncate()` of `tethered.pth` is refused. The earlier statement that CPython raises no audit event for it was wrong. - Locked mode: `shutil.copy2()` onto `tethered.pth` is refused on Windows. From Python 3.12 it replaces its destination through `_winapi.CopyFile2`, which raises no `open` event, so it got past the guard and could empty the hook. - Locked mode: creating a `tethered.start` file beside `tethered.pth` is refused (write-mode `open`, a rename or copy onto the name, `os.link`, `os.symlink`). From Python 3.15, `site.py` ignores the `import` line of a `.pth` file when a `.start` file of the same name sits beside it (PEP 829), so an empty file there stopped Python children from auto-activating. `os.mknod` raises no audit event and is not caught. - Locked mode: `tethered.pth` and `tethered.start` are recognised by their name and their directory, not by the text of the path. Before, a call that named the directory in another way got past the guard: through a symlink or a junction, by a Windows short name or with a `\\?\` prefix, as `tethered.pth::$DATA`, or relative to a directory descriptor (`dir_fd`). Ordinary tools did that without trying. `pip` names files by their resolved path, so `pip uninstall tethered` run from a locked process removed the hook from an environment that is reached through a symlink or a short name; and on POSIX `shutil.rmtree()` removes files relative to a descriptor, so it deleted the hook although the documentation said it was refused. Still not matched: another name for the file itself (a hard link, a symlink to the file), and `os.open(..., dir_fd=...)`, whose audit event does not carry the descriptor. What to do: install, upgrade and remove tethered from outside the processes that hold a locked policy. pip stops halfway when it is refused; [`docs/COMPATIBILITY.md`]() says what it leaves and how to repair it. - Locked mode: `tethered.pth` is guarded as a file, wherever a `tethered.pth` that is this file lies. uv installs by hard-linking out of its cache, so in an environment uv made the hook is also a `tethered.pth` in the cache directory, and a write to that one emptied the hook under a lock: Python children then started with no policy. A write-mode `open`, `os.truncate`, `os.chmod` and a copy onto such a file are now refused like the same operation on the hook. Reading it, removing it and clearing the cache are not refused. - Locked mode: the hook cannot be given another name. `os.link(hook, "x")` followed by `open("x", "w")` emptied the hook under a lock, in any environment: the link was only looked at as a way of creating `tethered.start`, and the write named nothing tethered knows. `os.link` and `os.symlink` with the hook as their source are now refused, and so is renaming another `tethered.pth` that is the same file. Still open, and stated in [`docs/security.md`](): a name of another spelling that was made before the policy was locked, `/proc/self/fd/N` on Linux, and `os.open(..., dir_fd=...)`. A hook that is emptied on one of those routes is caught by the next entry. - A `tethered.pth` counts as the bootstrap only while it holds tethered's own line. tethered used to know its hook by its name and its place. Another distribution that ships a top-level `tethered.pth` replaces tethered's when it is installed, without a word from pip or uv, and tethered took that file for its bootstrap: no warning, and a Python child of a locked, fail-closed process under `external_subprocess_policy="block"` was launched with no policy. `activate()` now logs a warning (`tethered: ... is not the file tethered installs under that name ...`) and treats `sys.executable` launches as external. The file is also read again at each launch of a Python child that would inherit, so a hook that is emptied, removed or replaced while the process runs (by an installer, by another program, on a route the locked-mode guard does not see) makes the next such launch an external one, with the reason in the log line and in `SubprocessBlocked.description`: `... — tethered.pth no longer holds tethered's bootstrap line: the child holds no policy`. Before, the path was found once and believed from then on. Under a locked policy that launch is refused outright (see Breaking changes). - A `tethered.start` file beside `tethered.pth` is found even where its creation could not be refused. From Python 3.15 such a file switches the hook off (PEP 829). Locked mode refuses creating one by the calls that raise an audit event; a file made with `os.mknod`, one that was there before the policy, and any such file under a policy that is not locked went unnoticed, and Python children started with no policy while tethered took them for covered. `activate()` now logs a warning (`tethered: ... is switched off by the tethered.start file beside it ...`) and treats `sys.executable` launches as external, and a file that appears later is met at the next launch of a Python child like a hook that was emptied. - Locked mode: tethered's own DNS lookups call the resolver captured when the policy was locked, and a connection attempted from inside such a lookup is refused. A replaced `_socket.getaddrinfo` could previously connect from there. - [`docs/security.md`]() now states what locked mode checks and what it does not stop. It no longer says that the remaining bypasses require `ctypes`: Python code written against tethered can still defeat locked mode, for example by replacing the standard-library functions the policy calls or by writing into the IP-to-hostname map. Newly documented limitations: the Windows `ProactorEventLoop`, hostnames resolved by `connect()` before the hook sees them, `socket.getnameinfo`, connections that are already open, and `.pth` files written into a site directory, which later child processes and new interpreters can run before tethered's bootstrap. The claim that the design is safe on free-threaded Python has been withdrawn; the C extension does not declare free-threading support. - uvloop: under asyncio the policy is enforced on the standard event loop only. In 0.5.3 a process that ran on uvloop, which uvicorn uses by default when it is installed, had a policy that was applied to nothing that went through the event loop: `httpx.AsyncClient`, asyncio streams and datagram endpoints reached forbidden hosts with no exception and no log line, `locked=True` and `fail_closed=True` included, and launches through `asyncio.create_subprocess_exec` / `create_subprocess_shell` got neither `external_subprocess_policy` nor the locked-mode environment check nor the active scope. tethered now refuses to run in that arrangement (the uvloop entry under Breaking changes). What remains is documented in [`docs/security.md`](): a `log_only` policy and a `scope()` without a policy run next to uvloop and see nothing of its loop; an interpreter that is outside a lock can still load uvloop; and uvicorn serves an application without a policy when a hand-written ASGI lifespan handler raises tethered's refusal. The README, `docs/SUBPROCESS.md` and `docs/ARCHITECTURE.md` said that tethered works with FastAPI, httpx and aiohttp and that `asyncio.create_subprocess_exec` is supported, without saying on which event loop. They now say it. - Documented limit, libraries that connect in C: a client library that resolves names and connects inside a C library of its own raises no audit event and is neither blocked nor reported, under a locked policy as well. The earlier one-line statement about "C extensions with raw socket calls" did not say how ordinary this is. Measured: pycurl, curl\_cffi, tornado's `curl_httpclient`, psycopg2, mysqlclient, the C extension of mysql-connector-python, pymssql, pyodbc with FreeTDS, grpcio, confluent-kafka, pyzmq and `awscrt.http` reach every forbidden destination; psycopg 3 has the name checked and the address not. [`docs/COMPATIBILITY.md`]() has the table and names the pure-Python alternatives, which are enforced. What to do: use a driver that goes through Python's `socket` module, or control such a library's traffic below Python. - Documented limit, libraries that resolve names themselves: dnspython, eventlet's default greendns, gevent with `GEVENT_RESOLVER=ares`, niquests with a resolver of its own, and c-ares when it was loaded before the policy. Nothing forbidden is reached, but a host the allow list names is refused by its address, and the name of any host is still sent to the name server. What to do: use the system resolver (`EVENTLET_NO_GREENDNS=yes`, gevent's default resolver), or allow the address. - Documented limits of other runtimes: rloop, granian's event loop, sends a datagram on an unconnected endpoint below Python, where it is not seen. Twisted reports a refused connection as its own `TimeoutError` after the connection timeout and never completes a request whose lookup was refused; nothing forbidden is reached. Under gevent's default resolver a refused lookup now and then never returns, because tethered logs the refusal from one of gevent's resolver threads; with the `tethered` logger at `ERROR` this was not seen in 180 processes. - Documented limit, unlocked policies in several interpreters of one process: each interpreter enforces its own policy on its own connections, but `_TETHERED_CHILD_POLICY` is one variable for the process, so Python child processes, and interpreters created later, get the policy of whichever interpreter activated last. What to do: give applications with different policies different processes, or lock one policy for the process. - Documented limit, CPython's internal test modules: one of the ways around locked mode that [`docs/security.md`]() lists needs access to the interpreter configuration, which CPython's internal test modules (`_testinternalcapi`, `_testcapi`) offer to Python code. They are installed almost everywhere: in the official `python` Docker images (regular, slim and alpine), with the `python3` package of Debian, Ubuntu and Alpine, in the distroless and Chainguard Python images, the AWS Lambda Python image and miniforge, and compiled into uv-managed Pythons. [The same page]() lists where the modules were found and where they were not, and what was checked: deleting them from the official images leaves locked mode working. - Documented limits, application servers and interpreter pools, stated in [`docs/security.md`]() with the configurations that work in [`docs/COOKBOOK.md`](): two mod\_wsgi application groups in one process race for the lock under concurrent first requests, and the one whose interpreter already existed gets no network (use one application per process, or take the lock in the main interpreter at process start with a script of its own); mod\_wsgi needs `python-home`, not `python-path`, for a virtual environment; under uWSGI `sys.executable` is the uwsgi binary, so a Python child counts as external unless `--py-sys-executable` names the interpreter; a locked policy survives whatever re-executes the server (a uWSGI reload, gunicorn's `SIGUSR2` upgrade with `--preload`, Django's autoreloader), so changing it takes a stop and a start; and an `InterpreterPoolExecutor` whose workers started partly before the lock has workers of both kinds. ## [0.5.3]() — 2026-08-19 ### Fixed - `TetheredLocked` crash in auto-activated child processes whose application startup code calls `activate(locked=True)` at import time (e.g. Django settings). The `tethered.pth` bootstrap re-engages the parent's locked policy before user code runs, so the app's own `activate()` call in a spawn-mode child hit the locked-replacement check and crashed. `activate()` over a locked policy is now an idempotent no-op when the requested policy's canonical payload is identical to the active one; `on_blocked` and `lock_token` from the no-op call are ignored (adopting a caller-supplied token would let untrusted code unlock the policy), and a differing policy still raises `TetheredLocked` — now with an `activate()`-specific message. ## [0.5.2]() — 2026-08-19 ### Added - Standalone overhead microbenchmark ([`benchmarks/overhead.py`]()) measuring per-event cost across deactivated / activated / activated+scope / activated+locked, and Hypothesis property tests for `AllowPolicy`. ### Fixed - False "substitution attempt" `SubprocessBlocked` in locked mode under process managers (honcho, supervisord-style runners). The canonical `_TETHERED_CHILD_POLICY` payload serialized exact-host rules from frozensets, whose iteration order follows per-process hash randomization (`PYTHONHASHSEED`) — so a spawn-mode child rebuilding its canonical payload ordered the same entries differently than the parent that serialized it. Any launch passing an env dict captured in another process (e.g. a manager pickling `os.environ` snapshots to runner children) then failed the payload-integrity check and was blocked. The `allow` list is now sorted, making the canonical payload deterministic across interpreters. Workaround on affected versions (0.5.0–0.5.1): set `PYTHONHASHSEED` to a fixed value for all processes. - `_normalize_host` re-strips whitespace after IPv6 scope-ID removal — splitting on the `%` separator could leave trailing whitespace that the initial strip missed. ## [0.5.1]() — 2026-05-01 ### Added - `hint=` parameter on `tethered.scope()`. Library authors (and app developers using `scope()` to tighten request handlers, jobs, or third-party calls) can attach a one-line egress contract — typically the hosts the scope needs plus a docs URL — that surfaces whenever any `EgressBlocked` fires while the scope is on the stack. The hint is configuration metadata on the scope: dormant in normal operation, emerging only when something is actually blocked. The hint travels with the scope through subprocess auto-propagation alongside `label=`, so a child blocked by an inherited scope sees the same guidance. See [`docs/COOKBOOK.md`](). - `EgressBlocked.scope_hint` attribute. When a hinted `scope()` is on the stack at block-time, `EgressBlocked` carries the deepest hinted scope's hint and the default message gains a trailing `Hint: ` line. The deepest-hinted-scope rule applies regardless of which layer produced the block — your own scope, an inner scope, the host's global `activate()` policy, or an outer scope set by the host or a higher-level library — so a host that has tethered configured but forgot to allowlist your endpoints still sees actionable guidance. Outer hints fall through when the inner scope is unhinted. ## [0.5.0]() — 2026-04-28 ### Added - `label=` parameter on `tethered.scope()`. Library authors can pass a human-readable label (e.g. `label="WeatherClient.get_forecast"`) that surfaces in log messages and as `EgressBlocked.scope_label` when the scope blocks. Defaults to the auto-derived `"scope()"` summary, so existing call sites are unchanged. See [`docs/COOKBOOK.md`](). - `EgressBlocked.scope_label` attribute. When a `scope()` (rather than the global policy) blocks the call, `EgressBlocked` carries the scope's label and the message gains a trailing `(blocked by