This page is a red-team report on the Python-level guards — the dynamic patching that denies file, socket, import, environment and sensitive-call access from inside the running interpreter (guard_files, guard_socket, guard_import, guard_envs, guard_api, and the arming machinery). It documents, objective by objective, what hostile code can and cannot reach once a profile is armed, which layer stops each attempt, and — crucially — the residual limits the layer does not claim to cover.

It is the companion of the eval-* assessment, which covers the dynamic-code sub-language, and of weaknesses, which lists the limits of the package in prose. This page turns those prose limits into a structured, test-pinned matrix and names the enforcing function or class for every row. Read implementation first if you need to know how the patching works before reasoning about what it stops.

Verification date: 2026-10-06. The focused test modules cited by this assessment reported 261 passed, 6 failed, 3 skipped and 4 expected failures on Python 3.13.5. All six failures require creating or binding sockets; the execution environment returns PermissionError: [Errno 1] Operation not permitted. This run therefore does not revalidate those socket rows. The individual evidence labels below remain scoped to their named tests and configurations.

The separate native guard study evaluates C wrappers and CPython audit hooks as ways to reduce introspection of original functions. It records the prototype results and why a general native layer was not pursued.

This assessment concerns the Python interception layer, not the OS boundary. It documents both tested refusals and routes that remain open to arbitrary Python code. Treat Blocked — demonstrated as a result for the named test and configuration, not as proof that every equivalent attack is blocked. Treat Reasoned as source analysis that has not been pinned by an isolated payload. The weaknesses page gives the short operational summary.

The two reports do not share a threat model, and conflating them would be a false guarantee.

• In the eval-* report the attacker controls a source string evaluated inside a bounded namespace. There the report can honestly say "every attribute read passes through _check_attr": the attacker never holds a real object reference the guard did not hand out.

• Here the attacker controls arbitrary bytecode running in the host interpreter. Any granted callable, any module object, any frame is a live Python object with full introspection. weaknesses.md states the consequence plainly: "arbitrary Python can always call native code … the OS-sandboxes remain the real barrier."

So the useful columns here are not "blocked vs allowed" in an absolute sense. They are: what the layer costs the attacker, what learning mode makes visible, and which OS layer actually stops what the patching cannot. The Python layer's job is to deny sensitive operations from non-hostile code and to surface them in learning mode — not to contain hostile bytecode. That is the OS sandbox's job (firejail, bwrap, unshare, qemu, landlock).

Naming the reader this layer is built for decides what is worth building, so it is stated here rather than left to be inferred from the matrix.

The target is code an LLM produced while solving the wrong problem, not an adversary. Such code reaches for open, requests.get or subprocess in the open, and stops at the first refusal. The layer exists to make that refusal happen, to name the rule that caused it, and to record it in learning mode.

Code written to break out is explicitly out of scope, and not for lack of effort: it needs none of the paths listed in section 6. One ctypes call, or one C extension, leaves every Python-level guard untouched and intact. Hardening this layer against that reader would buy nothing the layer does not already concede on the line above.

Two consequences, both deliberate:

• No C extension holding the arming flag, and no PEP 578 audit hook guarding it, are planned. Either would close one row of section 6 while the rows below it stay open, and neither survives a reader who can call native code anyway. The one audit hook the layer does install, in guard_import, is not that: it keeps the import finder at the head of sys.meta_path. Frameworks put their own finder there when they are imported (crewai, wrapt post-import hooks, httpx2 aliases, py-key-value), so overtaking the guard is the ordinary case, not an attack; the hook moves it back before each import instead of refusing.
• The residual entries in section 6 are documented, not scheduled. What the layer does owe its target is that an accidental disarming be loud rather than silent.

