tools.linux_cgroup_ns_tools module

Direct Linux cgroup v2 and namespace management.

Read/write cgroup pseudo-files under the unified hierarchy, create/remove cgroup directories, move processes via cgroup.procs, and run commands under unshare or nsenter (util-linux). All operations require the UNSANDBOXED_EXEC privilege.

Paths are always canonicalized and must resolve under /sys/fs/cgroup (no .. escapes to other filesystem trees).

async tools.linux_cgroup_ns_tools.cgroup_read_file(path, max_bytes=262144, ctx=None)[source]

Read a cgroup v2 pseudo-file under the unified hierarchy as text.

Handler for the cgroup_read_file tool: it lets a privileged user inspect cgroup controller state (e.g. memory.current, cgroup.controllers) by reading the pseudo-file at path. The read is bounded so a large or pathological file cannot blow up the response.

Requires the UNSANDBOXED_EXEC privilege, enforced via _check_priv(). The path is confined to /sys/fs/cgroup by _resolve_under_cgroup(), then the bytes are read directly off the filesystem and decoded with errors="replace", truncating past max_bytes (capped at _MAX_READ_BYTES_CAP). Results are wrapped with _json_ok() / _json_err(). Invoked through the tool dispatcher via the handler entry in this module’s TOOLS list (see tool_loader.py); no direct in-repo callers.

Parameters:

  • path (str) – Path to the pseudo-file, absolute or relative to the cgroup mount.

  • max_bytes (int) – Maximum number of bytes to return, clamped to the range [1, _MAX_READ_BYTES_CAP].

  • ctx (Any) – The ToolContext; required for the privilege check.

Returns:

A JSON success envelope with path, content and bytes_read, or a JSON error envelope on a missing context, denied privilege, path-validation failure, or OSError.

Return type:

str

async tools.linux_cgroup_ns_tools.cgroup_write_file(path, content, ctx=None)[source]

Write UTF-8 text into a cgroup v2 pseudo-file (a control operation).

Handler for the cgroup_write_file tool: this is how the bot actually reconfigures a cgroup, since cgroup v2 is driven entirely by writes to interface files (e.g. enabling controllers via cgroup.subtree_control or setting a limit via memory.max). The write goes straight to the kernel-backed pseudo-file, so its semantics depend on which file is targeted.

Requires the UNSANDBOXED_EXEC privilege via _check_priv(), and the path is confined under /sys/fs/cgroup by _resolve_under_cgroup() before pathlib.Path.write_text() is called. Envelopes come from _json_ok() / _json_err(). Invoked through the tool dispatcher via the handler entry in this module’s TOOLS list; no direct in-repo callers.

Parameters:

  • path (str) – Target pseudo-file path, absolute or relative to the cgroup mount.

  • content (str) – UTF-8 text to write verbatim to the file.

  • ctx (Any) – The ToolContext; required for the privilege check.

Returns:

A JSON success envelope with path and bytes_written, or a JSON error envelope on a missing context, denied privilege, path-validation failure, or OSError from the write.

Return type:

str

async tools.linux_cgroup_ns_tools.cgroup_mkdir(path, parents=True, ctx=None)[source]

Create a cgroup directory, optionally with its parents.

Handler for the cgroup_mkdir tool. Creating a directory under the unified hierarchy is how a new child cgroup is materialized: the kernel auto-populates it with the relevant cgroup.* interface files, after which processes can be moved in and limits applied. With parents true this behaves like mkdir -p and is idempotent (exist_ok=True).

Requires the UNSANDBOXED_EXEC privilege via _check_priv(); the path is confined under /sys/fs/cgroup by _resolve_under_cgroup() before pathlib.Path.mkdir(). Results use _json_ok() / _json_err(). Invoked through the tool dispatcher via the handler entry in this module’s TOOLS list; no direct in-repo callers.

Parameters:

  • path (str) – Directory to create, absolute or relative to the cgroup mount.

  • parents (bool) – When true, create any missing parent directories as well.

  • ctx (Any) – The ToolContext; required for the privilege check.

Returns:

A JSON success envelope with the created path, or a JSON error envelope on a missing context, denied privilege, path-validation failure, or OSError from the mkdir.

Return type:

str

async tools.linux_cgroup_ns_tools.cgroup_rmdir(path, ctx=None)[source]

Remove an empty cgroup directory under the unified hierarchy.

Handler for the cgroup_rmdir tool, the inverse of cgroup_mkdir(). The kernel only allows an empty cgroup to be removed, so this cleans up a child cgroup once every process has been migrated out of it. As an extra guard it refuses to delete the mount root itself.

Requires the UNSANDBOXED_EXEC privilege via _check_priv(); the path is confined under /sys/fs/cgroup by _resolve_under_cgroup() and compared against _cgroup_mount_resolved() before pathlib.Path.rmdir(). Results use _json_ok() / _json_err(). Invoked through the tool dispatcher via the handler entry in this module’s TOOLS list; no direct in-repo callers.

