# API reference ## `tethered.activate()` ```python tethered.activate( *, allow: list[str], log_only: bool = False, fail_closed: bool = False, allow_localhost: bool = True, on_blocked: Callable[[str, int | None], None] | None = None, locked: bool = False, lock_token: object | None = None, external_subprocess_policy: str = "warn", ) ``` | Parameter | Description | | --- | --- | | `allow` | Required. Allowed destinations — see [Allow list syntax](<#allow-list-syntax>). Pass `[]` to block all non-localhost connections. A malformed rule raises `ValueError` (see [Rule validation](<#rule-validation>)). | | `log_only` | Log what would be blocked instead of raising `EgressBlocked`. Default `False`. | | `fail_closed` | Block when the policy check itself errors, instead of failing open. Default `False`. | | `allow_localhost` | Allow loopback addresses (`127.0.0.0/8`, `::1`). Default `True`. | | `on_blocked` | Callback `(host, port) -> None` invoked on every blocked connection, including in log-only mode. | | `locked` | Enable tamper-resistant enforcement via C extension. Replacing or deactivating the policy then requires the `lock_token`, and a C-level integrity verifier refuses ALL socket operations, process launches, and the guarded `tethered.pth` / policy-variable operations while it detects tampering with tethered's own code or the active policy. Default `False`. See [Locked mode](<#locked-mode>). | | `lock_token` | Opaque token required when `locked=True` (`None` counts as missing: `ValueError`). Must be an instance like `object()` — singletons and values of immutable built-in types (`str`, `int`, `float`, `complex`, `bytes`, `bool`, `tuple`, `frozenset`, `Ellipsis`, `NotImplemented`) are rejected with `TypeError`, because an equal value created elsewhere can be the very same object. Compared by identity (`is`), not equality. tethered keeps no copy of the token outside the C extension; keep your own reference if you intend to unlock. | | `external_subprocess_policy` | Parent-side enforcement for *external* process launches: programs that are not Python, other Python interpreters, `sys.executable` launched with `-S` (which disables `site.py`), and Python launches that cannot be shown to inherit the policy. Values: `"warn"` (default — supply-chain visibility), `"allow"`, `"block"`. A Python child of `sys.executable` auto-inherits the policy and is unaffected by this setting. [The subprocess page]() has the table of what counts as external. | ### Replacing the active policy `activate()` can be called multiple times to replace the active policy — calling it again does not require `deactivate()` first. If the current policy is locked, the correct `lock_token` must be provided. Each call creates a completely new policy; no parameters carry over from previous calls. The addresses recorded for hostnames are dropped when the policy changes. A call that puts the same policy in place again (the same rules and settings) keeps them, so that a thread which has just looked a name up is not refused the connection that follows. The call is all-or-nothing, and calls are serialized, across threads and across the interpreters of the process: a call waits while another thread or interpreter is in the middle of an `activate()` or `deactivate()`, and when it gets its turn it sees the result (an interpreter that waited for a lock being taken elsewhere gets `TetheredLocked`). Whenever it raises, the previously active policy (or none), the lock, and the policy published to child processes are exactly as they were. Two of the cases in which it raises are not about its arguments: - **`ValueError` when the policy cannot be published to child processes**, because its serialized form does not fit in an environment variable. On Windows the limit is 32,767 characters, which is roughly 1,500 short rules. - **`RuntimeError` when the policy would not be applied:** when tethered's audit hook cannot be installed because another audit hook in the process refuses new hooks, and when uvloop is loaded (next section). ### Event loops and resolvers Under asyncio the policy is enforced on the standard event loop. uvloop does its networking outside Python's `socket` module and raises no audit event, so nothing that goes through a uvloop event loop could be checked. tethered therefore does not run next to it: - **`activate()` raises `RuntimeError` when uvloop is already loaded in the process**, unless `log_only=True`. Nothing is changed. The message begins `tethered: activate() refused — uvloop is loaded in this process.` and names the ways out; it is also logged at error level before it is raised, because a server can swallow the exception (uvicorn does for a hand-written ASGI lifespan handler). - **While a policy that is not log-only is active, `import uvloop` raises `ImportError`** (`tethered: uvloop was not loaded — a policy is active ...`). A server that takes uvloop only when the import works, as uvicorn and its gunicorn worker do, then runs on the standard loop. The refusal is logged once per process as a warning (`tethered: refused to load uvloop while a policy is active ...`), since such a server catches the error without a word. Nothing is refused or logged when uvloop is not installed. - **A log-only policy refuses nothing**, neither the import nor the activation. It logs one warning (`tethered: uvloop is loaded in this process. ...`) when it finds uvloop loaded, at `activate()` or when a socket is created, and reports nothing that goes through the loop. A `scope()` with no policy under it behaves the same way. uvicorn uses uvloop by default when it is installed; name the loop (`--loop asyncio`) or activate before the server is imported. [The cookbook]() says what each server needs. On Windows the default `ProactorEventLoop` is enforced only in part; run the loop as `asyncio.SelectorEventLoop`. Both are described in [the security model](). The same import refusal applies to pycares, the c-ares binding under aiodns: while a policy that is not log-only is active, `import pycares` raises `ImportError` (`tethered: pycares was not loaded — a policy is active ...`), and so does `import aiodns`. c-ares looks names up where tethered sees neither the lookup nor which host an address belongs to, so with it every host allowed by name would be refused. aiohttp falls back to its threaded resolver on its own. The refusal is logged once per process, at info level. A pycares that was imported before `activate()` is left alone, and `activate()` is not refused because of it. ### What it logs - One info line on success (`tethered: activated with N rules (log_only=...)`). - A warning when no `tethered.pth` is in a directory this interpreter's `site.py` processes (Python children will not inherit), or when the file that is there is not the one tethered installs (`tethered: ... is not the file tethered installs under that name ...`): another distribution that ships a `tethered.pth` replaces tethered's when it is installed. From Python 3.15 also when a `tethered.start` file lies beside the hook, which switches it off (`tethered: ... is switched off by the tethered.start file beside it ...`). - One warning per process when multiprocessing's fork server was started before the policy: its workers are copies of the fork server and are not restricted, under a locked policy either (see [the security model]()). - Later, one warning per process the first time the policy refuses (or, under `log_only`, reports) a connection to an IP address that no hostname is known for while the policy has hostname rules (`tethered: no hostname is known for the refused address ...`). Usually that is an address nothing allows, but it is also what a library that resolves names outside Python's `socket` module produces for a host the allow list names. ### Rule validation Rules are parsed when `activate()` or `scope()` is called, and a malformed rule raises `ValueError`. That covers: - an empty rule, and a URL; - a port that is non-numeric, empty, negative or outside 0–65535 (`host:abc`, `host:`, `host:-1`, `host:70000`); - text after the `]` of a bracketed IP address (`[::1]x`), and a network prefix inside the brackets (`[2001:db8::/32]`); - an invalid network prefix (`[2001:db8::]/200`); - a rule with no host (`:443`); - a hostname containing `:`, which includes wildcards over IPv6 text such as `fe80::*` (use CIDR); - a `*` pattern with no literal character (`*`, `*.*`, `*[!/]`: a `[...]` set does not count as one). Three things are accepted that may not be expected: - One trailing dot on the host part is ignored, so `api.example.com.` and `api.example.com.:443` are the same rules as without it. A dot after the port (`host:443.`) is an error. - A rule may begin with a `[seq]` character set: brackets are read as an IP literal only when they contain an IP address. - An address-shaped wildcard such as `10.*` is a pattern over text, not an address range: it also allows `10.attacker.example`. tethered logs a warning for such a rule, once per rule per process. Use CIDR for ranges. ## `tethered.scope()` ```python tethered.scope( *, allow: list[str], allow_localhost: bool = True, log_only: bool = False, fail_closed: bool = False, on_blocked: Callable[[str, int | None], None] | None = None, label: str | None = None, hint: str | None = None, ) ``` | Parameter | Description | | --- | --- | | `allow` | Required. Allowed destinations — see [Allow list syntax](<#allow-list-syntax>). A malformed rule raises `ValueError`, as for `activate()`. | | `allow_localhost` | Allow loopback addresses. Default `True`. | | `log_only` | Log what would be blocked instead of raising. Default `False`. | | `fail_closed` | Block when the policy check itself errors. Default `False`. | | `on_blocked` | Callback `(host, port) -> None` on every blocked connection. | | `label` | Human-readable name for this scope. Appears in log messages and as `EgressBlocked.scope_label` when this scope produces a block. Library authors should use it to identify call sites — e.g. `label="WeatherClient.get_forecast"`. Defaults to an auto-derived `"scope()"` summary. | | `hint` | Actionable guidance attached to any `EgressBlocked` raised while this scope is the deepest hinted scope on the stack — e.g. `hint="mylib needs api.mylib.com:443 — see https://…/security"`. Surfaces as `EgressBlocked.scope_hint` and as a trailing `Hint: …` line on the message. Runs of whitespace, embedded newlines included, collapse to a single space; `None`, an empty string and whitespace alone mean no hint. The hint travels with the scope into child processes. | Use as a **context manager** (`with tethered.scope(allow=[...]):`) or a **decorator** (`@tethered.scope(allow=[...])`). Supports both sync and async functions. Cleanup is automatic — no `deactivate()` call needed. A scope is active in the context that entered it (a thread, an asyncio task, a greenlet under gevent or eventlet), from entry until its block exits. It does not follow work into another thread: a thread started inside the block and `loop.run_in_executor` run without the scope, while `asyncio.to_thread` copies the context and stays inside it ([the compatibility page]() has what was measured under real servers). Generator and async generator functions cannot be decorated (`TypeError`). Inside a generator, wrap each I/O call in its own `with tethered.scope(...)` block and do not `yield` inside one: a scope that is open across a `yield` stays active in the consumer's context until the generator resumes. Exiting a scope removes that scope's own entry from the stack, whatever has been entered or exited in between. Exiting it in a context that never entered it removes nothing and logs a warning. `scope()` works on its own — no `activate()` required. When used alone, the scope IS the policy for that code path. Code outside the scope is unaffected. Entering a scope (`with`, or calling a decorated function) raises `RuntimeError` when tethered's audit hook cannot be installed, for the same reason as `activate()`; the body does not run and no scope is left active. Three caveats apply under asyncio: - A scope's DNS-time check does not apply to `loop.getaddrinfo`, which runs `socket.getaddrinfo` in an executor thread that does not carry the scope. The connection that follows is still checked against the scope. - Under uvloop a scope is not applied to anything that goes through the event loop, connections included, and nothing is logged for it. An enforcing `activate()` policy keeps uvloop out of the process (see [Event loops and resolvers](<#event-loops-and-resolvers>)); a scope used on its own does not, and only logs a one-time warning when it is entered with uvloop loaded. - On Windows the default `ProactorEventLoop` gets no connect-time enforcement at all, for scopes or for `activate()`: run the loop as `asyncio.SelectorEventLoop` (see [the security model]()). Scopes can only **restrict**, never widen. If the app also called `activate()`, the effective policy is the intersection — a connection must be allowed by both. > **Package maintainers:** Use `scope()`, never `activate()`. Your library doesn't own the process — the app does. `activate()` is a process-wide operation that would interfere with the host application's own policy. `scope()` is context-local and safe to use from any library. ## `tethered.deactivate()` ```python tethered.deactivate(*, lock_token: object | None = None) ``` Disable enforcement. All connections are allowed again. Internal state (IP-to-hostname mappings, callback references) is fully cleared — a subsequent `activate()` starts fresh. If activated with `locked=True`, the matching `lock_token` must be provided or `TetheredLocked` is raised. `TetheredLocked` is also raised, even with the right token, when the locked policy has failed its integrity check (the message says so). The process then has to be restarted, or the original objects restored. Like `activate()`, the call is serialized with other `activate()` / `deactivate()` calls, in this interpreter and in the others, and leaves everything as it was if it raises. Both raise `RuntimeError` in the two cases where waiting could never end: when the call is made from inside another interpreter's `activate()` / `deactivate()` on the same thread, and when Python is shutting down while another thread holds its turn. ## `tethered.EgressBlocked` Raised when a connection is blocked. Subclass of `RuntimeError`. ```python try: urllib.request.urlopen("https://evil.test") except tethered.EgressBlocked as e: print(e.host) # "evil.test" print(e.port) # 443 print(e.resolved_from) # original hostname if connecting by resolved IP print(e.scope_label) # "scope(api.mylib.com:443)" if a scope blocked it; None for global blocks print(e.scope_hint) # actionable guidance from the deepest hinted scope, or None ``` | Attribute | Type | Meaning | | --- | --- | --- | | `host` | `str` | The host (or IP) the call attempted to reach. | | `port` | `int \\| None` | The port, when known (`None` for `getaddrinfo` / DNS-only events). | | `resolved_from` | `str \\| None` | When connecting by a resolved IP, the hostname most recently seen resolving to that IP. `None` for direct hostname connects or when no mapping is known. | | `scope_label` | `str \\| None` | The label of the `scope()` that blocked the call (e.g. `"scope(api.mylib.com:443)"`), or `None` if the block came from the global `activate()` policy. Useful for libraries that wrap `EgressBlocked` and want to attribute the block to the right scope when multiple are nested. See [COOKBOOK.md\#for-package-authors](). | | `scope_hint` | `str \\| None` | The `hint=` set on the deepest hinted `scope()` on the stack at block-time, or `None` when no hinted scope was active. The deepest hinted scope wins whichever layer produced the block: an outer hint surfaces when no closer scope set one, and a hint also surfaces when the global `activate()` policy is what blocks, so a library's guidance reaches the user in blocks the host application's policy produces. | When `scope_label` is non-`None`, the message includes a trailing `(blocked by