Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: gate tool file access outside the session sandbox (#10907)

Daniel Hana76c38c4ab49
diff --git a/studio/backend/core/inference/tool_path_approval.py b/studio/backend/core/inference/tool_path_approval.py
new file mode 100644
index 00000000000..54eff400935
--- /dev/null
+++ b/studio/backend/core/inference/tool_path_approval.py
@@ -0,0 +1,3312 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Approval decisions for file access that leaves the session sandbox.
+
+Split out of ``tools.py`` because it is a subsystem rather than a handful of helpers: the read and
+write silent roots, the shared ``_path_needs_approval`` predicate, and the two operand scanners that
+decide which tokens of a terminal command or which arguments of a python snippet are paths at all.
+
+The import between this module and ``tools`` runs both ways, so both sides bind the MODULE rather
+than its names and resolve attributes at call time. That is what keeps the cycle harmless whichever
+module is imported first.
+"""
+
+import ast
+import fnmatch
+import functools
+import os
+import re
+import shlex
+import sys
+import time
+import urllib.parse
+
+# Names this module borrows from `tools`. They are BOUND at the bottom of `tools` rather than
+# imported here, because the two modules import each other and a from-import would run before the
+# other side finished. The list is explicit so the boundary is visible rather than ambient.
+_BORROWED = (
+ "_ARCHIVE_CTOR_NAMES",
+ "_AUTO_SAFE_WRAPPERS",
+ "_AUTO_UNSAFE_PY_WRITE_METHODS",
+ "_GLOB_META_RE",
+ "_MAX_PATH_SCAN_CHARS",
+ "_PATH_CTORS",
+ "_REDIR_PREFIX_RE",
+ "_SANDBOX_SITE_DIR",
+ "_WIN_DRIVE_RE",
+ "_WRAPPER_VALUE_FLAGS_BY_CMD",
+ "_folded_path",
+ "_glob_token_sensitive",
+ "_has_kwarg_splat",
+ "_legacy_sandbox_root",
+ "_mode_arg_writes",
+ "_parse_python",
+ "_posix_join",
+ "_references_sensitive_path",
+ "_token_command_base",
+ "_tree_nodes",
+ "current_account_id",
+ "sandbox_root",
+)
+
+
+def _bind(namespace) -> None:
+ """Bind the borrowed names from `tools`, once, at the end of its import.
+
+ Two of the tables here EXTEND a table that lives in `tools`, and a module-level union would run
+ before that module finished. They are completed here instead, along with the union derived from
+ them, so the tables are whole before the first classification.
+ """
+ globals().update({name: namespace[name] for name in _BORROWED if name in namespace})
+ global _PY_PATH_WRITE_CALLS, _PY_PATH_ARCHIVE_CTORS, _PY_ALIASABLE_PATH_CALLS
+ _PY_PATH_WRITE_CALLS = _PY_PATH_WRITE_CALLS | frozenset(
+ namespace.get("_AUTO_UNSAFE_PY_WRITE_METHODS", ())
+ )
+ _PY_PATH_ARCHIVE_CTORS = _PY_PATH_ARCHIVE_CTORS | frozenset(
+ namespace.get("_ARCHIVE_CTOR_NAMES", ())
+ )
+ _PY_ALIASABLE_PATH_CALLS = (
+ frozenset({"open", "fdopen"})
+ | _PY_PATH_READ_CALLS
+ | _PY_PATH_WRITE_CALLS
+ | _PY_PATH_DEST_SECOND_CALLS
+ | _PY_PATH_SERIALIZE_CALLS
+ | _PY_PATH_CONTENT_FIRST_CALLS
+ | _PY_PATH_ARCHIVE_CTORS
+ | _PY_PATH_SUBPROCESS_CALLS
+ )
+
+
+# The tool child runs unconfined for the installation owner (account_confinement returns None there), so the session
+# sandbox is a working DIRECTORY, not a boundary: an absolute path in a tool call reaches the real filesystem with the
+# user's own permissions. A RELATIVE path resolves inside that workdir, so it stays silent and ordinary in-sandbox work
+# is untouched; an absolute path outside the roots below is the host's own data, and auto mode asks before it is read
+# or written.
+_SYSTEM_READ_SILENT_ROOTS = (
+ # Installed software and kernel interfaces. Reading these is how a tool learns about the machine; the credential
+ # checks run FIRST, so /etc/shadow and friends still ask despite /etc being here.
+ "/usr",
+ "/bin",
+ "/sbin",
+ "/lib",
+ "/lib32",
+ "/lib64",
+ "/opt",
+ "/snap",
+ "/nix",
+ "/etc",
+ "/var/lib",
+ "/proc",
+ "/sys",
+ "/dev",
+ # Runtime state (pid files, sockets). /run/secrets and /run/credentials are covered by the credential check that
+ # runs first. Mirrors tool_confinement._SYSTEM_READ_ROOTS.
+ "/run",
+ # The same directory under its older name. On Linux it is a symlink to /run; on macOS it is the
+ # REAL location (/private/var/run), and `/etc/resolv.conf` is a link into it, so resolving the
+ # candidate landed outside every root and an ordinary `grep nameserver /etc/resolv.conf` asked.
+ "/var/run",
+ # macOS
+ "/System",
+ "/Library",
+ "/Applications",
+ # Windows
+ "C:\\Windows",
+ "C:\\Program Files",
+ "C:\\Program Files (x86)",
+ "C:\\ProgramData",
+)
+
+
+# Carved OUT of the system roots above: these are tmpfs the user's own processes own, so their
+# contents are user data rather than machine state, and `/dev` and `/run` being read-silent must not
+# reach them. Normalized at module level because the roots they sit under are literals too.
+_WRITABLE_RUNTIME_SUBTREES = tuple(
+ os.path.normcase(part)
+ # `/dev/fd/<n>` is the same kernel link `/proc/self/fd/<n>` is, and it reaches whatever the
+ # descriptor was opened on, so it is no more a property of /dev than the /proc spellings are.
+ for part in ("/dev/shm", "/dev/mqueue", "/dev/fd", "/run/user", "/run/lock")
+)
+
+
+# Pseudo-devices a command legitimately writes to (`2> /dev/null`); the rest of /dev is read-silent but not
+# write-silent.
+_WRITE_SILENT_DEVICE_NODES = (
+ "/dev/null",
+ "/dev/zero",
+ "/dev/stdout",
+ "/dev/stderr",
+ "/dev/tty",
+ "/dev/full",
+)
+
+
+# Roots are resolved from settings and a sqlite table, so they are cached rather than rebuilt per token. A stale entry
+# only ever costs (or spares) one approval prompt, so a short TTL beats invalidation plumbing.
+_SILENT_ROOT_TTL_S = 60.0
+
+
+_silent_roots_cache = None
+
+
+def _normalized_fs_text(text: str) -> str:
+ """Fold a path to the form root containment compares against: `~` expanded, separators
+ canonical, `.`/`..` collapsed, case-folded where the platform is case-insensitive."""
+ if os.sep != "/":
+ text = text.replace("/", os.sep)
+ if text[:1] == "~":
+ try:
+ text = os.path.expanduser(text)
+ except Exception: # noqa: BLE001 - a broken HOME must not break classification
+ pass
+ return os.path.normcase(os.path.normpath(text)).rstrip(os.sep) or os.sep
+
+
+def _silent_root_list(producers) -> "tuple[str, ...]":
+ """Normalize each producer's paths, skipping any that raises: a root that cannot be resolved
+ (a retired account, an unset studio home) must narrow the allowlist, never crash the scan."""
+ roots: "list[str]" = []
+ for producer in producers:
+ try:
+ value = producer()
+ except Exception: # noqa: BLE001 - every root is best effort
+ continue
+ if value is None:
+ continue
+ items = value if isinstance(value, (list, tuple, set)) else (value,)
+ for item in items:
+ if not item:
+ continue
+ try:
+ root = _normalized_fs_text(str(item))
+ except Exception: # noqa: BLE001
+ continue
+ # "/" would make every path silent, so a root that folds to the filesystem root is dropped.
+ if root and root != os.sep and root not in roots:
+ roots.append(root)
+ return tuple(roots)
+
+
+def _excluding_ancestors_of_studio_home(roots) -> "tuple[str, ...]":
+ """Drop any root that is the studio home or contains it.
+
+ ``studio.db`` (chat history, provider and MCP configuration) and ``auth/`` live directly in that
+ directory, so a root reaching it hands a tool all of Studio's own state.
+ """
+ from utils.paths.storage_roots import studio_root
+
+ try:
+ home = _normalized_fs_text(str(studio_root()))
+ except Exception: # noqa: BLE001 - an unresolvable home means nothing to protect against here
+ return tuple(roots)
+ return tuple(root for root in roots if not (home == root or home.startswith(root + os.sep)))
+
+
+def _build_silent_roots() -> "tuple[tuple[str, ...], tuple[str, ...]]":
+ """(read-silent, write-silent) roots. Write-silent is the narrower set: where tool output
+ ordinarily lands. Read-silent adds installed software and the model libraries the user pointed
+ Studio at, which a tool reads all the time and which carry no user documents."""
+ from utils.paths.storage_roots import (
+ cache_root,
+ project_workspaces_root,
+ shared_project_workspaces_root,
+ shared_tmp_root,
+ tmp_root,
+ well_known_model_dirs,
+ )
+
+ # Only the OUTPUT subdirectories are silent, never the studio home itself. studio_root() holds studio.db (chat
+ # history, provider and MCP configuration) and auth/ alongside them, and in the default layout
+ # shared_sandbox_root() resolves to that same directory, so granting either one would hand a tool everything
+ # Studio owns -- which is the opposite of what this gate is for.
+ write_roots = _silent_root_list(
+ (
+ sandbox_root,
+ _legacy_sandbox_root,
+ tmp_root,
+ # Not the SHARED bases: `shared_project_workspaces_root()` is the ancestor of every
+ # account's `Accounts/<id>/Projects`, and `shared_tmp_root()` of every account's tmp,
+ # so allowlisting either hands the owner (who gets no OS confinement) another account's
+ # private data. The owner's own `tmp_root()` IS the shared base, so nothing is lost.
+ project_workspaces_root,
+ cache_root,
+ # Studio downloads models into these itself, so a tool that fetches one must not need approval for the
+ # cache write. Credential files inside them (token, stored_tokens) are caught by the sensitive-path check.
+ lambda: _hf_cache_dirs(),
+ lambda: _WRITE_SILENT_DEVICE_NODES,
+ )
+ )
+ # Several of those producers fall back to the studio home when their own subdirectory is not configured
+ # (tmp_root and shared_sandbox_root both do in the default layout), and one such fallback silently grants
+ # everything Studio owns. Drop any root that IS the studio home or an ancestor of it; the narrow
+ # subdirectories under it are kept, so this cannot be defeated by adding another producer later.
+ write_roots = _excluding_ancestors_of_studio_home(write_roots)
+ read_roots = write_roots + _excluding_ancestors_of_studio_home(
+ _silent_root_list(
+ (
+ lambda: _SYSTEM_READ_SILENT_ROOTS,
+ # The interpreter, its stdlib and site-packages: a tool reads these to introspect its own environment.
+ lambda: (
+ sys.prefix,
+ sys.base_prefix,
+ sys.exec_prefix,
+ getattr(sys, "base_exec_prefix", ""),
+ os.path.dirname(sys.executable),
+ os.environ.get("VIRTUAL_ENV", ""),
+ _SANDBOX_SITE_DIR,
+ ),
+ # Model folders the user registered with Studio, plus the well-known LM Studio / Ollama locations. These
+ # hold weights, not documents, and reading them is the point of the app.
+ _scan_folder_roots,
+ well_known_model_dirs,
+ )
+ )
+ )
+ return read_roots, write_roots
+
+
+def _hf_cache_dirs() -> "tuple[str, ...]":
+ """The HF cache locations, including one the owner configured in the UI.
+
+ Skipped entirely when the database does not exist yet, for the same reason the scan folders are:
+ the configured value is read through `get_app_setting`, which opens `studio.db`, and a
+ classification must not be what creates it. The environment and default locations still resolve,
+ so a first run keeps the caches it actually has.
+ """
+ from utils.hf_cache_settings import known_hf_cache_homes, known_hf_hub_caches
+
+ if not _studio_db_exists():
+ from utils.hf_cache_settings import get_hf_cache_paths
+ try:
+ paths = get_hf_cache_paths()
+ except Exception: # noqa: BLE001 - best effort, as every root here is
+ return ()
+ return tuple(str(p) for p in (paths.cache_home, paths.hub_cache, paths.xet_cache) if p)
+ return tuple(str(p) for p in (*known_hf_cache_homes(), *known_hf_hub_caches()))
+
+
+_studio_db_path_cache: "tuple | None" = None
+
+
+def _studio_db_path_for(identity) -> "str | None":
+ """`studio.db`'s path, memoized on the account and environment the roots cache is keyed on.
+
+ `studio_db_path()` re-resolves the studio root on every call, which measured at ~28us here and
+ was most of the cost of VALIDATING an already cached root set. The memo key is the same one the
+ roots cache uses, so a changed home still re-resolves; only the repeated lookup is saved.
+ """
+ global _studio_db_path_cache
+ cached = _studio_db_path_cache
+ if cached is not None and cached[0] == identity:
+ return cached[1]
+ from storage.studio_db import studio_db_path
+
+ try:
+ path = str(studio_db_path())
+ except Exception: # noqa: BLE001 - an unresolvable path is no database
+ path = None
+ _studio_db_path_cache = (identity, path)
+ return path
+
+
+def _studio_db_revision(identity = ()) -> int:
+ """The database's modification time, or 0 when there is none. Changes whenever a root that is
+ stored in it does.
+
+ The write-ahead log counts too: the server runs a WAL keeper, so a committed change to a scan
+ folder or a cache setting lands in `studio.db-wal` and leaves the main file's mtime alone. Read
+ on its own, a revoked folder stayed read-silent until the TTL expired.
+ """
+ path = _studio_db_path_for(identity)
+ if path is None:
+ return 0
+ try:
+ revision = os.stat(path).st_mtime_ns
+ except Exception: # noqa: BLE001 - no database is a stable revision of its own
+ return 0
+ try:
+ wal = os.stat(f"{path}-wal")
+ # Size as well as mtime: a commit within the same mtime granularity still grows the log.
+ revision ^= wal.st_mtime_ns ^ wal.st_size
+ except Exception: # noqa: BLE001 - no WAL is simply no extra revision
+ pass
+ return revision
+
+
+def _studio_db_exists() -> bool:
+ """Whether `studio.db` is already there.
+
+ Opening it CREATES it and initialises 27 tables, so any root that reads a stored setting has to
+ ask this first: on a first run the very first tool call would otherwise create the database as a
+ side effect of deciding whether to ask about a path.
+ """
+ from storage.studio_db import studio_db_path
+ try:
+ return studio_db_path().exists()
+ except Exception: # noqa: BLE001 - an unresolvable path is no stored setting either
+ return False
+
+
+def _scan_folder_roots() -> "tuple[str, ...]":
+ """Model folders the owner added in the UI. Read from the same table the model browser uses.
+
+ Only when the database already EXISTS. Opening it creates the file and initialises the schema,
+ and a classification is not a reason for that to happen: on a first run the very first tool call
+ would have created `studio.db` as a side effect of deciding whether to ask about a path. No
+ database means no folders were ever registered, which is the same answer an empty table gives.
+ """
+ from storage.studio_db import list_scan_folders
+
+ if not _studio_db_exists():
+ return ()
+ return tuple(str(row.get("path") or "") for row in list_scan_folders())
+
+
+# Environment that relocates a root. The cache key carries it, so repointing the studio home or a cache mid-process
+# takes effect at once instead of serving the previous install's roots for up to the TTL. Reading a few env vars is
+# nanoseconds; re-resolving the roots is milliseconds, which is why the TTL exists at all.
+_SILENT_ROOT_ENV_KEYS = (
+ "UNSLOTH_STUDIO_HOME",
+ # The alias the resolver accepts alongside it, and the other variables that MOVE a root. Keyed
+ # on one of a pair only, changing the other left the previous install's roots live until the TTL.
+ "STUDIO_HOME",
+ "UNSLOTH_STUDIO_PROJECTS_HOME",
+ "UNSLOTH_STUDIO_DOCUMENTS_HOME",
+ "OLLAMA_MODELS",
+ "UNSLOTH_STUDIO_SANDBOX_HOME",
+ "HF_HOME",
+ "HF_HUB_CACHE",
+ "HUGGINGFACE_HUB_CACHE",
+ "XDG_CACHE_HOME",
+ "VIRTUAL_ENV",
+)
+
+
+def _silent_roots() -> "tuple[tuple[str, ...], tuple[str, ...]]":
+ global _silent_roots_cache
+ try:
+ account = current_account_id() or ""
+ except Exception: # noqa: BLE001
+ account = ""
+ # The database's mtime too: registered scan folders and the configured cache root live in it, so
+ # removing a folder revoked a root that stayed silent for up to the TTL otherwise.
+ identity = (account, tuple(os.environ.get(k) for k in _SILENT_ROOT_ENV_KEYS))
+ account = identity + (_studio_db_revision(identity),)
+ now = time.monotonic()
+ cached = _silent_roots_cache
+ if cached is not None and cached[1] == account and now - cached[0] < _SILENT_ROOT_TTL_S:
+ return cached[2], cached[3]
+ try:
+ read_roots, write_roots = _build_silent_roots()
+ except Exception: # noqa: BLE001 - no allowlist is the fail-closed direction (more prompts)
+ read_roots, write_roots = (), ()
+ _silent_roots_cache = (now, account, read_roots, write_roots)
+ return read_roots, write_roots
+
+
+def _looks_absolute(text: str) -> bool:
+ """True for a path that reaches the real filesystem rather than the session workdir: POSIX
+ absolute, `~`-rooted, a Windows drive path, or a UNC share. Windows spellings count on every
+ platform, since misjudging one only costs a prompt."""
+ if not text:
+ return False
+ if text[0] == "/":
+ return True
+ # A local `file:` URI is an absolute reference spelled with a scheme, so the operand scanners
+ # have to keep it rather than dropping it as a relative name.
+ if text[:5].lower() == "file:":
+ uri_path = _file_uri_path(text)
+ return bool(uri_path) and _looks_absolute(uri_path)
+ if text[0] == "~":
+ # A PLAIN `~` is the sandbox: `_build_safe_env` and `_build_bypass_env` both set the child's
+ # HOME to the tool workdir, so the shell and `expanduser` alike resolve `~/notes.txt` to a
+ # file inside the session. `~alice` still names a host account, so it stays absolute.
+ return not (len(text) == 1 or text[1] in "/\\")
+ # A single leading backslash is root-relative on Windows (it resolves from the current drive's root), not a
+ # sandbox-relative name, so it counts alongside the UNC `\\server\share` form.
+ if text[0] == "\\":
+ return True
+ # `C:notes.txt` is DRIVE-relative: it resolves against drive C's own current directory, which is
+ # not the session workdir, so it reaches the real filesystem as much as `C:\notes.txt` does.
+ return bool(_WIN_DRIVE_RE.match(text) or _WIN_DRIVE_RELATIVE_RE.match(text))
+
+
+# `C:notes.txt`, with no separator: the drive's own current directory, not this one.
+# Anchored at both ends and single-colon, so a shell expansion like `${p:0:3}` (which folds to
+# `p:0:3`) is not read as a path on drive P.
+_WIN_DRIVE_RELATIVE_RE = re.compile(r"^[A-Za-z]:(?![\\/:])[^:\s]+$")
+
+
+# The kernel symlinks under /proc that reach outside /proc: `root` is the process's root directory,
+# `cwd` its working directory, `fd/<n>` an open file. The shell's own PID spellings resolve to a
+# number before the path is opened, so they name the same links a literal number does.
+_PROC_ID_RE = r"(?:self|thread-self|\d+|\$\$|\$\{?BASHPID\}?|\$\{?PPID\}?)"
+# `/proc/<pid>/task/<tid>/root` resolves through the same kernel link the process-level spelling
+# does, so the task level is matched too.
+_PROC_MAGIC_LINK_RE = re.compile(
+ rf"/proc/{_PROC_ID_RE}/(?:task/{_PROC_ID_RE}/)?(?:root|cwd|fd)(?:/|$)"
+)
+
+
+# A local `file:` URI, in the spellings sqlite3 and the stdlib accept: `file:/p`, `file:///p` and
+# `file://localhost/p`. A host other than localhost is a remote resource, not a path here.
+_FILE_URI_RE = re.compile(r"^file://(?:localhost)?(?=/)|^file:(?=/)", re.IGNORECASE)
+
+
+def _contained_in(candidate: str, roots) -> bool:
+ """Component-boundary containment, never a raw prefix test."""
+ return any(candidate == root or candidate.startswith(root + os.sep) for root in roots)
+
+
+def _resolved_fs_text(text: str) -> str:
+ """*text* with its symlinked components resolved, folded the way the roots are."""
+ try:
+ return _normalized_fs_text(os.path.realpath(text))
+ except Exception: # noqa: BLE001 - an unresolvable path keeps the lexical answer
+ return text
+
+
+def _file_uri_path(text: str) -> "str | None":
+ """The filesystem path a local `file:` URI names, or None if *text* is not one.
+
+ `sqlite3.connect("file:/media/alice/private.db?mode=ro", uri = True)` opens the same database the
+ bare path does, but the scheme made it read as a relative name and the read went silent. The
+ query and fragment are the URI's own, not part of the path, and `%XX` is decoded because the OS
+ sees the decoded form.
+ """
+ if not _FILE_URI_RE.match(text):
+ return None
+ path = _FILE_URI_RE.sub("", text, count = 1)
+ for separator in ("?", "#"):
+ cut = path.find(separator)
+ if cut != -1:
+ path = path[:cut]
+ if "%" in path:
+ try:
+ path = urllib.parse.unquote(path)
+ except Exception: # noqa: BLE001 - a malformed escape must not break classification
+ pass
+ return path or None
+
+
+def _names_a_managed_account_subtree(candidate: str) -> bool:
+ """Whether *candidate* descends into a per-account directory of a managed install."""
+ parts = candidate.replace("\\", "/").lower().split("/")
+ return any(part == "accounts" and index + 1 < len(parts) for index, part in enumerate(parts))
+
+
+def _path_needs_approval(text, *, writing: bool = False) -> bool:
+ """True when reading (or, with ``writing``, creating/overwriting) this path leaves the sandbox
+ for the user's own filesystem.
+
+ Order matters: the credential checks run first, so the allowlist below can never turn
+ ``/etc/shadow`` or ``~/.ssh/id_rsa`` into a silent read just because ``/etc`` is read-silent.
+ A relative path stays silent -- it resolves inside the per-session workdir.
+ """
+ if not isinstance(text, str) or not text.strip():
+ return False
+ text = text.strip()
+ if len(text) > _MAX_PATH_SCAN_CHARS:
+ return True
+ # \x02 marks a pathlib .parent walking OUT of its root (see _folded_path). It is an escape marker, so it asks;
+ # treating it like the unresolved marker would turn the signal into a pass.
+ if "\x02" in text:
+ return True
+ # \x00 is a segment the folder could not resolve, which is not a decidable path.
+ if "\x00" in text:
+ return False
+ # A `file:` URI names the same file the bare path does, so it is classified as that path.
+ uri_path = _file_uri_path(text)
+ if uri_path is not None:
+ return _path_needs_approval(uri_path, writing = writing)
+ if not _looks_absolute(text):
+ # Relative: resolves inside the session workdir. Only the credential/traversal scan applies.
+ return bool(_references_sensitive_path(text) or _glob_token_sensitive(text))
+ try:
+ candidate = _normalized_fs_text(text)
+ except Exception: # noqa: BLE001
+ return True
+ # The filesystem root ITSELF, which no silent root can cover (`_silent_root_list` drops a root
+ # that folds to `os.sep`, or everything would be silent). Reading it yields the top-level names
+ # and nothing else, so `ls /` asked for approval while `ls /usr` did not. Exact match only:
+ # anything UNDER it is still decided by the roots below.
+ if not writing and candidate == os.sep:
+ return False
+ # `/proc/<pid>/root`, `/cwd` and `/fd/<n>` are kernel magic symlinks: the kernel resolves them
+ # before anything that follows, so `/proc/self/root/home/alice/report.txt` opens the very file
+ # `/home/alice/report.txt` does while reading, lexically, as an ordinary `/proc` path. `/proc` is
+ # read-silent, so containment on the text alone let the whole filesystem in through it.
+ if _PROC_MAGIC_LINK_RE.match(candidate.replace(os.sep, "/")):
+ return True
+ # A writable subtree of an otherwise system root. `/dev/shm` and `/run/user/<uid>` are tmpfs the
+ # user's own processes write into, so a read there is a read of somebody's data, not of the
+ # machine's configuration. Checked before containment, so the enclosing root cannot cover them.
+ if any(
+ candidate == root or candidate.startswith(root + os.sep)
+ for root in _WRITABLE_RUNTIME_SUBTREES
+ ):
+ return True
+ read_roots, write_roots = _silent_roots()
+ roots = write_roots if writing else read_roots
+ if not _contained_in(candidate, roots):
+ return True
+ # On a managed install the shared projects and tmp bases hold every account's own subtree, so a
+ # silent root can be an ANCESTOR of another account's private data. Their segment is never
+ # silent, whichever root it sits under.
+ if _names_a_managed_account_subtree(candidate):
+ return True
+ # Lexical containment is not enough on its own: a symlink INSIDE a silent root can resolve
+ # outside it, and the lexical answer would have allowed the read. Resolved only here, where the
+ # answer would otherwise be silence, so the stat is paid on the paths that are about to be
+ # allowed rather than on every token. A link planted between this and the open is not covered;
+ # that TOCTOU gap is the OS sandbox's to close.
+ resolved = _resolved_fs_text(candidate)
+ # Against the RESOLVED roots as well: a root that is itself a symlink (a sandbox under a
+ # macOS `/tmp`, `/dev/stdout`) would otherwise reject everything under it.
+ if resolved != candidate and not _contained_in(resolved, roots):
+ if not _contained_in(resolved, tuple(_resolved_fs_text(r) for r in roots)):
+ return True
+ # Inside a silent root, so only a credential underneath one still asks. Running the (superlinear) credential
+ # scan only here, rather than on every operand, keeps the ordering guarantee at a fraction of the cost:
+ # a path outside the roots already returned True, which is what the scan would have concluded anyway.
+ # The RESOLVED target as well: a link inside one silent root can point at a credential inside
+ # another (`/models/public -> $HF_HOME/token`), and the lexical name carries none of it.
+ if _credential_under_silent_root(candidate) or (
+ resolved != candidate and _credential_under_silent_root(resolved)
+ ):
+ return True
+ if resolved != candidate and _references_sensitive_path(resolved):
+ return True
+ return bool(_references_sensitive_path(text) or _glob_token_sensitive(text))
+
+
+# Secrets that live INSIDE a root this scan otherwise keeps silent. The name-based rules matter most for a cache
+# relocated off its default path: _SENSITIVE_PATH_RE recognises a token store by the "huggingface" directory in the
+# path, so HF_HOME=/media/hf-cache would hide one, and the whole cache root is allowlisted.
+_CREDENTIAL_BASENAMES = frozenset(
+ {
+ "token",
+ "stored_tokens",
+ "credentials",
+ "auth.db",
+ ".netrc",
+ "netrc",
+ ".git-credentials",
+ ".pypirc",
+ ".npmrc",
+ "id_rsa",
+ "id_ed25519",
+ "id_ecdsa",
+ "id_dsa",
+ }
+)
+
+
+# Files under a read-silent system root that _SENSITIVE_PATH_RE does not name.
+_CREDENTIAL_PATH_SUFFIXES = (
+ "/etc/gshadow",
+ "/etc/gshadow-",
+ "/etc/krb5.keytab",
+ "/etc/master.passwd",
+ "/etc/security/opasswd",
+ "/etc/ipsec.secrets",
+)
+
+
+def _credential_under_silent_root(candidate: str) -> bool:
+ """True for a secret sitting inside an otherwise silent root, so the allowlist cannot expose it."""
+ if os.path.basename(candidate) in _CREDENTIAL_BASENAMES:
+ return True
+ # Compared on a separator-unified copy: the candidate is normalised to the HOST separator, so on
+ # Windows `/etc/gshadow` arrived as `\\etc\\gshadow` and matched none of these. What a path text
+ # means must not depend on which machine classifies it.
+ unified = candidate.replace("\\", "/")
+ if any(unified.endswith(suffix) for suffix in _CREDENTIAL_PATH_SUFFIXES):
+ return True
+ # Studio's own identity database and key material live under <studio home>/auth.
+ return "/auth/" in unified + "/"
+
+
+# Commands whose file operands are READ. Deliberately narrow: only names whose operands are unambiguously paths, so a
+# command this scan does not model contributes nothing rather than a guess.
+# `zcat --help`: "Usage: zcat [OPTION]... [FILE]...", uncompressing each to stdout. The
+# whole family reads the file it is given exactly as `cat` does.
+# `iconv --help`: "Usage: iconv [OPTION...] [FILE...]", so a bare operand is a file it reads.
+# `help test`: "unary expressions ... are often used to examine the status of a file", and
+# the answer is existence, type, ownership and timestamps of whatever they are given.
+# Changing directory to an absolute path re-points every RELATIVE operand that follows it, which is how the
+# rest of this scan decides a command stays in the sandbox. `cd /usr/lib && ls` still stays silent.
+_PATH_READ_COMMANDS = frozenset(
+ """
+ cat zcat bzcat xzcat lzcat lz4cat zstdcat iconv test [ [[ tac head tail less more wc stat
+ file od xxd hexdump strings base64 b64encode md5 md5sum sha1sum sha224sum sha256sum
+ sha384sum sha512sum shasum cksum sum cut sort uniq nl rev column paste join comm expand
+ unexpand fold fmt jq yq diff cmp grep egrep fgrep rg ag ack ls dir du tree find fd readlink
+ realpath awk gawk mawk sed openssl xmllint csvlook type get-content gc tar 7z unrar cd pushd
+ """.split()
+)
+
+
+# Commands whose file operands are CREATED or OVERWRITTEN.
+_PATH_WRITE_COMMANDS = frozenset(
+ {
+ # A permission change MODIFIES the file's metadata, and the first operand is the mode or
+ # owner rather than a path, so it is skipped through `_PATH_ARG_SKIP`.
+ "chmod",
+ "chown",
+ "chgrp",
+ "tee",
+ "touch",
+ "mkdir",
+ "truncate",
+ "shred",
+ "zip",
+ # Each of these replaces its operand with the compressed or decompressed file.
+ "gzip",
+ "gunzip",
+ "bzip2",
+ "bunzip2",
+ "xz",
+ "unxz",
+ "zstd",
+ }
+)
+# `gzip --help`: "-c, --stdout write on standard output, keep original files unchanged". In that
+# mode the operand is only READ, so it belongs against the wider read roots.
+_STDOUT_COMPRESSORS = frozenset({"gzip", "gunzip", "bzip2", "bunzip2", "xz", "unxz", "zstd"})
+_STDOUT_FLAGS = frozenset({"-c", "--stdout", "--to-stdout"})
+
+
+# Copy-like commands: the LAST operand is the destination (a write), the earlier ones are sources (reads).
+_PATH_DEST_LAST_COMMANDS = frozenset({"cp", "mv", "install", "ln", "rsync"})
+
+
+# `zip -h`: "zip [options] [zipfile list]", so the FIRST positional is the archive being written and
+# every later one is a source it reads. Scoring them all as writes prompted on archiving anything
+# out of a read-silent root. `-m` deletes the sources after adding them, which makes them writes.
+_PATH_DEST_FIRST_COMMANDS = frozenset({"zip"})
+
+
+# Commands whose SOURCE operand is checked as a write. `mv --help`: "Rename SOURCE to DEST", so the
+# source is gone afterwards. `ln` does not remove its target, but it hands the sandbox a name that
+# WRITES to it: after `ln -s /scan/model.gguf local`, an ordinary relative write through `local`
+# lands outside. `cp` and `rsync` read theirs and leave them alone.
+_PATH_SOURCE_MUTATING_COMMANDS = frozenset({"mv", "ln"})
+
+
+# Interpreters and clients whose operands are files they LOAD. `python /media/private/job.py` reads
+# that file and runs it, which is strictly more than `cat` of the same path, yet the command was in
+# no table so every operand was dropped. Treated as reads, since that is what decides the prompt;
+# whether the loaded program then writes is not knowable here.
+# `awk` and `jq` are deliberately absent: their first positional is a PROGRAM, and a script that
+# starts with a slash (`awk '/^\/usr/ {print}'`) would read as an absolute path.
+# `unzip` READS its archive; the extraction destination is a flag (`-d`) handled above.
+_PATH_SCRIPT_COMMANDS = frozenset(
+ """
+ python python2 python3 py perl bash sh zsh ksh dash fish csh tcsh source ruby node deno bun
+ php lua luajit julia rscript duckdb curl wget date unzip
+ """.split()
+)
+
+
+# `git` carries its paths on flags rather than in operand position, so it only needs the flag spec
+# below; listing it here would read a subcommand name as a path.
+# jq is here rather than among the readers because its POSITIONAL is a filter, not a path: only the
+# values of its flags name files.
+_PATH_FLAG_ONLY_COMMANDS = frozenset("git make jq gcc g++ cc c++ clang clang++".split())
+
+
+# Commands whose first positional is a PROGRAM or PATTERN, not a file: `sed '/etc/d' notes.txt` and
+# `grep /usr/bin list.txt` must not read as absolute-path operands. The value is how many positionals to skip.
+_PATH_ARG_SKIP = {
+ "chmod": 1,
+ "chown": 1,
+ "chgrp": 1,
+ "sed": 1,
+ "awk": 1,
+ "gawk": 1,
+ "mawk": 1,
+ "jq": 1,
+ "yq": 1,
+ "grep": 1,
+ "egrep": 1,
+ "fgrep": 1,
+ "rg": 1,
+ "ag": 1,
+ "ack": 1,
+ "tar": 1,
+ "openssl": 1,
+ "xargs": 1,
+}
+
+
+# Commands whose skipped positional is a LEGACY OPTION WORD, which GNU tar only recognises as the
+# very first argument (`tar cf out.tar src`). Skipping unconditionally eats a real operand from the
+# ordinary hyphenated spelling: in `tar -cf local.tar /media/private`, `-cf` and its archive value
+# are already consumed as flags, so the skip would discard `/media/private` and the read would never
+# be classified. grep and sed are NOT in here: their skipped positional is a pattern, which is the
+# first POSITIONAL rather than the first argument, so their skip stays unconditional.
+_PATH_SKIP_FIRST_ARG_ONLY = frozenset({"tar"})
+
+
+# Long spellings of an archive command's create mode. The short forms are read letter by letter out
+# of the cluster; these carry the same meaning and are matched whole.
+# `tar --help`: `--delete` deletes members from the archive and `-A, --concatenate` appends other
+# archives to it, so both MUTATE the file `-f` names exactly as create, append and update do.
+_ARCHIVE_CREATE_LONG_FLAGS = frozenset(
+ {"--create", "--append", "--update", "--delete", "--concatenate", "--catenate"}
+)
+
+
+# The short spellings of the same three: create, append, update. All write the archive.
+_ARCHIVE_WRITE_SHORT_MODES = ("c", "r", "u", "A")
+# `7z --help`: the FIRST word is the command, and `a` adds to (creating or updating) an archive,
+# `u` updates and `d` deletes from it. The tar-style mode letters mean nothing here.
+_SEVENZIP_WRITE_COMMANDS = frozenset({"a", "u", "d", "rn"})
+
+
+# Flags that supply the pattern or program themselves. `_PATH_ARG_SKIP` spends a positional on it by
+# default, but `grep -f patterns.txt FILE` and `sed -e s/a/b/ FILE` already have theirs, so keeping
+# the skip would discard the first real input path and leave the read unclassified.
+_PATTERN_SUPPLYING_FLAGS = {
+ "grep": {"-f", "--file", "-e", "--regexp"},
+ "egrep": {"-f", "--file", "-e", "--regexp"},
+ "fgrep": {"-f", "--file", "-e", "--regexp"},
+ # `rg --files [PATH ...]` takes no pattern at all (`rg --help`: "rg [OPTIONS] --files [PATH ...]"),
+ # so the skip would spend the first positional and leave the enumerated tree unclassified.
+ "rg": {"-f", "--file", "-e", "--regexp", "--files"},
+ "ag": {"-f", "--file", "-e"},
+ "ack": {"-f", "--file"},
+ "sed": {"-f", "--file", "-e", "--expression"},
+ "awk": {"-f", "--file"},
+ "gawk": {"-f", "--file"},
+ "mawk": {"-f", "--file"},
+}
+
+
+# Module-level `open()` functions, whose path is the FIRST ARGUMENT even though the call is spelled
+# as an attribute. Contrast `Path(p).open()`, where the receiver is the path.
+# tarfile.open(name, mode) takes the path first like the rest; without it the module read as
+# a path-bearing receiver and the archive operand was never scanned.
+# `import builtins; builtins.open(p, "w")` is the builtin under a qualified name. Without it
+# the module itself read as the path and the real one was never added.
+# `from PIL import Image; Image.open(p)` is a module-level open taking the path first, so
+# without it the bare `Image` folded as the path and the file was never seen.
+_PY_MODULE_OPEN_RECEIVERS = frozenset(
+ """
+ io os posix gzip bz2 lzma codecs tokenize dbm shelve wave tarfile builtins __builtin__ PIL
+ Image
+ """.split()
+)
+
+
+# Receivers that are MODULES rather than paths, for every path-taking call, not only `open`. An
+# attribute call on one of these puts its paths in the ARGUMENTS: `os.rename(src, dst)` moves dst,
+# where `Path(src).rename(dst)` moves the receiver. Reading the receiver as a path on the module
+# form folds the bare module name and loses the real destination.
+_PY_MODULE_PATH_RECEIVERS = _PY_MODULE_OPEN_RECEIVERS | frozenset(
+ # pandas belongs here for the same reason numpy does: `pd.read_csv(path)` carries its path in the
+ # arguments, never as the receiver.
+ {
+ "shutil",
+ "pathlib",
+ "zipfile",
+ "json",
+ "pickle",
+ "numpy",
+ "np",
+ "torch",
+ "joblib",
+ "cv2",
+ "pandas",
+ "pd",
+ }
+)
+
+
+# `test`/`[` reach the filesystem ONLY through their file operators (`help test`); every other
+# operand is a string being compared. `[ "$d" != "/" ]` names no path at all.
+_TEST_COMMANDS = frozenset({"test", "[", "[["})
+_TEST_FILE_UNARY_FLAGS = frozenset(
+ """
+ -a -b -c -d -e -f -g -h -k -p -r -s -u -w -x -G -L -N -O -S
+ """.split()
+)
+_TEST_FILE_BINARY_OPS = frozenset({"-nt", "-ot", "-ef"})
+
+
+def _test_command_operands(args) -> "list[str]":
+ """The tokens `test`/`[` actually stat: the operand of a unary file test and both sides of
+ `-nt`/`-ot`/`-ef`."""
+ paths: "list[str]" = []
+ for index, arg in enumerate(args):
+ if arg in _TEST_FILE_UNARY_FLAGS:
+ if index + 1 < len(args):
+ paths.append(args[index + 1])
+ elif arg in _TEST_FILE_BINARY_OPS:
+ if index:
+ paths.append(args[index - 1])
+ if index + 1 < len(args):
+ paths.append(args[index + 1])
+ return paths
+
+
+# Commands that turn their INPUT into another command's arguments, so a path arrives from the pipeline rather than
+# from an operand position.
+_PATH_FORWARDING_COMMANDS = frozenset({"xargs", "parallel"})
+
+
[email protected]_cache(maxsize = 1)
+def _classified_terminal_commands() -> frozenset:
+ """Every command this scan can reason about, path-bearing or not.
+
+ Used by the subprocess fallback to tell "the child accesses no path" from "the child is a name
+ nothing here models". `_AUTO_SAFE_TERMINAL_COMMANDS` is the second half of that: `echo` and
+ `printf` take no path operand, and treating their arguments as paths asked for approval on a
+ child that the identical terminal command runs silently.
+ """
+ return frozenset(
+ _PATH_READ_COMMANDS
+ | _PATH_WRITE_COMMANDS
+ | _PATH_DEST_LAST_COMMANDS
+ | _PATH_SCRIPT_COMMANDS
+ | _PATH_FLAG_ONLY_COMMANDS
+ | _PATH_ARCHIVE_COMMANDS
+ | _PATH_FORWARDING_COMMANDS
+ | frozenset(_PATH_FLAG_SPECS)
+ | frozenset(_tools._AUTO_SAFE_TERMINAL_COMMANDS)
+ )
+
+
+# What a flag's VALUE is, per command. "read"/"write" mean the value is a path with that access; "skip" means the
+# value is data (a delimiter, a pattern, a count) and must be stepped over so it is never read as an operand --
+# `cut -d /` and `sort -t /` pass a slash as a field separator, not as the root directory. "archive" follows the
+# command's create/extract mode. A flag absent from a command's table does NOT consume the token after it, so an
+# unmodelled path-taking flag still gets seen as a positional.
+_PATH_FLAG_SPECS = {
+ "cp": {"-t": "write", "--target-directory": "write", "-S": "skip", "--suffix": "skip"},
+ "mv": {"-t": "write", "--target-directory": "write", "-S": "skip", "--suffix": "skip"},
+ # `iconv -o, --output=FILE` writes the converted text there; the rest name encodings, not paths.
+ "iconv": {
+ "-o": "write",
+ "--output": "write",
+ "-f": "skip",
+ "--from-code": "skip",
+ "-t": "skip",
+ "--to-code": "skip",
+ },
+ # `make --help`: `-f FILE` reads that makefile and `-C DIR` changes to that directory first, so
+ # both select what make reads and executes. The bare positionals are TARGETS, not paths.
+ "make": {
+ "-f": "read",
+ "--file": "read",
+ "--makefile": "read",
+ # `-C DIR` is where make RUNS, and a recipe writes there (`make -C /models clean`).
+ "-C": "write",
+ "--directory": "write",
+ "-j": "skip",
+ "--jobs": "skip",
+ "-l": "skip",
+ },
+ # `gcc --help`: `-o <file>` places the output there, truncating it. The positionals are source
+ # files, which the flag-only treatment leaves alone.
+ "gcc": {"-o": "write"},
+ "g++": {"-o": "write"},
+ "cc": {"-o": "write"},
+ "c++": {"-o": "write"},
+ "clang": {"-o": "write"},
+ "clang++": {"-o": "write"},
+ "install": {
+ "-t": "write",
+ "--target-directory": "write",
+ "-m": "skip",
+ "-g": "skip",
+ "-o": "skip",
+ },
+ "ln": {"-t": "write", "--target-directory": "write", "-S": "skip", "--suffix": "skip"},
+ "rsync": {"--exclude": "skip", "--exclude-from": "read", "--files-from": "read"},
+ "sort": {
+ "-o": "write",
+ "--output": "write",
+ "--files0-from": "read",
+ # `sort --help`: "get random bytes from FILE", read whenever -R is in play.
+ "--random-source": "read",
+ "-t": "skip",
+ "--field-separator": "skip",
+ "-k": "skip",
+ "--key": "skip",
+ "-T": "skip",
+ "--temporary-directory": "skip",
+ "-S": "skip",
+ "--buffer-size": "skip",
+ },
+ "grep": {
+ "-f": "read",
+ "--file": "read",
+ "--exclude-from": "read",
+ "-e": "skip",
+ "--regexp": "skip",
+ "--include": "skip",
+ "--exclude": "skip",
+ "--exclude-dir": "skip",
+ "-m": "skip",
+ "-A": "skip",
+ "-B": "skip",
+ "-C": "skip",
+ "-d": "skip",
+ "-D": "skip",
+ },
+ "tar": {
+ "-f": "archive",
+ "--file": "archive",
+ # The listed-incremental snapshot is CREATED or updated by tar, so it is a write wherever it
+ # points, independent of whether this invocation creates or extracts the archive itself.
+ "-g": "write",
+ "--listed-incremental": "write",
+ "-C": "extract_dir",
+ "--directory": "extract_dir",
+ "-T": "read",
+ "--files-from": "read",
+ # `tar --help`: `--add-file=FILE` adds the named file, so it is read exactly as `-T`'s
+ # list members are. Unmodelled, the whole token was discarded and the path never seen.
+ "--add-file": "read",
+ "-X": "read",
+ "--exclude-from": "read",
+ "--exclude": "skip",
+ },
+ # `diff --from-file=FILE1 local.txt` compares FILE1 to every operand, so the file it names is
+ # read even though nothing occupies an operand position. The value-taking options that are NOT
+ # paths are listed too, so a NUM or a pattern is stepped over rather than read as one.
+ "diff": {
+ "--from-file": "read",
+ "--to-file": "read",
+ "-X": "read",
+ "--exclude-from": "read",
+ "-S": "read",
+ "--starting-file": "read",
+ "-x": "skip",
+ "--exclude": "skip",
+ "-D": "skip",
+ "--ifdef": "skip",
+ "--label": "skip",
+ "-W": "skip",
+ "--width": "skip",
+ "--tabsize": "skip",
+ "--horizon-lines": "skip",
+ "--line-format": "skip",
+ "-C": "skip",
+ "--context": "skip",
+ "-U": "skip",
+ "--unified": "skip",
+ },
+ # `git -C <path>` runs the whole command in that directory, so `git -C /media/private-repo show
+ # HEAD:secret.txt` prints a file outside the sandbox with nothing in an operand position to show
+ # for it. `git -h` gives the form as `git [-C <path>] [--git-dir=<path>] ... <command>`.
+ "git": {
+ "-C": "read",
+ "--git-dir": "read",
+ "--work-tree": "read",
+ # `git archive --add-file <file>` reads an untracked file into the archive and `--output`
+ # writes the archive itself (`git archive -h`). Both are subcommand options rather than
+ # global ones, but the spec is per command, and no other git subcommand takes either name.
+ "--add-file": "read",
+ "--output": "write",
+ "-o": "write",
+ # `git clone -h`: `--[no-]separate-git-dir <gitdir>` puts the repository metadata there,
+ # which is a write outside the sandbox while every remaining operand stays relative.
+ "--separate-git-dir": "write",
+ "-c": "skip",
+ "--exec-path": "skip",
+ "--namespace": "skip",
+ },
+ # `curl file:///p` READS a local file and `curl -o p url` writes one (`curl --manual`: the FILE
+ # scheme can read or write local files). Ordinary http(s) URLs are not absolute paths, so they
+ # never reach the gate; only the `file:` scheme does.
+ "curl": {
+ # `curl --help all`: `-K, --config <file>` reads a config from a file, and the attached
+ # `--config=` spelling was discarded whole rather than exposing its value.
+ "-K": "read",
+ "--config": "read",
+ "-o": "write",
+ "--output": "write",
+ # `--output-dir <dir>` is where `-O` puts what it downloads (`curl --help all`), and `-O`
+ # itself contributes no operand, so without this an ordinary download wrote outside the
+ # sandbox with nothing in the command for the gate to look at.
+ "--output-dir": "write",
+ "-O": "skip",
+ "-d": "skip",
+ "--data": "skip",
+ "-H": "skip",
+ "--header": "skip",
+ "-X": "skip",
+ "--request": "skip",
+ "-u": "skip",
+ "--user": "skip",
+ "-A": "skip",
+ "--user-agent": "skip",
+ "-e": "skip",
+ "--referer": "skip",
+ "--max-time": "skip",
+ "--connect-timeout": "skip",
+ },
+ "wget": {
+ "-O": "write",
+ "--output-document": "write",
+ # `-P, --directory-prefix=PREFIX` (`wget --help`): both spellings save under that prefix.
+ "-P": "write",
+ "--directory-prefix": "write",
+ # `wget --help`: `-o, --output-file=FILE` logs to FILE and `-a, --append-output=FILE`
+ # appends to it. A plain download writes the log wherever it is pointed.
+ "-o": "write",
+ "--output-file": "write",
+ "-a": "write",
+ "--append-output": "write",
+ "--header": "skip",
+ },
+ "zip": {"-x": "skip", "-i": "skip"},
+ # `unzip ... archive ... [-d exdir]` (`unzip -hh`): the ARCHIVE is read and the extraction
+ # target is written. Listed as all-writes, even `unzip -l /usr/share/doc/example.zip` asked,
+ # because a read under the read-silent /usr was measured against the narrower write roots.
+ "unzip": {"-d": "write", "-x": "skip", "-O": "skip", "-P": "skip"},
+ "cut": {
+ "-d": "skip",
+ "--delimiter": "skip",
+ "-f": "skip",
+ "--fields": "skip",
+ "-c": "skip",
+ "--characters": "skip",
+ "-b": "skip",
+ "--bytes": "skip",
+ "--output-delimiter": "skip",
+ },
+ "awk": {"-f": "read", "--file": "read", "-v": "skip", "--assign": "skip", "-F": "skip"},
+ "sed": {"-f": "read", "--file": "read", "-e": "skip", "--expression": "skip", "-l": "skip"},
+ "jq": {
+ "-f": "read",
+ "--from-file": "read",
+ # `jq --help`: `-L directory` searches modules there, so the filter can `include` a file
+ # from outside the sandbox without naming it.
+ "-L": "read",
+ "--library-path": "read",
+ "--arg": "skip",
+ "--argjson": "skip",
+ "--indent": "skip",
+ },
+ "find": {
+ "-name": "skip",
+ "-iname": "skip",
+ "-path": "skip",
+ "-regex": "skip",
+ "-newer": "read",
+ },
+ # `fd --help`: `--ignore-file <path>` adds a custom ignore file, which it reads.
+ "fd": {
+ "--base-directory": "read",
+ "--search-path": "read",
+ "--ignore-file": "read",
+ "--exclude": "skip",
+ },
+ "column": {"-s": "skip", "--separator": "skip", "-o": "skip", "--output-separator": "skip"},
+ "paste": {"-d": "skip", "--delimiters": "skip"},
+ "join": {"-t": "skip", "-1": "skip", "-2": "skip", "-e": "skip", "-o": "skip"},
+ "head": {"-n": "skip", "--lines": "skip", "-c": "skip", "--bytes": "skip"},
+ "tail": {"-n": "skip", "--lines": "skip", "-c": "skip", "--bytes": "skip"},
+ "openssl": {"-in": "read", "-out": "write"},
+ "du": {"--exclude": "skip"},
+ # `date -f DATEFILE` processes every line of that file, and an invalid line is echoed back in the
+ # diagnostic, so the contents reach tool output (`date --help`).
+ # `date --help`: `-f FILE` reads dates from it and `-r, --reference=FILE` displays that file's
+ # last modification time; `-d`/`--date`/`-s` take a date STRING, not a path.
+ "date": {
+ "-f": "read",
+ "--file": "read",
+ "-r": "read",
+ "--reference": "read",
+ "-d": "skip",
+ "--date": "skip",
+ "-s": "skip",
+ },
+ "tree": {"-o": "write", "-P": "skip", "-I": "skip"},
+ "cd": {},
+}
+
+
+# Archive tools: creating writes the archive, extracting reads it.
+
+# ripgrep's own path-bearing options, on top of the grep spec it inherits below. `rg --help` gives
+# `--ignore-file=PATH` as a gitignore-formatted rules file, which is read.
+_RG_EXTRA_FLAG_SPEC = {
+ "--ignore-file": "read",
+ "--pre": "skip",
+ "--type-add": "skip",
+ "--colors": "skip",
+}
+
+
+for _alias, _base in (
+ ("egrep", "grep"),
+ ("fgrep", "grep"),
+ ("rg", "grep"),
+ ("ag", "grep"),
+ ("ack", "grep"),
+ ("gawk", "awk"),
+ ("mawk", "awk"),
+ ("yq", "jq"),
+ ("7z", "zip"),
+ ("pushd", "cd"),
+):
+ _PATH_FLAG_SPECS[_alias] = _PATH_FLAG_SPECS[_base]
+_PATH_FLAG_SPECS["rg"] = {**_PATH_FLAG_SPECS["rg"], **_RG_EXTRA_FLAG_SPEC}
+
+_PATH_ARCHIVE_COMMANDS = frozenset({"tar", "zip", "7z"})
+
+
+# Wrapper flags that take a SEPARATE value, so the token after them is the wrapper's, not the command.
+# The shared set is the fallback; a wrapper listed in `_WRAPPER_VALUE_FLAGS_BY_CMD` uses its own,
+# which is the accurate one. `stdbuf -o L cat FILE` stopped the scan on `L` and lost the file.
+_WRAPPER_VALUE_FLAGS = frozenset(
+ {"-n", "-u", "--unset", "-S", "--signal", "-k", "--kill-after", "--chdir", "-C"}
+)
+
+
+# Wrappers whose first bare operand belongs to the wrapper (`timeout 5 cat x`).
+_WRAPPER_LEADING_VALUE_COMMANDS = frozenset({"timeout", "nice", "ionice", "stdbuf"})
+
+
+_WRAPPER_LEADING_DURATION_RE = re.compile(r"^\d+(?:\.\d+)?[smhd]?$")
+
+
+# A token has to carry one of these before it can spell an absolute path in any supported syntax.
+_PATH_HINT_RE = re.compile(r"[/~\\:]")
+
+
+# `sed -i` rewrites its operands in place, unlike a plain sed.
+_SED_INPLACE_FLAGS = ("-i", "--in-place")
+# A short option that consumes the rest of its token as a value, so `perl -Ilib` is not an `-i`.
+_SHORT_OPTION_VALUE_CHARS = "eflI"
+
+
+def _clusters_inplace(arg: str) -> bool:
+ """`sed -ni` edits in place just as `sed -i` does: short options cluster into one token."""
+ if not arg.startswith("-") or arg.startswith("--"):
+ return False
+ for char in arg[1:]:
+ if char == "i":
+ return True
+ if char in _SHORT_OPTION_VALUE_CHARS:
+ break
+ return False
+
+
+_REDIR_WRITE_RE = re.compile(r"^\d*(?:>>?\|?|&>>?)$")
+
+
+# A single `<` only. `<<` introduces a here-document whose next token is its DELIMITER, and `<<<` a
+# here-string whose next token is literal data: no shell opens either as a file, so reading them as
+# operands asked for approval on `cat <<< /media/x` when nothing is opened at all.
+_REDIR_READ_RE = re.compile(r"^\d*<$")
+
+
+# The here-document and here-string forms, matched only to skip the word that follows them.
+_REDIR_HEREDOC_RE = re.compile(r"^\d*<<<?-?$")
+
+
+# A whole token that is a NAME=value prefix, as opposed to _SHELL_ASSIGN_RE which finds them inside a command string.
+_SHELL_ASSIGN_TOKEN_RE = re.compile(r"^[A-Za-z_]\w*=")
+
+
+def _terminal_path_operands(tokens, text = None) -> "list[tuple[str, bool]]":
+ """Absolute file operands a command list touches, as ``(path, writing)``.
+
+ Only commands in the tables above contribute operands, and only tokens that look absolute are
+ returned -- a relative operand lands in the session workdir, and a flag value that is not a path
+ (``head -n 5``) cannot look absolute. Redirection targets are included whichever command owns
+ them, since ``> /abs/file`` truncates that file regardless.
+ """
+ # Every operand this can report is absolute in some spelling, and each of those spellings needs
+ # one of these characters: a POSIX root or tilde, a UNC or Windows separator, or the colon of a
+ # drive letter. A redirection keeps its target in the same token (`>/abs/x`), so the character
+ # is present there too. No such character anywhere means no operand, and the segment machinery
+ # can be skipped outright -- which is the case for almost every ordinary command.
+ if not any(_PATH_HINT_RE.search(t) for t in tokens):
+ return []
+ # shlex does not treat < and > as punctuation, so `echo CHANGED>/media/x` arrives as ONE token with the
+ # redirection buried inside it. Split those out, or the target is never seen.
+ tokens = _split_attached_redirections(tokens, text)
+ operands: "list[tuple[str, bool]]" = []
+ segment: "list[str]" = []
+ # Redirections are read from the RAW text when there is one: quoting is the thing being decided,
+ # and `echo CHANGED>"/media/x host/a"` lexes to one token carrying both a live `>` and a space.
+ # The token pass below still covers a bare word list (a subprocess argv); duplicates are
+ # harmless, since these are candidates rather than a count.
+ if text and ("<" in text or ">" in text):
+ operands.extend(_raw_redirection_targets(text))
+
+ def flush() -> None:
+ if segment:
+ operands.extend(_segment_path_operands(segment))
+ segment.clear()
+
+ pending_redirect = None
+ pending_heredoc = False
+ for token in tokens:
+ if pending_heredoc:
+ # The word after `<<` names the delimiter and the word after `<<<` is the data itself,
+ # so neither is opened. A SUBSTITUTION inside it still runs though, before the data is
+ # handed over: `cat <<< "$(cat /media/x)"` reads that file, which is the thing this skip
+ # got wrong when it was added.
+ pending_heredoc = False
+ if not _looks_separator_for_paths(token):
+ operands.extend((path, False) for path in _substitution_operand_paths(token))
+ continue
+ if pending_redirect is not None:
+ # `>| /abs` lexes as `>` then `|`: the punctuation is part of the operator, so keep waiting for the
+ # target rather than consuming the pipe as one.
+ if _looks_separator_for_paths(token):
+ continue
+ writing, pending_redirect = pending_redirect, None
+ if _looks_absolute(token):
+ operands.append((token, writing))
+ continue
+ if _looks_separator_for_paths(token):
+ flush()
+ continue
+ if _REDIR_HEREDOC_RE.match(token):
+ pending_heredoc = True
+ continue
+ if _REDIR_WRITE_RE.match(token) or _REDIR_READ_RE.match(token):
+ pending_redirect = bool(_REDIR_WRITE_RE.match(token))
+ continue
+ prefix = _REDIR_PREFIX_RE.match(token)
+ if prefix:
+ # `<<END` and `<<<data` carry their word in the same token, and neither is opened.
+ if _REDIR_HEREDOC_RE.match(prefix.group(0)):
+ continue
+ target = token[prefix.end() :]
+ if target and _looks_absolute(target):
+ operands.append((target, ">" in prefix.group(0)))
+ continue
+ segment.append(token)
+ flush()
+ # A forwarding command builds ANOTHER command's argument list out of the pipeline's text, so the path never
+ # reaches the operand position this scan reads (`echo /media/x | xargs cat`). Every absolute token in the line is
+ # a candidate operand once one is present.
+ # The basename/lower/lookup per token is only worth paying once a forwarding name is present at
+ # all, so screen the tokens with a plain substring test first.
+ if any("xargs" in t or "parallel" in t for t in tokens) and any(
+ _token_command_base(t) in _PATH_FORWARDING_COMMANDS for t in tokens
+ ):
+ # The wrapped command decides the mode: `xargs touch` MODIFIES what it is handed, and
+ # charging it as a read left a write to a read-silent root silent.
+ forwarded_write = _forwarded_command_writes(tokens)
+ operands.extend((t, forwarded_write) for t in tokens if _looks_absolute(t))
+ # A backtick substitution runs as a command of its own, so it is scanned as one IN ADDITION to
+ # the pass above. Not instead of: `cat `echo /media/x`` puts the path in the outer command's
+ # operand position too, and replacing the tokens dropped exactly that reading.
+ # A `cd` to an absolute directory moves where every RELATIVE path after it lands, and those are
+ # the paths this scan deliberately treats as sandbox-local. Rather than tracking a working
+ # directory (which the classifier has no state for), the destination is charged as a write when
+ # anything after it writes: `cd /models && touch weights.gguf` then asks, while `cd /models &&
+ # ls` does not.
+ operands.extend(_directory_change_write_targets(tokens))
+ nested = _split_backticks(tokens, text)
+ if nested != list(tokens):
+ operands.extend(_terminal_path_operands(nested, text))
+ # `<( ... )` and `>( ... )` run their body as a command of its OWN, handing the outer command a
+ # pipe rather than the path. The lexer splits the parenthesis across tokens, so the body was
+ # never classified and `pr <(cat /media/x)` printed the file under an unmodelled outer command.
+ if text and "(" in text:
+ for body in _process_substitution_bodies(text):
+ try:
+ inner = shlex.split(body)
+ except ValueError:
+ inner = body.split()
+ if inner:
+ operands.extend(_terminal_path_operands(inner, body))
+ return operands
+
+
+def _process_substitution_bodies(text: str) -> "list[str]":
+ """The body of each `<( ... )` / `>( ... )`, matched on BALANCED parentheses.
+
+ A body can hold a substitution of its own (`<(cat $(echo /media/x))`), and a pattern that
+ excluded parentheses rejected the whole body when it did. Depth-counted rather than recursive,
+ and each body is shorter than the text it came from, so the caller's recursion still terminates.
+ """
+ bodies: "list[str]" = []
+ index = 0
+ while index < len(text) - 1:
+ if text[index] in "<>" and text[index + 1] == "(":
+ depth = 0
+ for end in range(index + 1, len(text)):
+ if text[end] == "(":
+ depth += 1
+ elif text[end] == ")":
+ depth -= 1
+ if depth == 0:
+ bodies.append(text[index + 2 : end])
+ index = end
+ break
+ else:
+ break
+ index += 1
+ return bodies
+
+
+_ATTACHED_REDIR_RE = re.compile(r"(\d*(?:>>|>\||&>>|&>|>|<<<|<<|<))")
+
+
+def _raw_redirection_targets(text: str) -> "list[tuple[str, bool]]":
+ """`(target, writing)` for each redirection whose OPERATOR is unquoted in *text*.
+
+ Read from the raw command rather than the lexed tokens: any rule based on the token alone gets
+ either the quoted-data case or the attached-target case wrong. A here-document or here-string
+ takes a delimiter or literal data, never a file, so those operators are skipped.
+ """
+ out: "list[tuple[str, bool]]" = []
+ quote = ""
+ index = 0
+ while index < len(text):
+ char = text[index]
+ if char == "\\" and quote != "'":
+ index += 2
+ continue
+ if quote:
+ if char == quote:
+ quote = ""
+ index += 1
+ continue
+ if char in "'\"":
+ quote = char
+ index += 1
+ continue
+ if char not in "<>":
+ index += 1
+ continue
+ start = index
+ while index < len(text) and text[index] in "<>":
+ index += 1
+ operator = text[start:index]
+ if operator.startswith("<<"):
+ continue
+ writing = ">" in operator
+ while index < len(text) and text[index] in " \t":
+ index += 1
+ word = ""
+ while index < len(text) and (quote or text[index] not in " \t\n;&|()"):
+ char = text[index]
+ if char == "\\" and quote != "'" and index + 1 < len(text):
+ word += text[index + 1]
+ index += 2
+ continue
+ if quote:
+ if char == quote:
+ quote = ""
+ else:
+ word += char
+ elif char in "'\"":
+ quote = char
+ else:
+ word += char
+ index += 1
+ if word and _looks_absolute(word):
+ out.append((word, writing))
+ return out
+
+
+def _token_is_always_quoted(
+ token: str,
+ text: "str | None",
+ *,
+ double: bool = True,
+) -> bool:
+ """Whether EVERY occurrence of *token* in *text* is a quoted one.
+
+ Counted rather than searched: the same word can appear twice, once as data and once as syntax.
+ `echo 'x>/media/x'; echo x>/media/x` lexes to that token twice, and a membership test found the
+ quoted spelling and left the live redirection of the second command unsplit.
+ """
+ if not text or not token:
+ return False
+ occurrences = text.count(token)
+ if not occurrences:
+ return False
+ quoted = text.count(f"'{token}'")
+ if double:
+ quoted += text.count(f'"{token}"')
+ return occurrences == quoted
+
+
+def _split_backticks(tokens, text = None) -> "list[str]":
+ """Break a token carrying a backtick substitution into its own command.
+
+ `` echo `cat /media/x` `` runs that read as a command of its own, but the outer lexer keeps the
+ backticks inside ordinary tokens, so the path arrived as an argument of `echo` and was dropped
+ with it. `$( ... )` needs none of this: its brackets are punctuation to the lexer already.
+
+ The backtick becomes a separator, which is exactly what it is here -- everything between a pair
+ is a command line in its own right, and the segment machinery classifies it as one.
+ """
+ if not any("`" in token for token in tokens):
+ return list(tokens)
+ out: "list[str]" = []
+ for token in tokens:
+ # SINGLE quotes only: a command substitution still runs inside double quotes, so
+ # `echo "`cat /media/x`"` executes the read exactly as the unquoted form does.
+ if "`" not in token or _token_is_always_quoted(token, text, double = False):
+ out.append(token)
+ continue
+ for index, piece in enumerate(token.split("`")):
+ if index:
+ out.append("(")
+ # Split on whitespace too: inside double quotes the substitution is ONE token, so the
+ # body arrived as a single word and the command at its head was never read as one.
+ out.extend(piece.split())
+ return out
+
+
+def _split_attached_redirections(tokens, text = None) -> "list[str]":
+ """Break a token that carries a redirection operator inside it into its parts.
+
+ ``echo CHANGED>/media/x`` lexes as one token because ``shlex`` is not given ``<``/``>`` as
+ punctuation, which hid the redirection target from the operand scan.
+
+ A QUOTED word is data, not syntax: `printf 'see >/media/private/report'` opens no file, and the
+ lexer has already dropped the quotes by the time the token arrives here. Two signs that it was
+ quoted are enough to leave it alone -- whitespace inside it, which no redirection operator has,
+ and the quoted spelling appearing in the command text the tokens came from.
+ """
+ if not any(("<" in t or ">" in t) for t in tokens):
+ return list(tokens)
+ out: "list[str]" = []
+ for token in tokens:
+ if "<" not in token and ">" not in token:
+ out.append(token)
+ continue
+ if any(ch.isspace() for ch in token) or _token_is_always_quoted(token, text):
+ out.append(token)
+ continue
+ prefix = _REDIR_PREFIX_RE.match(token)
+ tail = token[prefix.end() :] if prefix else token
+ if prefix and "<" not in tail and ">" not in tail:
+ # One leading redirection with its target attached (`>out.txt`), which the redirection
+ # handling upstream already understands. Leave it whole.
+ out.append(token)
+ continue
+ # More than one redirection in the token. bash accepts `</dev/null>/media/x cmd`, and
+ # keeping that whole recorded a single read of `/dev/null>/media/x` under the silent /dev
+ # root while the real write to /media/x was never seen.
+ parts = [piece for piece in _ATTACHED_REDIR_RE.split(token) if piece]
+ out.extend(parts if len(parts) > 1 else [token])
+ return out
+
+
+# Words that END one command and begin another. `if true; then cat /abs; fi` groups the read under
+# `then` otherwise, which is in no command table, so the whole segment was discarded unscanned.
+_SHELL_CONTROL_WORDS = frozenset(
+ """
+ if then elif else fi for while until select do done case esac in { } !
+ """.split()
+)
+
+
+def _looks_separator_for_paths(token: str) -> bool:
+ return bool(token) and (all(ch in ";&|()" for ch in token) or token in _SHELL_CONTROL_WORDS)
+
+
+def _segment_path_operands(segment) -> "list[tuple[str, bool]]":
+ """Operands of one simple command (no separators, redirections already removed)."""
+ index = 0
+ # Leading NAME=value assignments and safe wrappers (env, timeout, nice ...) precede the real command. A wrapper
+ # brings its OWN options and values with it (`timeout 5 cat x`, `nice -n 5 cat x`, `env -u VAR cat x`), so those
+ # are stepped over too; otherwise `5` reads as the command and the real one is never screened.
+ while index < len(segment):
+ token = segment[index]
+ base = os.path.basename(token).lower()
+ if _SHELL_ASSIGN_TOKEN_RE.match(token):
+ index += 1
+ continue
+ if base in _tools._MULTICALL_BINARIES:
+ # `busybox cat /media/x` dispatches to the applet named FIRST, so the applet is the
+ # command this scan has to classify. The main high-risk scan already unwraps these.
+ index += 1
+ continue
+ if base not in _AUTO_SAFE_WRAPPERS:
+ break
+ index += 1
+ while index < len(segment):
+ candidate = segment[index]
+ # `env --help`: `env [OPTION]... [-] [NAME=VALUE]... [COMMAND [ARG]...]`, and "A mere -
+ # implies -i". The lone dash is env's OWN option, so the command still follows it;
+ # treating it as the command left `env - FOO=bar cat /media/x` unscreened.
+ if candidate == "-" and base == "env":
+ index += 1
+ continue
+ if candidate.startswith("-") and candidate != "-":
+ # A wrapper flag that takes a separate value consumes the token after it.
+ index += 1
+ takes_value = _WRAPPER_VALUE_FLAGS_BY_CMD.get(base)
+ if (
+ candidate in (takes_value if takes_value else _WRAPPER_VALUE_FLAGS)
+ and index < len(segment)
+ and not segment[index].startswith("-")
+ ):
+ index += 1
+ continue
+ # `timeout 5 cat x`: a bare duration is the wrapper's own operand, not the command.
+ if base in _WRAPPER_LEADING_VALUE_COMMANDS and _WRAPPER_LEADING_DURATION_RE.match(
+ candidate
+ ):
+ index += 1
+ continue
+ break
+ if index >= len(segment):
+ return []
+ command = os.path.basename(segment[index]).lower()
+ if command.endswith(".exe"):
+ command = command[: -len(".exe")]
+ args = segment[index + 1 :]
+ # `/media/alice/tool --flag` RUNS a file outside the sandbox, which reads it before anything the
+ # rest of this scan looks at. Taking the basename dropped the only spelling of that path, so the
+ # command word is reported as a read of its own before it is reduced to a name.
+ # A path ending in a separator names a DIRECTORY and can never be the binary, which is what
+ # keeps a `sed` expression fragment such as `/x/` from reading as one.
+ launched = (
+ [(segment[index], False)]
+ if _looks_absolute(segment[index]) and not segment[index].endswith(("/", "\\"))
+ else []
+ )
+ if command in _TEST_COMMANDS:
+ operands = list(launched)
+ for arg in _test_command_operands(args):
+ if _looks_absolute(arg):
+ operands.append((arg, False))
+ else:
+ operands.extend((path, False) for path in _substitution_operand_paths(arg))
+ return operands
+ # `sqlite3 FILE 'DELETE ...'` CREATES the file when absent and modifies it otherwise, so the
+ # database is a write unless the invocation is explicitly read-only (`sqlite3 --help` documents
+ # `-readonly`). Classifying it as a read let a delete against a read-silent-but-not-write-silent
+ # root through, a configured model folder being the realistic one.
+ sqlite_write = command == "sqlite3" and not any(
+ arg in ("-readonly", "--readonly") for arg in args
+ )
+ read_cmd = (
+ command in _PATH_READ_COMMANDS or command in _PATH_SCRIPT_COMMANDS or command == "sqlite3"
+ )
+ flag_only = command in _PATH_FLAG_ONLY_COMMANDS
+ write_cmd = command in _PATH_WRITE_COMMANDS or sqlite_write
+ if (
+ write_cmd
+ and command in _STDOUT_COMPRESSORS
+ and any(
+ arg in _STDOUT_FLAGS
+ or (arg.startswith("-") and not arg.startswith("--") and "c" in arg.lstrip("-"))
+ for arg in args
+ )
+ ):
+ # The operand is still opened, just not modified, so it becomes a READ rather than nothing.
+ write_cmd = False
+ read_cmd = True
+ dest_last = command in _PATH_DEST_LAST_COMMANDS
+ if not (read_cmd or write_cmd or dest_last or flag_only):
+ return launched
+ inplace = command in ("sed", "perl") and any(
+ arg in _SED_INPLACE_FLAGS or arg.startswith("--in-place") or _clusters_inplace(arg)
+ for arg in args
+ )
+ spec = _PATH_FLAG_SPECS.get(command, {})
+ # `tar cf out.tar .` / `tar -cf out.tar .` create the archive; the same flags only read when extracting.
+ # Scan every short-flag token, not just args[0]: `tar -g snap -cf out.tar src` carries the mode
+ # on a later flag, and reading only the first argument would classify out.tar as a read. Limited
+ # to args[0] (the legacy option word) plus single-dash tokens, because an ORDINARY FILENAME can
+ # contain a "c" -- `tar -xf a.tar src` must not look like a create.
+ # `tar --help`: `-r` appends to the archive and `-u` updates it, so both MUTATE the file `-f`
+ # names, exactly as `-c` does. Only `c` was read here, and an append to a read-silent root asked
+ # for nothing.
+ if command == "git" and "init" in args:
+ # `git init <directory>` CREATES the repository there (`git init -h`); every other git
+ # subcommand takes its paths through the flags the spec already lists.
+ after = args[args.index("init") + 1 :]
+ target = next((arg for arg in after if not arg.startswith("-")), None)
+ return launched + ([(target, True)] if target else [])
+ if command in ("7z", "7za", "7zr"):
+ # `7z a out.7z src`: the archive is the first positional after the command word.
+ creating = bool(args) and args[0].lower() in _SEVENZIP_WRITE_COMMANDS
+ archive_from_flag = False
+ return launched + _seven_zip_operands(args, creating)
+ creating = command in _PATH_ARCHIVE_COMMANDS and (
+ any(
+ any(mode in arg.lstrip("-") for mode in _ARCHIVE_WRITE_SHORT_MODES)
+ for index, arg in enumerate(args)
+ if not arg.startswith("--") and (index == 0 or arg.startswith("-"))
+ )
+ # The long spellings carry the same mode and were not read at all, so
+ # `tar --create --file=/models/out.tar` classified the archive as a READ.
+ or any(arg.split("=", 1)[0] in _ARCHIVE_CREATE_LONG_FLAGS for arg in args)
+ )
+ # Whether the archive came from `-f`/`--file` rather than from the first positional.
+ archive_from_flag = command in _PATH_ARCHIVE_COMMANDS and any(
+ arg.split("=", 1)[0] in ("-f", "--file")
+ or (arg.startswith("-") and not arg.startswith("--") and "f" in arg.lstrip("-"))
+ for arg in args
+ )
+ # `install -d` / `mkdir -p` style: every positional is a directory being CREATED.
+ directory_mode = command == "install" and any(
+ arg == "-d"
+ or arg == "--directory"
+ or (arg.startswith("-") and not arg.startswith("--") and "d" in arg.lstrip("-"))
+ for arg in args
+ )
+ skip = _PATH_ARG_SKIP.get(command, 0)
+ operands: "list[tuple[str, bool]]" = list(launched)
+ positionals: "list[str]" = []
+ pattern_flags = _PATTERN_SUPPLYING_FLAGS.get(command, frozenset())
+ pending_flag = None
+ for index, arg in enumerate(args):
+ if pending_flag is not None:
+ flag, pending_flag = pending_flag, None
+ _add_flag_operand(operands, spec.get(flag), arg, write_cmd, creating)
+ continue
+ if arg.startswith("-") and arg != "-":
+ # A flag can carry a path (`sort -o /abs` writes, `grep -f /abs` reads, `cp -t /abs` is the destination)
+ # or carry DATA that merely looks like one (`cut -d /`). Both must be consumed, with the right meaning.
+ name, sep, attached = arg.partition("=")
+ # The pattern came from a flag, so no positional is owed to one and the first input file
+ # is a real operand rather than something to step over.
+ if name in pattern_flags:
+ skip = 0
+ if name not in spec:
+ name = _resolved_long_flag(spec, name) or name
+ kind = spec.get(name)
+ if sep and kind:
+ _add_flag_operand(operands, kind, attached, write_cmd, creating)
+ continue
+ if not sep and kind:
+ pending_flag = name
+ continue
+ flag, value = _short_flag_with_value(arg, spec)
+ if flag in pattern_flags:
+ skip = 0
+ if flag and value:
+ _add_flag_operand(operands, spec.get(flag), value, write_cmd, creating)
+ elif flag:
+ pending_flag = flag
+ continue
+ if skip > 0:
+ # For a legacy-option-word command the skip is only owed to the first ARGUMENT; anything
+ # later is a real operand. `positionals` is still empty exactly when no positional has
+ # been taken yet, which is what "this is args[0]" means once flags are discounted.
+ if command not in _PATH_SKIP_FIRST_ARG_ONLY or index == 0:
+ skip -= 1
+ continue
+ skip = 0
+ positionals.append(arg)
+ for position, arg in enumerate(positionals):
+ # `key=value` forms (dd if=..., --output=...) carry the path on the right.
+ if "=" in arg and not _looks_absolute(arg):
+ arg = arg.split("=", 1)[1]
+ if dest_last:
+ # `install -d DIRECTORY...` creates every operand (`install --help`), so there is no
+ # source to distinguish and the "more than one positional" rule does not apply.
+ writing = (
+ directory_mode
+ or command in _PATH_SOURCE_MUTATING_COMMANDS
+ or (position == len(positionals) - 1 and len(positionals) > 1)
+ )
+ elif command in _PATH_DEST_FIRST_COMMANDS:
+ writing = position == 0 or any(
+ arg == "-m"
+ or arg == "--move"
+ or (arg.startswith("-") and not arg.startswith("--") and "m" in arg.lstrip("-"))
+ for arg in args
+ )
+ else:
+ # `creating and position == 0` is the LEGACY form, `tar cf out.tar src`, where the
+ # archive occupies the first positional. With `-f` the archive arrived as a flag value
+ # and was classified there, so the first positional is a SOURCE: `tar -cf out.tar
+ # /usr/share/doc` reads that directory and must not ask under the read-silent root.
+ writing = write_cmd or inplace or (creating and position == 0 and not archive_from_flag)
+ if not _looks_absolute(arg):
+ # The shell expands a substitution in this position into the operand the command
+ # actually opens, so a literal path inside one counts as if it were written here.
+ operands.extend((path, writing) for path in _substitution_operand_paths(arg))
+ continue
+ operands.append((arg, writing))
+ return operands
+
+
+# Relative writes after a `chdir` land under the NEW directory, so the destination is charged as a
+# write when the snippet writes anything afterwards. Mirrors the terminal `cd` rule; the classifier
+# keeps no working-directory state, and a path computed at runtime stays the documented residual.
+def _ctor_opens_for_write(node) -> bool:
+ """`h5py.File(path, "w")` rewrites the file it names; the default `"r"` mode does not."""
+ mode = next(
+ (kw.value for kw in _call_keywords(node) if kw.arg == "mode"),
+ node.args[1] if len(node.args) > 1 else None,
+ )
+ return (
+ isinstance(mode, ast.Constant)
+ and isinstance(mode.value, str)
+ and any(char in mode.value for char in "wax+")
+ )
+
+
+def _subprocess_child_writes(tree) -> bool:
+ """`subprocess.run(["touch", "f"])` writes, though no python writer call appears in the tree."""
+ for node in ast.walk(tree):
+ if not isinstance(node, ast.Call):
+ continue
+ if (getattr(node.func, "attr", None) or getattr(node.func, "id", None)) not in (
+ _PY_PATH_SUBPROCESS_CALLS
+ ):
+ continue
+ head = node.args[0] if node.args else None
+ words = getattr(head, "elts", [head])
+ first = next(
+ (w.value for w in words if isinstance(w, ast.Constant) and isinstance(w.value, str)), ""
+ )
+ if _command_base_writes(
+ _token_command_base(_shell_words(first)[0] if first.split() else "")
+ ):
+ return True
+ return False
+
+
+def _python_directory_change_targets(tree, operands) -> "list[tuple[str, bool]]":
+ """The absolute destination of an `os.chdir` in a snippet that also writes."""
+ # `open` is not listed: the operand pass already reports its mode, so a read through it does
+ # not count as writing while `open(p, "w")` does.
+ writers = _PY_PATH_WRITE_CALLS | _PY_PATH_CONTENT_FIRST_CALLS
+ if (
+ not any(writing for _path, writing in operands)
+ and not any(
+ isinstance(node, ast.Call)
+ and (getattr(node.func, "attr", None) or getattr(node.func, "id", None)) in writers
+ for node in ast.walk(tree)
+ )
+ # A relative operand handed to a child process leaves no path entry at all, so the write
+ # `os.chdir("/models"); subprocess.run(["touch", "w.gguf"])` performs is only visible here.
+ and not _subprocess_child_writes(tree)
+ ):
+ return []
+ targets: "list[tuple[str, bool]]" = []
+ for node in ast.walk(tree):
+ if not isinstance(node, ast.Call):
+ continue
+ if (getattr(node.func, "attr", None) or getattr(node.func, "id", None)) != "chdir":
+ continue
+ first = node.args[0] if node.args else None
+ if isinstance(first, ast.Constant) and isinstance(first.value, str):
+ targets.append((first.value, True))
+ return targets
+
+
+def _inline_code_operands(source: str) -> "list[tuple[str, bool]]":
+ """Operands of a literal `-c` payload, read as python. Anything unparseable yields nothing."""
+ try:
+ return _python_path_operands(ast.parse(source))
+ except Exception: # noqa: BLE001 - not python, or not parseable: the token scan still applies
+ return []
+
+
+def _shell_words(text: str) -> "list[str]":
+ """Split a `shell = True` command line the way the shell does.
+
+ A plain `str.split()` tore `cat '/media/x/My Documents/private.txt'` into two tokens, neither of
+ which looked absolute, so the read was never seen. Quotes are the thing being decided here.
+ """
+ if not text:
+ return []
+ try:
+ words = shlex.split(text)
+ except ValueError: # unbalanced quotes: the raw words are the best available reading
+ words = text.split()
+ return words or [text]
+
+
+def _seven_zip_operands(args, creating: bool) -> "list[tuple[str, bool]]":
+ """Operands of a 7-Zip invocation: `7z <command> <archive> [files...]`.
+
+ The archive is written whenever the command word adds to, updates, deletes from or renames in
+ it, and read otherwise (`x`, `l`, `t`). The remaining positionals are the files it packs.
+ """
+ positionals = [arg for arg in args[1:] if not arg.startswith("-")]
+ operands: "list[tuple[str, bool]]" = []
+ for index, arg in enumerate(positionals):
+ if _looks_absolute(arg):
+ operands.append((arg, creating if index == 0 else False))
+ else:
+ operands.extend(
+ (path, creating if index == 0 else False)
+ for path in _substitution_operand_paths(arg)
+ )
+ return operands
+
+
+# Commands whose presence after a `cd` means something under the new directory is written.
+_DIRECTORY_CHANGE_COMMANDS = frozenset({"cd", "pushd"})
+
+
+def _resolved_long_flag(spec, name: str) -> "str | None":
+ """GNU long options accept unambiguous abbreviations, so `cp --targ=` IS `--target-directory=`."""
+ if not name.startswith("--") or len(name) < 3:
+ return None
+ matches = [flag for flag in spec if flag.startswith(name)]
+ return matches[0] if len(matches) == 1 else None
+
+
+def _command_base_writes(base: str) -> bool:
+ """Whether a bare command word modifies what it is handed."""
+ return (
+ base in _PATH_WRITE_COMMANDS
+ or base in _PATH_DEST_LAST_COMMANDS
+ or base in _PATH_ARCHIVE_COMMANDS
+ or base in _EXTRA_WRITE_COMMANDS
+ )
+
+
+_EXTRA_WRITE_COMMANDS = frozenset("rm rmdir touch truncate dd shred sed perl".split())
+# `xargs -n 1 cmd`: these carry their value in the NEXT token, which is not the wrapped command.
+_FORWARDING_VALUE_FLAGS = frozenset("-a -d -E -e -I -i -L -l -n -P -s".split())
+
+
+def _forwarded_command_writes(tokens) -> bool:
+ """`... | xargs touch` writes every path it is handed; `... | xargs cat` only reads them."""
+ for index, token in enumerate(tokens):
+ if _token_command_base(token) not in _PATH_FORWARDING_COMMANDS:
+ continue
+ skip = False
+ for candidate in tokens[index + 1 :]:
+ if skip:
+ skip = False
+ elif candidate.startswith("-"):
+ skip = candidate in _FORWARDING_VALUE_FLAGS
+ else:
+ return _command_base_writes(_token_command_base(candidate))
+ return False
+
+
+# An interpreter whose `-c` payload is a command line or a snippet of its own.
+_INLINE_CODE_COMMANDS = frozenset("python python2 python3 sh bash zsh dash ksh".split())
+
+
+def _nested_payload_writes(tokens, index: int) -> bool:
+ """Whether an interpreter's `-c` payload writes, so the directory it runs in is a write target.
+
+ `cd /models && python -c "open('weights.gguf', 'w')"` writes through a RELATIVE path, which the
+ payload scan cannot place and the command-name test never sees.
+ """
+ payload = next((tokens[i + 1] for i in range(index, len(tokens) - 1) if tokens[i] == "-c"), "")
+ if not payload:
+ return False
+ words = _shell_words(payload)
+ if words and _command_base_writes(_token_command_base(words[0])):
+ return True
+ operands = _inline_code_operands(payload) or _terminal_path_operands(words, payload)
+ return any(writing for _path, writing in operands)
+
+
+def _directory_change_write_targets(tokens) -> "list[tuple[str, bool]]":
+ """The absolute destination of a `cd` that is followed by a write, as a write operand."""
+ targets: "list[str]" = []
+ writes_after = False
+ for index, token in enumerate(tokens):
+ base = _token_command_base(token)
+ if base in _DIRECTORY_CHANGE_COMMANDS:
+ operand = tokens[index + 1] if index + 1 < len(tokens) else ""
+ if _looks_absolute(operand):
+ targets.append(operand)
+ continue
+ if not targets:
+ continue
+ if (
+ _command_base_writes(base)
+ or (base in _INLINE_CODE_COMMANDS and _nested_payload_writes(tokens, index))
+ or _REDIR_WRITE_RE.match(token)
+ or _REDIR_PREFIX_RE.match(token)
+ and ">" in token
+ ):
+ writes_after = True
+ return [(target, True) for target in targets] if writes_after else []
+
+
+def _serializes_to_second_arg(func, module_aliases: "dict | None" = None) -> bool:
+ """True for ``torch.save(obj, path)``-style calls, where the path is the SECOND argument.
+
+ The receiver is resolved through the import aliases first: `import torch as t` makes it `t`,
+ which is in no table, and the call would otherwise fall through to the generic writer branch
+ that never looks at the second argument.
+ """
+ if not isinstance(func, ast.Attribute):
+ return False
+ receiver = func.value
+ while isinstance(receiver, ast.Attribute):
+ receiver = receiver.value
+ if not isinstance(receiver, ast.Name):
+ return False
+ name = (module_aliases or {}).get(receiver.id, receiver.id)
+ return name in _PY_SERIALIZE_SECOND_ARG_MODULES
+
+
+def _short_flag_with_value(arg: str, spec) -> "tuple[str | None, str | None]":
+ """Resolve a short-flag token against a command's flag table.
+
+ Handles the attached form (`sort -o/abs/out`) and the cluster (`tar -cf out.tar`, where only
+ the LAST letter takes the value). Returns ``(flag, value)``; ``value`` is None when the value
+ is the next token.
+ """
+ if arg.startswith("--") or len(arg) < 2:
+ return None, None
+ head = arg[:2]
+ if head in spec:
+ return head, (arg[2:] or None)
+ body = arg[1:]
+ if body.isalpha():
+ last = "-" + body[-1]
+ return (last, None) if last in spec else (None, None)
+ # A cluster whose value is ATTACHED to the last letter: `tar -cf/media/x/out.tar`, which GNU tar
+ # accepts and which creates that archive. Requiring the whole body to be alphabetic rejected it
+ # the moment the value contained a separator, so the archive operand was never seen. Split at
+ # the first non-letter: everything before it is the cluster, the rest is the value.
+ for index, char in enumerate(body):
+ if not char.isalpha():
+ break
+ else:
+ return None, None
+ if index < 1:
+ return None, None
+ last = "-" + body[index - 1]
+ value = body[index:]
+ return (last, value or None) if last in spec else (None, None)
+
+
+# A command substitution or arithmetic/brace expansion sitting where a path belongs. shlex keeps the
+# whole thing as ONE token, and that token is not itself absolute, so the operand scan saw nothing at
+# all for `cat "$(printf /media/private/report.txt)"` while the shell handed `cat` the real path.
+_SUBSTITUTION_RE = re.compile(r"\$\((.*?)\)|`([^`]*)`|\$\{([^{}]*)\}", re.DOTALL)
+
+
+def _substitution_operand_paths(token: str) -> "list[str]":
+ """Absolute paths written literally INSIDE a substitution in `token`.
+
+ Only literals are recovered, which is the common shape (`$(printf /abs)`, `$(echo /abs)`,
+ `` `cat /abs` ``). A substitution whose output is genuinely dynamic yields nothing here; that
+ remains the documented static-analysis gap rather than something this pretends to solve.
+ """
+ paths: "list[str]" = []
+ for match in _SUBSTITUTION_RE.finditer(token):
+ inner = next((group for group in match.groups() if group), "")
+ if not inner:
+ continue
+ try:
+ words = shlex.split(inner)
+ except ValueError:
+ words = inner.split()
+ paths.extend(word for word in words if _looks_absolute(word))
+ return paths
+
+
+def _add_flag_operand(operands, kind, value: str, write_cmd: bool, creating: bool) -> None:
+ """Record a path supplied as a flag value, with the access that flag implies.
+
+ ``kind`` of "skip" means the value was data, not a path, and is simply consumed.
+ """
+ if not kind or kind == "skip" or not value:
+ return
+ if not _looks_absolute(value):
+ writing_sub = kind == "write" or (write_cmd and kind != "archive")
+ operands.extend((path, writing_sub) for path in _substitution_operand_paths(value))
+ return
+ if kind == "archive":
+ writing = creating
+ elif kind == "extract_dir":
+ # tar -C is where the operation HAPPENS, so its sense is the inverse of the archive's:
+ # extracting creates and overwrites members under it, creating only reads them from it.
+ writing = not creating
+ else:
+ writing = kind == "write" or write_cmd
+ operands.append((value, writing))
+
+
+def _terminal_reaches_outside_sandbox(tokens, text: "str | None" = None) -> bool:
+ """True when a command list reads or writes an absolute path outside the silent roots.
+
+ *text*, when given, is the command the tokens came from. A POSIX lexer treats a backslash as an
+ escape, so `cat C:\\Users\\alice\\notes.txt` arrives here as `C:Usersalicenotes.txt` and every
+ Windows absolute path was invisible to the gate. The raw text is re-lexed without that rule when
+ it carries a drive or a UNC share, and the operands from both passes are weighed.
+ """
+ if not any(_ABSOLUTE_HINT_RE.search(token) for token in tokens):
+ # A POSIX lex may have eaten the separators that make the path absolute, so a Windows
+ # spelling in the raw text still deserves the second pass below.
+ if not (text and _WINDOWS_SPELLING_RE.search(text)):
+ return False
+ if any(
+ _path_needs_approval(path, writing = writing)
+ for path, writing in _terminal_path_operands(tokens, text)
+ ):
+ return True
+ if not text or not _WINDOWS_SPELLING_RE.search(text):
+ return False
+ raw = _lex_keeping_backslashes(text)
+ if raw is None or raw == list(tokens):
+ return False
+ return any(
+ _path_needs_approval(path, writing = writing)
+ for path, writing in _terminal_path_operands(raw, text)
+ )
+
+
+# A drive-qualified path or a UNC share, the two spellings a POSIX lexer destroys.
+# A drive-qualified path, a UNC share, or a ROOT-relative one: `cat \\Users\\alice\\notes.txt` opens
+# `\\Users\\alice\\notes.txt` on the current drive, and a POSIX lex turns it into `Usersalicenotes.txt`
+# with nothing absolute left to see.
+_WINDOWS_SPELLING_RE = re.compile(r"(?:^|[\s'\"=])[A-Za-z]:(?![:\s])|\\\\[^\\/]|(?:^|\s)\\[^\\/\s]")
+
+
+def _lex_keeping_backslashes(text: str) -> "list[str] | None":
+ """Split *text* with the backslash left alone, so a Windows path survives. None if unparseable."""
+ try:
+ lexer = shlex.shlex(text, posix = False, punctuation_chars = ";&|()")
+ lexer.whitespace_split = True
+ tokens = list(lexer)
+ except ValueError:
+ return None
+ return [t[1:-1] if len(t) > 1 and t[0] == t[-1] and t[0] in "\"'" else t for t in tokens]
+
+
+# A token can only carry an absolute path if it holds a separator, a tilde or a drive colon.
+_ABSOLUTE_HINT_RE = re.compile(r"[/~\\]|^[A-Za-z]:")
+
+
+# Python callables whose first argument (or receiver, for a method) names a file being READ. Only names that take a
+# path are listed: `json.load(fh)` and `copy.copy(obj)` fold to nothing, so sharing a name with one of these costs
+# nothing.
+# Readers whose NAME alone is ambiguous, so they are keyed on the receiving module. `numpy.load`
+# takes a filename; the `load` of every other serializer in these tables takes a file object.
+_PY_QUALIFIED_READ_CALLS = {
+ "numpy": frozenset({"load"}),
+ "np": frozenset({"load"}),
+}
+# Readers reached through an INSTANCE rather than a module, so neither the receiver nor the bare
+# name identifies them. `ConfigParser().read(p)` opens the file it is handed (and accepts a LIST of
+# them), while `read` on anything else is an ordinary method, so the constructor is what says which
+# is which.
+# `io.FileIO(p)` opens the path directly, as `io.open` does.
+_PY_MODULE_OPEN_CTORS = {"FileIO"}
+
+
+# Constructors that OPEN their first argument, so the path is the constructor's rather than the
+# reader method's: `pd.ExcelFile(p).parse(0)` never names the workbook again after this call.
+# `h5py.File(path, "r")` and `netCDF4.Dataset(path)` open the file they are handed, like the pandas
+# pair above. The mode sits where `open`'s does, so the shared ctor branch decides read or write.
+_PY_PATH_OPENING_CTORS = frozenset({"ExcelFile", "HDFStore", "File", "Dataset"})
+
+
+_PY_INSTANCE_READ_CTORS = {
+ "ConfigParser": frozenset({"read"}),
+ "RawConfigParser": frozenset({"read"}),
+ "SafeConfigParser": frozenset({"read"}),
+}
+
+
+# `io.open_code(path)` opens that file in binary mode (it is what the interpreter itself
+# uses to read source), so it reads a path exactly as `open` does.
+# The stat family alongside the `os.path.get*` helpers that wrap it: they answer existence,
+# size, ownership and timestamps for a path outside the sandbox.
+# The predicate family answers existence and type for a path, which is the same disclosure
+# `test -e` and `os.stat` make.
+# os.chdir re-points every relative path that follows, the same way `cd` does in the shell.
+# Readers that DESCEND. `glob`/`iglob`/`rglob` are listed because their pattern decides, and a
+# pattern rooted at `/` reaches the whole host either way.
+_PY_RECURSIVE_READ_CALLS = frozenset("walk rglob glob iglob".split())
+
+
+_PY_PATH_READ_CALLS = frozenset(
+ """
+ open_code read_text read_bytes getline getlines loadtxt genfromtxt fromfile read_csv
+ read_table read_fwf read_parquet read_json read_excel read_pickle read_feather read_hdf
+ read_stata read_sas read_orc read_xml read_html read_sql_table imread connect stat lstat
+ exists lexists isfile isdir islink ismount is_file is_dir is_symlink getsize getmtime
+ getctime getatime listdir scandir walk iterdir glob iglob rglob samefile realpath readlink
+ load_workbook from_file imageio parse iterparse chdir open_memmap memmap get_data read_image
+ loadmat
+ """.split()
+)
+
+
+# Callables whose first argument (or receiver) names a file being CREATED, OVERWRITTEN or REMOVED.
+_PY_PATH_WRITE_CALLS = frozenset(
+ {
+ # `shutil.make_archive` CREATES `base_name + ext`; its source directories are read through
+ # `_PY_PATH_KWARGS_BY_CALL`.
+ "make_archive",
+ "write_text",
+ "write_bytes",
+ "touch",
+ "mkdir",
+ "makedirs",
+ "rename",
+ "renames",
+ "replace",
+ "remove",
+ "unlink",
+ "rmdir",
+ "removedirs",
+ "rmtree",
+ "chmod",
+ "chown",
+ "symlink",
+ "symlink_to",
+ "hardlink_to",
+ "link",
+ "truncate",
+ "mkfifo",
+ "mknod",
+ "utime",
+ }
+) # extended with `tools._AUTO_UNSAFE_PY_WRITE_METHODS` in `_bind`
+
+
+# Archive constructors: the mode sits in the second argument, exactly like open().
+# Extended with `tools._ARCHIVE_CTOR_NAMES` in `_bind`.
+_PY_PATH_ARCHIVE_CTORS = frozenset({"TarFile", "tarfile"})
+
+
+# Serializers whose DESTINATION is the second argument: the first is the object being written out. Only true for the
+# modules below; numpy.save / savez take the path FIRST, so the receiver is what disambiguates them.
+_PY_PATH_SERIALIZE_CALLS = frozenset({"save", "dump", "save_file", "save_model"})
+
+
+_PY_SERIALIZE_SECOND_ARG_MODULES = frozenset(
+ {
+ "torch",
+ "joblib",
+ "pickle",
+ "cloudpickle",
+ "dill",
+ "safetensors",
+ "st",
+ "toml",
+ "yaml",
+ "json",
+ }
+)
+
+
+# Writers whose first argument is CONTENT, not a path (the path is the receiver).
+_PY_PATH_CONTENT_FIRST_CALLS = frozenset({"write_text", "write_bytes", "write"})
+
+
+# Keywords that always name a destination, whatever the call's default access is.
+# `tempfile` creators put their file in `dir` when it is given, and in TMPDIR otherwise.
+_PY_TEMPFILE_CALLS = frozenset(
+ """mkstemp mkdtemp NamedTemporaryFile TemporaryFile TemporaryDirectory SpooledTemporaryFile""".split()
+)
+
+
+_PY_PATH_DEST_KWARGS = frozenset(
+ {
+ "dst",
+ "dest",
+ "destination",
+ "target",
+ "output",
+ "out",
+ "save_directory",
+ "f",
+ # `shutil.unpack_archive(a, extract_dir = d)` writes the members under `d`.
+ "extract_dir",
+ }
+)
+
+
+# Spawning a child hands the path to a process this scan does not see, so its argv is screened wholesale.
+_PY_PATH_SUBPROCESS_CALLS = frozenset(
+ # `os.popen(cmd)` runs the command line through a shell exactly as `os.system` does; only the
+ # handle it returns differs, and that is not what decides whether the child touched a path.
+ {
+ "run",
+ "Popen",
+ "call",
+ "check_call",
+ "check_output",
+ "getoutput",
+ "getstatusoutput",
+ "system",
+ "popen",
+ }
+)
+
+
+# Callables whose SECOND argument is the destination (shutil.copy(src, dst), os.rename(a, b)).
+# The members of the table below that REMOVE the source: after one, the source path is gone.
+_PY_PATH_MOVE_CALLS = frozenset({"move", "rename", "renames", "replace"})
+
+
+# `os.symlink(target, name)` does not remove its target, but it hands the sandbox a name that WRITES
+# to it, so the target is checked as a write for the same reason the terminal `ln` source is. The
+# call itself creates the escape, which is what separates it from the pre-existing-symlink residual.
+_PY_PATH_LINK_CALLS = frozenset({"link", "symlink"})
+
+
+# Archive members are written UNDER the destination these take, so it is a write of a whole tree.
+_PY_PATH_EXTRACT_CALLS = frozenset({"extract", "extractall"})
+
+
+_PY_PATH_DEST_SECOND_CALLS = frozenset(
+ {
+ "copy",
+ "copy2",
+ "copyfile",
+ "copytree",
+ "copymode",
+ "copystat",
+ "move",
+ "rename",
+ "renames",
+ "replace",
+ "link",
+ "symlink",
+ # `shutil.unpack_archive(filename, extract_dir)` reads the archive and CREATES its members
+ # under the destination, so the pair reads exactly like a copy.
+ "unpack_archive",
+ }
+)
+
+
+# Keyword arguments that carry a path on these callables.
+_PY_PATH_KWARGS = (
+ "path",
+ "file",
+ "filename",
+ "filepath",
+ "file_path",
+ "fname",
+ "name",
+ "src",
+ "source",
+ "dst",
+ "dest",
+ "destination",
+ "output",
+ "out",
+ "path_or_buf",
+ "filepath_or_buffer",
+ "save_directory",
+ "directory",
+ "folder",
+ "dirname",
+ "top",
+)
+
+
+# Path parameters named by one callable only, which is why they are not in the shared list above: a
+# bare `filenames = ` or `pathname = ` elsewhere is not necessarily a path this scan should open.
+_PY_PATH_KWARGS_BY_CALL = {
+ "read": ("filenames",),
+ # Pillow's `Image.open(fp = ...)`, and the stdlib spellings that name the file differently.
+ "open": ("fp",),
+ "imread": ("fname",),
+ "load": ("file",),
+ "glob": ("pathname", "root_dir"),
+ "iglob": ("pathname", "root_dir"),
+ "listdir": ("path",),
+ "scandir": ("path",),
+ "walk": ("top",),
+ # `pandas.read_excel(io = ...)`: `io` is the documented name of its first parameter.
+ "read_excel": ("io",),
+ # `shutil.make_archive(base_name, format, root_dir, base_dir)`: the archive is the first
+ # argument (a write), and the two directories it packs are reads.
+ "make_archive": ("root_dir", "base_dir"),
+}
+
+
+# Positional arguments that are SOURCE paths on a call whose first argument is already classified.
+# `shutil.make_archive("backup", "zip", "/home/alice/private")` passes the directory it packs third.
+_PY_PATH_EXTRA_READ_POSITIONS = {"make_archive": (2, 3)}
+
+
+# Every call name the path tables model, so an alias of any of them resolves back. Built from the
+# tables themselves rather than repeated by hand, so a name added to one is aliasable at once.
+_PY_ALIASABLE_PATH_CALLS = (
+ frozenset({"open", "fdopen"})
+ | _PY_PATH_READ_CALLS
+ | _PY_PATH_WRITE_CALLS
+ | _PY_PATH_DEST_SECOND_CALLS
+ | _PY_PATH_SERIALIZE_CALLS
+ | _PY_PATH_CONTENT_FIRST_CALLS
+ | _PY_PATH_ARCHIVE_CTORS
+ | _PY_PATH_SUBPROCESS_CALLS
+)
+
+
+def _python_function_aliases(tree, module_aliases: "dict | None" = None) -> dict:
+ """Local name -> real function, for `from io import open as fopen` and `reader = open`.
+
+ Every MODELED path call is covered, not only the open-like ones: `from pandas import read_csv as
+ rc` leaves a plain `Name` under a name in no table, so the call is never dispatched and its path
+ argument is never looked at. Restricting this to `open` left every other reader and writer in
+ the tables reachable under an alias.
+
+ A plain assignment binds the same identity as an import does, so `reader = open` and
+ `rc = pandas.read_csv` are followed too. An attribute is only followed when its receiver is a
+ modelled module, so `sock.open` and `self.open` stay unmodelled rather than resolving to the
+ builtin. A name assigned more than once is dropped: which function it holds at the call is not
+ answerable here, and guessing either way would be wrong half the time.
+ """
+ aliases: dict = {}
+ assigned: dict = {}
+ seen_twice: "set[str]" = set()
+ for node in _tree_nodes(tree):
+ if isinstance(node, ast.ImportFrom):
+ for entry in node.names:
+ if entry.asname and entry.name in _PY_ALIASABLE_PATH_CALLS:
+ aliases[entry.asname] = entry.name
+ continue
+ # `reader: object = open` binds exactly what the unannotated form does.
+ if isinstance(node, ast.AnnAssign):
+ if node.value is None or not isinstance(node.target, ast.Name):
+ continue
+ node = ast.Assign(targets = [node.target], value = node.value)
+ if not isinstance(node, ast.Assign):
+ continue
+ value = node.value
+ if isinstance(value, ast.Name):
+ real = value.id
+ elif isinstance(value, ast.Attribute) and isinstance(value.value, ast.Name):
+ receiver = value.value.id
+ receiver = (module_aliases or {}).get(receiver, receiver)
+ real = value.attr if receiver in _PY_MODULE_PATH_RECEIVERS else None
+ else:
+ real = None
+ for target in node.targets:
+ if not isinstance(target, ast.Name):
+ continue
+ # A rebinding does not undo the calls BEFORE it: `reader = open;
+ # reader('/media/x').read(); reader = None` performs the read, and dropping the name
+ # outright let it through. The first modelled binding is kept, and a later one is
+ # ignored rather than replacing it, which is the fail-closed reading of an order this
+ # whole-tree pass does not track. Nothing is gated by the binding alone: the name has to
+ # be CALLED with a path outside the sandbox before it reaches an approval.
+ if target.id in seen_twice:
+ # A first binding that was not itself modelled leaves room for a later one.
+ if real and real != target.id:
+ assigned.setdefault(target.id, real)
+ continue
+ seen_twice.add(target.id)
+ # Recorded even when the right-hand side is not itself a modelled name: `reader2 =
+ # reader` only becomes meaningful once the chain below resolves it, and an entry that
+ # never lands on a modelled call is dropped there.
+ if real and real != target.id:
+ assigned[target.id] = real
+ for name, real in assigned.items():
+ aliases.setdefault(name, real)
+ # `reader = open; reader2 = reader` binds the same function one step further out, so each alias
+ # is followed to the modelled name at the end of its chain. Bounded by the number of aliases,
+ # and a cycle simply stops when a name repeats.
+ resolved: dict = {}
+ for name, real in aliases.items():
+ seen = {name}
+ while real in aliases and real not in seen:
+ seen.add(real)
+ real = aliases[real]
+ if real in _PY_ALIASABLE_PATH_CALLS:
+ resolved[name] = real
+ return resolved
+
+
+def _python_module_aliases(tree) -> dict:
+ """Local name -> real module, for `import io as stream` and `import os.path as p`.
+
+ Only the ROOT module is recorded, which is what the receiver tables are keyed on.
+
+ `from PIL import Image as I` counts too: `Image` is itself a modelled receiver, so `I.open(p)`
+ has to resolve back to it or the call reads as a Path-style method and the filename argument is
+ never looked at.
+ """
+ aliases: dict = {}
+ assigned: "list[tuple[str, str]]" = []
+ for node in _tree_nodes(tree):
+ if isinstance(node, ast.ImportFrom):
+ for entry in node.names:
+ if entry.asname and entry.name in _PY_MODULE_PATH_RECEIVERS:
+ aliases[entry.asname] = entry.name
+ continue
+ # `stream = io` copies the module under a new name, exactly as `import io as stream` does.
+ # Resolved after the walk, since the import it refers to may come later in the source.
+ if isinstance(node, ast.Assign) and isinstance(node.value, ast.Name):
+ for target in node.targets:
+ if isinstance(target, ast.Name) and target.id != node.value.id:
+ assigned.append((target.id, node.value.id))
+ if not isinstance(node, ast.Import):
+ continue
+ for entry in node.names:
+ root = entry.name.split(".", 1)[0]
+ aliases[entry.asname or root] = root
+ # A copy only counts when what it copies resolves to a modelled module, so `x = some_object`
+ # binds nothing. Followed to the end of its chain, and a name bound more than once is dropped.
+ bound_twice = {name for name, _ in assigned if sum(1 for n, _ in assigned if n == name) > 1}
+ for name, source in assigned:
+ if name in bound_twice or name in aliases:
+ continue
+ seen = {name}
+ while source in dict(assigned) and source not in seen and source not in aliases:
+ seen.add(source)
+ source = dict(assigned)[source]
+ root = aliases.get(source, source)
+ if root in _PY_MODULE_PATH_RECEIVERS:
+ aliases[name] = root
+ return aliases
+
+
+def _chained_instance_reader_methods(receiver, module_aliases: "dict | None" = None) -> frozenset:
+ """Reader methods for `ConfigParser().read(p)`, where the receiver is the constructor call."""
+ if not isinstance(receiver, ast.Call):
+ return frozenset()
+ func = receiver.func
+ if isinstance(func, ast.Attribute):
+ name = func.attr
+ elif isinstance(func, ast.Name):
+ name = (module_aliases or {}).get(func.id, func.id)
+ else:
+ return frozenset()
+ return _PY_INSTANCE_READ_CTORS.get(name, frozenset())
+
+
+# `ZipFile.write(src)` and `TarFile.add(src)` name a file ON DISK and copy it INTO the archive, so
+# the first argument is a path being READ. That is the opposite of `f.write(data)`, which is why the
+# receiver has to identify it. Only the member-based archives: a `GzipFile`/`BZ2File` write takes
+# data, exactly like an ordinary file object.
+_PY_ARCHIVE_SOURCE_CALLS = frozenset({"write", "add"})
+_PY_ARCHIVE_MEMBER_CTORS = frozenset({"ZipFile", "TarFile"})
+
+
+def _python_archive_ctor_names(tree) -> "set[str]":
+ """Local names imported FROM an archive module that construct one.
+
+ `from tarfile import open as topen` binds a constructor under a name whose resolved spelling is
+ `open`, which is the builtin everywhere else, so the module it came from is what identifies it.
+ """
+ names: "set[str]" = set()
+ for node in _tree_nodes(tree):
+ if isinstance(node, ast.ImportFrom) and node.module in ("tarfile", "zipfile"):
+ for entry in node.names:
+ if entry.name in ("open", "ZipFile", "TarFile"):
+ names.add(entry.asname or entry.name)
+ return names
+
+
+def _is_archive_ctor_call(
+ node,
+ module_aliases = None,
+ local_ctors = frozenset(),
+) -> bool:
+ """True for `zipfile.ZipFile(...)`, `ZipFile(...)`, `tarfile.open(...)` and their aliases."""
+ if not isinstance(node, ast.Call):
+ return False
+ func = node.func
+ if isinstance(func, ast.Attribute):
+ receiver = func.value
+ base = receiver.id if isinstance(receiver, ast.Name) else ""
+ base = (module_aliases or {}).get(base, base)
+ # `tarfile.open` / `zipfile.ZipFile` are the documented constructors.
+ return func.attr in _PY_ARCHIVE_MEMBER_CTORS or (
+ func.attr == "open" and base in ("tarfile", "zipfile")
+ )
+ if isinstance(func, ast.Name):
+ return (
+ func.id in local_ctors
+ or (module_aliases or {}).get(func.id, func.id) in _PY_ARCHIVE_MEMBER_CTORS
+ )
+ return False
+
+
+def _python_archive_object_names(
+ tree,
+ module_aliases = None,
+ local_ctors = frozenset(),
+) -> "set[str]":
+ """Local names holding a member-based archive, bound by assignment or by `with ... as`."""
+ names: "set[str]" = set()
+
+ def bind(target, value) -> None:
+ if isinstance(target, ast.Name) and _is_archive_ctor_call(
+ value, module_aliases, local_ctors
+ ):
+ names.add(target.id)
+
+ for node in _tree_nodes(tree):
+ if isinstance(node, ast.Assign):
+ for target in node.targets:
+ bind(target, node.value)
+ elif isinstance(node, ast.AnnAssign) and node.value is not None:
+ bind(node.target, node.value)
+ elif isinstance(node, (ast.With, ast.AsyncWith)):
+ for item in node.items:
+ bind(item.optional_vars, item.context_expr)
+ return names
+
+
+def _python_instance_reader_names(tree) -> dict:
+ """`local name -> reader methods`, for a reader reached through an instance.
+
+ `cfg = ConfigParser(); cfg.read(p)` opens p, and `read` on any other receiver is an ordinary
+ method, so the CONSTRUCTOR is what identifies it. Import aliases count. The chained
+ `ConfigParser().read(p)` binds no name and is resolved separately, at the call site.
+ """
+ ctors = dict(_PY_INSTANCE_READ_CTORS)
+ for node in _tree_nodes(tree):
+ if isinstance(node, ast.ImportFrom):
+ for entry in node.names:
+ if entry.asname and entry.name in _PY_INSTANCE_READ_CTORS:
+ ctors[entry.asname] = _PY_INSTANCE_READ_CTORS[entry.name]
+ names: dict = {}
+ for node in _tree_nodes(tree):
+ # `cfg: ConfigParser = ConfigParser()` binds exactly what the unannotated form binds.
+ if isinstance(node, ast.AnnAssign) and node.value is not None:
+ if not isinstance(node.target, ast.Name):
+ continue
+ node = ast.Assign(targets = [node.target], value = node.value)
+ if not isinstance(node, ast.Assign) or not isinstance(node.value, ast.Call):
+ continue
+ func = node.value.func
+ ctor = func.attr if isinstance(func, ast.Attribute) else getattr(func, "id", "")
+ methods = ctors.get(ctor)
+ if not methods:
+ continue
+ for target in node.targets:
+ if isinstance(target, ast.Name):
+ names[target.id] = methods
+ return names
+
+
+def _python_qualified_read_aliases(tree) -> "set[str]":
+ """Local names bound from a module whose reader is only modelled QUALIFIED.
+
+ `numpy.load` takes a filename while every other `load` in these tables takes an open file, so the
+ name is keyed on its module. `from numpy import load` and `from numpy import load as read_array`
+ drop that module, and the call arrives as a bare Name the reader table deliberately omits.
+ """
+ aliases: "set[str]" = set()
+ for node in _tree_nodes(tree):
+ if not isinstance(node, ast.ImportFrom):
+ continue
+ module = (node.module or "").split(".")[0]
+ readers = _PY_QUALIFIED_READ_CALLS.get(module)
+ if not readers:
+ continue
+ for entry in node.names:
+ if entry.name in readers:
+ aliases.add(entry.asname or entry.name)
+ return aliases
+
+
+# Method names that mean a filesystem operation on a path OBJECT and something else entirely on any
+# other receiver: `text.replace(a, b)` and `items.remove(x)` touch no file. The qualified forms
+# (`os.replace`, `os.remove`) are unambiguous and are handled by the module receiver instead.
+_PY_AMBIGUOUS_PATH_METHODS = frozenset({"replace", "remove"})
+
+
+def _receiver_is_a_path_object(receiver, ctors, path_objects) -> bool:
+ """True when the receiver of an ambiguous method is a `Path`-like value.
+
+ A direct `Path(p).replace(q)`, a name bound to one, or a chain off either. Anything else -- a
+ str, a list, a DataFrame -- is left alone, which is what the pre-existing analyzer did by
+ keeping these names qualified.
+ """
+ while isinstance(receiver, ast.Attribute):
+ receiver = receiver.value
+ if isinstance(receiver, ast.Call):
+ func = receiver.func
+ name = func.attr if isinstance(func, ast.Attribute) else getattr(func, "id", "")
+ return name in ctors
+ if isinstance(receiver, ast.Name):
+ return receiver.id in path_objects
+ return False
+
+
+def _python_path_object_names(tree, ctors) -> "set[str]":
+ """Local names bound to a `Path`-like object, by assignment or by `with ... as`."""
+ names: "set[str]" = set()
+
+ def bind(target, value) -> None:
+ if not isinstance(target, ast.Name) or not isinstance(value, ast.Call):
+ return
+ func = value.func
+ name = func.attr if isinstance(func, ast.Attribute) else getattr(func, "id", "")
+ if name in ctors:
+ names.add(target.id)
+
+ for node in _tree_nodes(tree):
+ if isinstance(node, ast.Assign):
+ for target in node.targets:
+ bind(target, node.value)
+ elif isinstance(node, ast.AnnAssign) and node.value is not None:
+ bind(node.target, node.value)
+ elif isinstance(node, (ast.With, ast.AsyncWith)):
+ for item in node.items:
+ bind(item.optional_vars, item.context_expr)
+ return names
+
+
+def _python_path_fold_aliases(tree) -> "tuple[set, set]":
+ """`(path constructor names, os.path.join names)`, including the local names imports bind them to.
+
+ `from pathlib import Path as P` leaves `P(...)` under a name the fold does not know, so the call
+ resolves to nothing and the path it builds is never checked. The main analyzer already collects
+ these for its own fold; the operand pass needs the same two sets.
+ """
+ ctors = set(_PATH_CTORS)
+ joins: "set[str]" = set()
+ for node in _tree_nodes(tree):
+ if isinstance(node, ast.ImportFrom):
+ module = node.module or ""
+ for entry in node.names:
+ local = entry.asname or entry.name
+ if entry.name in _PATH_CTORS:
+ ctors.add(local)
+ elif entry.name == "join" and (module == "os.path" or module.endswith(".path")):
+ joins.add(local)
+ continue
+ # `P = Path` binds the constructor exactly as an import alias does, and `j = os.path.join`
+ # the join. Without this the call folded to nothing and the path it built was never seen.
+ if not isinstance(node, ast.Assign):
+ continue
+ value = node.value
+ if isinstance(value, ast.Name):
+ source = value.id
+ elif isinstance(value, ast.Attribute):
+ source = value.attr
+ else:
+ continue
+ for target in node.targets:
+ if not isinstance(target, ast.Name) or target.id == source:
+ continue
+ if source in ctors:
+ ctors.add(target.id)
+ elif source in joins or source == "join":
+ joins.add(target.id)
+ return ctors, joins
+
+
+def _python_path_bindings(
+ tree,
+ ctors = None,
+ joins = None,
+) -> dict:
+ """Names bound to a foldable path (`p = '/media/x'`, `p := Path('/media') / 'x'`), so a read
+ through the variable folds to the same path a literal would.
+
+ A name bound more than once keeps EVERY path it was bound to, not the last one: rebinding
+ ``p`` after the read must not reclassify the read that already happened.
+
+ EVERY target of a chained assignment is bound, not just the first: `src = backup = '/media/x'`
+ has to make `open(src)` foldable, or the read runs unprompted.
+ """
+ bindings: dict = {}
+ extra: "dict[str, list[str]]" = {}
+ for node in _tree_nodes(tree):
+ if isinstance(node, ast.Assign):
+ targets, value = list(node.targets), node.value
+ elif isinstance(node, ast.NamedExpr):
+ targets, value = [node.target], node.value
+ elif isinstance(node, ast.AnnAssign) and node.value is not None:
+ targets, value = [node.target], node.value
+ else:
+ continue
+ # `p, _ = "/media/x", 1` binds elementwise, and it does so per target, so the tuple halves of
+ # `a, b = c, d = "/media/x", "/media/y"` are both reached.
+ pairs = []
+ for target in targets:
+ if isinstance(target, ast.Tuple) and isinstance(value, (ast.Tuple, ast.List)):
+ pairs.extend(zip(target.elts, value.elts))
+ else:
+ pairs.append((target, value))
+ for target, bound in pairs:
+ if not isinstance(target, ast.Name):
+ continue
+ try:
+ folded = _folded_path(bound, bindings, ctors, joins)
+ except Exception: # noqa: BLE001 - folding is best effort
+ continue
+ # A name this value is DERIVED from may itself have held other paths, and folding with
+ # the primary binding alone loses them: `base = 'local'; base = '/media/x'; p = base +
+ # '/f'` folded p to `local/f` only, so the out-of-sandbox read through p was invisible.
+ # One alternate is substituted at a time rather than the full cartesian product, which
+ # keeps this linear in the number of rebindings.
+ derived: "list[str]" = []
+ if extra:
+ for used in {n.id for n in ast.walk(bound) if isinstance(n, ast.Name)}:
+ for alternate in _capped_alternates(extra.get(used, ())):
+ try:
+ other = _folded_path(bound, {**bindings, used: alternate}, ctors, joins)
+ except Exception: # noqa: BLE001 - folding is best effort
+ continue
+ if isinstance(other, str) and other and "\x00" not in other:
+ derived.append(other)
+ if not isinstance(folded, str) or not folded or "\x00" in folded:
+ # The primary fold failed, but a rebound dependency can still make it resolvable.
+ for candidate in _capped_alternates(derived):
+ extra.setdefault(target.id, []).append(candidate)
+ continue
+ if target.id in bindings and bindings[target.id] != folded:
+ extra.setdefault(target.id, []).append(folded)
+ else:
+ bindings[target.id] = folded
+ for candidate in _capped_alternates(derived):
+ if candidate != bindings.get(target.id):
+ extra.setdefault(target.id, []).append(candidate)
+ # Rebindings ride along under a private key so `add` can test every value a name ever held.
+ if extra:
+ bindings[_REBOUND_PATHS_KEY] = extra
+ return bindings
+
+
+# Private key inside the bindings map holding `name -> [other paths it was bound to]`.
+_REBOUND_PATHS_KEY = "\x00__rebound__"
+
+
+# Ceiling on alternates carried through a derived binding. A loop that rebinds a name many times
+# would otherwise grow this without bound for no extra signal.
+_MAX_REBOUND_ALTERNATES = 8
+
+
+# Rebound names substituted into one compound expression, bounding the work on a snippet that
+# assembles a path from many variables each bound several times.
+_MAX_REBOUND_NAMES = 3
+
+
+def _capped_alternates(values) -> "list[str]":
+ """Bound a list of candidate paths WITHOUT dropping the ones that can need approval.
+
+ A plain slice discards by position, so eight benign reassignments ahead of
+ `base = "/media/private"` hid the only value that mattered. Absolute candidates are kept first
+ and the cap is spent on the remainder, so the bound limits work rather than coverage.
+ """
+ values = list(values)
+ if len(values) <= _MAX_REBOUND_ALTERNATES:
+ return values
+
+ # Ranked by what the value would COST, not by whether it happens to be absolute: a path under a
+ # silent root needs no approval, so filling the cap with sandbox rebindings would drop the one
+ # `/media/...` value that does. Ordering by need keeps the bound on work, not coverage.
+ # The cap is spent here, before the access mode is known, so BOTH modes have to be represented
+ # or one of them starves. The write-silent roots are a subset of the read-silent ones, which
+ # gives a total order: a value gated for reading is gated for writing too, a value like
+ # `/usr/share` is gated only for writing, and a sandbox path is gated for neither. Ranking on
+ # read alone dropped `/usr/share` and let the `open(p, "w")` that followed overwrite it in
+ # silence; ranking on "either mode" let nine `/usr/...` rebindings crowd out the one `/media/...`
+ # value. Ordering by strength keeps both.
+ def rank(value: str) -> int:
+ if _path_needs_approval(value):
+ return 0
+ return 1 if _path_needs_approval(value, writing = True) else 2
+
+ ranked: "list[list[str]]" = [[], [], []]
+ for value in values:
+ ranked[rank(value)].append(value)
+ return (ranked[0] + ranked[1] + ranked[2])[:_MAX_REBOUND_ALTERNATES]
+
+
+def _sequence_elements(node, containers) -> "list":
+ """The elements of a literal sequence, or the node itself when it is not one.
+
+ A NAME holding one counts: `paths = ["/media/x"]; cfg.read(paths)` passes the same list the
+ inline form passes, and handing the bare name to the fold resolved nothing. The paths come from
+ the literal containers already collected for subscripts, so there is one place that knows what a
+ name holds.
+ """
+ if node is None:
+ return []
+ if isinstance(node, (ast.List, ast.Tuple)):
+ return list(node.elts)
+ if isinstance(node, ast.Name) and node.id in containers:
+ return [ast.Constant(value = path) for path in containers[node.id]]
+ return [node]
+
+
+def _sqlite_opens_read_only(node, given = None) -> bool:
+ """True when a sqlite connection is provably read-only: a `file:...?mode=ro` URI."""
+ first = given if given is not None else (node.args[0] if node.args else None)
+ if not isinstance(first, ast.Constant) or not isinstance(first.value, str):
+ return False
+ lowered = first.value.lower()
+ return lowered.startswith("file:") and ("mode=ro" in lowered or "immutable=1" in lowered)
+
+
+def _call_keywords(node) -> "list":
+ """A call's keywords, with a LITERAL `**{...}` splat expanded into the keywords it stands for.
+
+ `pd.read_csv(**{"filepath_or_buffer": "/media/x"})` passes the path under its own parameter
+ name; the splat arrives as a keyword whose `arg` is None, so the name was never matched.
+ """
+ keywords = list(node.keywords)
+ for keyword in node.keywords:
+ if keyword.arg is not None or not isinstance(keyword.value, ast.Dict):
+ continue
+ for key, value in zip(keyword.value.keys, keyword.value.values):
+ if isinstance(key, ast.Constant) and isinstance(key.value, str):
+ keywords.append(ast.keyword(arg = key.value, value = value))
+ return keywords
+
+
+def _python_fileinput_readers(tree) -> "set[str]":
+ """Local names bound by `from fileinput import input` / `FileInput`, with or without an alias.
+
+ Tracked by PROVENANCE rather than by name: a bare `input` is the builtin prompt on its own, and
+ only an import from this module makes it the reader that opens a file.
+ """
+ names: "set[str]" = set()
+ for node in ast.walk(tree):
+ if isinstance(node, ast.ImportFrom) and node.module == "fileinput":
+ for entry in node.names:
+ if entry.name in ("input", "FileInput"):
+ names.add(entry.asname or entry.name)
+ return names
+
+
+def _python_literal_containers(tree) -> dict:
+ """Name -> the absolute-looking strings a literal list, tuple or dict assigned to it holds."""
+ containers: dict = {}
+ for node in _tree_nodes(tree):
+ if isinstance(node, ast.AnnAssign) and node.value is not None:
+ targets, value = [node.target], node.value
+ elif isinstance(node, ast.Assign):
+ targets, value = node.targets, node.value
+ else:
+ continue
+ paths = _literal_container_paths(value)
+ if not paths:
+ continue
+ for target in targets:
+ if isinstance(target, ast.Name):
+ containers.setdefault(target.id, []).extend(paths)
+ return containers
+
+
+def _literal_container_paths(node) -> "list[str]":
+ """The absolute-looking strings a literal list, tuple or dict holds, values only for a dict."""
+ if isinstance(node, (ast.List, ast.Tuple)):
+ elements = node.elts
+ elif isinstance(node, ast.Dict):
+ elements = node.values
+ else:
+ return []
+ return [
+ element.value
+ for element in elements
+ if isinstance(element, ast.Constant)
+ and isinstance(element.value, str)
+ and _looks_absolute(element.value)
+ ]
+
+
+def _subscript_literal_paths(node, containers) -> "list[str]":
+ """The paths a subscript can resolve to, when everything about it is a literal.
+
+ A constant index resolves to the ONE element it names, which is both exact and free of the cap
+ below. Otherwise every path the container holds is a candidate, ranked so the ones that need
+ approval survive the cap: a container of nine paths whose last is the outside one would
+ otherwise have lost it to eight read-silent ones ahead of it.
+ """
+ target = node.value
+ paths = (
+ list(containers.get(target.id, ()))
+ if isinstance(target, ast.Name)
+ else _literal_container_paths(target)
+ )
+ index = node.slice
+ if isinstance(index, ast.Constant) and isinstance(index.value, int) and paths:
+ # The literal index is into the container as WRITTEN, and only the absolute strings of it
+ # are collected here, so this resolves exactly when the container is all paths.
+ exact = _exact_indexed_path(target, containers, index.value)
+ if exact is not None:
+ return [exact]
+ return _capped_alternates(paths)
+
+
+def _exact_indexed_path(target, containers, index: int) -> "str | None":
+ """The element a constant index names, when every element of the container is an absolute path."""
+ if isinstance(target, (ast.List, ast.Tuple)):
+ elements = target.elts
+ else:
+ return None
+ if not all(
+ isinstance(element, ast.Constant) and isinstance(element.value, str) for element in elements
+ ):
+ return None
+ try:
+ value = elements[index].value
+ except IndexError:
+ return None
+ return value if _looks_absolute(value) else None
+
+
+def _python_path_operands(tree) -> "list[tuple[str, bool]]":
+ """Absolute path operands a python snippet reads or writes, as ``(path, writing)``.
+
+ Reuses ``_folded_path`` so a path assembled from literals, an f-string, ``os.path.join`` or a
+ ``Path`` chain resolves the same way the credential scan resolves it. A path the folder cannot
+ resolve yields nothing here; the dynamic-alias checks elsewhere cover those.
+ """
+ ctors, joins = _python_path_fold_aliases(tree)
+ qualified_readers = _python_qualified_read_aliases(tree)
+ instance_readers = _python_instance_reader_names(tree)
+ bindings = _python_path_bindings(tree, ctors, joins)
+ rebound = bindings.get(_REBOUND_PATHS_KEY) or {}
+ module_aliases = _python_module_aliases(tree)
+ function_aliases = _python_function_aliases(tree, module_aliases)
+ # `from zipfile import ZipFile as Z` binds the constructor under a name no table holds, so the
+ # function aliases count here exactly as the module ones do.
+ archive_aliases = {**module_aliases, **function_aliases}
+ archive_ctors = _python_archive_ctor_names(tree)
+ path_objects = _python_path_object_names(tree, ctors)
+ archive_objects = _python_archive_object_names(tree, archive_aliases, archive_ctors)
+ containers = _python_literal_containers(tree)
+ fileinput_readers = _python_fileinput_readers(tree)
+ operands: "list[tuple[str, bool]]" = []
+
+ def add_subprocess_operands(call) -> None:
+ """Screen a child process's argv with the terminal operand scanner.
+
+ Handing the words to the shell scan keeps the read/write distinction: `["cp", "a", "/etc/b"]`
+ is a write to /etc, not a read of it. `shell = True` passes one command line, which splits
+ the same way.
+ """
+ words: "list[str]" = []
+ for argument in (*call.args, *(k.value for k in call.keywords)):
+ for piece in ast.walk(argument):
+ if isinstance(piece, ast.Constant) and isinstance(piece.value, str):
+ words.extend(_shell_words(piece.value))
+ elif isinstance(piece, ast.Name):
+ # Split a folded value the same way a literal is split. `cmd = "cat /media/x";
+ # subprocess.run(cmd, shell = True)` otherwise appended one unrecognised word,
+ # so the operand scan saw no command and no path.
+ folded = bindings.get(piece.id)
+ if isinstance(folded, str) and folded:
+ words.extend(_shell_words(folded))
+ for path in rebound.get(piece.id, ()):
+ words.extend(_shell_words(path))
+ # `subprocess.run(["echo"], executable = "/media/x")` LAUNCHES that binary; argv[0] is only
+ # what the child sees as its name. Scanned on its own, since a recognised argv command
+ # otherwise suppressed the fallback that would have caught it.
+ for keyword in _call_keywords(call):
+ if keyword.arg == "executable":
+ add(keyword.value, False)
+ # argv[0] IS the binary that runs, whatever follows it. A recognised command name later in
+ # the list (`["/media/x/payload", "cat"]`) made the operand scan return something, which
+ # suppressed the bare-path fallback below, so the outside binary launched unscreened.
+ head = call.args[0] if call.args else None
+ if isinstance(head, (ast.List, ast.Tuple)) or (
+ isinstance(head, ast.Name) and head.id in containers
+ ):
+ argv0 = next(iter(_sequence_elements(head, containers)), None)
+ if argv0 is not None:
+ add(argv0, False)
+ # `subprocess.run(["python", "-c", "open('/media/x', 'w')"])` carries CODE, not a path, so
+ # the terminal operand scan sees nothing. The payload goes through the python scan instead.
+ elements = _sequence_elements(call.args[0], containers) if call.args else []
+ literals = [
+ e.value for e in elements if isinstance(e, ast.Constant) and isinstance(e.value, str)
+ ]
+ for index, literal in enumerate(literals[:-1]):
+ if (
+ literal in ("-c", "-e")
+ and _token_command_base(literals[0]) in _PATH_SCRIPT_COMMANDS
+ ):
+ operands.extend(_inline_code_operands(literals[index + 1]))
+ if words:
+ from_command = _terminal_path_operands(words)
+ operands.extend(from_command)
+ # A bare path with no recognised command around it still reaches the child. Only then:
+ # once the scan has classified the child command, `subprocess.run(["echo", "/home/x"])`
+ # is the same nothing `echo /home/x` is at a terminal, and prompting on one and not the
+ # other was a difference with no reason behind it.
+ if not from_command and not any(
+ _token_command_base(word) in _classified_terminal_commands() for word in words
+ ):
+ operands.extend((word, False) for word in words if _looks_absolute(word))
+
+ def add(node, writing: bool) -> None:
+ if node is None:
+ return
+ # `open(p := "/media/x")` passes the assigned VALUE to the call, so fold through the walrus.
+ if isinstance(node, ast.NamedExpr):
+ node = node.value
+ # `pd.read_csv(*["/media/x.csv"])` hands the reader a literal path through a splat, which
+ # the fold has no value for. Only a literal sequence is unpacked, so nothing dynamic is
+ # guessed at.
+ if isinstance(node, ast.Starred):
+ for element in _sequence_elements(node.value, containers):
+ if element is not node.value:
+ add(element, writing)
+ return
+ try:
+ folded = _folded_path(node, bindings, ctors, joins)
+ except Exception: # noqa: BLE001
+ return
+ if isinstance(folded, str) and folded:
+ operands.append((folded, writing))
+ elif isinstance(node, ast.Subscript):
+ # `paths = ["/media/x"]; open(paths[0])` and `open({"p": "/media/x"}["p"])` name the
+ # path with nothing dynamic in them, and the fold has no value for a subscript. Every
+ # literal the container holds counts rather than the indexed one: the index is not
+ # always constant, and a container of paths is read through whichever element is picked.
+ for path in _subscript_literal_paths(node, containers):
+ operands.append((path, writing))
+ # A name rebound elsewhere in the snippet reaches every path it ever held, and the scan
+ # cannot order the statements, so each candidate counts.
+ if isinstance(node, ast.Name) and node.id in rebound:
+ operands.extend((path, writing) for path in rebound[node.id])
+ return
+ # The same name inside a larger expression: `open(base + '/report')` folds `base` to one of
+ # its bindings and the others never reach the gate. Substituted one name at a time, since a
+ # path is assembled from one variable and literals far more often than from two.
+ names = [
+ piece.id
+ for piece in ast.walk(node)
+ if isinstance(piece, ast.Name) and piece.id in rebound
+ ]
+ for rebound_name in list(dict.fromkeys(names))[:_MAX_REBOUND_NAMES]:
+ for alternate in rebound[rebound_name]:
+ try:
+ refolded = _folded_path(
+ node, {**bindings, rebound_name: alternate}, ctors, joins
+ )
+ except Exception: # noqa: BLE001 - folding is best effort
+ continue
+ if isinstance(refolded, str) and refolded and refolded != folded:
+ operands.append((refolded, writing))
+
+ for node in _tree_nodes(tree):
+ if not isinstance(node, ast.Call):
+ continue
+ func = node.func
+ if isinstance(func, ast.Attribute):
+ name = func.attr
+ elif isinstance(func, ast.Name):
+ # `from io import open as fopen` leaves a plain Name in no table; resolve it back.
+ name = function_aliases.get(func.id, func.id)
+ else:
+ continue
+ first = node.args[0] if node.args else None
+ second = node.args[1] if len(node.args) > 1 else None
+ is_method = isinstance(func, ast.Attribute)
+ # Whether an attribute call's receiver is a MODULE rather than a path, resolved through the
+ # import aliases. Decided once here: every branch below that treats the receiver as a path
+ # has a module-function counterpart that does not.
+ receiver_name = (
+ module_aliases.get(getattr(func.value, "id", ""), getattr(func.value, "id", ""))
+ if is_method
+ else ""
+ )
+ module_receiver = is_method and receiver_name in _PY_MODULE_PATH_RECEIVERS
+ writing_default = name in _PY_PATH_WRITE_CALLS
+ if name in _PY_MODULE_OPEN_CTORS and receiver_name in _PY_MODULE_OPEN_RECEIVERS:
+ # `io.FileIO(p)` opens the path the same way `io.open(p)` does; the mode argument is a
+ # string in the same position, so the write decision is the open one.
+ add(first, _open_call_writes(node, mode_index = 1))
+ elif name in ("open", "fdopen"):
+ # The mode decides: `open(p)` reads, `open(p, 'w')` creates or truncates. As a METHOD
+ # (Path(p).open('w')) the receiver is the path, so the mode moves to the first argument.
+ # os.open is the low-level create and counts as a write either way.
+ #
+ # An attribute call is NOT automatically receiver-based: `io.open(p)`, `gzip.open(p)` and
+ # the rest of _PY_MODULE_OPEN_RECEIVERS are module functions taking the path FIRST, so
+ # folding their receiver yields the bare module name and the read escapes unprompted.
+ # `import io as stream` makes the receiver `stream`, which is in no table; the alias is
+ # resolved above, or the call reads as a Path-style method and the path argument is
+ # never looked at.
+ receiver = receiver_name
+ # A dotted receiver has no `.id`, so `PIL.Image.open(p)` left receiver_name empty and
+ # read as a Path-style method. The trailing name is the one the table is keyed on.
+ tail = func.value.attr if is_method and isinstance(func.value, ast.Attribute) else ""
+ path_is_receiver = is_method and not (
+ receiver in _PY_MODULE_OPEN_RECEIVERS or tail in _PY_MODULE_OPEN_RECEIVERS
+ )
+ writing = _open_call_writes(node, mode_index = 0 if path_is_receiver else 1) or (
+ receiver in ("os", "posix")
+ )
+ writing_default = writing
+ add(func.value if path_is_receiver else first, writing)
+ elif name in _PY_PATH_ARCHIVE_CTORS:
+ # ZipFile(name) reads, ZipFile(name, "w") writes -- the same mode position as open().
+ writing = _open_call_writes(node, mode_index = 1)
+ writing_default = writing
+ add(first, writing)
+ elif name in _PY_PATH_SUBPROCESS_CALLS:
+ # A child process is not bound by this scan at all, so its argv is screened as a command line: that way
+ # `subprocess.run(["cp", "x", "/etc/y"])` is seen as the WRITE it is, not as two reads.
+ add_subprocess_operands(node)
+ elif (
+ name in _PY_AMBIGUOUS_PATH_METHODS
+ and is_method
+ and not module_receiver
+ and not _receiver_is_a_path_object(func.value, ctors, path_objects)
+ ):
+ # `text.replace(a, b)` and `items.remove(x)` transform data in memory. Only a Path-like
+ # receiver makes these the filesystem calls of the same name; `os.replace` / `os.remove`
+ # arrive with a module receiver and are dispatched below as before.
+ continue
+ elif name in _PY_PATH_DEST_SECOND_CALLS:
+ # shutil.copy(src, dst) as a function; as a METHOD (Path(p).rename(q)) the receiver is the source.
+ # `os.rename(...)` is spelled as an attribute but is the FUNCTION form, so its receiver is
+ # a module and both paths are arguments.
+ receiver_is_path = is_method and not module_receiver
+ # A move REMOVES its source, so that side is a write too: `os.rename('/models/w.gguf',
+ # 'stolen.gguf')` takes the file out of a read-silent root with a relative destination.
+ # A copy leaves its source alone, which is why this is not the whole table.
+ add(
+ func.value if receiver_is_path else first,
+ name in _PY_PATH_MOVE_CALLS or name in _PY_PATH_LINK_CALLS,
+ )
+ add(first if receiver_is_path else second, True)
+ elif name in _PY_PATH_SERIALIZE_CALLS and _serializes_to_second_arg(func, module_aliases):
+ # torch.save(obj, path) / joblib.dump(obj, path) put the DESTINATION second, the opposite of
+ # numpy.save(path, arr) and df.to_csv(path), so the receiver decides which argument to read.
+ add(second, True)
+ elif name in _PY_PATH_EXTRACT_CALLS:
+ # `ZipFile(a).extractall(dest)` and the tarfile equivalents CREATE files under the
+ # destination, which is the first argument for `extractall` and the second (`path = `)
+ # for `extract`. The archive itself is read by the constructor, which is modelled.
+ add(second if name == "extract" else first, True)
+ for keyword in _call_keywords(node):
+ if keyword.arg == "path":
+ add(keyword.value, True)
+ elif (
+ name in _PY_ARCHIVE_SOURCE_CALLS
+ and is_method
+ and (
+ receiver_name in archive_objects
+ or _is_archive_ctor_call(func.value, module_aliases)
+ )
+ ):
+ # The member being added comes FROM the filesystem.
+ add(first, False)
+ elif name in _PY_PATH_CONTENT_FIRST_CALLS:
+ # Path(p).write_text(content): the first argument is DATA, not a path. Only the receiver is a path, so a
+ # config value that happens to look like one ("/api/v1/items") must not read as a write target.
+ add(func.value if is_method else None, True)
+ elif name in _PY_PATH_WRITE_CALLS:
+ add(first, True)
+ if is_method:
+ add(func.value, True)
+ elif is_method and (
+ name in instance_readers.get(receiver_name, ())
+ or name in _chained_instance_reader_methods(func.value, module_aliases)
+ ):
+ # `cfg = ConfigParser(); cfg.read(p)`, the chained `ConfigParser().read(p)`, and the
+ # list form `cfg.read([a, b])`.
+ for element in _sequence_elements(first, containers):
+ add(element, False)
+ elif name in _PY_QUALIFIED_READ_CALLS.get(receiver_name, ()) or (
+ not is_method and name in qualified_readers
+ ):
+ # Qualified, because the bare name is ambiguous: `numpy.load(p)` opens a path while
+ # `json.load(f)`, `pickle.load(f)` and `torch.load(f)` all take an already-open file.
+ add(first, False)
+ elif (name in ("input", "FileInput") and is_method and receiver_name == "fileinput") or (
+ not is_method and func.id in fileinput_readers
+ ):
+ # Qualified so the builtin input("/data directory: ") prompt is not read as a file, and
+ # through the import aliases so `import fileinput as fi` resolves back. `FileInput` is
+ # the constructor `input` returns, and iterates the same files.
+ # `files = ` is the keyword spelling of the same argument, and takes a sequence too.
+ given = first
+ if given is None:
+ given = next((kw.value for kw in _call_keywords(node) if kw.arg == "files"), None)
+ for element in _sequence_elements(given, containers):
+ add(element, False)
+ elif name in ("connect", "Connection") and receiver_name in ("sqlite3", "apsw"):
+ # A connection CREATES the file if it is missing and can write it afterwards, so the
+ # database is a write target unless the URI says otherwise. (The whole call already
+ # prompts through the existing sqlite rule; this makes the operand itself accurate.)
+ # `sqlite3.connect(database = "/media/x/private.db")` is the documented keyword spelling
+ # of the same argument (`apsw.Connection` names it `filename`), and opens the same file.
+ given = first
+ if given is None:
+ given = next(
+ (kw.value for kw in _call_keywords(node) if kw.arg in ("database", "filename")),
+ None,
+ )
+ add(given, not _sqlite_opens_read_only(node, given))
+ elif name in _PY_TEMPFILE_CALLS:
+ # `tempfile.mkstemp(dir = "/media/x")` CREATES its file in that directory; without the
+ # keyword it lands in the sandbox's own TMPDIR, which is silent.
+ add(next((kw.value for kw in _call_keywords(node) if kw.arg == "dir"), None), True)
+ elif name in _PY_PATH_OPENING_CTORS:
+ # The mode applies to the keyword spelling of the path too (`h5py.File(name = ...,
+ # mode = "w")`), which reaches the shared keyword loop rather than this `add`.
+ writing_default = _ctor_opens_for_write(node)
+ add(first, writing_default)
+ elif name in _PY_PATH_READ_CALLS:
+ start = len(operands)
+ add(first, False)
+ if is_method:
+ add(func.value, False)
+ if name in _PY_RECURSIVE_READ_CALLS:
+ # The filesystem root itself is silent, because `ls /` names its entries and opens
+ # nothing. A RECURSIVE reader rooted there is a different act: it descends into
+ # every directory on the host, so what it reaches is reported instead of the root.
+ for path, _writing in operands[start:]:
+ if path.rstrip("/\\") == "":
+ operands.append((path.rstrip("/\\") + "/**", False))
+ else:
+ continue
+ for position in _PY_PATH_EXTRA_READ_POSITIONS.get(name, ()):
+ if position < len(node.args):
+ add(node.args[position], False)
+ for keyword in _call_keywords(node):
+ if keyword.arg in _PY_PATH_KWARGS_BY_CALL.get(name, ()):
+ # A parameter name only this callable uses, so it is read per call rather than from the
+ # shared list: `ConfigParser.read(filenames = ...)` takes a sequence as readily as a str.
+ for element in _sequence_elements(keyword.value, containers):
+ add(element, False)
+ elif keyword.arg in _PY_PATH_DEST_KWARGS:
+ add(keyword.value, True)
+ elif keyword.arg in _PY_PATH_KWARGS:
+ # `open(file = p, mode = "w")` is the same write the positional form is: carry the mode decided
+ # above rather than re-deriving it from a table that does not list `open`.
+ add(keyword.value, writing_default)
+ operands.extend(_python_directory_change_targets(tree, operands))
+ return operands
+
+
+def _python_reaches_outside_sandbox(tree, code = None) -> bool:
+ """True when python code reads or writes an absolute path outside the silent roots."""
+ # No separator, tilde or drive colon anywhere in the source means no absolute path can be spelled in it, so the
+ # two AST walks below are pure cost. Ordinary numeric / dataframe work takes this exit.
+ if isinstance(code, str) and not _ABSOLUTE_HINT_RE.search(code):
+ return False
+ try:
+ operands = _python_path_operands(tree)
+ except Exception: # noqa: BLE001 - an unexpected AST shape must not crash the classifier
+ return False
+ return any(_path_needs_approval(path, writing = writing) for path, writing in operands)
+
+
+def _open_call_writes(node, *, mode_index: int) -> bool:
+ """Write check for an open-like call whose mode sits at ``mode_index``.
+
+ ``open(file, mode)`` carries it at 1; ``Path(p).open(mode)`` at 0, because the receiver is the
+ path. Reading the wrong position silently turns a write into a read.
+ """
+ if _has_kwarg_splat(node):
+ return True # **{"mode": "w"} could request a write
+ if any(isinstance(a, ast.Starred) for a in node.args):
+ return True # *("f", "w") could splat a write mode into the positionals
+ mode = node.args[mode_index] if len(node.args) > mode_index else None
+ for kw in node.keywords or []:
+ if kw.arg == "mode":
+ mode = kw.value
+ return _mode_arg_writes(mode)
+
+
+# Importing this module on its own must still bind the borrowed names, and `tools` is what calls
+# `_bind`. Placed LAST so that call finds this module complete whichever of the two is imported
+# first: from here, `tools` runs to its end and binds; from `tools`, this line finds the module it
+# is already inside and its own bind follows immediately.
+from . import tools as _tools # noqa: E402,F401
diff --git a/studio/backend/core/inference/tools.py b/studio/backend/core/inference/tools.py
index 0bcba5464cf..60dd375ad6e 100644
--- a/studio/backend/core/inference/tools.py
+++ b/studio/backend/core/inference/tools.py
@@ -2763,6 +2763,55 @@ _SHELL_PARAM_OP_RE = re.compile(r"\$\{[A-Za-z_]\w*:?[-=+]([^{}]*)\}")
# path fails closed rather than spending unbounded time. Ordinary commands are far below these bounds.
_MAX_PATH_SCAN_CHARS = 2048
_MAX_TERMINAL_SCAN_CHARS = 4096
+# A glob needs one of these to expand into anything but itself; used to skip the glob scans outright.
+_GLOB_META_RE = re.compile(r"[?*\[]")
+# Where the memoised node list is parked on a parsed tree (see _tree_nodes).
+_TREE_NODES_ATTR = "_unsloth_walk_nodes"
+
+
[email protected]_cache(maxsize = 2048)
+def _token_command_base(token: str) -> str:
+ """The command name a shell token would run: separators stripped, directory dropped, folded to
+ lower case.
+
+ Several scans recompute this for every token of every command, and the tokens repeat heavily
+ (`cat`, `-la`, `|`), so the result is memoised. Pure function of the token text.
+ """
+ return os.path.basename(token.strip(";&|()`{}")).lower()
+
+
[email protected]_cache(maxsize = 64)
+def _parse_python(code: str):
+ """``(tree, None)`` or ``(None, SyntaxError)`` for a snippet, parsed at most once.
+
+ Classifying one python tool call parses the same source two or three times over: the safety
+ check parses it, the classifier parses it again, and the ``python -c`` path parses it a third
+ time before delegating. The tree is only ever read, so one parse serves all of them. The cache
+ is bounded and keyed on the source text, so it cannot go stale.
+ """
+ try:
+ return ast.parse(code), None
+ except SyntaxError as exc:
+ return None, exc
+
+
+def _tree_nodes(tree) -> list:
+ """``list(ast.walk(tree))``, computed once per parsed tree.
+
+ The python classifiers each sweep the whole tree a dozen times looking for a different node
+ shape, and every ``ast.walk`` rebuilds the same traversal from scratch. The node list is
+ identical for all of them, so it is built once and parked on the tree itself: the classifiers
+ only read the AST, and each call parses its own tree, so nothing can go stale. Falls back to a
+ plain walk if the attribute cannot be set.
+ """
+ nodes = getattr(tree, _TREE_NODES_ATTR, None)
+ if nodes is None:
+ nodes = list(ast.walk(tree))
+ try:
+ setattr(tree, _TREE_NODES_ATTR, nodes)
+ except (AttributeError, TypeError):
+ pass
+ return nodes
def _references_sensitive_path(text: str) -> bool:
@@ -2770,14 +2819,17 @@ def _references_sensitive_path(text: str) -> bool:
via parent traversal."""
if len(text) > _MAX_PATH_SCAN_CHARS:
return True
+ if _PARENT_TRAVERSAL_RE.search(text) or _SENSITIVE_PATH_RE.search(text):
+ return True
+ # The redundant-slash and de-bracketed rewrites exist to defeat `cat /etc//passwd` and
+ # `cat /etc/pass[w]d`. Both are identity for an ordinary command, and re-scanning a string the
+ # pattern has already rejected cannot change the answer, so only a rewrite that actually
+ # changed the text is worth a second pass.
norm = _REDUNDANT_SLASH_RE.sub("", text)
+ if norm != text and _SENSITIVE_PATH_RE.search(norm):
+ return True
debracket = _GLOB_BRACKET_RE.sub(lambda m: m.group(1)[0], text)
- return bool(
- _PARENT_TRAVERSAL_RE.search(text)
- or _SENSITIVE_PATH_RE.search(text)
- or _SENSITIVE_PATH_RE.search(norm)
- or _SENSITIVE_PATH_RE.search(debracket)
- )
+ return bool(debracket != text and _SENSITIVE_PATH_RE.search(debracket))
def _pattern_matches_dir(pattern: str, target: str) -> bool:
@@ -2793,6 +2845,11 @@ def _pattern_matches_dir(pattern: str, target: str) -> bool:
def _glob_token_sensitive(token: str) -> bool:
"""True if a single ? / * / [..] glob token could expand to a sensitive file or a file under a
secret/credential directory. Shared by the terminal scan and the Python glob check."""
+ # Only a glob can expand into something else, and none of the rewrites below introduce a
+ # metacharacter that was not already in the raw token (the POSIX-class rewrite needs a '['
+ # itself), so a token without one cannot match whatever the rewrites do to it.
+ if not _GLOB_META_RE.search(token):
+ return False
token = _REDIR_PREFIX_RE.sub("", _SHELL_QUOTE_RE.sub("", token))
# A POSIX class ([[:lower:]]) matches one char, like `?`, but fnmatch treats it as a literal set; normalize so cat
# /etc/pass[[:lower:]]d resolves.
@@ -2819,12 +2876,56 @@ def _glob_token_sensitive(token: str) -> bool:
def _glob_hits_sensitive(command: str) -> bool:
"""True if any glob token in a command could expand to a sensitive file, so `cat /e??/passwd`
asks even without a literal sensitive path."""
+ # Splitting and scanning every token is wasted on the overwhelmingly common command that
+ # contains no glob at all: each token would reach the same early return.
+ if not _GLOB_META_RE.search(command):
+ return False
return any(
_glob_token_sensitive(token)
for token in command.replace(";", " ").replace("|", " ").split()
)
+# A drive path is absolute only with a separator: `C:\x` is rooted, while `C:x` is relative to the drive's current
+# directory, so the separator is required rather than optional.
+_WIN_DRIVE_RE = re.compile(r"^[A-Za-z]:[\\/]")
+# The separator-less spelling, `D:notes.txt`, which is drive D's own current directory.
+_WIN_DRIVE_RELATIVE_JOIN_RE = re.compile(r"^[A-Za-z]:(?![\\/:])[^:\s]+$")
+
+
+def _posix_join(parts) -> str:
+ """Join folded path pieces the way ``os.path.join`` and ``Path(...)`` actually resolve them.
+
+ An absolute component DISCARDS everything before it: `os.path.join("/usr", "/media/x")` opens
+ `/media/x`, not `/usr/media/x`. Doing this at the join keeps the distinction from a doubled
+ separator inside one literal, which the OS simply collapses -- `/home/alice//usr/report.txt` is
+ `/home/alice/usr/report.txt` and has nothing to do with `/usr`. Inferring the join from `//`
+ after the fact could not tell those apart, and read `/usr` out of the literal.
+ """
+ out = ""
+ for part in parts:
+ if not out:
+ out = part
+ elif _WIN_DRIVE_RE.match(part) or _WIN_DRIVE_RELATIVE_JOIN_RE.match(part):
+ # Any drive-qualified operand discards the left, `C:\\Windows` joined with `D:notes.txt`
+ # being drive D's file and not a file under C. `ntpath.join` agrees; keeping the left
+ # placed a drive-D reference inside an allowed drive-C directory.
+ out = part
+ elif part[:2] == "\\\\":
+ # A UNC share is its own root: joining it onto a drive kept `C:` in front of `\\\\server`.
+ out = part
+ elif part[:1] in ("/", "\\"):
+ # A leading backslash is ROOTED on Windows, on the current drive: `C:\\Windows` joined
+ # with `\\Users\\alice` opens `C:\\Users\\alice`, so the drive survives and everything
+ # after it does not. Without this the fold kept the path under the read-silent
+ # `C:\\Windows`.
+ drive = _WIN_DRIVE_RE.match(out)
+ out = (out[:2] if drive else "") + part
+ else:
+ out = out.rstrip("/") + "/" + part
+ return out
+
+
def _expand_shell_assignments(command: str) -> str:
"""Best-effort substitution of `NAME=value ... $NAME`, so a sensitive path split across an
assignment and an argument (p=/etc; cat $p/passwd) is still visible to the scan. Also applies
@@ -3098,8 +3199,10 @@ def _folded_path(
right = fold(node.right)
left = "\x00" if left is None else left
right = "\x00" if right is None else right
- # Path('/etc') / 'passwd' joins with a separator; '+' concatenates.
- return left + "/" + right if isinstance(node.op, ast.Div) else left + right
+ # Path('/etc') / 'passwd' joins with a separator; '+' concatenates. The `/` operator is
+ # a JOIN, so an absolute right side discards the left exactly as os.path.join does:
+ # Path("/usr") / "/media/x" opens /media/x.
+ return _posix_join((left, right)) if isinstance(node.op, ast.Div) else left + right
if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Mod):
# Old-style formatting: '%s/%s' % ('/etc', 'passwd') -> /etc/passwd.
template = fold(node.left)
@@ -3130,11 +3233,14 @@ def _folded_path(
if isinstance(node, ast.Call):
func = node.func
if isinstance(func, ast.Attribute) and func.attr == "joinpath":
- # Path('/etc').joinpath('passwd') -> receiver and args are pieces.
+ # Path('/etc').joinpath('passwd') -> receiver and args are pieces. Joined with the
+ # same POSIX rule the `/` operator and os.path.join use: an absolute piece DISCARDS
+ # everything to its left, so `Path('/usr').joinpath('/media/x')` is `/media/x` and
+ # not a path under the read-silent `/usr`.
base = fold(func.value)
parts = [base if base is not None else "\x00"]
parts += [(fold(a) or "\x00") for a in node.args]
- return "/".join(parts)
+ return _posix_join(parts)
if isinstance(func, ast.Attribute) and func.attr in ("glob", "rglob", "iglob"):
# Path('/etc').glob('passw?') -> the receiver dir joined with the glob pattern; _glob_token_sensitive
# then tests /etc/passw?.
@@ -3177,19 +3283,22 @@ def _folded_path(
and isinstance(node.args[0], (ast.List, ast.Tuple))
):
pieces = [(fold(e) or "\x00") for e in node.args[0].elts]
+ # `str.join` CONCATENATES, whatever the separator: `"/".join(["/a", "/usr/b"])`
+ # is `/a//usr/b`, not `/usr/b`. Only os.path.join and pathlib let a later
+ # absolute piece discard the earlier ones.
return sep.join(pieces)
parts = [(fold(a) or "\x00") for a in node.args]
- return "/".join(parts)
+ return _posix_join(parts)
# A bare os.path.join alias (from os.path import join): join(*pieces).
if isinstance(func, ast.Name) and func.id in join_names:
parts = [(fold(a) or "\x00") for a in node.args]
- return "/".join(parts)
+ return _posix_join(parts)
# A bare/qualified/aliased pathlib constructor (Path(...), P(...)).
if (isinstance(func, ast.Attribute) and func.attr in ctors) or (
isinstance(func, ast.Name) and func.id in ctors
):
parts = [(fold(a) or "\x00") for a in node.args]
- return "/".join(parts)
+ return _posix_join(parts)
# '/etc/{}'.format('passwd') -> /etc/passwd (literal template + args).
if isinstance(func, ast.Attribute) and func.attr == "format":
template = fold(func.value)
@@ -3252,10 +3361,14 @@ def _command_references_sensitive(command: str) -> bool:
after undoing the shell expansions that would hide it: quotes/backslash escapes,
brace/parameter/ANSI-C expansion and NAME=value prefixes."""
stripped = _SHELL_QUOTE_RE.sub("", command).replace("\\", "")
- candidates = []
+ # The three base forms and their four expansions collapse to the same string for an ordinary
+ # command (nothing to unquote, no $'..', no ${x:-y}, no braces, no NAME=value), so scanning the
+ # list verbatim runs the same superlinear pattern up to twelve times over identical text. A set
+ # keeps every distinct candidate and drops only exact repeats, so the answer is unchanged.
+ candidates = set()
for c in (command, stripped, _decode_ansi_c(command)):
c_param = _expand_param_defaults(c)
- candidates.extend((c, c_param, _expand_braces(c_param), _expand_shell_assignments(c_param)))
+ candidates.update((c, c_param, _expand_braces(c_param), _expand_shell_assignments(c_param)))
return any(_glob_hits_sensitive(c) or _references_sensitive_path(c) for c in candidates)
@@ -3294,13 +3407,21 @@ def _terminal_is_potentially_unsafe(command: str) -> bool:
scan_tokens = tokens
# find/fd group with (...) which resets command context, so a trailing -delete/-exec could slip past; scan every
# token when find/fd appears.
- if any(os.path.basename(t.strip(";&|()`{}")).lower() in ("find", "fd") for t in scan_tokens):
+ if any(_token_command_base(t) in ("find", "fd") for t in scan_tokens):
if any(t.split("=", 1)[0] in _AUTO_UNSAFE_FIND_LIKE_FLAGS for t in scan_tokens):
return True
# A recursive reader rooted outside the sandbox reads host files, as do the always-recursive walkers (tree /home,
# du /); ask. Bash expands ~/~user to a home dir after this decision, so a tilde root is a sandbox escape too.
+ # An absolute operand outside the silent roots reaches the user's own filesystem; the sandbox workdir only
+ # contains RELATIVE paths. Run unconditionally, matching _terminal_is_high_risk: gating this on a leading / or ~
+ # would skip every Windows spelling (C:\..., \\server\share) and every attached redirection, leaving the stricter
+ # classifier weaker than the looser one.
+ if _terminal_reaches_outside_sandbox(tokens, command) or (
+ scan_tokens is not tokens and _terminal_reaches_outside_sandbox(scan_tokens, command)
+ ):
+ return True
if any(t.startswith("/") or t.startswith("~") for t in scan_tokens):
- token_bases = [os.path.basename(t.strip(";&|()`{}")).lower() for t in tokens]
+ token_bases = [_token_command_base(t) for t in tokens]
if any(b in _AUTO_RECURSIVE_SEARCH or b in _AUTO_RECURSIVE_LISTERS for b in token_bases):
return True
# ls only walks the whole subtree with -R/--recursive; a non-recursive ls /home lists one level and stays
@@ -3414,10 +3535,13 @@ def _python_is_potentially_unsafe(code: str) -> bool:
# confirmation first.
if _check_code_safety(code) is not None:
return True
- try:
- tree = ast.parse(code)
- except SyntaxError:
+ tree, _parse_error = _parse_python(code)
+ if _parse_error is not None:
return False # runs into a normal traceback; nothing to guard
+ # An absolute read/write outside the silent roots leaves the session workdir, which only ever holds relative
+ # paths. Kept in step with the high-risk gate so the two classifiers agree on filesystem scope.
+ if _python_reaches_outside_sandbox(tree, code):
+ return True
# Names bound to the builtin open (f = open; f, _ = (open, print)) so an aliased writer call is still checked
# below. builtins_aliases tracks `import builtins [as b]` for builtins.exec/eval.
open_aliases = {"open"}
@@ -3552,7 +3676,7 @@ def _python_is_potentially_unsafe(code: str) -> bool:
# call is checked, so a later benign reassignment would otherwise mask the earlier sensitive value and
# auto-approve. Count every binding target up front and poison multiply-bound names to the escape sentinel.
assign_counts: "dict[str, int]" = {}
- for node in ast.walk(tree):
+ for node in _tree_nodes(tree):
binding_targets = []
if isinstance(node, ast.Assign):
binding_targets = node.targets
@@ -3563,7 +3687,7 @@ def _python_is_potentially_unsafe(code: str) -> bool:
if isinstance(sub, ast.Name):
assign_counts[sub.id] = assign_counts.get(sub.id, 0) + 1
multi_assigned_names = {name for name, count in assign_counts.items() if count > 1}
- for node in ast.walk(tree):
+ for node in _tree_nodes(tree):
if isinstance(node, ast.Import):
for alias in node.names:
if alias.name == "builtins":
@@ -3823,7 +3947,7 @@ def _python_is_potentially_unsafe(code: str) -> bool:
_module_names = set(_AUTO_UNSAFE_PY_LOAD_MODULES) # receivers: yaml.load
_bare_names = set(_AUTO_UNSAFE_YAML_LOADERS) # loaders named on their own
_imported_modules = set() # only the module itself, for the return rule
- for node in ast.walk(tree):
+ for node in _tree_nodes(tree):
if isinstance(node, ast.Import):
for alias in node.names:
_root = alias.name.split(".")[0]
@@ -3851,7 +3975,7 @@ def _python_is_potentially_unsafe(code: str) -> bool:
node = node.value
return isinstance(node, ast.Name) and node.id in _module_names
- for node in ast.walk(tree):
+ for node in _tree_nodes(tree):
if isinstance(node, ast.Attribute):
if node.attr in _AUTO_UNSAFE_YAML_LOADERS:
return True
@@ -3868,7 +3992,7 @@ def _python_is_potentially_unsafe(code: str) -> bool:
if isinstance(_out, ast.Name) and _out.id in _imported_modules:
return True
try:
- for node in ast.walk(tree):
+ for node in _tree_nodes(tree):
if isinstance(node, ast.Import):
for alias in node.names:
if alias.name.split(".")[0] in _AUTO_UNSAFE_PY_MODULES:
@@ -5512,9 +5636,7 @@ def _inline_python_is_high_risk(code: str) -> bool:
"""Screen a `python -c` payload with the same analyzer the python tool uses, so an ordinary
one-liner runs and a destructive one still asks. Source that does not parse fails closed:
shell quoting may have mangled it, leaving nothing to screen."""
- try:
- ast.parse(code)
- except SyntaxError:
+ if _parse_python(code)[1] is not None:
return True
return _python_is_high_risk(code)
@@ -5602,18 +5724,21 @@ def _terminal_is_high_risk(command: str, _depth: int = 0) -> bool:
tokens = list(lexer)
except ValueError:
return True
+ # The sandbox directory is a working directory, not a boundary, so an absolute operand outside the silent
+ # roots reads or rewrites the user's own files. Runs per expansion pass, so a path assembled from a variable
+ # is judged on its resolved form too.
+ if _terminal_reaches_outside_sandbox(tokens, text):
+ return True
recursive = any(
t in ("-R", "--recursive")
or (t[:1] == "-" and t[:2] != "--" and "=" not in t and "R" in t[1:])
for t in tokens
)
- find_like = any(
- os.path.basename(t.strip(";&|()`{}")).lower() in ("find", "fd") for t in tokens
- )
+ find_like = any(_token_command_base(t) in ("find", "fd") for t in tokens)
# Shared out over the sed words present, so a lone sed reads its whole argument list and a line packed with
# them stays linear (_sed_scan_limit).
sed_scan_limit = _sed_scan_limit(
- sum(1 for t in tokens if os.path.basename(t.strip(";&|()`{}")).lower() in _SED_COMMANDS)
+ sum(1 for t in tokens if _token_command_base(t) in _SED_COMMANDS)
)
# Built at most once per pass, and only when a sed program actually names a variable, so a line packed with
# sed words stays linear.
@@ -5631,9 +5756,9 @@ def _terminal_is_high_risk(command: str, _depth: int = 0) -> bool:
return True
# GNU tar runs --checkpoint-action=exec=CMD at each checkpoint, hiding a command (including hard-blocked ones)
# inside an argument.
- if any(
- os.path.basename(t.strip(";&|()`{}")).lower() in _ARG_EXEC_FLAG_OWNERS for t in tokens
- ) and any(t.split("=", 1)[0] in _HIGH_RISK_ARG_EXEC_FLAGS for t in tokens):
+ if any(_token_command_base(t) in _ARG_EXEC_FLAG_OWNERS for t in tokens) and any(
+ t.split("=", 1)[0] in _HIGH_RISK_ARG_EXEC_FLAGS for t in tokens
+ ):
return True
# An interpreter serving on the network exposes the session workdir; the sandbox keeps no network namespace.
if _LISTENER_PY_MODULE_RE.search(text) or _LISTENER_BIN_AT_CMD_RE.search(text):
@@ -6173,14 +6298,17 @@ def _python_is_high_risk(code: str) -> bool:
# refusal.
if _check_code_safety(code) is not None:
return True
- try:
- tree = ast.parse(code)
- except SyntaxError:
+ tree, _parse_error = _parse_python(code)
+ if _parse_error is not None:
# Unparsable code never runs, but scan the raw text anyway.
return _references_sensitive_path(code)
+ # The session workdir confines RELATIVE paths only: an absolute path outside the silent roots reads or rewrites
+ # the user's own files, which is the same loss the terminal `rm` gate already asks about.
+ if _python_reaches_outside_sandbox(tree, code):
+ return True
# A credential basename only names a file when it appears in a string, so match it there rather than across the
# source: `credentials = {}` and `def load_credentials()` do no I/O and must not prompt.
- for _node in ast.walk(tree):
+ for _node in _tree_nodes(tree):
if (
isinstance(_node, ast.Constant)
and isinstance(_node.value, str)
@@ -6193,7 +6321,7 @@ def _python_is_high_risk(code: str) -> bool:
# Modules whose handles end processes; tracked so an unrelated .kill() on a user-defined object is not mistaken
# for one.
psutil_names: "set[str]" = set()
- for _node in ast.walk(tree):
+ for _node in _tree_nodes(tree):
if isinstance(_node, ast.Import):
for _a in _node.names:
if _a.name.split(".")[0] in _PY_PROCESS_MODULES:
@@ -6227,7 +6355,7 @@ def _python_is_high_risk(code: str) -> bool:
and value.args[0].value in ("os", "posix", "nt")
)
- for node in ast.walk(tree):
+ for node in _tree_nodes(tree):
if isinstance(node, ast.ImportFrom) and node.module in _PY_DESTRUCTIVE_FS_MODULES:
for alias in node.names:
if alias.name in _PY_DESTRUCTIVE_FS_IMPORT_NAMES:
@@ -6294,7 +6422,7 @@ def _python_is_high_risk(code: str) -> bool:
# `rm = getattr(os, "remove")` stores the lookup and calls it later, so the direct getattr(...)(...) shape never
# sees it. Bind the name here instead.
- for node in ast.walk(tree):
+ for node in _tree_nodes(tree):
if not (
isinstance(node, ast.Assign)
and isinstance(node.value, ast.Call)
@@ -6317,7 +6445,7 @@ def _python_is_high_risk(code: str) -> bool:
# `f = open(path, "r+")` then `f.truncate(0)` zeroes the file. Gated via the handle name, not the bare `.truncate`
# attribute: pandas DataFrame.truncate() is common here and non-destructive.
file_handles: "set[str]" = set()
- for node in ast.walk(tree):
+ for node in _tree_nodes(tree):
if (
isinstance(node, ast.Assign)
and isinstance(node.value, ast.Call)
@@ -6339,7 +6467,7 @@ def _python_is_high_risk(code: str) -> bool:
):
file_handles.add(item.optional_vars.id)
if file_handles:
- for node in ast.walk(tree):
+ for node in _tree_nodes(tree):
if (
isinstance(node, ast.Call)
and isinstance(node.func, ast.Attribute)
@@ -6350,7 +6478,7 @@ def _python_is_high_risk(code: str) -> bool:
return True
# A bound reference (f = os.remove; f(x)) hides the call site behind a plain Name, so record the target name as a
# destructive alias to catch f(...) below.
- for node in ast.walk(tree):
+ for node in _tree_nodes(tree):
if isinstance(node, ast.Assign) and isinstance(node.value, ast.Subscript):
if _is_module_dict_lookup(node.value):
for tgt in node.targets:
@@ -6369,7 +6497,7 @@ def _python_is_high_risk(code: str) -> bool:
# An annotated binding (f: object = os.remove) is the same alias.
if _is_destructive_attr(node.value.attr, node.value.value):
destructive_fs_aliases.add(node.target.id)
- for node in ast.walk(tree):
+ for node in _tree_nodes(tree):
if not isinstance(node, ast.Call):
continue
func = node.func
@@ -6410,7 +6538,7 @@ def _python_is_high_risk(code: str) -> bool:
# above, so fold the string-literal variables through _folded_path and re-check. An unresolved fragment folds to a
# sentinel so a partial fold never false-positives.
str_vars: "dict[str, str]" = {}
- for node in ast.walk(tree):
+ for node in _tree_nodes(tree):
if not (
isinstance(node, ast.Assign)
and len(node.targets) == 1
@@ -6427,14 +6555,14 @@ def _python_is_high_risk(code: str) -> bool:
if folded and "\x00" not in folded and "\x02" not in folded:
str_vars[node.targets[0].id] = folded
- for node in ast.walk(tree):
+ for node in _tree_nodes(tree):
if isinstance(node, (ast.BinOp, ast.JoinedStr, ast.Call)):
folded = _folded_path(node, str_vars)
if folded and _folded_is_sensitive(folded):
return True
# exec/eval/compile/__import__ of a non-literal runs whatever it builds at runtime, past the static checks above;
# ask. A literal eval("1+1") is harmless and runs.
- for node in ast.walk(tree):
+ for node in _tree_nodes(tree):
if not isinstance(node, ast.Call):
continue
func = node.func
@@ -13176,9 +13304,9 @@ def _check_signal_escape_patterns(code: str):
"""Check for patterns that could escape signal-based timeouts. Returns (safe: bool, details:
dict). Vendored from unsloth_zoo.rl_environments to avoid importing unsloth_zoo (needs GPU
drivers; fails on Apple Silicon)."""
- try:
- tree = ast.parse(code)
- except SyntaxError as e:
+ tree, _parse_error = _parse_python(code)
+ if _parse_error is not None:
+ e = _parse_error
return False, {
"error": f"SyntaxError: {e}",
"signal_tampering": [],
@@ -13779,7 +13907,7 @@ def _check_signal_escape_patterns(code: str):
)
def _module_has_hf_import(tree: ast.AST) -> bool:
- for n in ast.walk(tree):
+ for n in _tree_nodes(tree):
if isinstance(n, ast.Import):
for alias in n.names:
if alias.name.split(".", 1)[0] in _HF_IMPORT_MODULES:
@@ -16075,3 +16203,14 @@ def _bash_exec(
os.unlink(os.path.join(workdir, _scratch_name))
except OSError:
pass
+
+
+# The out-of-sandbox approval subsystem lives in its own module: the silent roots, the shared
+# `_path_needs_approval` predicate and the two operand scanners. Imported at the END because the two
+# modules reference each other, and bound by name here so the call sites below read unchanged.
+from . import tool_path_approval as _path_gate # noqa: E402
+
+_path_gate._bind(globals())
+_PATH_FLAG_SPECS = _path_gate._PATH_FLAG_SPECS
+_python_reaches_outside_sandbox = _path_gate._python_reaches_outside_sandbox
+_terminal_reaches_outside_sandbox = _path_gate._terminal_reaches_outside_sandbox
diff --git a/studio/backend/tests/test_permission_mode.py b/studio/backend/tests/test_permission_mode.py
index 4ba895841a4..cfdaab65db2 100644
--- a/studio/backend/tests/test_permission_mode.py
+++ b/studio/backend/tests/test_permission_mode.py
@@ -141,15 +141,18 @@ def _clear_pending():
("cat ~/.aws/credentials", True), # credential path
("cat /home/a/.azure/msal_token_cache.json", True), # azure token store
("cat ~/.config/gh/hosts.yml", True), # gh cli credentials
- ("cat ~/.config/app/settings.json", False), # ordinary config stays safe
+ # A plain `~` IS the sandbox: both env builders set the child's HOME to the tool workdir.
+ ("cat ~/.config/app/settings.json", False),
("cat /home/alice/.cache/huggingface/token", True), # HF login token
("cat ~/.cache/huggingface/stored_tokens", True), # HF multi-token store
("cat /home/alice/.huggingface/token", True), # legacy HF token location
- ("cat /home/alice/myhuggingface/token", False), # unrelated dir stays safe
+ # Not the HF token store, so no credential match -- but another user's home is outside the sandbox, so the
+ # read gate asks anyway.
+ ("cat /home/alice/myhuggingface/token", True),
(
"cat /home/alice/.cache/huggingface/hub/models--x/config.json",
- False,
- ), # HF model cache is not a credential
+ True,
+ ), # not a credential; THIS install's own HF cache stays silent (test_configured_cache_reads_stay_silent)
("cat /run/secrets/hf_token", True), # docker secret mount
("cat /var/run/secrets/kubernetes.io/serviceaccount/token", True), # k8s mount
("cat /run/app.pid", False), # ordinary /run file stays safe
@@ -206,7 +209,7 @@ def _clear_pending():
("du -sh", False), # du with no path defaults to cwd
("du -sh ./build", False), # relative disk-usage stays safe
("ls -R subdir", False), # relative recursive listing stays safe
- ("ls -la /home", False), # non-recursive listing of one level stays here
+ ("ls -la /home", True), # one level, but it is the host's home tree, not the sandbox
("sort --files0-from=list.txt", True), # reads an indirect file list
("sort --files0-from list.txt", True), # separate-value form
("sort -u data.txt", False), # ordinary sort stays read only
@@ -228,7 +231,10 @@ def _clear_pending():
("cat proj/.en?", True), # .env anywhere via a glob
("cat notes/dra?t.txt", False), # benign globbed basename stays safe
("cat data/token_counts.tx?", False), # 'token' prefix basename stays safe
- ("ls /home/*/projects", False), # benign glob not into a cred dir
+ (
+ "ls /home/*/projects",
+ True,
+ ), # no credential dir, but an absolute listing outside the sandbox
("grep -R TOKEN ~root", True), # tilde-user recursive root escapes
("grep -R TOKEN ~/logs", True), # tilde-home recursive root escapes
("cat /etc/pass{w,}d", True), # brace expansion builds /etc/passwd
@@ -254,7 +260,7 @@ def _clear_pending():
("cat $'notes.txt'", False), # benign ANSI-C quote stays safe
("cat /home/*/.az?re/msal_token_cache.json", True), # azure token glob
("cat /home/*/.config/g?/hosts.yml", True), # gh config glob
- ("cat /home/*/projects/readme", False), # benign home glob stays safe
+ ("cat /home/*/projects/readme", True), # no credential match, but a read of the host's home
("cat /proc/$PPID/task/$PPID/environ", True), # per-thread proc env alias
("cat /proc/cpuinfo", False), # non-sensitive proc read stays safe
("grep -R TOKEN ${root:-/home}", True), # default-param recursive root
@@ -266,10 +272,13 @@ def _clear_pending():
("p=hello; cat notes/${p,,}", False), # benign case expansion stays safe
("f=-delete; find . $f", True), # find action hidden behind an assignment
("g=e??; cat /$g/passwd", True), # glob assembled through an assignment
- ("g=abc; cat /$g/readme", False), # benign assigned path stays safe
+ (
+ "g=abc; cat /$g/readme",
+ True,
+ ), # the assignment resolves to /abc/readme, outside the sandbox
("cat /etc/pass[[:lower:]]d", True), # POSIX class glob builds /etc/passwd
("x=passwd; p=x; cat /etc/${!p}", True), # indirect expansion builds path
- ("x=notes; p=x; cat /home/${!p}", False), # benign indirect expansion stays safe
+ ("x=notes; p=x; cat /home/${!p}", True), # indirect expansion resolves into the host's home
("cat </dev/tcp/example.com/80", True), # bash /dev/tcp opens a socket
("cat < /dev/udp/1.2.3.4/53", True), # bash /dev/udp opens a socket
("cat /dev/null", False), # ordinary /dev file stays safe
@@ -429,7 +438,8 @@ def test_terminal_classifier(command, unsafe):
("echo x >> ~/.profile", True),
("cp payload.desktop ~/.config/autostart/x.desktop", True),
("cp x.service ~/.config/systemd/user/x.service", True),
- ("mkdir ~/.config/myapp", False), # a non-persistence ~/.config dir is fine
+ # No persistence hook, and a plain `~` resolves inside the sandbox.
+ ("mkdir ~/.config/myapp", False),
# non-persistence /etc reads/writes stay ordinary (no over-prompt)
("cat /etc/hostname", False),
("grep nameserver /etc/resolv.conf", False),
@@ -2012,7 +2022,7 @@ def test_high_risk_dispatcher_non_terminal():
True,
), # qualified path-ctor alias (P = pathlib.Path)
(
- "import pathlib\nP = pathlib.Path\n(P('/tmp') / 'x').read_text()",
+ "import pathlib\nP = pathlib.Path\n(P('/usr/share') / 'x').read_text()",
False,
), # benign qualified path-ctor alias stays safe
(
@@ -2104,8 +2114,8 @@ def test_high_risk_dispatcher_non_terminal():
), # reads the Hugging Face login token
(
"open('/home/alice/.cache/huggingface/hub/models--x/config.json').read()",
- False,
- ), # HF model cache is not a credential
+ True,
+ ), # not a credential; THIS install's own HF cache stays silent (test_configured_cache_reads_stay_silent)
("import numpy as np\nnp.mean([1, 2])", False), # a benign numpy read stays safe
(
"from pathlib import Path\nP = Path\n(P('/etc') / 'passwd').read_text()",
@@ -2116,9 +2126,9 @@ def test_high_risk_dispatcher_non_terminal():
True,
), # os.path.join aliased
(
- "from pathlib import Path\nP = Path\n(P('/tmp') / 'x').read_text()",
+ "from pathlib import Path\nP = Path\n(P('/usr/share') / 'x').read_text()",
False,
- ), # benign alias
+ ), # benign alias, under a read-silent root: /tmp is the SHARED temp dir, not the session's
(
"from pathlib import Path\nPath('/etc').joinpath('passwd').read_text()",
True,
@@ -2141,8 +2151,8 @@ def test_high_risk_dispatcher_non_terminal():
), # with_suffix drops the suffix onto a secret
(
"from pathlib import Path\nPath('/tmp/a').with_name('b.txt').read_text()",
- False,
- ), # benign with_name in the sandbox stays safe
+ True,
+ ), # not a secret, but /tmp is outside the sandbox (which has its own TMPDIR)
(
"from pathlib import Path\nPath('report.txt').with_suffix('.md').read_text()",
False,
@@ -2151,8 +2161,8 @@ def test_high_risk_dispatcher_non_terminal():
# destructured string literals fold into the sensitive path
("d, f = ('/etc', 'passwd')\nopen('/'.join([d, f])).read()", True),
# destructured literals reused through str.join
- ("base, leaf = ('/tmp', 'x')\nopen(base + '/' + leaf).read()", False),
- # benign destructured literals stay safe
+ ("base, leaf = ('/tmp', 'x')\nopen(base + '/' + leaf).read()", True),
+ # destructured literals fold to /tmp/x: no secret, but outside the sandbox's own TMPDIR
("open(b'/etc/passwd').read()", True), # bytes path literal
("open(b'data.txt').read()", False), # benign bytes literal stays safe
(
@@ -3232,3 +3242,1147 @@ def test_auto_mode_prompts_on_dangerous_python_work(code):
@pytest.mark.parametrize("name", _DANGEROUS_MCP)
def test_auto_mode_prompts_on_dangerous_mcp_work(name):
assert is_high_risk_tool_call(f"{MCP_TOOL_PREFIX}{name}", {"code": "x"}) is True
+
+
+# The reported sandbox escape (HF discussion #107, Desktop v0.1.808-beta): the session sandbox directory is a working
+# directory, not an OS boundary, so an ABSOLUTE path in a tool call reaches the user's real filesystem with their own
+# permissions. Deletion already prompted; reading and overwriting did not. These are the reporter's own operations,
+# plus the ones that reach the same files by another route.
+_OUTSIDE_DIR = "/media/kuser/MEDIA_SSD/MyProjects/local_ai_project_ternary"
+_OUTSIDE_FILE = _OUTSIDE_DIR + "/memory.md"
+
+_OUTSIDE_SANDBOX_TERMINAL = (
+ f"cat {_OUTSIDE_FILE}", # the read half of the report: no credential match, but the host's own data
+ f"head -c 200 {_OUTSIDE_FILE}",
+ f"tail -n 5 {_OUTSIDE_FILE}",
+ f"wc -l {_OUTSIDE_FILE}",
+ f"stat {_OUTSIDE_FILE}",
+ f"ls -la {_OUTSIDE_DIR}",
+ f"cp {_OUTSIDE_FILE} ./stolen.md", # exfiltration INTO the sandbox
+ f"cp ./payload.md {_OUTSIDE_FILE}", # ... and the reverse, which overwrites
+ f"mv {_OUTSIDE_FILE} {_OUTSIDE_FILE}.bak",
+ f"sed -i 's/a/b/' {_OUTSIDE_FILE}", # in-place rewrite of a host file
+ f"echo clobbered > {_OUTSIDE_FILE}", # redirect truncates it
+ f"echo more >> {_OUTSIDE_FILE}",
+ f"tee {_OUTSIDE_FILE}",
+ f"touch {_OUTSIDE_DIR}/new_file",
+ f"mkdir {_OUTSIDE_DIR}/new_dir",
+ "cat /home/kuser/Documents/taxes.pdf", # another user's documents
+ "wc -l ~alice/notes.txt", # a named account is the real home, not the sandbox
+ "ls -la /home",
+)
+
+_OUTSIDE_SANDBOX_PYTHON = (
+ f"print(open({_OUTSIDE_FILE!r}).read())", # the exact bypass the report used, read side
+ f"open({_OUTSIDE_FILE!r}, 'w').write('clobbered')", # overwrite, which used to run unprompted
+ f"open({_OUTSIDE_FILE!r}, 'a').write('more')",
+ f"from pathlib import Path\nPath({_OUTSIDE_FILE!r}).read_text()",
+ f"from pathlib import Path\nPath({_OUTSIDE_FILE!r}).write_text('x')",
+ f"from pathlib import Path\nPath({_OUTSIDE_DIR!r} + '/new').touch()",
+ f"import os\nos.remove({_OUTSIDE_FILE!r})", # the reporter's os.remove
+ f"import shutil\nshutil.rmtree({_OUTSIDE_DIR!r})",
+ f"import shutil\nshutil.copy({_OUTSIDE_FILE!r}, './stolen.md')",
+ f"import os\nprint(os.listdir({_OUTSIDE_DIR!r}))",
+ f"import os\nfor root, dirs, files in os.walk({_OUTSIDE_DIR!r}):\n print(root)",
+ f"import pandas as pd\nprint(pd.read_csv({_OUTSIDE_FILE!r}))", # a reader that is not open()
+ f"import numpy as np\nnp.loadtxt({_OUTSIDE_FILE!r})",
+ f"import linecache\nprint(linecache.getline({_OUTSIDE_FILE!r}, 1))",
+ f"import json\nprint(json.load(open({_OUTSIDE_FILE!r})))",
+ f"import numpy as np\nnp.save({_OUTSIDE_DIR!r} + '/weights.npy', np.zeros(3))",
+ f"p = {_OUTSIDE_FILE!r}\nprint(open(p).read())", # through a variable
+ f"from pathlib import Path\np = Path({_OUTSIDE_DIR!r}) / 'memory.md'\nprint(p.read_text())",
+ f"import os\nprint(open(os.path.join({_OUTSIDE_DIR!r}, 'memory.md')).read())",
+ "print(open('/home/kuser/Documents/taxes.pdf', 'rb').read())",
+)
+
+# The same shape of call, but pointed somewhere a tool reads all the time. These must NOT start prompting, or auto
+# mode becomes unusable and users turn the sandbox off -- which is what the reporter was advised to do.
+_ALLOWLISTED_TERMINAL = (
+ "cat /proc/cpuinfo",
+ "cat /etc/os-release",
+ "ls /usr/lib",
+ "ls -la /usr/share/doc",
+ "wc -l /usr/include/stdio.h",
+ "stat /bin/sh",
+ "cat /sys/class/net/eth0/address",
+ "sed '/etc/d' notes.txt", # a sed PROGRAM that starts with a slash is not a path
+ "grep /usr/bin list.txt", # a PATTERN that looks like a path is not a path
+ "awk '/home/ {print}' access.log",
+ "python train.py 2> /dev/null",
+ "head -n 5 data.csv",
+ "sort -k 2 -t , data.csv",
+ "jq '.results[0]' out.json",
+ "diff old.py new.py",
+ "cp build/a.txt build/b.txt",
+ "find . -name '*.safetensors'",
+ # The other side of the tar fix: a relative operand stays silent in every spelling, and an
+ # ordinary filename containing a "c" must not read as tar's create mode.
+ "tar -cf out.tar data src",
+ "tar -xf archive.tar src",
+ "tar czf out.tgz .",
+ # -C in CREATE mode really is only a read, and a substitution naming no path is not an operand.
+ "tar -C /usr/share -cf out.tar .",
+ 'echo "$(date)"',
+ 'echo "$(ls)"',
+ # The pattern-flag fix must not make an ordinary grep or a plain redirect prompt.
+ "grep -e needle local.log",
+ "grep -f patterns.txt local.log",
+ "grep --exclude-from=filters needle local.txt",
+ "cat notes.txt > out.txt",
+ "echo hi > /dev/null",
+ "tar --extract --file=/usr/share/in.tar",
+ "cat /usr/share/doc/readme",
+)
+
+_ALLOWLISTED_PYTHON = (
+ "print(open('/proc/cpuinfo').read())",
+ "import os\nprint(os.listdir('/usr/lib'))",
+ "print(open('/etc/os-release').read())",
+ "import sys\nprint(open(sys.prefix + '/pyvenv.cfg').read())",
+ "import pandas as pd\ndf = pd.read_csv('train.csv')\ndf.to_csv('out.csv')",
+ "import numpy as np\nnp.save('embeddings.npy', np.zeros(3))",
+ "from pathlib import Path\nPath('results').mkdir(exist_ok=True)",
+ "import json\nprint(json.load(open('config.json')))",
+ # The module-open fix reads the first argument instead of the receiver; a relative one is silent.
+ "import io\nprint(io.open('notes.txt').read())",
+ "import gzip\ngzip.open('data.gz', 'rb').read()",
+ "import io as stream\nprint(stream.open('notes.txt').read())",
+ "import os.path as p\nprint(p.join('data', 'train.csv'))",
+ "from io import open as fopen\nprint(fopen('notes.txt').read())",
+ "from os.path import join as j\nprint(j('data', 'train.csv'))",
+ "from pandas import read_csv as rc\nrc('train.csv')",
+ "import os\nopen(os.path.join('/usr', 'share', 'doc')).read()",
+ (
+ "\n".join(f"base = '/usr/a{i}'" for i in range(9))
+ + "\np = base + '/report.txt'\nopen(p).read()"
+ ),
+ "base = 'local'\np = base + '/report.txt'\nopen(p).read()",
+ "import os\nos.rename('a.txt', 'b.txt')",
+ "import shutil\nshutil.copy('a.txt', 'b.txt')",
+ "import tarfile\ntarfile.open('out.tar', 'w')",
+ "import numpy as np\nnp.save('emb.npy', [1])",
+ (
+ "base = 'local'\n"
+ + "\n".join(f"base = 'r{i}'" for i in range(30))
+ + "\np = base + '/r.txt'\nopen(p).read()"
+ ),
+ # ... and the receiver IS the path for Path.open, which must keep working.
+ "from pathlib import Path\nPath('out.txt').open('w').write('hi')",
+)
+
+
+# Routes that reach an out-of-sandbox path WITHOUT naming it in an operand position. Each of these ran silently
+# before the operand scan learned about them.
+_OUTSIDE_SANDBOX_INDIRECT_TERMINAL = (
+ # Running a path-qualified binary READS that file before anything else it does.
+ "/media/alice/tool --flag",
+ # The interpreter payload writes through a RELATIVE path, under the directory the `cd` set.
+ "cd /usr/share/doc && python -c \"open('w.gguf', 'w').write('x')\"",
+ # `gcc -o FILE` truncates that file; `make -C DIR` runs recipes that write there;
+ # `git init DIR` creates the repository in it.
+ "gcc -E input.c -o /media/alice/private.txt",
+ "make -C /usr/share/doc clean",
+ "git init /usr/share/doc/repo",
+ # A permission change modifies the file it names; the mode or owner is not a path.
+ "chmod 000 /media/alice/report.txt",
+ "chown alice /media/alice/report.txt",
+ # `fd --ignore-file <path>` reads that file as a custom ignore list.
+ "fd --ignore-file=/media/alice/private.rules needle .",
+ # GNU long options accept unambiguous abbreviations, so `--targ=` is the destination.
+ "cp --targ=/usr/share/doc payload",
+ # Short options cluster, so `-ni` edits in place exactly as `-i` does.
+ "sed -ni 's/x/y/p' /usr/share/doc/notes",
+ # `xargs` forwards the paths to ANOTHER command, whose mode is the one that counts.
+ "printf '%s\\n' /usr/share/doc/new.txt | xargs touch",
+ "ls | xargs -I {} cp {} /usr/share/doc/",
+ # A `cd` to an absolute directory moves where every later RELATIVE write lands.
+ f"cd {_OUTSIDE_DIR} && touch weights.gguf",
+ f"cd {_OUTSIDE_DIR} && echo hi > out.txt",
+ # `tar --add-file=FILE` adds that file, so it is read.
+ f"tar -cf out.tar --add-file={_OUTSIDE_FILE}",
+ # `date --help`: `-r, --reference=FILE` displays that file's modification time.
+ f"date --reference={_OUTSIDE_FILE}",
+ # `tar --help`: `--delete` removes members and `-A` appends archives, both mutating `-f`.
+ f"tar --delete -f {_OUTSIDE_DIR}/a.tar member",
+ f"tar -A -f {_OUTSIDE_DIR}/a.tar b.tar",
+ # `7z a` creates or updates the archive named first after the command word.
+ f"7z a {_OUTSIDE_DIR}/out.7z local.txt",
+ f"7z a out.7z {_OUTSIDE_DIR}/src",
+ # `-c` only stops the operand being REWRITTEN; it is still opened.
+ f"gzip -c {_OUTSIDE_DIR}/x",
+ f"zstd {_OUTSIDE_DIR}/x",
+ # `zcat` and friends uncompress the file they are given to stdout.
+ f"zcat {_OUTSIDE_DIR}/private.gz",
+ f"zstdcat {_OUTSIDE_DIR}/private.zst",
+ # A substitution nested inside a process substitution.
+ f"cat <(cat $(echo {_OUTSIDE_FILE}))",
+ # `<( ... )` runs its body as a command of its own, under an outer command this scan does not model.
+ f"pr <(cat {_OUTSIDE_FILE})",
+ f"comm <(sort {_OUTSIDE_FILE}) <(sort b)",
+ f"tee >(gzip > {_OUTSIDE_DIR}/out.gz) < notes.txt",
+ # `env --help`: a mere `-` implies `-i`, so the command still follows it.
+ f"env - FOO=bar cat {_OUTSIDE_FILE}",
+ # A file operator of `test`/`[` still stats what it is given, including through a substitution.
+ f"[ -f {_OUTSIDE_FILE} ]",
+ f"test -r {_OUTSIDE_FILE}",
+ f'[ -e "$(echo {_OUTSIDE_FILE})" ]',
+ f"test {_OUTSIDE_FILE} -nt ./local.txt",
+ # One token carrying both a live `>` and a quoted target with a space in it.
+ f'echo CHANGED>"{_OUTSIDE_DIR} host/notes.txt"',
+ # A here-string word is DATA, but a substitution inside it runs before the data is handed over.
+ f'cat <<< "$(cat {_OUTSIDE_FILE})"',
+ # `curl --help all`: `-K, --config <file>` reads a config from a file; the attached spelling was
+ # discarded whole rather than exposing its value.
+ f"curl --config={_OUTSIDE_FILE} https://example.com",
+ # `jq --help`: `-L directory` searches modules there, so the filter includes a file from
+ # outside the sandbox without ever naming it.
+ f"jq -n -L {_OUTSIDE_DIR} 'include \"report\"; rows'",
+ f"jq --library-path {_OUTSIDE_DIR} '.a' data.json",
+ # Windows spellings a POSIX lexer destroys or a drive-letter pattern misses: root-relative on
+ # the current drive, and drive-relative against THAT drive's own directory.
+ r"cat \\Users\\alice\\notes.txt",
+ "cat C:notes.txt",
+ # `/dev/fd/<n>` is the kernel link `/proc/self/fd/<n>` is, so it is not a property of /dev.
+ "cat /dev/fd/3",
+ # `make --help`: `-f FILE` reads that makefile and `-C DIR` changes to it first.
+ f"make -f {_OUTSIDE_DIR}/Makefile",
+ f"make -C {_OUTSIDE_DIR}",
+ # A multicall binary dispatches to the applet named first, so that is the command to classify.
+ f"busybox cat {_OUTSIDE_FILE}",
+ f"toybox cat {_OUTSIDE_FILE}",
+ # `help test`: the unary expressions examine the status of a file.
+ f"test -e {_OUTSIDE_FILE}",
+ f"[ -r {_OUTSIDE_FILE} ]",
+ # `ln` hands the sandbox a name that WRITES to its target, so a relative write through the link
+ # lands outside afterwards.
+ f"ln -s {_OUTSIDE_FILE} local.md",
+ f"ln {_OUTSIDE_FILE} local.md",
+ # tmpfs the user's own processes own: their contents are user data, not machine state.
+ "cat /dev/shm/private",
+ "cat /run/user/1000/app/session.json",
+ # `mv --help`: "Rename SOURCE to DEST", so the source is gone afterwards; `cp` leaves it.
+ f"mv {_OUTSIDE_FILE} ./local.md",
+ # `tar --help`: `-r` appends to the archive and `-u` updates it, both writes of the `-f` file.
+ f"tar -rf {_OUTSIDE_DIR}/archive.tar local",
+ f"tar -uf {_OUTSIDE_DIR}/archive.tar local",
+ # The same word twice, once as data and once as syntax: a membership test found the quoted
+ # spelling and left the live redirection of the second command unsplit.
+ f"echo 'x>{_OUTSIDE_FILE}'; echo x>{_OUTSIDE_FILE}",
+ # `/proc/<pid>/task/<tid>/root` resolves through the same kernel link as the process spelling.
+ f"cat /proc/$$/task/$$/root{_OUTSIDE_FILE}",
+ f"cat /proc/self/task/12/root{_OUTSIDE_FILE}",
+ # A command substitution runs inside DOUBLE quotes too, and the quoted body arrives as one
+ # token, so the command at its head was not read as a command at all.
+ f'echo "`cat {_OUTSIDE_FILE}`"',
+ # `iconv --help`: "Usage: iconv [OPTION...] [FILE...]", and `-o, --output=FILE` writes.
+ f"iconv {_OUTSIDE_FILE}",
+ f"iconv -o {_OUTSIDE_DIR}/out.txt local.txt",
+ # A control word ends one command and begins another, so the read below was grouped under
+ # `then` / `do` / `{`, none of which is a command any table knows.
+ f"if true; then cat {_OUTSIDE_FILE}; fi",
+ f"for f in a b; do cat {_OUTSIDE_FILE}; done",
+ f"while true; do cat {_OUTSIDE_FILE}; done",
+ f"{{ cat {_OUTSIDE_FILE}; }}",
+ # A backtick substitution is a command of its own, but the lexer keeps the backticks inside
+ # ordinary tokens, so the read arrived as an argument of `echo` and was dropped with it.
+ f"echo `cat {_OUTSIDE_FILE}`",
+ # `wget --help`: `-o, --output-file=FILE` logs there and `-a, --append-output=FILE` appends.
+ f"wget --output-file={_OUTSIDE_FILE} https://example.com",
+ f"wget -o {_OUTSIDE_FILE} https://example.com",
+ # `git clone -h`: `--[no-]separate-git-dir <gitdir>` puts the repository metadata there.
+ f"git clone --separate-git-dir={_OUTSIDE_DIR}/repo repo checkout",
+ # `sort --help`: "--random-source=FILE get random bytes from FILE". Attached, it was discarded
+ # as an unknown option and the host file it named was read without a word.
+ f"sort -R --random-source={_OUTSIDE_FILE} input.txt",
+ f"sort -R --random-source {_OUTSIDE_FILE} input.txt",
+ f"cd {_OUTSIDE_DIR} && cat memory.md", # chdir re-points every relative path that follows
+ f"cd {_OUTSIDE_DIR}; cat memory.md",
+ f"(cd {_OUTSIDE_DIR} && cat memory.md)",
+ f"pushd {_OUTSIDE_DIR}",
+ f"echo {_OUTSIDE_FILE} | xargs cat", # the path arrives through the pipeline, not an operand
+ f"tar cf - {_OUTSIDE_DIR}",
+ f"D={_OUTSIDE_DIR}; cat $D/memory.md", # assembled from an assignment
+ # tar's legacy option word is only the FIRST argument. The ordinary hyphenated spelling has no
+ # such word, so a blanket positional skip ate the real operand and the whole tree read silently.
+ f"tar -cf local.tar {_OUTSIDE_DIR}",
+ f"tar -czf local.tgz {_OUTSIDE_DIR}",
+ # -g/--listed-incremental names a snapshot file tar CREATES, in both spellings.
+ f"tar --listed-incremental={_OUTSIDE_DIR}/state.snar -cf local.tar src",
+ f"tar -g {_OUTSIDE_DIR}/state.snar -cf local.tar src",
+ # -C is where the operation HAPPENS: extracting creates and overwrites members under it, so a
+ # directory that is only READ-silent (a scan folder, /usr/share) is still being written here.
+ "tar -C /usr/share -xf local.tar",
+ f"tar -C {_OUTSIDE_DIR} -xf local.tar",
+ # shlex keeps a command substitution as ONE non-absolute token, so the operand scan saw nothing
+ # while the shell handed the command the real path.
+ f'cat "$(printf {_OUTSIDE_FILE})"',
+ f"cat `echo {_OUTSIDE_FILE}`",
+ f'cp local.txt "$(echo {_OUTSIDE_DIR}/out)"',
+ # A flag supplied the pattern, so no positional is owed to one and the first input file is a
+ # real operand. Keeping the skip discarded it and the read went unclassified.
+ f"grep -f patterns.txt {_OUTSIDE_FILE}",
+ f"sed -f prog.sed {_OUTSIDE_FILE}",
+ f"grep -e needle {_OUTSIDE_FILE}",
+ f"sed -e s/a/b/ {_OUTSIDE_FILE}",
+ f"grep --exclude-from={_OUTSIDE_DIR}/filters needle local.txt",
+ f"grep --exclude-from {_OUTSIDE_DIR}/filters needle local.txt",
+ # bash accepts several redirections before the command word. Kept whole, the token read as one
+ # silent /dev read and the write past it was never seen.
+ f"</dev/null>{_OUTSIDE_DIR}/out printf payload",
+ # A doubled separator inside ONE literal is just a separator; the OS collapses it. Treating it
+ # as a second root read /usr out of the path and the real file went silent.
+ "cat /home/alice//usr/report.txt",
+ # A cluster whose value is ATTACHED to its last letter, which GNU tar accepts.
+ f"tar -cf{_OUTSIDE_DIR}/out.tar src",
+ # The long spelling of create carries the same mode as -c.
+ "tar --create --file=/usr/share/out.tar src",
+ # /proc is read-silent, but /proc/<pid>/root is a kernel symlink to the process root, so the
+ # kernel resolves it before the rest and this opens the very file the plain path does.
+ "cat /proc/self/root/home/alice/report.txt",
+ "head -n 5 /proc/1234/cwd/../../home/alice/report.txt",
+ # diff compares --from-file to every operand, so it reads a file nothing occupies an operand
+ # position for.
+ "diff --from-file=/home/alice/private.txt local.txt",
+ "diff --to-file /home/alice/private.txt local.txt",
+ # An interpreter READS the file it is handed, and then runs it.
+ "python /home/alice/private.py",
+ "bash /home/alice/job.sh",
+ "sqlite3 /home/alice/private.db 'select 1'",
+ # `rg --files [PATH ...]` takes no pattern, so the skip was eating the enumerated tree.
+ "rg --files /media/kuser/MEDIA_SSD/private",
+ # git carries its working directory on a flag, so nothing sits in an operand position.
+ "git -C /media/kuser/MEDIA_SSD/private-repo show HEAD:secret.txt",
+ "git --git-dir=/media/kuser/MEDIA_SSD/r/.git log",
+ # A `file:` URI names the same file the bare path does.
+ 'sqlite3 file:/media/kuser/MEDIA_SSD/x.db?mode=ro "select 1"',
+ # `stdbuf -o L` takes its value as a separate token, so the scan stopped on `L`.
+ "stdbuf -o L cat /media/kuser/MEDIA_SSD/private.txt",
+ "unzip /media/kuser/MEDIA_SSD/private.zip",
+ "unzip a.zip -d /media/kuser/MEDIA_SSD/out",
+ # curl reads and writes local files through the file scheme.
+ "curl file:///media/kuser/MEDIA_SSD/private.txt",
+ "curl -o /media/kuser/MEDIA_SSD/out.txt https://example.com",
+ # sqlite3 creates the database when absent, so the operand is a write by default.
+ "sqlite3 /usr/share/catalog.db 'DELETE FROM entries'",
+ # A POSIX lexer eats the backslash, so every Windows absolute path was invisible to the gate.
+ # Asserted on every host, because what a path text means must not depend on the classifier's OS.
+ r"cat C:\Users\alice\Documents\private.txt",
+ r"type \\server\share\private.txt",
+ # `wget -P DIR` saves into DIR; a duplicate table key had dropped that classification.
+ "wget -P /usr/share/models https://example.com/m.bin",
+ # `date -f DATEFILE` reads every line and echoes an invalid one back.
+ "date -f /media/kuser/MEDIA_SSD/private.txt",
+ # ripgrep's own path option, absent from the grep spec it inherits.
+ "rg --ignore-file=/media/kuser/MEDIA_SSD/private.rules needle .",
+ # `install -d DIR...` CREATES every operand, so the destination-last rule does not apply.
+ "install -d /dev/shm/tool-output",
+ # `git archive --add-file` reads an untracked file into the archive; `--output` writes it.
+ "git archive --add-file=/media/kuser/MEDIA_SSD/private.txt -o out.tar HEAD",
+ "git archive --output=/media/kuser/MEDIA_SSD/out.tar HEAD",
+ # `--output-dir` is where `-O` puts the download, and `-O` itself contributes no operand.
+ "curl --output-dir=/media/kuser/MEDIA_SSD/private -O https://example.com/payload",
+ "wget --directory-prefix=/media/kuser/MEDIA_SSD/private https://example.com/payload",
+)
+
+_OUTSIDE_SANDBOX_INDIRECT_PYTHON = (
+ # The filesystem root is silent for a LISTING, not for a walk that descends the whole host.
+ "import os\nfor r, d, f in os.walk('/'):\n print(f)",
+ # `tempfile` creators write into `dir` when it is given.
+ "import tempfile\ntempfile.mkstemp(dir = '/media/alice')",
+ "import tempfile\ntempfile.TemporaryDirectory(dir = '/usr/share/doc')",
+ # The constructor's mode applies to the keyword spelling of the path too.
+ "import h5py\nh5py.File(name = '/usr/share/doc/model.h5', mode = 'w')",
+ # `sqlite3.Connection` is the public constructor `connect` returns; it opens the same file.
+ "import sqlite3\nsqlite3.Connection('/media/alice/private.db')",
+ "import apsw\napsw.Connection(filename = '/media/alice/private.db')",
+ # `h5py.File(path, "w")` truncates the file the constructor names.
+ "import h5py\nh5py.File('/usr/share/doc/model.h5', 'w')",
+ "import netCDF4\nnetCDF4.Dataset('/usr/share/doc/grid.nc', mode = 'a')",
+ # A relative operand handed to a child process lands wherever the `chdir` moved it.
+ "import os, subprocess\nos.chdir('/usr/share/doc')\nsubprocess.run(['touch', 'new.gguf'])",
+ # `pandas.read_excel(io = ...)` is the documented name of its first parameter.
+ f"import pandas as pd\nprint(pd.read_excel(io = {_OUTSIDE_FILE!r}))",
+ # The same names on a Path-like receiver, and their qualified forms, are the filesystem calls.
+ f"import os\nos.replace({_OUTSIDE_FILE!r}, 'b')",
+ f"import os\nos.remove({_OUTSIDE_FILE!r})",
+ f"from pathlib import Path\np = Path('x')\np.replace({_OUTSIDE_FILE!r})",
+ # `h5py.File(path, "r")` opens the file it is handed.
+ f"import h5py\nprint(h5py.File({_OUTSIDE_FILE!r}, 'r')['d'][:])",
+ # An interpreter's `-c` payload is CODE, so it is classified as code.
+ f"import subprocess\nsubprocess.run(['python', '-c', \"open({_OUTSIDE_FILE!r}, 'w')\"])",
+ # A `chdir` to an absolute directory moves where every later RELATIVE write lands.
+ f"import os\nos.chdir({_OUTSIDE_DIR!r})\nopen('weights.gguf', 'w').write('x')",
+ # A quoted path with a space in a `shell = True` command line.
+ f"import subprocess\nsubprocess.run(\"cat '{_OUTSIDE_DIR}/My Documents/private.txt'\", shell = True)",
+ # `io.open_code` opens its argument in binary mode, which is a read of that path.
+ f"import io\nprint(io.open_code({_OUTSIDE_FILE!r}).read())",
+ # `ZipFile.write` / `TarFile.add` name a SOURCE on disk and copy it into the archive.
+ f"import zipfile\nz = zipfile.ZipFile('out.zip', 'w')\nz.write({_OUTSIDE_FILE!r})",
+ f"import tarfile\nwith tarfile.open('out.tar', 'w') as t:\n t.add({_OUTSIDE_FILE!r})",
+ # `shutil.unpack_archive` creates the members under its destination.
+ f"import shutil\nshutil.unpack_archive('local.zip', {_OUTSIDE_DIR!r})",
+ f"import shutil\nshutil.unpack_archive('local.zip', extract_dir = {_OUTSIDE_DIR!r})",
+ # `make_archive` takes `root_dir` third and `base_dir` fourth, positionally too.
+ f"import shutil\nshutil.make_archive('backup', 'zip', {_OUTSIDE_DIR!r})",
+ f"import shutil\nshutil.make_archive('backup', 'zip', 'src', {_OUTSIDE_DIR!r})",
+ # `from tarfile import open as topen` resolves to the name `open`, so the MODULE identifies it.
+ f"from tarfile import open as topen\nt = topen('o.tar', 'w')\nt.add({_OUTSIDE_FILE!r})",
+ # A constructor imported under an alias binds the same archive object.
+ f"from zipfile import ZipFile as Z\nz = Z('local.zip', 'w')\nz.write({_OUTSIDE_FILE!r})",
+ # A literal splat hands the reader the same path the plain call does.
+ f"import pandas as pd\npd.read_csv(*[{_OUTSIDE_FILE!r}])",
+ # `shutil.make_archive` writes `base_name` and reads the directory it packs.
+ f"import shutil\nshutil.make_archive({_OUTSIDE_DIR!r} + '/backup', 'zip', 'src')",
+ f"import shutil\nshutil.make_archive('backup', 'zip', root_dir = {_OUTSIDE_DIR!r})",
+ # argv[0] IS the binary that runs, even when a later word is a command name this scan knows.
+ f"import subprocess\nsubprocess.run([{_OUTSIDE_FILE!r}, 'cat'])",
+ # `sqlite3.connect(database = ...)` is the documented keyword spelling of the same argument.
+ f"import sqlite3\nsqlite3.connect(database = {_OUTSIDE_FILE!r})",
+ # `str.join` concatenates: `"/".join(["/a", "/usr/b"])` is `/a//usr/b`, not `/usr/b`.
+ f"print(open('/'.join([{_OUTSIDE_DIR!r}, '/usr/share/doc/readme'])).read())",
+ # The same reader under its documented keyword name.
+ f"from PIL import Image\nprint(Image.open(fp = {_OUTSIDE_FILE!r}).size)",
+ # `executable` is what LAUNCHES; argv[0] is only the name the child sees.
+ f"import subprocess\nsubprocess.run(['echo'], executable = {_OUTSIDE_FILE!r})",
+ # The call itself creates the escape: a name in the sandbox that writes to the target.
+ f"import os\nos.symlink({_OUTSIDE_DIR!r}, 'local')",
+ f"import os\nos.link({_OUTSIDE_FILE!r}, 'local')",
+ # The constructor opens the workbook; the later `parse` never names it again.
+ f"import pandas as pd\nbook = pd.ExcelFile({_OUTSIDE_FILE!r})\nprint(book.parse(0))",
+ # The predicate family answers existence and type, the same disclosure `test -e` makes.
+ f"import os\nprint(os.path.exists({_OUTSIDE_FILE!r}))",
+ f"import os\nprint(os.path.isfile({_OUTSIDE_FILE!r}))",
+ f"import pathlib\nprint(pathlib.Path({_OUTSIDE_DIR!r}).is_dir())",
+ # `os.popen` runs a command line through a shell exactly as `os.system` does.
+ f"import os\nos.popen('cat {_OUTSIDE_FILE}').read()",
+ # Archive members are written UNDER the destination, so it is a write of a whole tree.
+ f"import zipfile\nzipfile.ZipFile('local.zip').extractall({_OUTSIDE_DIR!r})",
+ f"import tarfile\ntarfile.open('local.tar').extractall({_OUTSIDE_DIR!r})",
+ f"import tarfile\ntarfile.open('local.tar').extract('m', path = {_OUTSIDE_DIR!r})",
+ # Imported by name, so the call is a bare `Name` rather than a qualified one.
+ f"from fileinput import input as read\nprint(next(read({_OUTSIDE_FILE!r})))",
+ f"from fileinput import FileInput\nprint(FileInput({_OUTSIDE_FILE!r}))",
+ # Past the candidate cap, and reached by a constant index.
+ f"paths = ['/usr/a', '/usr/b', '/usr/c', '/usr/d', '/usr/e', '/usr/f', '/usr/g', '/usr/h', {_OUTSIDE_FILE!r}]\nopen(paths[8]).read()",
+ # Existence, size, ownership and timestamps of a path outside the sandbox.
+ f"import os\nprint(os.stat({_OUTSIDE_FILE!r}))",
+ f"import os\nprint(os.lstat({_OUTSIDE_FILE!r}))",
+ f"import pathlib\nprint(pathlib.Path({_OUTSIDE_FILE!r}).stat())",
+ # A move REMOVES its source, so the source side is a write wherever it sits.
+ f"import os\nos.rename({_OUTSIDE_FILE!r}, 'stolen.txt')",
+ f"import pathlib\npathlib.Path({_OUTSIDE_FILE!r}).rename('stolen.txt')",
+ f"import shutil\nshutil.move({_OUTSIDE_FILE!r}, 'stolen.txt')",
+ # A literal sequence held in a NAME is the same list the inline form passes.
+ f"import configparser\ncfg = configparser.ConfigParser()\npaths = [{_OUTSIDE_FILE!r}]\ncfg.read(paths)",
+ f"import fileinput\npaths = [{_OUTSIDE_FILE!r}]\nfor line in fileinput.input(files = paths):\n print(line)",
+ # A literal `**{...}` passes the path under its own parameter name, and the splat arrives as a
+ # keyword whose `arg` is None, so the name was never matched.
+ f"import pandas as pd\npd.read_csv(**{{'filepath_or_buffer': {_OUTSIDE_FILE!r}}})",
+ # The aliased receiver and the constructor `input` returns, which iterates the same files.
+ f"import fileinput as fi\nfor line in fi.input({_OUTSIDE_FILE!r}):\n print(line)",
+ f"import fileinput\nfor line in fileinput.FileInput({_OUTSIDE_FILE!r}):\n print(line)",
+ # Nothing dynamic in either: the container, the index and the path are all literals.
+ f"paths = [{_OUTSIDE_FILE!r}]\nopen(paths[0]).read()",
+ f"cfg = {{'db': {_OUTSIDE_FILE!r}}}\nopen(cfg['db']).read()",
+ f"open({{'p': {_OUTSIDE_FILE!r}}}['p']).read()",
+ # `io.FileIO(p)` opens the path exactly as `io.open(p)` does.
+ f"import io\nio.FileIO({_OUTSIDE_FILE!r}).read()",
+ # An annotated instance assignment binds the reader exactly as the plain form does.
+ f"import configparser\ncfg: configparser.ConfigParser = configparser.ConfigParser()\ncfg.read({_OUTSIDE_FILE!r})",
+ # Called BEFORE the rebinding, so dropping the alias outright let the read through.
+ f"reader = open\nprint(reader({_OUTSIDE_FILE!r}).read())\nreader = None",
+ # The rebound name sits inside a larger expression, where only its first binding was folded.
+ f"base = 'local'\nbase = {_OUTSIDE_DIR!r}\nopen(base + '/report').read()",
+ f"import os\nbase = 'local'\nbase = {_OUTSIDE_DIR!r}\nopen(os.path.join(base, 'report')).read()",
+ # Parameter names only these callables use, so the shared keyword list never carried them.
+ f"import configparser\nc = configparser.ConfigParser()\nc.read(filenames = {_OUTSIDE_FILE!r})",
+ f"import configparser\nc = configparser.ConfigParser()\nc.read(filenames = ['a.ini', {_OUTSIDE_FILE!r}])",
+ f"import glob\nprint(glob.glob(pathname = {_OUTSIDE_DIR!r} + '/*.txt'))",
+ f"import glob\nprint(glob.glob('*.txt', root_dir = {_OUTSIDE_DIR!r}))",
+ f"import os\nos.chdir({_OUTSIDE_DIR!r})\nprint(open('memory.md').read())",
+ f"import subprocess\nsubprocess.run(['cat', {_OUTSIDE_FILE!r}])", # a child process this scan cannot follow
+ f"import subprocess\nsubprocess.check_output('cat {_OUTSIDE_FILE}', shell = True)",
+ f"import fileinput\nfor line in fileinput.input({_OUTSIDE_FILE!r}):\n print(line)",
+ f"import zipfile\nzipfile.ZipFile({_OUTSIDE_DIR!r} + '/a.zip', 'w')",
+ f"import pathlib\npathlib.Path({_OUTSIDE_FILE!r}).open().read()", # the path is the receiver
+ # Spelled as an attribute, but these are MODULE functions taking the path first, so treating the
+ # receiver as the path folded the bare module name and the read escaped.
+ f"import io\nio.open({_OUTSIDE_FILE!r}).read()",
+ f"import gzip\ngzip.open({_OUTSIDE_DIR!r} + '/data.gz', 'rb').read()",
+ f"import os\nos.open({_OUTSIDE_FILE!r}, os.O_CREAT | os.O_WRONLY)",
+ # A chained assignment has more than one target; skipping the statement left the name unfoldable.
+ f"source = backup = {_OUTSIDE_FILE!r}\nprint(open(source).read())",
+ f"a, b = c, d = {_OUTSIDE_FILE!r}, 'local.txt'\nprint(open(c).read())",
+ # An aliased import leaves a receiver that is in no table, so the call read as a Path-style
+ # method and its first argument was never looked at.
+ f"import io as stream\nstream.open({_OUTSIDE_FILE!r}).read()",
+ f"import gzip as gz\ngz.open({_OUTSIDE_DIR!r} + '/d.gz', 'rb').read()",
+ # `from io import open as fopen` leaves a plain Name in no table.
+ f"from io import open as fopen\nfopen({_OUTSIDE_FILE!r}).read()",
+ f"from gzip import open as gopen\ngopen({_OUTSIDE_DIR!r} + '/d.gz', 'rb').read()",
+ # A DERIVED binding has to carry every value its dependency ever held, or the rebinding is lost
+ # the moment the path is assembled rather than used directly.
+ f"base = 'local'\nbase = {_OUTSIDE_DIR!r}\np = base + '/report.txt'\nopen(p).read()",
+ f"import os\nb = 'local'\nb = {_OUTSIDE_DIR!r}\np = os.path.join(b, 'r.txt')\nopen(p).read()",
+ # A module function spelled as an attribute puts BOTH paths in its arguments; reading the
+ # receiver as the source folded the bare module name and lost the destination entirely.
+ f"import os\nos.rename('local.txt', {_OUTSIDE_DIR!r} + '/out.txt')",
+ f"import shutil\nshutil.copy('local.txt', {_OUTSIDE_DIR!r} + '/out.txt')",
+ # tarfile.open takes the path first like the other module opens.
+ f"import tarfile\ntarfile.open({_OUTSIDE_DIR!r} + '/a.tar', 'w')",
+ # The serializer receiver has to be resolved through the alias, or the call falls through to a
+ # branch that never looks at the second argument.
+ f"import torch as t\nt.save(m, {_OUTSIDE_DIR!r} + '/model.pt')",
+ # Any MODELED path call is reachable under an alias, not just the open-like ones.
+ f"from pandas import read_csv as rc\nrc({_OUTSIDE_DIR!r} + '/report.csv')",
+ f"from shutil import copy as cp\ncp('a.txt', {_OUTSIDE_DIR!r} + '/out.txt')",
+ # A command string recovered from a variable has to be split like a literal one.
+ f"import subprocess\ncmd = 'cat {_OUTSIDE_FILE}'\nsubprocess.run(cmd, shell = True)",
+ f"open('/home/alice//usr/report.txt').read()",
+ # The alternate cap is ranked by what needs APPROVAL: nine read-silent rebindings must not
+ # crowd out the one value that does.
+ (
+ "\n".join(f"base = '/usr/a{i}'" for i in range(9))
+ + f"\nbase = {_OUTSIDE_DIR!r}\np = base + '/report.txt'\nopen(p).read()"
+ ),
+ # The alternate cap must bound WORK, not coverage: eight benign reassignments ahead of the
+ # absolute one must not hide it.
+ (
+ "base = 'local'\n"
+ + "\n".join(f"base = 'r{i}'" for i in range(9))
+ + f"\nbase = {_OUTSIDE_DIR!r}\np = base + '/report.txt'\nopen(p).read()"
+ ),
+ # A plain assignment binds the same identity an import alias does.
+ f"reader = open\nprint(reader({_OUTSIDE_FILE!r}).read())",
+ "import pandas as pd\nrc = pd.read_csv\nrc('/media/kuser/MEDIA_SSD/report.csv')",
+ # /usr/share is read-silent and write-gated, so ranking the alternates as reads dropped it and
+ # the write that followed overwrote a system directory in silence.
+ (
+ "\n".join(f"base = 'sub{i}'" for i in range(9))
+ + "\nbase = '/usr/share'\np = base + '/out'\nopen(p, 'w').write('x')"
+ ),
+ # The builtin under a qualified name, and under an alias of the module.
+ 'import builtins\nbuiltins.open("/media/kuser/MEDIA_SSD/x", "w").write("y")',
+ 'import builtins as b\nb.open("/media/kuser/MEDIA_SSD/x").read()',
+ # A module-level open whose receiver is not a path.
+ "from PIL import Image\nImage.open('/media/kuser/MEDIA_SSD/photo.png')",
+ "import PIL.Image\nPIL.Image.open('/media/kuser/MEDIA_SSD/photo.png')",
+ # An alias of an alias binds the same function.
+ "reader = open\nreader2 = reader\nreader2('/media/kuser/MEDIA_SSD/x').read()",
+ # joinpath drops everything left of an absolute piece, exactly as `/` and os.path.join do.
+ "from pathlib import Path\nPath('/usr').joinpath('/media/kuser/MEDIA_SSD/x.txt').read_text()",
+ # numpy.load takes a FILENAME, unlike every other `load` in these tables.
+ "import numpy as np\nnp.load('/media/kuser/MEDIA_SSD/private.npy')",
+ # A constructor or a join under an import alias builds the same path.
+ "from pathlib import Path as P\nP('/media/kuser/MEDIA_SSD/private.txt').read_text()",
+ "from os.path import join as j\nopen(j('/media/kuser/MEDIA_SSD', 'private.txt')).read()",
+ # numpy.load is modelled on its module, so a from-import has to carry that provenance.
+ "from numpy import load\nload('/media/kuser/MEDIA_SSD/private.npy')",
+ "from numpy import load as read_array\nread_array('/media/kuser/MEDIA_SSD/x.npy')",
+ # `Image` is itself a modelled receiver, so an aliased from-import has to resolve back to it.
+ "from PIL import Image as I\nI.open('/media/kuser/MEDIA_SSD/private.png')",
+ # A constructor bound by assignment, which is the same binding an import alias makes.
+ "from pathlib import Path\nP = Path\nP('/media/kuser/MEDIA_SSD/private.txt').read_text()",
+ "import os.path\nj = os.path.join\nopen(j('/media/kuser/MEDIA_SSD', 'x.txt')).read()",
+ # A module copied through an assignment is the same module.
+ "import io\nstream = io\nstream.open('/media/kuser/MEDIA_SSD/private.txt').read()",
+ # A reader reached through an INSTANCE: the constructor is what identifies it.
+ "import configparser\nc = configparser.ConfigParser()\nc.read('/media/kuser/MEDIA_SSD/p.ini')",
+ "import configparser\nconfigparser.ConfigParser().read('/media/kuser/MEDIA_SSD/p.ini')",
+ # The keyword spelling of fileinput's argument, and its sequence form.
+ "import fileinput\nfor line in fileinput.input(files = '/media/kuser/MEDIA_SSD/p.txt'):\n print(line)",
+ # An annotated binding is the same binding.
+ "reader: object = open\nreader('/media/kuser/MEDIA_SSD/private.txt').read()",
+)
+
+# The same indirections pointed somewhere ordinary: these must stay silent.
+_INDIRECT_BENIGN_TERMINAL = (
+ "/usr/bin/python3 script.py",
+ 'cd /usr/share/doc && python -c "print(1)"',
+ "gcc -o out main.c",
+ "make -C ./sub all",
+ "git init ./repo",
+ "chmod 644 notes.txt",
+ "cp --targ=./staged payload",
+ "cp --preserve=mode notes.txt copy.txt",
+ # Reading through the same spellings stays silent under a read-silent root.
+ "sed -n '1,5p' /usr/share/doc/notes",
+ "find /usr/share/doc -name '*.txt' | xargs cat",
+ "ls /usr/share | xargs -n 1 echo",
+ "env - FOO=bar cat notes.txt",
+ "pr <(cat notes.txt)",
+ # `basename` / `dirname` print components of a NAME; they open nothing.
+ "basename /media/alice/private.txt",
+ "dirname /media/alice/private.txt",
+ "zcat archive.gz",
+ # `-c` keeps the original unchanged, so a system-root read stays a read.
+ "gzip -dc /usr/share/doc/archive.gz",
+ "gunzip -c /usr/share/doc/archive.gz",
+ "zstd out.txt",
+ "7z a out.7z src",
+ "7z x out.7z",
+ # A `cd` with nothing writing after it, and a relative one, are both ordinary.
+ "cd /usr/share/doc && ls",
+ "cd /usr/share/doc && grep -rn TODO .",
+ "cd build && touch x",
+ "tar -cf out.tar --add-file=local.txt",
+ "date --reference=./notes.txt",
+ "date +%s",
+ # `zip archive src`: the archive is written, the sources are read.
+ "zip local.zip /usr/share/doc/file",
+ "cat <(cat $(echo notes.txt))",
+ "diff <(sort a) <(sort b)",
+ # `test`/`[` only stat the operand of a FILE operator; the rest is string comparison.
+ 'while [ "$d" != "/" ]; do d=$(dirname "$d"); done',
+ '[ "$root" = "/" ] && echo top',
+ # The filesystem root itself is covered by no silent root, but reading it shows only the
+ # top-level names.
+ "ls /",
+ "echo 'a<b' > out.txt",
+ 'cat <<< "$(date)"',
+ "curl --config=./local.conf https://example.com",
+ "jq -L ./modules '.a' data.json",
+ "jq -r '.items[] | .name' out.json",
+ "p=hello; cat notes/${p:0:3}",
+ "echo a:b:c",
+ "git commit -m 'fix: thing'",
+ "make -j4",
+ "make -f Makefile.dev install",
+ "busybox cat notes.txt",
+ "test -e ./notes.txt",
+ "[ -d build ]",
+ "test -e /usr/bin/python3",
+ "ln -s ./a ./b",
+ "cat /dev/urandom",
+ "cat /run/systemd/resolve/resolv.conf",
+ "cp /usr/share/doc/x.txt ./local.txt",
+ "mv build/a.txt build/b.txt",
+ "tar -xf /usr/share/doc/archive.tar",
+ "cat /proc/self/status",
+ 'echo "`ls`"',
+ "iconv -f utf8 -t ascii local.txt",
+ "iconv -o out.txt local.txt",
+ "if true; then cat notes.txt; fi",
+ "for f in *.txt; do wc -l $f; done",
+ "echo `ls`",
+ # Quoted, so the backticks are literal and nothing runs.
+ f"echo 'a `cat {_OUTSIDE_FILE}` b'",
+ # Quoted, so the shell prints it and opens nothing.
+ f"printf 'see >{_OUTSIDE_FILE}'",
+ f'echo "a > {_OUTSIDE_FILE}"',
+ "wget -o log.txt https://example.com",
+ "git clone --separate-git-dir=.git repo checkout",
+ # No shell opens either of these: `<<` names a here-document delimiter and `<<<` is the data.
+ f"cat <<< {_OUTSIDE_FILE}",
+ f"cat << {_OUTSIDE_DIR}/END",
+ "cat <<EOF\nhello\nEOF",
+ "sort -R input.txt",
+ "cd build && make",
+ "cd /usr/lib && ls",
+ "echo notes.txt | xargs cat",
+ "tar czf out.tgz .",
+ "cat /proc/cpuinfo",
+ "cat /proc/self/status",
+ "diff -u a.txt b.txt",
+ "diff -W 80 --label /before a.txt b.txt",
+ "python train.py",
+ "python -m pytest -q",
+ "python -c 'print(1)'",
+ "bash scripts/build.sh",
+ "python /usr/lib/python3/dist-packages/x.py",
+ "sqlite3 data.db 'select 1'",
+ "rg --files src",
+ "rg pattern src",
+ "git status",
+ "git -C src log",
+ 'git -c user.name=x commit -m "y"',
+ 'sqlite3 file:local.db "select 1"',
+ "curl https://example.com/x",
+ "curl file:///usr/share/doc/x.txt",
+ "date",
+ "date -d yesterday",
+ "rg --ignore-file=.rgignore needle .",
+ "wget https://example.com/x",
+ "install -d out",
+ "install a.txt b.txt",
+ "git archive -o out.tar HEAD",
+ "curl --output-dir=out -O https://example.com/payload",
+ "wget --directory-prefix=downloads https://example.com/payload",
+ "tar -cf out.tar /usr/share/doc",
+ # A read-only sqlite invocation under a read-silent root. Without `-readonly` the database is a
+ # write, which /usr is not silent for.
+ 'sqlite3 -readonly file:/usr/share/x.db "select 1"',
+ "stdbuf -o L cat notes.txt",
+ # The archive is READ, so a listing under the read-silent /usr must not ask.
+ "unzip -l /usr/share/doc/example.zip",
+ "unzip a.zip",
+ "cat ~/notes.txt",
+ "mkdir ~/.config/myapp",
+)
+
+_INDIRECT_BENIGN_PYTHON = (
+ "import os\nprint(os.listdir('/'))",
+ "import os\nfor r, d, f in os.walk('/usr/share/doc'):\n print(f)",
+ "import tempfile\ntempfile.mkstemp()",
+ "import tempfile\ntempfile.mkdtemp(dir = './scratch')",
+ "import h5py\nh5py.File(name = '/usr/share/doc/model.h5', mode = 'r')",
+ "import h5py\nh5py.File('/usr/share/doc/model.h5', 'r')",
+ "import os, subprocess\nos.chdir('/usr/share/doc')\nsubprocess.run(['ls', '-la'])",
+ "import zipfile\nz = zipfile.ZipFile('out.zip', 'w')\nz.write('notes.txt')",
+ "import io\nprint(io.open_code('local.py').read())",
+ "import pandas as pd\nprint(pd.read_excel(io = 'book.xlsx'))",
+ "import subprocess\nsubprocess.run(['python', '-c', 'print(1)'])",
+ "import h5py\nprint(h5py.File('local.h5', 'r')['d'][:])",
+ # A `chdir` with only reads after it, and a relative one, are both ordinary.
+ "import os\nos.chdir('/usr/share/doc')\nprint(open('x').read())",
+ "import os\nos.chdir('build')\nopen('x', 'w').write('y')",
+ # `replace` and `remove` on a str, a list or a DataFrame touch no file.
+ "text = 'a'\nprint(text.replace('/media/alice', 'x'))",
+ "import pandas as pd\ndf = pd.DataFrame()\ndf.replace('/media/alice', 'x')",
+ "items = ['/media/alice']\nitems.remove('/media/alice')",
+ # A gzip/bz2/lzma object takes DATA, exactly like an ordinary file handle.
+ "import gzip\nf = gzip.GzipFile('out.gz', 'w')\nf.write(b'/home/alice/x')",
+ "import shutil\nshutil.unpack_archive('local.zip', 'build')",
+ "import shutil\nshutil.make_archive('backup', 'zip', 'src')",
+ "from zipfile import ZipFile as Z\nz = Z('local.zip', 'w')\nz.write('notes.txt')",
+ "from tarfile import open as topen\nt = topen('o.tar', 'w')\nt.add('notes.txt')",
+ # An ordinary handle's write is DATA, whatever it looks like.
+ "f = open('a.txt', 'w')\nf.write('/home/alice/x')",
+ "import pandas as pd\npd.read_csv(*['local.csv'])",
+ # A splat of something dynamic stays the documented residual rather than a guess.
+ "import pandas as pd\npd.read_csv(*args)",
+ "import subprocess\nsubprocess.run(['/usr/bin/python3', 'train.py'])",
+ "import sqlite3\nsqlite3.connect(database = 'local.db')",
+ "from PIL import Image\nprint(Image.open(fp = 'local.png').size)",
+ "import subprocess\nsubprocess.run(['echo'], executable = '/bin/sh')",
+ "import os\nos.symlink('models', 'local')",
+ "import pandas as pd\nbook = pd.ExcelFile('book.xlsx')\nprint(book.parse(0))",
+ "import os\nprint(os.path.exists('notes.txt'))",
+ "import pathlib\nprint(pathlib.Path('build').is_dir())",
+ "import os\nos.popen('ls').read()",
+ "import zipfile\nzipfile.ZipFile('local.zip').extractall('out')",
+ "from fileinput import input as read\nprint(next(read('notes.txt')))",
+ "paths = ['/usr/share/a', '/usr/share/b']\nopen(paths[1]).read()",
+ "import os\nprint(os.stat('notes.txt'))",
+ "import pathlib\nprint(pathlib.Path('notes.txt').stat())",
+ "import shutil\nshutil.copy('/usr/share/doc/x.txt', 'copy.txt')",
+ "import os\nos.rename('a.txt', 'b.txt')",
+ "import configparser\ncfg = configparser.ConfigParser()\npaths = ['a.ini']\ncfg.read(paths)",
+ "import pandas as pd\npd.read_csv(**{'filepath_or_buffer': 'data.csv'})",
+ "import fileinput as fi\nfor line in fi.input('notes.txt'):\n print(line)",
+ "value = input('/data directory: ')",
+ "paths = ['notes.txt', 'data.csv']\nopen(paths[0]).read()",
+ "import io\nio.FileIO('notes.txt').read()",
+ # A child command the scan DOES classify, and one that takes no path operand at all: prompting
+ # here and not on the identical terminal command was a difference with no reason behind it.
+ "import subprocess\nsubprocess.run(['echo', '/home/alice/private.txt'])",
+ "import subprocess\nsubprocess.run(['printf', '%s', '/home/alice/private.txt'])",
+ "import configparser\ncfg: configparser.ConfigParser = configparser.ConfigParser()\ncfg.read('settings.ini')",
+ "base = 'local'\nbase = 'other'\nopen(base + '/report').read()",
+ "import configparser\nc = configparser.ConfigParser()\nc.read(filenames = 'settings.ini')",
+ "import glob\nprint(glob.glob(pathname = '*.txt'))",
+ "import glob\nprint(glob.glob('*.txt', root_dir = 'data'))",
+ "import os\nos.chdir('subdir')",
+ "import subprocess\nsubprocess.run(['ls', '-la'])",
+ "import subprocess\nsubprocess.run(['python', 'train.py'])",
+ "import zipfile\nzipfile.ZipFile('out.zip', 'w')",
+ "reader = open\nprint(reader('notes.txt').read())",
+ "import pandas as pd\nrc = pd.read_csv\nrc('data.csv')",
+ # Bound twice, so which function it holds at the call is not answerable.
+ "reader = open\nreader = None\nprint(reader)",
+ 'import builtins\nbuiltins.open("notes.txt").read()',
+ "from PIL import Image\nImage.open('local.png')",
+ "reader = open\nreader2 = reader\nreader2('notes.txt').read()",
+ "from pathlib import Path\nPath('/usr').joinpath('share', 'x.txt').read_text()",
+ "open('~/notes.txt').read()",
+ "import numpy as np\nnp.load('data.npy')",
+ "import json\njson.load(open('cfg.json'))",
+ "from pathlib import Path as P\nP('data.csv').read_text()",
+ "from pathlib import Path\nP = Path\nP('data.csv').read_text()",
+ "import io\nstream = io\nstream.open('notes.txt').read()",
+ "import configparser\nc = configparser.ConfigParser()\nc.read('app.ini')",
+ "f = open('x')\nf.read()",
+ "import fileinput\nfor line in fileinput.input(files = 'notes.txt'):\n print(line)",
+ "reader: object = open\nreader('notes.txt').read()",
+ "Foo().read('/media/kuser/MEDIA_SSD/x')",
+ "stream = something\nstream.open('/media/kuser/MEDIA_SSD/x')",
+ "from numpy import load\nload('data.npy')",
+ "from json import load\nload(open('cfg.json'))",
+ "from PIL import Image as I\nI.open('local.png')",
+)
+
+
[email protected]("command", _OUTSIDE_SANDBOX_INDIRECT_TERMINAL)
+def test_auto_mode_prompts_on_indirect_out_of_sandbox_terminal(command):
+ assert is_high_risk_tool_call("terminal", {"command": command}) is True
+
+
[email protected]("code", _OUTSIDE_SANDBOX_INDIRECT_PYTHON)
+def test_auto_mode_prompts_on_indirect_out_of_sandbox_python(code):
+ assert is_high_risk_tool_call("python", {"code": code}) is True
+
+
[email protected]("command", _INDIRECT_BENIGN_TERMINAL)
+def test_indirect_forms_stay_silent_inside_the_sandbox_terminal(command):
+ assert is_high_risk_tool_call("terminal", {"command": command}) is False
+
+
[email protected]("code", _INDIRECT_BENIGN_PYTHON)
+def test_indirect_forms_stay_silent_inside_the_sandbox_python(code):
+ assert is_high_risk_tool_call("python", {"code": code}) is False
+
+
[email protected]("command", _OUTSIDE_SANDBOX_TERMINAL)
+def test_auto_mode_prompts_on_out_of_sandbox_terminal_paths(command):
+ assert is_high_risk_tool_call("terminal", {"command": command}) is True
+
+
[email protected]("code", _OUTSIDE_SANDBOX_PYTHON)
+def test_auto_mode_prompts_on_out_of_sandbox_python_paths(code):
+ assert is_high_risk_tool_call("python", {"code": code}) is True
+
+
[email protected]("command", _ALLOWLISTED_TERMINAL)
+def test_auto_mode_stays_silent_inside_allowlisted_roots_terminal(command):
+ assert is_high_risk_tool_call("terminal", {"command": command}) is False
+
+
[email protected]("code", _ALLOWLISTED_PYTHON)
+def test_auto_mode_stays_silent_inside_allowlisted_roots_python(code):
+ assert is_high_risk_tool_call("python", {"code": code}) is False
+
+
+def test_configured_cache_reads_stay_silent():
+ """A read under THIS install's own sandbox / model cache is ordinary work, unlike the same path
+ shape under someone else's home."""
+ from core.inference import tool_path_approval as path_gate
+
+ read_roots, write_roots = path_gate._silent_roots()
+ assert read_roots, "no silent roots resolved; every absolute read would prompt"
+ for root in read_roots:
+ assert path_gate._path_needs_approval(os.path.join(root, "model", "config.json")) is False
+ for root in write_roots:
+ assert path_gate._path_needs_approval(os.path.join(root, "out.bin"), writing = True) is False
+
+
+def test_credential_paths_outrank_the_allowlist():
+ """The allowlist must never turn a credential read silent: /etc is read-silent, /etc/shadow is
+ not."""
+ from core.inference import tool_path_approval as path_gate
+ for path in (
+ "/etc/shadow",
+ "/etc/ssh/ssh_host_rsa_key",
+ "~/.ssh/id_rsa",
+ "~/.aws/credentials",
+ "/proc/self/environ",
+ ):
+ assert path_gate._path_needs_approval(path) is True, path
+
+
+def test_relative_paths_never_prompt():
+ """Relative paths resolve inside the per-session workdir, which is the whole reason ordinary
+ in-sandbox work stays silent."""
+ from core.inference import tool_path_approval as path_gate
+ for path in ("out.txt", "./data/train.csv", "build/artifacts/model.gguf", "-", ""):
+ assert path_gate._path_needs_approval(path, writing = True) is False, path
+
+
+def test_windows_spellings_are_treated_as_absolute():
+ """Path syntax is judged on every host, so a Windows-only classifier bug cannot hide behind a
+ Linux test run."""
+ from core.inference import tool_path_approval as path_gate
+ for path in ("C:\\Users\\kuser\\Documents\\taxes.xlsx", "\\\\fileserver\\share\\secret.docx"):
+ assert path_gate._path_needs_approval(path) is True, path
+
+
+def test_unresolved_dynamic_paths_do_not_prompt():
+ """A path the folder could not resolve carries the NUL sentinel; it is not a decidable path, and
+ the dynamic-alias checks cover those separately."""
+ from core.inference import tool_path_approval as path_gate
+ assert path_gate._path_needs_approval("/media/\x00/file") is False
+
+
+def test_parent_escape_sentinel_asks():
+ """\x02 marks a pathlib .parent walking OUT of its root. It is an escape marker, so grouping it
+ with the unresolved marker would turn the signal into a pass."""
+ from core.inference import tool_path_approval as path_gate
+ assert path_gate._path_needs_approval("\x02/file") is True
+
+
+# Every payload below reached a host path with no approval prompt in the first cut of the
+# out-of-sandbox gate, and was found by reviewing it. They are kept as regressions because each one
+# is a DIFFERENT way of losing the path or its access mode, not a variation on one mistake.
+_REVIEWED_BYPASS_PYTHON = (
+ # The write mode was re-derived from a table that does not list `open`, so keyword writes were
+ # checked against the READ allowlist and every read-silent root became silently writable.
+ 'open(file = "/etc/evil.conf", mode = "w").write("pwn")',
+ 'open(file = "/usr/lib/evil.py", mode = "w")',
+ 'import zipfile\nzipfile.ZipFile(file = "/usr/lib/evil.zip", mode = "w")',
+ # Path(p).open("w") carries the mode in the FIRST argument, because the receiver is the path.
+ 'from pathlib import Path\nPath("/etc/new_service.conf").open("w").write("payload")',
+ 'from pathlib import Path\nPath("/etc/evil.conf").open("w")',
+ # A name rebound later must not reclassify the read that already happened.
+ 'p = "/media/x/report.txt"\nprint(open(p).read())\np = "local.txt"',
+ # Binding forms the first pass did not fold.
+ 'print(open(p := "/media/x/report.txt").read())',
+ 'p: str = "/media/alice/notes.txt"\nprint(open(p).read())',
+ 'p, _ = "/media/x/memory.md", 1\nopen(p).read()',
+ # A later absolute component discards the earlier one, so the /usr prefix is not protection.
+ 'import os\nopen(os.path.join("/usr", "/media/x/report.txt")).read()',
+ 'from pathlib import Path\n(Path("/usr") / "/media/x/report.txt").read_text()',
+ # A child process is not bound by this scan, and its argv carries the access mode.
+ 'import subprocess\nsubprocess.run(["touch", "/etc/evil.conf"])',
+ 'import subprocess\nsubprocess.run(["cp", "./payload", "/etc/evil.conf"])',
+ 'import subprocess\nsubprocess.run("echo evil > /etc/app.conf", shell = True)',
+ # Serializers put the destination second.
+ 'import torch\ntorch.save(model, "/media/kuser/model.pt")',
+ 'import torch\ntorch.save(model, f = "/media/kuser/model.pt")',
+ 'import joblib\njoblib.dump(data, "/media/kuser/data.joblib")',
+ # As a method, the receiver is the source being moved away.
+ 'from pathlib import Path\nPath("/media/x/memory.md").rename("stolen.md")',
+ # A single leading backslash is root-relative on Windows, not sandbox-relative.
+ 'open(r"\\Users\\alice\\report.txt").read()',
+ # .parent walking out of its root is an escape marker, not an unresolved path.
+ 'from pathlib import Path\np = Path("/media/x/sub/file").parent\nopen(p / "memory.md").read()',
+)
+
+_REVIEWED_BYPASS_TERMINAL = (
+ # shlex is not given < and > as punctuation, so the redirect target hid inside one token.
+ "echo CHANGED>/media/review/report.txt",
+ "cat</media/alice/notes.txt",
+ "printf changed>/media/alice/notes.txt",
+ "echo CLOBBERED >| /media/report.txt",
+ # A wrapper brings its own options, so skipping only its name left `5` reading as the command.
+ "timeout 5 cat /media/review/report.txt",
+ "nice -n 5 cat /media/review/report.txt",
+ "env -u UNUSED cat /media/alice/notes.txt",
+ "env -i cat /home/review/Documents/note.txt",
+ # A path can arrive as a flag VALUE, with the flag deciding read or write.
+ "cp --target-directory=/media/review payload.txt",
+ "cp -t /usr/share/review payload.txt",
+ "sort --output=/media/alice/notes.txt local.txt",
+ "sort -o/media/alice/notes.txt local.txt",
+ "sort -o /usr/local/share/note.txt local.txt",
+ "grep -f /media/alice/patterns.txt local.txt",
+ "grep --file=/media/report.txt local.txt",
+ "awk -f /media/kuser/script.awk file.txt",
+ "jq -f /media/kuser/filter.jq file.json",
+ # Creating an archive writes it; only extracting reads it.
+ "tar -cf /media/alice/out.tar local.txt",
+ "tar cf /media/x/out.tar .",
+ "tar -cf /etc/evil.tar .",
+ "tar -C /media/kuser -xf archive.tar",
+)
+
+# Flag values that merely LOOK like paths. A delimiter is data, and prompting on it would nag on
+# ordinary text processing.
+_FLAG_VALUE_NOT_A_PATH = (
+ "cut -d '/' -f 1 data.txt",
+ "sort -t / -k 2 data.txt",
+ "column -s / -t input.txt",
+ "paste -d / a.txt b.txt",
+ "echo a/b | cut -d '/' -f1",
+ "echo hello/world | tr '/' '_'",
+ "grep -e '/pattern' list.txt",
+ "sed -e '/foo/d' -e '/bar/d' file.txt",
+ "head -n 5 data.csv",
+ "tail -c 200 notes.txt",
+ "tar -xf archive.tar",
+ "tar czf out.tgz .",
+ "timeout 5 python train.py",
+ "nice -n 5 make",
+ "env -u FOO python train.py",
+ "sort -o out.txt in.txt",
+ "grep -f patterns.txt list.txt",
+)
+
+
[email protected]("code", _REVIEWED_BYPASS_PYTHON)
+def test_reviewed_python_bypasses_now_ask(code):
+ assert is_high_risk_tool_call("python", {"code": code}) is True
+
+
[email protected]("command", _REVIEWED_BYPASS_TERMINAL)
+def test_reviewed_terminal_bypasses_now_ask(command):
+ assert is_high_risk_tool_call("terminal", {"command": command}) is True
+
+
[email protected]("command", _FLAG_VALUE_NOT_A_PATH)
+def test_flag_values_that_look_like_paths_stay_silent(command):
+ assert is_high_risk_tool_call("terminal", {"command": command}) is False
+
+
+ "code",
+ (
+ # The first argument is CONTENT; only the receiver is a path.
+ 'from pathlib import Path\nPath("route.txt").write_text("/api/v1/items")',
+ 'from pathlib import Path\nPath("manifest.txt").write_text("/media/alice/model.gguf")',
+ 'from pathlib import Path\nPath("paths.txt").write_bytes(b"/home/review/Documents")',
+ # The builtin prompt is not a filename (the read entry exists for fileinput.input).
+ 'val = input("/home/user/data directory: ")',
+ # numpy.save takes the path FIRST, unlike torch.save.
+ "import numpy as np\nnp.save('embeddings.npy', np.zeros(3))",
+ "import torch\ntorch.save(model, 'ckpt.pt')",
+ # C:relative.txt is relative to the drive's current directory, not rooted.
+ 'open("C:relative.txt").read()',
+ "import subprocess\nsubprocess.run(['ls', '-la'])",
+ ),
+)
+def test_reviewed_false_positives_stay_silent(code):
+ assert is_high_risk_tool_call("python", {"code": code}) is False
+
+
+def test_high_risk_implies_potentially_unsafe():
+ """The stricter gate must stay a superset of the looser one. Gating the out-of-sandbox check on
+ a leading / or ~ broke that: every Windows spelling skipped the stricter classifier."""
+ for command in (*_REVIEWED_BYPASS_TERMINAL, "cat 'C:\\Users\\alice\\notes.txt'"):
+ if is_high_risk_tool_call("terminal", {"command": command}):
+ assert (
+ is_potentially_unsafe_tool_call("terminal", {"command": command}) is True
+ ), command
+
+
+def test_credentials_inside_a_silent_root_still_ask():
+ """A relocated cache is allowlisted wholesale, so the token store inside it needs a name-based
+ rule: the path no longer contains the directory name the credential regex looks for."""
+ from core.inference import tool_path_approval as path_gate
+
+ read_roots, _ = path_gate._silent_roots()
+ hf_roots = [root for root in read_roots if "huggingface" in root]
+ for root in hf_roots:
+ assert path_gate._path_needs_approval(os.path.join(root, "token")) is True
+ assert path_gate._path_needs_approval(os.path.join(root, "stored_tokens")) is True
+ assert (
+ path_gate._path_needs_approval(os.path.join(root, "hub", "m", "config.json")) is False
+ )
+ for path in ("/etc/gshadow", "/etc/krb5.keytab", "/etc/security/opasswd"):
+ assert path_gate._path_needs_approval(path) is True, path
+
+
+def test_studio_own_state_is_never_silent():
+ """The studio home holds studio.db (chat history, provider and MCP configuration) and auth/
+ next to the sandbox. Several root producers fall back to that directory when their own
+ subdirectory is unset, and one such fallback would grant a tool everything Studio owns."""
+ from core.inference import tool_path_approval as path_gate
+ from utils.paths.storage_roots import studio_root
+
+ home = str(studio_root())
+ for path in (os.path.join(home, "studio.db"), os.path.join(home, "auth", "auth.db")):
+ assert path_gate._path_needs_approval(path) is True, path
+ assert path_gate._path_needs_approval(path, writing = True) is True, path
+ assert is_high_risk_tool_call("terminal", {"command": f"cat {home}/studio.db"}) is True
+ assert is_high_risk_tool_call("terminal", {"command": f"echo x > {home}/studio.db"}) is True
+ # The output subdirectories under it stay silent, or ordinary tool work would prompt.
+ for path in (os.path.join(home, "sandbox", "out.txt"), os.path.join(home, "cache", "m.bin")):
+ assert path_gate._path_needs_approval(path, writing = True) is False, path
+
+
+def test_classification_does_not_create_the_studio_database(tmp_path, monkeypatch):
+ # A classification asks the roots where the model folders and the HF cache are, and both are
+ # stored in `studio.db`. Opening it CREATES it and initialises the schema, so on a first run the
+ # very first tool call was creating the database as a side effect of deciding whether to prompt.
+ # Both root sources skip the lookup when the file is not there, which is the same answer an
+ # empty table gives.
+ import core.inference.tool_path_approval as gate
+
+ home = tmp_path / "studio-home"
+ home.mkdir()
+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(home))
+ monkeypatch.setattr(gate, "_silent_roots_cache", None)
+ try:
+ before = sorted(str(p.relative_to(home)) for p in home.rglob("*") if p.is_file())
+ assert is_high_risk_tool_call("terminal", {"command": "cat /media/review/document.txt"})
+ assert not is_high_risk_tool_call("terminal", {"command": "cat notes.txt"})
+ after = sorted(str(p.relative_to(home)) for p in home.rglob("*") if p.is_file())
+ assert before == after, after
+ finally:
+ gate._silent_roots_cache = None
+
+
+def test_a_symlink_inside_a_silent_root_does_not_make_its_target_silent(tmp_path, monkeypatch):
+ # Lexical containment alone allowed `<silent root>/link/secret.txt`, which the kernel opens
+ # outside that root. Resolved only where the answer would otherwise be silence, so the stat is
+ # paid on the paths about to be allowed.
+ import pathlib
+
+ import core.inference.tool_path_approval as gate
+
+ home = tmp_path / "studio-home"
+ home.mkdir()
+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(home))
+ monkeypatch.setattr(gate, "_silent_roots_cache", None)
+ try:
+ # Roots are case-folded on a case-insensitive platform, so the raw path is not a prefix.
+ folded_home = gate._normalized_fs_text(str(home))
+ root = next((r for r in gate._silent_roots()[0] if r.startswith(folded_home)), None)
+ assert root, "no silent root under the test studio home"
+ pathlib.Path(root).mkdir(parents = True, exist_ok = True)
+ outside = tmp_path / "outside"
+ outside.mkdir()
+ (outside / "secret.txt").write_text("s")
+ link = pathlib.Path(root) / "link"
+ try:
+ link.symlink_to(outside, target_is_directory = True)
+ except OSError: # Windows needs a privilege this runner may not hold
+ pytest.skip("this platform does not allow creating a symlink here")
+ assert gate._path_needs_approval(str(link / "secret.txt")) is True
+ assert gate._path_needs_approval(str(link / "secret.txt"), writing = True) is True
+ # A link that stays INSIDE the silent roots but lands on a credential: containment passes
+ # on the resolved path, so the credential check has to run on it too.
+ secret = pathlib.Path(root) / "token"
+ secret.write_text("k")
+ alias = pathlib.Path(root) / "public"
+ alias.symlink_to(secret)
+ assert gate._path_needs_approval(str(alias)) is True
+ # An ordinary path under the same root is unaffected.
+ assert gate._path_needs_approval(str(pathlib.Path(root) / "ok.txt")) is False
+ finally:
+ gate._silent_roots_cache = None
+
+
+def test_a_revoked_root_is_not_served_from_the_cache(tmp_path, monkeypatch):
+ # Scan folders and the configured cache root live in `studio.db`, so removing one has to
+ # invalidate the roots. Keyed on the account and environment only, the old root stayed silent
+ # for up to the 60 second TTL.
+ import core.inference.tool_path_approval as gate
+ from storage.studio_db import studio_db_path
+
+ home = tmp_path / "studio-home"
+ home.mkdir()
+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(home))
+ monkeypatch.setattr(gate, "_silent_roots_cache", None)
+ builds = []
+
+ def one():
+ builds.append(1)
+ return (("/old",), ("/old",))
+
+ def two():
+ builds.append(1)
+ return (("/new",), ("/new",))
+
+ try:
+ monkeypatch.setattr(gate, "_build_silent_roots", one)
+ assert gate._silent_roots() == (("/old",), ("/old",))
+ assert gate._silent_roots() == (("/old",), ("/old",))
+ assert len(builds) == 1, "the cache did not serve the second call"
+ path = studio_db_path()
+ path.parent.mkdir(parents = True, exist_ok = True)
+ path.write_bytes(b"x")
+ monkeypatch.setattr(gate, "_build_silent_roots", two)
+ assert gate._silent_roots() == (("/new",), ("/new",))
+ assert len(builds) == 2
+
+ # The server runs a WAL keeper, so a committed change lands in `studio.db-wal` and leaves
+ # the main file's mtime alone. Read on its own, the revoked root stayed silent until the TTL.
+ def three():
+ builds.append(1)
+ return (("/wal",), ("/wal",))
+
+ path.with_name(path.name + "-wal").write_bytes(b"wal")
+ monkeypatch.setattr(gate, "_build_silent_roots", three)
+ assert gate._silent_roots() == (("/wal",), ("/wal",))
+ assert len(builds) == 3
+ finally:
+ gate._silent_roots_cache = None