Parameters:

  • path (str) – Empty directory to remove, absolute or relative to the cgroup mount.

  • ctx (Any) – The ToolContext; required for the privilege check.

Returns:

A JSON success envelope with the removed path, or a JSON error envelope on a missing context, denied privilege, path-validation failure, an attempt to remove the mount root, or an OSError (notably when the directory is non-empty).

Return type:

str

async tools.linux_cgroup_ns_tools.cgroup_move_pid(cgroup_path, pid, ctx=None)[source]

Move a process into a cgroup by writing its PID to cgroup.procs.

Handler for the cgroup_move_pid tool. In cgroup v2 a task is assigned to a cgroup by writing its PID into that cgroup’s cgroup.procs file; this is the step that actually subjects a running process to the cgroup’s controllers and limits. The target directory must already exist (created via cgroup_mkdir()).

Requires the UNSANDBOXED_EXEC privilege via _check_priv(). The cgroup_path is confined under /sys/fs/cgroup by _resolve_under_cgroup(), checked to be an existing directory, and the PID is written to cgroup.procs inside it. Results use _json_ok() / _json_err(). Invoked through the tool dispatcher via the handler entry in this module’s TOOLS list; no direct in-repo callers.

Parameters:

  • cgroup_path (str) – Existing target cgroup directory, absolute or relative to the cgroup mount.

  • pid (int) – Process ID to move into the cgroup.

  • ctx (Any) – The ToolContext; required for the privilege check.

Returns:

A JSON success envelope with cgroup_path and pid, or a JSON error envelope on a missing context, denied privilege, path-validation failure, a non-directory target, or an OSError from the write.

Return type:

str

async tools.linux_cgroup_ns_tools.linux_unshare_exec(command, unshare_flags=None, timeout=120, ctx=None)[source]

Run a command in fresh Linux namespaces via unshare (util-linux).

Handler for the linux_unshare_exec tool. It assembles and runs unshare [unshare_flags] -- command ..., letting a privileged user execute a process inside newly unshared namespaces (mount, PID, net, user, etc.) for isolation or experimentation. The flag tokens are accepted in a forgiving form and normalized to real options.

Requires the UNSANDBOXED_EXEC privilege via _check_priv(), validates that command is a non-empty list, normalizes unshare_flags through _sanitize_flag_list(), resolves the unshare binary with shutil.which(), clamps timeout to _MAX_SUBPROCESS_TIMEOUT, and executes the assembled argv via _run_exec_limited() (no shell). Results use _json_ok() / _json_err(). Invoked through the tool dispatcher via the handler entry in this module’s TOOLS list; no direct in-repo callers.

Parameters:

  • command (list[str]) – Executable and arguments to run after --; must be a non-empty list of strings.

  • unshare_flags (list[str] | None) – Optional namespace flags, accepted as bare names or short/long options and normalized before use.

  • timeout (int) – Wall-clock seconds before the child is killed, clamped to [1, _MAX_SUBPROCESS_TIMEOUT].

  • ctx (Any) – The ToolContext; required for the privilege check.

Returns:

A JSON success envelope with returncode, stdout, stderr and the full command, or a JSON error envelope on a missing context, denied privilege, invalid arguments, or a missing unshare executable.

Return type:

str

async tools.linux_cgroup_ns_tools.linux_nsenter_exec(target_pid, command, nsenter_flags=None, timeout=120, ctx=None)[source]

Run a command inside another process’s namespaces via nsenter.

Handler for the linux_nsenter_exec tool. It assembles and runs nsenter -t <pid> [nsenter_flags] -- command ... (util-linux), so a privileged user can join an existing task’s namespaces – for example to debug inside a container by entering its mount and network namespaces. This is the counterpart to linux_unshare_exec(), which instead creates new namespaces.

Requires the UNSANDBOXED_EXEC privilege via _check_priv(), validates target_pid is positive and command is a non-empty list, normalizes nsenter_flags through _sanitize_flag_list(), resolves the nsenter binary with shutil.which(), clamps timeout to _MAX_SUBPROCESS_TIMEOUT, and executes the assembled argv via _run_exec_limited() (no shell). Results use _json_ok() / _json_err(). Invoked through the tool dispatcher via the handler entry in this module’s TOOLS list; no direct in-repo callers.

Parameters:

  • target_pid (int) – PID of the process whose namespaces to enter; must be a positive integer.

  • command (list[str]) – Executable and arguments to run after --; must be a non-empty list of strings.

  • nsenter_flags (list[str] | None) – Optional namespace flags, accepted as bare names or short/long options and normalized before use.

  • timeout (int) – Wall-clock seconds before the child is killed, clamped to [1, _MAX_SUBPROCESS_TIMEOUT].

  • ctx (Any) – The ToolContext; required for the privilege check.

Returns:

A JSON success envelope with returncode, stdout, stderr and the full command, or a JSON error envelope on a missing context, denied privilege, invalid arguments, or a missing nsenter executable.

Return type:

str