• Two enforcement states: disarmed and armed
• Attack matrix by objective
  • 1. Read or write a file outside the whitelist
  • 2. Open a socket or exfiltrate
  • 3. Execute a process or native code
  • 4. Read a secret
  • 5. Import a forbidden module
  • 6. Disarm the guard or reach an original
  • 7. Mutate the rules
  • 8. Attack the IPC channel
  • 9. Poison learning mode
• Guards that are inert by design
• Residual limits — denial of service
• Reproducing the assessment

Every row is marked demonstrated (pinned by an executed test) or reasoned (established from the source, not run as an isolated payload).

Nothing is enforced until lifecycle.arm() flips a module global (_armed, set in lifecycle.arm(), read by lifecycle.is_armed()). Framework code runs disarmed; user code runs armed. lifecycle is the single owner of that state: guard_api reads it through the _lc_is_armed alias (see objective 6), and guard_socket's _rules_loaded flag tracks a different concept.

The wrappers short-circuit when disarmed — guard_api's control point returns the raw function if not _lc_is_armed() (guard_api._wrap_guarded). This is by design, but it also means the arming flag is a single point whose reset disarms everything; see objective 6.

The canonicalization is itself re-entrant-safe: _safe_realpath calls os.lstat/os.readlink, which are patched, so a _canonicalizing context var suppresses the inner re-check — it is read at the head of _apply_dest_to_src_rules. The path returned to the syscall stays unresolved, so link semantics are preserved; only the decision uses the resolved path.

These are the defining limits of a patch-based layer, not defects to be fixed in it. They are why the OS sandbox exists.

The main process talks to the sandboxed child over SSE, on local HTTP.

This objective is not in weaknesses.md and is specific to the project's design, so it is stated in full.

In learning mode the verified guards do not enforce: they record the attempt and then let the real operation proceed. For example, the sensitive-call wrapper calls the real function anyway (guard_api._wrap_guarded), and the file and import guards record instead of raising (guard_files._apply_dest_to_src_rules, guard_import.GuardFinder.find_spec). Every observed file, socket, import, env and call is serialized verbatim into the next run's profile (learning.generate_config_from_learning), with no validation of whether the behavior was legitimate.

Consequence: hostile code run under learning mode both executes unguarded and writes its own permissions into the whitelist the next run trusts.

One subject, pickle, is covered only in part, by design. It is not a discovered vulnerability -- do not report it as an escape.

• Pickle deserialization is covered only in part, by design. pickle.Unpickler is _pickle.Unpickler, an immutable C type, so neither its __init__ nor its load can be patched. Rebinding the module name to a function would break the subclassing a restricted unpickler needs: this is the same shape as ctypes.pythonapi. Unpickler(fp).load() therefore stays reachable, pinned as test_guard_api.py::test_the_unpickler_route_is_guarded (xfail).

  What is covered runs through guard_api: pickle.loads, pickle.load and their _pickle twins are registry entries under the deserialization category, denied by default like every other sensitive call and grantable with python-api=ALLOW:deserialization (warned at load, as dynamic-code is). A pickle stream is a program: its opcodes name a callable and call it, which reaches os.system without an import and without a source string the eval-* layer could parse. Pinned end to end by test_guard_api.py::test_pickle_loads_and_its_twin_are_refused_end_to_end.

  Like the rest of this layer, that denies the call from cooperative code and gives learning-mode visibility. It is not a barrier against hostile bytecode, which reaches os.system by a hundred other routes; the OS sandbox is the barrier for that class. test_escape_with_pickle_blocked stays xfail: removing pickle from sys.modules blocks nothing.

  The only untrusted data this package unpickles is the child's result and exception payloads, rebuilt in the trusted parent by remote/base_sse_daemon._rebuild_remote_exception and the result branch of the same module's event dispatch. A crafted payload would be arbitrary code execution in the host process, outside the sandbox. Both child->parent sites therefore go through remote/tools.py::from_b85_restricted, in two steps. First, an opcode prescan (allowlist by family plus anti-DoS budgets). Then, a find_class that triggers no import from the stream and vets each global:

  • the exception channel is fail-closed (Exception subclasses, tblib, base data types);
  • the result channel is a fail-open denylist of dangerous gadgets keyed by every C-twin (posix.system, _socket.socket);
  • a shape check runs on tblib.Traceback before as_traceback().

  The result guard is toggled by remote-result-guard (default on). Being fail-open, it raises the cost of a gadget on return values rather than closing the class; the exception guard is fail-closed. Because an exception's state routinely holds a type that guard refuses (httpx.Request, a Path, an application object), the child also sends a descriptor of the exception — class, message, denials, all primitives — and the parent falls back to it when the rich form is refused, rather than losing the refusal itself. An exception crossing that way arrives without its attributes. The transport binds pickle.dumps/pickle.loads at import so the framework's own serialization is not charged to the user's profile, and the registry does not cover this call. See transport-unpickle-guard.md. parent->child (args/kwargs) stays on the raw from_b85: there the trust runs the other way.

