calute.security.sandbox

calute.security.sandbox#

Sandbox and elevated execution configuration for Calute.

Provides a configurable abstraction for deciding whether tool execution runs in the host environment or in a sandboxed context.

Sandbox modes:

off: All execution on host (default, simplest).
warn: Log warnings for tools that would be sandboxed.
strict: Require sandbox for designated tools (raises if unavailable).

Elevated execution:

Some tools need to break out of the sandbox (e.g., file I/O that must access the real filesystem). The elevated flag on a tool marks it as exempt from sandboxing.

This module provides the config models, runtime decision layer, and the SandboxBackend protocol that concrete backends must implement.

class calute.security.sandbox.ExecutionContext(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: Enum

Describes the runtime environment where a tool will actually execute.

HOST#: The tool runs directly in the host Python process with full access to the filesystem, network, and system resources.

SANDBOX#: The tool runs inside an isolated sandbox environment managed by a SandboxBackend implementation.

Example

>>> ctx = ExecutionContext.SANDBOX
>>> ctx.value
'sandbox'

HOST = 'host'#

SANDBOX = 'sandbox'#

class calute.security.sandbox.ExecutionDecision(context: ExecutionContext, tool_name: str, reason: str)[source]#

Bases: object

Result of the sandbox router’s decision for a specific tool invocation.

Encapsulates where the tool should run and why that decision was made, providing an auditable record for logging or policy review.

context#

The ExecutionContext indicating whether the tool should run on the host or in a sandbox.

Type: calute.security.sandbox.ExecutionContext

tool_name#

The name of the tool this decision applies to.

Type: str

reason#

A human-readable explanation of why this execution context was chosen.

Type: str

context: ExecutionContext#

reason: str#

tool_name: str#

class calute.security.sandbox.SandboxBackend(*args, **kwargs)[source]#

Bases: Protocol

Protocol defining the interface that all sandbox backends must implement.

Concrete implementations (e.g., DockerSandboxBackend, SubprocessSandboxBackend) must provide all three methods to be used by the SandboxRouter.

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

Execute a tool function inside the sandboxed runtime.

Parameters

tool_name – The name of the tool being executed, used for logging and error messages.
func – The callable to execute within the sandbox.
arguments – Keyword arguments to pass to func.

Returns

The return value of func(**arguments) as produced inside the sandbox.

Raises

RuntimeError – If the sandbox execution fails for any reason (timeout, crash, serialisation error, etc.).

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

Return a dictionary describing the backend’s capabilities and status.

Returns: A dict containing at minimum a "backend" key with the backend name and an "available" boolean. Additional backend-specific keys (e.g., "image", "isolation_level") may be included.

is_available() → bool[source]#

Check whether the backend is ready to accept execution requests.

Returns: True if the backend’s runtime dependencies are satisfied and it can execute tools, False otherwise.

class calute.security.sandbox.SandboxBackendConfig(image: str = 'python:3.12-slim', mount_paths: dict[str, str] = <factory>, mount_readonly: bool = True, env_vars: dict[str, str] = <factory>, extra_args: dict[str, typing.Any] = <factory>)[source]#

Bases: object

Backend-specific settings for sandbox execution.

image#

Container image name (for Docker backend).

Type: str

mount_paths#

Host paths to mount into the sandbox (maps host -> container).

Type: dict[str, str]

mount_readonly#

Whether mounts are read-only by default.

Type: bool

env_vars#

Environment variables to inject into the sandbox.

Type: dict[str, str]

extra_args#

Additional backend-specific arguments.

Type: dict[str, Any]

env_vars: dict[str, str]#

extra_args: dict[str, Any]#

image: str = 'python:3.12-slim'#

mount_paths: dict[str, str]#

mount_readonly: bool = True#

class calute.security.sandbox.SandboxConfig(mode: ~calute.security.sandbox.SandboxMode = SandboxMode.OFF, sandboxed_tools: set[str] = <factory>, elevated_tools: set[str] = <factory>, sandbox_timeout: float = 30.0, sandbox_memory_limit_mb: int = 512, sandbox_network_access: bool = False, working_directory: str | None = None, backend_type: str | None = None, backend_config: ~calute.security.sandbox.SandboxBackendConfig = <factory>)[source]#

Bases: object

Configuration for sandbox behavior.

mode#

The sandbox enforcement mode.

Type: calute.security.sandbox.SandboxMode

sandboxed_tools#

Tools that should run in sandbox when mode != off.

Type: set[str]

elevated_tools#

Tools exempt from sandbox (run on host always).

Type: set[str]

sandbox_timeout#

Timeout for sandboxed execution in seconds.

Type: float

sandbox_memory_limit_mb#

Memory limit for sandboxed processes.

Type: int

sandbox_network_access#

Whether sandbox has network access.

Type: bool

working_directory#

Working directory inside the sandbox.

Type: str | None

backend_type#

Name of the sandbox backend to use (e.g. "docker", "subprocess").

Type: str | None

backend_config#

Backend-specific settings.

Type: calute.security.sandbox.SandboxBackendConfig

backend_config: SandboxBackendConfig#

backend_type: str | None = None#

elevated_tools: set[str]#

mode: SandboxMode = 'off'#

sandbox_memory_limit_mb: int = 512#

sandbox_network_access: bool = False#

sandbox_timeout: float = 30.0#

sandboxed_tools: set[str]#

working_directory: str | None = None#

exception calute.security.sandbox.SandboxExecutionUnavailableError(tool_name: str)[source]#

Bases: RuntimeError

Raised when strict sandbox execution is required but no backend is configured.

This error occurs in SandboxMode.STRICT mode when a tool designated for sandboxed execution is invoked but no SandboxBackend has been provided to the SandboxRouter.

tool_name#: The name of the tool that required sandbox execution.

class calute.security.sandbox.SandboxMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: Enum

Sandbox enforcement modes controlling how tool execution is handled.

OFF#: No sandboxing; all tools execute directly on the host. This is the default and simplest mode.

WARN#: Advisory mode; tools that would be sandboxed are logged with a warning but still execute on the host.

STRICT#: Enforcement mode; tools designated for sandboxing must execute in a sandbox backend. Raises SandboxExecutionUnavailableError if no backend is configured.

Example

>>> mode = SandboxMode.STRICT
>>> mode.value
'strict'

OFF = 'off'#

STRICT = 'strict'#

WARN = 'warn'#

class calute.security.sandbox.SandboxRouter(config: calute.security.sandbox.SandboxConfig | None = None, backend: calute.security.sandbox.SandboxBackend | None = None)[source]#

Bases: object

Decides the execution context (host vs. sandbox) for tool calls.

The router inspects the SandboxConfig to determine whether a given tool should run on the host or be dispatched to a SandboxBackend. Elevated tools always run on the host, regardless of the sandbox mode.

config#: The SandboxConfig governing sandbox behaviour.

backend#: An optional SandboxBackend instance used to execute sandboxed tools. Required when config.mode is SandboxMode.STRICT.

Example

>>> config = SandboxConfig(mode=SandboxMode.WARN, sandboxed_tools={"execute_shell"})
>>> router = SandboxRouter(config)
>>> decision = router.decide("execute_shell")
>>> decision.context
<ExecutionContext.HOST: 'host'>

decide(tool_name: str) → ExecutionDecision[source]#

Determine where a tool should execute based on the current configuration.

The decision logic follows this precedence:

If the tool is in elevated_tools, it always runs on the host.
If the sandbox mode is SandboxMode.OFF, the tool runs on the host.
If the tool is in sandboxed_tools and mode is SandboxMode.WARN, a warning is logged and it runs on the host.
If the tool is in sandboxed_tools and mode is SandboxMode.STRICT, it runs in the sandbox.
Otherwise, the tool runs on the host.

Parameters: tool_name – The name of the tool to route.
Returns: An ExecutionDecision containing the chosen ExecutionContext and the reason for the decision.

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

Execute a tool function within the configured sandbox backend.

This method delegates execution to the SandboxBackend assigned to this router. It intentionally does not fall back to host execution; if no backend is configured, an error is raised so that strict mode guarantees are upheld.

Parameters

tool_name – The name of the tool being executed, used for logging and error reporting.
func – The callable to execute within the sandbox.
arguments – Keyword arguments to pass to func.

Returns

The return value of func(**arguments) as produced inside the sandbox.

Raises

SandboxExecutionUnavailableError – If no SandboxBackend is configured on this router.
RuntimeError – If the sandbox backend encounters an execution error (timeout, crash, serialisation failure, etc.).

calute.security.sandbox

Contents

calute.security.sandbox#