calute.security.sandbox_backends.subprocess_backend

calute.security.sandbox_backends.subprocess_backend#

Subprocess-based sandbox backend for Calute.

Provides lightweight isolation by running tool functions in a separate Python subprocess. On Unix platforms, resource limits are applied to the child process for memory capping.

This backend is always available (no Docker required) and is suitable when some process-level isolation is acceptable, although it does not provide filesystem or network sandboxing.

class calute.security.sandbox_backends.subprocess_backend.SubprocessSandboxBackend(sandbox_config: SandboxConfig)[source]#

Bases: object

Sandbox backend that runs tools in a child Python subprocess.

This provides process-level isolation: a crash or memory overflow in the child will not bring down the host process. It does not provide filesystem or network isolation.

On Unix platforms, the resource module is used to apply memory limits (RLIMIT_AS) to the child process. On Windows, the memory limit environment variable is set but may not be enforced if the resource module is unavailable.

The execution flow mirrors DockerSandboxBackend:

  1. The callable and arguments are pickle-serialised and base64-encoded.

  2. The encoded payload is piped as stdin to a child Python process.

  3. The child deserialises, executes, and writes the result back to stdout as base64-encoded pickle.

  4. The host deserialises and returns the result.

_config#

The SandboxConfig governing timeout, memory limits, and working directory for the child process.

execute(tool_name: str, func: Callable, arguments: dict) → Any[source]#

Execute a callable with arguments in a child Python subprocess.

The function and its arguments are serialised with pickle, base64-encoded, and piped to a child Python process that applies memory limits, executes the function, and returns the result via stdout.

Parameters

  • tool_name – The name of the tool being executed, used for logging and error messages.

  • func – The callable to execute in the child process. Must be picklable.

  • arguments – Keyword arguments to pass to func. All values must be picklable.

Returns

The return value of func(**arguments) as produced in the child process.

Raises

RuntimeError – If the subprocess times out, exits with a non-zero code, the result cannot be deserialised, or the function raised an exception inside the child process.

get_capabilities() → dict[str, Any][source]#

Return a dictionary describing the subprocess backend’s capabilities.

Returns

  • "backend": Always "subprocess".

  • "available": Always True.

  • "isolation_level": Always "process".

  • "filesystem_isolation": Always False (no filesystem sandboxing).

  • "network_isolation": Always False (no network sandboxing).

  • "memory_limit_mb": Configured memory limit in megabytes.

  • "timeout": Configured execution timeout in seconds.

Return type

A dict with the following keys

is_available() → bool[source]#

Check whether the subprocess backend is available.

This backend is always available since it only requires the Python interpreter that is already running the host process.

Returns

Always True.

Contents