These match the package's stated position: the Python layer raises cost and adds visibility; the OS sandbox is the barrier.

Exhausting CPU, memory or file descriptors is out of scope for this layer, by the same reasoning as the eval-* report: a patch on a Python function cannot bound native resource use. The OS sandbox (cgroups, ulimit, the VM providers) owns denial of service.

# blocked escapes (pinned as passing) + known-open escapes (pinned as xfail)
uv run pytest tests/unit_tests/test_escape_pysandbox.py \
              tests/unit_tests/guard/test_guard_escape_fixes.py -v

# the per-guard enforcement corpus grounding the "blocked" rows
uv run pytest tests/unit_tests/guard/test_guard_api.py \
              tests/unit_tests/guard/test_guard_import.py \
              tests/unit_tests/guard/test_guard_socket.py \
              tests/unit_tests/guard/test_guard_os.py \
              tests/unit_tests/test_learning.py -v

# the dir_fd and descriptor rows of objective 1
uv run pytest tests/unit_tests/guard/test_guard_files_coverage.py \
              tests/unit_tests/guard/test_guard_shutil.py -v -k "dir_fd or descriptor or rmtree"

The three xfail entries of the escape files are the open escapes: test_escape_with_subclasses (objective 6), test_escape_with_globals_introspection (objective 4), and test_escape_with_pickle_blocked (the pickle entry of inert guards). Tampering with sys.meta_path, a hostile pickle and a name built at run time are not among them: the import audit hook puts the finder back at the head once it is unhooked or overtaken, as test_tampering_with_meta_path_leaves_the_next_import_guarded shows. Once armed, guard_api refuses pickle.loads and the call a built name reaches, as test_a_hostile_pickle_is_refused_once_armed and test_a_name_built_at_run_time_is_refused_at_the_call show. The corpus xfail is test_guard_api.py::test_the_unpickler_route_is_guarded, which records that pickle.Unpickler is an immutable C type. All are strict=True, so if any is ever closed, the XPASS fails the suite and this page must change with it.

Bottom line: the Python layer denies every sensitive operation from cooperative code and pins each denial to a test. Against hostile bytecode, it only raises cost and provides learning-mode visibility: the class-hierarchy walk, the wrappers' closure originals, ctypes.pythonapi, pickle, and the arming flag remain reachable by design. Containing those is the OS sandbox's role, stated plainly rather than papered over.

• Treat the Python layer as a guardrail for code that is wrong, not hostile. Against code written to break out, use a kernel provider.
• Never use learning mode with untrusted code: it executes unguarded and writes its own permissions into the whitelist.
• Review every generated profile before trusting it. That review is the only barrier.
• Grant python-api=ALLOW:deserialization only when a trusted payload requires it.
• Leave remote-result-guard on, and rely on the OS sandbox for denial of service.

• Security assessment of the eval-* guard
• Transport unpickle guard, weaknesses, implementation
• Kernel providers: landlock, bwrap, firejail, unshare, qemu