You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@burr.apache.org by eb...@apache.org on 2026/07/12 15:30:59 UTC

(burr) branch main updated: docs: tighten Condition.expr documentation; remove misleading empty globals dict (#819)

This is an automated email from the ASF dual-hosted git repository.

elijahbenizzy pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/burr.git


The following commit(s) were added to refs/heads/main by this push:
     new 2e021569 docs: tighten Condition.expr documentation; remove misleading empty globals dict (#819)
2e021569 is described below

commit 2e021569e17ef60a06d11be9f222522431e7d316
Author: Elijah ben Izzy <el...@users.noreply.github.com>
AuthorDate: Sun Jul 12 08:30:54 2026 -0700

    docs: tighten Condition.expr documentation; remove misleading empty globals dict (#819)
---
 burr/core/action.py | 34 +++++++++++++++++++++++++++++-----
 1 file changed, 29 insertions(+), 5 deletions(-)

diff --git a/burr/core/action.py b/burr/core/action.py
index 08771d41..a7df2ab1 100644
--- a/burr/core/action.py
+++ b/burr/core/action.py
@@ -410,14 +410,35 @@ class Condition(Function):
 
     @staticmethod
     def expr(expr: str) -> "Condition":
-        """Returns a condition that evaluates the given expression. Expression must use
-        only state variables and Python operators. Do not trust that anything else will work.
+        """Returns a condition that evaluates the given expression against state.
 
-        Do not accept expressions generated from user-inputted text, this has the potential to be unsafe.
+        This helper is intended for **developer-authored** expressions written in source
+        code alongside the rest of the application graph -- semantically equivalent to
+        passing a lambda. The string is handed to Python's built-in :func:`eval`, with
+        state keys bound as locals, so any valid Python expression is permitted.
 
         You can also refer to this as ``from burr.core import expr`` in the API.
 
-        :param expr: Expression to evaluate
+        .. warning::
+            ``Condition.expr`` runs the supplied string under a full Python ``eval``.
+            Passing user-supplied or otherwise attacker-controllable strings to this
+            function is equivalent to arbitrary code execution inside the application
+            process. For example, an attacker who controls the expression string can
+            execute ``__import__("os").system("...")`` or
+            ``__import__("subprocess").check_output([...])`` and reach anything the
+            host process can reach.
+
+            The ``globals=None`` argument to ``eval`` below is **not** a sandbox:
+            CPython auto-injects ``__builtins__`` when globals is empty or ``None``,
+            which is in fact relied upon here so that expressions like ``len(x)`` work.
+            No part of this function attempts to sandbox the evaluation.
+
+            If you need to accept untrusted expressions, do not use ``expr``. Track
+            ``apache/burr#817`` for the opt-in safe-AST evaluator intended for that
+            use case.
+
+        :param expr: Expression to evaluate. Must be a developer-authored Python
+            expression over state variables and standard operators/builtins.
         :return: A condition that evaluates the given expression
         """
         tree = ast.parse(expr, mode="eval")
@@ -440,7 +461,10 @@ class Condition(Function):
         # Compile the expression into a callable function
         def condition_func(state: State) -> bool:
             __globals = state.get_all()  # we can get all because externally we will subset
-            return eval(compile(tree, "<string>", "eval"), {}, __globals)
+            # NOTE: globals=None is *not* a sandbox -- CPython injects __builtins__
+            # automatically. See the docstring above. Builtins (e.g. ``len``) are
+            # intentionally available to developer-authored expressions.
+            return eval(compile(tree, "<string>", "eval"), None, __globals)
 
         return Condition(keys, condition_func, name=expr)