Skip to content

python_interpreter_sandbox.md

Latest commit

 

History

History
34 lines (23 loc) · 3.6 KB

python_interpreter_sandbox.md

File metadata and controls

34 lines (23 loc) · 3.6 KB

PythonInterpreterTool Sandboxing

The PythonInterpreterTool allows the agent to execute Python code in a controlled environment. To ensure safety and prevent malicious or unintended actions, the tool employs several sandboxing mechanisms.

Core Sandboxing Principles

  1. Custom AST Evaluator: Instead of using Python's eval() or exec() directly on user code, the tool parses the code into an Abstract Syntax Tree (AST) and then walks through this tree, evaluating nodes one by one in a controlled manner. This allows fine-grained interception and control over what operations are permitted.

  2. Import Control:

    • Allowlist: The tool uses an allowlist (authorized_imports) to specify which Python modules can be imported. Attempts to import modules not on this list will be blocked.
    • Granular Control: The allowlist can be configured to allow specific submodules (e.g., os.path) without allowing the entire parent module (e.g., os).
    • Safe Module Copying: When a module is imported, a "safe copy" is created. This process inspects the module and its submodules, pruning any parts that are not explicitly authorized, to prevent indirect importing of disallowed code.
    • Configuration: The authorized_imports list is configurable when an instance of PythonInterpreterTool is created. The default list includes common safe modules like math.

  3. Restricted Built-ins and Functions:

    • Only a curated list of Python built-in functions (BASE_PYTHON_TOOLS) are available by default (e.g., len(), str(), range(), math functions).
    • Known dangerous functions (e.g., eval, exec, open, os.system, subprocess.call) are explicitly blacklisted (DANGEROUS_FUNCTIONS) and cannot be called even if they are part of an allowed module (defense in depth via the safer_eval mechanism).

  4. Attribute Access Control:

    • Direct access to "dunder" attributes (e.g., object.__dict__, function.__globals__, object.__subclasses__) is blocked. This helps prevent introspection and manipulation of internal states that could lead to sandbox escapes.

  5. Resource Limits:

    • The interpreter imposes limits on the number of operations (MAX_OPERATIONS) and loop iterations (MAX_WHILE_ITERATIONS) to prevent denial-of-service attacks through infinite loops or overly complex computations.

  6. Unsupported Operations:

    • Python features that are complex to sandbox or pose security risks (e.g., global, nonlocal keywords, direct memory manipulation via ctypes unless explicitly allowed) are generally not supported by the custom AST evaluator and will result in errors.

Security Considerations for Developers

  • Review authorized_imports: When using the PythonInterpreterTool, carefully consider which modules are truly necessary for the intended tasks and restrict the authorized_imports list accordingly.
  • Least Privilege: Grant only the minimum necessary permissions. If a task only needs math.sqrt, consider if authorizing the entire math module is acceptable or if more granular control is needed (though typically, standard library modules like math are safe if the functions themselves are not dangerous).
  • Tool Output: Be mindful that the output of the executed code (both return values and print statements) could potentially contain sensitive information if the code handles such data.

By combining these mechanisms, the PythonInterpreterTool aims to provide a reasonably safe environment for executing Python code generated by LLMs or other sources, while still offering significant computational capabilities.