Skip to content

Automate browser based workflows with AI

Declare one safe-namespace contract for both CodeBlock executors (SKY-14776) (#8512)

Andrew Neilson2ca614c8e391
diff --git a/skyvern/cli/mcp_tools/blocks.py b/skyvern/cli/mcp_tools/blocks.py
index 1fa6ad2e5..c6c573c0e 100644
--- a/skyvern/cli/mcp_tools/blocks.py
+++ b/skyvern/cli/mcp_tools/blocks.py
@@ -10,6 +10,7 @@ from __future__ import annotations
import json
import re
from pathlib import Path
+from types import SimpleNamespace
from typing import Annotated, Any
import structlog
@@ -388,6 +389,33 @@ WORKFLOW_KNOWLEDGE_TOPIC_HEADERS: dict[str, str] = {
_kb_cache: dict[str, dict[str, Any]] | None = None
_knowledge_topic_cache: dict[str, dict[str, str]] | None = None
+CODE_BLOCK_RUNTIME_TOPIC = "code_block_runtime"
+
+
+def _code_block_runtime_topic() -> dict[str, str]:
+ """Render the names a CodeBlock may use from the executor's own namespace declaration."""
+ # Keep workflow model imports deferred for the lightweight-install import contract.
+ from skyvern.forge.sdk.workflow.models.block import CodeBlock # noqa: PLC0415
+
+ safe_vars = CodeBlock.build_safe_vars()
+ builtin_names = sorted(name for name in safe_vars["__builtins__"] if not name.startswith("__"))
+ shims = {name: sorted(vars(value)) for name, value in safe_vars.items() if isinstance(value, SimpleNamespace)}
+ helpers = sorted(name for name in safe_vars if name != "__builtins__" and name not in shims)
+ lines = [
+ "Names a code block's Python may use. Imports are blocked; the runtime binds everything listed here.",
+ "",
+ "Builtins: " + ", ".join(builtin_names),
+ "",
+ "Module shims (only the listed attributes exist, e.g. datetime.datetime.now(), not datetime.now()):",
+ *(f"- {name}: {', '.join(attrs)}" for name, attrs in sorted(shims.items())),
+ "",
+ "Helpers: page, " + ", ".join(helpers),
+ "",
+ "For a date in a template field use {{current_date}}; inside code use datetime.date.today() "
+ "or datetime.datetime.now(datetime.UTC).",
+ ]
+ return {"topic": CODE_BLOCK_RUNTIME_TOPIC, "title": "CODE BLOCK RUNTIME", "content": "\n".join(lines)}
+
def _parse_knowledge_topics() -> dict[str, dict[str, str]]:
"""Index the knowledge document by its authored top-level sections."""
@@ -527,7 +555,8 @@ async def skyvern_workflow_knowledge(
description=(
"Knowledge topic IDs to retrieve. Omit to list every topic. Common IDs include "
"workflow_parameters, parameter_templating, workflow_execution_flow, choosing_a_block, "
- "common_patterns, best_practices, captcha_solver, and proxy_location."
+ "common_patterns, best_practices, captcha_solver, proxy_location, and code_block_runtime "
+ "(the builtins, module shims, and helpers a code block's Python may use)."
)
),
] = None,
@@ -541,8 +570,7 @@ async def skyvern_workflow_knowledge(
action = "skyvern_workflow_knowledge"
knowledge = _parse_knowledge_topics()
- catalog = list(knowledge)
- if not catalog:
+ if not knowledge:
return make_result(
action,
ok=False,
@@ -552,6 +580,8 @@ async def skyvern_workflow_knowledge(
"Use get_block_schema for exact block fields and retry workflow knowledge later.",
),
)
+ knowledge = {**knowledge, CODE_BLOCK_RUNTIME_TOPIC: _code_block_runtime_topic()}
+ catalog = list(knowledge)
if topics is None:
return make_result(action, data={"topics": catalog, "count": len(catalog)})
diff --git a/skyvern/forge/sdk/copilot/tools/mcp_hooks.py b/skyvern/forge/sdk/copilot/tools/mcp_hooks.py
index e3d338679..76571f28c 100644
--- a/skyvern/forge/sdk/copilot/tools/mcp_hooks.py
+++ b/skyvern/forge/sdk/copilot/tools/mcp_hooks.py
@@ -1858,7 +1858,8 @@ _WORKFLOW_KNOWLEDGE_DESCRIPTION = (
"Read authoritative Skyvern workflow concepts and authoring guidance. Use this before answering "
"questions about workflow structure, parameters, execution, authoring patterns, or block selection. "
"Common topic IDs are workflow_parameters, parameter_templating, workflow_execution_flow, "
- "choosing_a_block, common_patterns, and best_practices; omit topics to list every available ID. "
+ "choosing_a_block, common_patterns, best_practices, and code_block_runtime (the builtins, module "
+ "shims, and helpers a code block's Python may use); omit topics to list every available ID. "
"Request only the relevant sections. For exact fields of a specific block type, use "
"get_block_schema instead."
)
diff --git a/skyvern/forge/sdk/workflow/code_block_safety.py b/skyvern/forge/sdk/workflow/code_block_safety.py
index 97c437fea..c2d2c9266 100644
--- a/skyvern/forge/sdk/workflow/code_block_safety.py
+++ b/skyvern/forge/sdk/workflow/code_block_safety.py
@@ -3,10 +3,18 @@
from __future__ import annotations
import ast
+import asyncio
+import builtins
+import datetime
+import html
+import json
+import re
import textwrap
from collections import Counter
from collections.abc import Callable
from string import Formatter
+from types import SimpleNamespace
+from typing import Any
from skyvern.forge.sdk.workflow.exceptions import InsecureCodeDetected
@@ -162,6 +170,85 @@ ALLOWED_SCRIPT_DUNDER_READS: frozenset[str] = frozenset({"__all__", "__doc__", "
ALLOWED_SCRIPT_DUNDER_WRITES: frozenset[str] = frozenset({"__all__"})
ALLOWED_SCRIPT_NAMEDTUPLE_ATTRS: frozenset[str] = frozenset({"_asdict", "_fields", "_make", "_replace"})
+# Twins of codeblock/codeblock_runtime.py's _ALWAYS_DENIED_BUILTINS / _SANDBOX_ONLY_BUILTINS; the
+# runner image carries its own copy and tests/cloud asserts the two stay equal.
+ALWAYS_DENIED_BUILTINS: frozenset[str] = frozenset(
+ {
+ "eval",
+ "exec",
+ "compile",
+ "open",
+ "input",
+ "breakpoint",
+ "help",
+ "exit",
+ "quit",
+ "copyright",
+ "credits",
+ "license",
+ "BaseException",
+ "BaseExceptionGroup",
+ "GeneratorExit",
+ "KeyboardInterrupt",
+ "SystemExit",
+ "format",
+ "memoryview",
+ }
+)
+SANDBOX_ONLY_BUILTINS: frozenset[str] = frozenset(
+ {
+ "getattr",
+ "setattr",
+ "delattr",
+ "vars",
+ "globals",
+ "locals",
+ "type",
+ "super",
+ "staticmethod",
+ "classmethod",
+ "property",
+ }
+)
+
+
+def safe_builtins() -> dict[str, Any]:
+ """Builtins a CodeBlock may use while sharing the worker process; dunders drop out via the underscore filter."""
+ denied = ALWAYS_DENIED_BUILTINS | SANDBOX_ONLY_BUILTINS
+ return {name: value for name, value in vars(builtins).items() if not name.startswith("_") and name not in denied}
+
+
+def module_shims() -> dict[str, SimpleNamespace]:
+ """Fresh module-shaped namespaces both CodeBlock executors bind as globals."""
+ return {
+ "asyncio": SimpleNamespace(sleep=asyncio.sleep),
+ "re": SimpleNamespace(
+ match=re.match,
+ search=re.search,
+ findall=re.findall,
+ finditer=re.finditer,
+ fullmatch=re.fullmatch,
+ sub=re.sub,
+ compile=re.compile,
+ split=re.split,
+ escape=re.escape,
+ I=re.I,
+ S=re.S,
+ IGNORECASE=re.IGNORECASE,
+ MULTILINE=re.MULTILINE,
+ DOTALL=re.DOTALL,
+ ),
+ "json": SimpleNamespace(dumps=json.dumps, loads=json.loads),
+ "html": SimpleNamespace(escape=html.escape),
+ "datetime": SimpleNamespace(
+ datetime=datetime.datetime,
+ date=datetime.date,
+ timedelta=datetime.timedelta,
+ timezone=datetime.timezone,
+ UTC=datetime.UTC,
+ ),
+ }
+
def _import_roots(node: ast.Import | ast.ImportFrom) -> tuple[str, ...]:
if isinstance(node, ast.Import):
diff --git a/skyvern/forge/sdk/workflow/models/block.py b/skyvern/forge/sdk/workflow/models/block.py
index af52da5f0..9ee22cbd5 100644
--- a/skyvern/forge/sdk/workflow/models/block.py
+++ b/skyvern/forge/sdk/workflow/models/block.py
@@ -186,6 +186,7 @@ from skyvern.forge.sdk.workflow.code_block_authorized_files import (
)
from skyvern.forge.sdk.workflow.code_block_safety import BLOCKED_ATTRS as CODE_BLOCK_BLOCKED_ATTRS
from skyvern.forge.sdk.workflow.code_block_safety import is_safe_code as _shared_is_safe_code
+from skyvern.forge.sdk.workflow.code_block_safety import module_shims, safe_builtins
from skyvern.forge.sdk.workflow.constants import OUTPUT_PARAMETER_MAX_VALUE_BYTES
from skyvern.forge.sdk.workflow.context_manager import (
NON_SECRET_CREDENTIAL_FIELDS,
@@ -5281,7 +5282,7 @@ def _link_without_overwrite(source: str, directory: str) -> str:
candidate = os.path.join(directory, f"{stem} ({attempt}){suffix}")
-_LATE_SAFE_GLOBALS = frozenset({"round", "abs", "attach_authorized_file", "clear_browser_data"})
+_LATE_SAFE_GLOBALS = frozenset({"attach_authorized_file", "clear_browser_data", "html", "datetime"})
CODE_BLOCK_DIALOG_POLICY_HELPER_NAME = "set_dialog_policy"
@@ -5411,55 +5412,18 @@ class CodeBlock(Block):
@staticmethod
def build_safe_vars() -> dict[str, Any]:
+ # Builtins live under __builtins__ rather than as globals so a workflow parameter can shadow
+ # a builtin name by normal scoping, matching codeblock_runtime.build_safe_vars.
return {
"__builtins__": {
- # Only allow several builtins due to security concerns. LOAD_BUILD_CLASS and the
- # class body's implicit __module__ binding resolve these from here, not globals.
+ **safe_builtins(),
+ # LOAD_BUILD_CLASS and the class body's implicit __module__ binding resolve these here.
"__build_class__": _code_block_build_class,
"__name__": "skyvern.code_block",
},
"print": print,
- "len": len,
- "range": range,
- "str": str,
- "int": int,
- "float": float,
- "dict": dict,
- "list": list,
- "tuple": tuple,
- "set": set,
- "bool": bool,
- "isinstance": isinstance,
- "enumerate": enumerate,
- "any": any,
- "all": all,
- "max": max,
- "min": min,
- "sum": sum,
- "round": round,
- "abs": abs,
- "sorted": sorted,
"sleep": asyncio.sleep,
- "asyncio": SimpleNamespace(sleep=asyncio.sleep),
- "re": SimpleNamespace(
- match=re.match,
- search=re.search,
- findall=re.findall,
- finditer=re.finditer,
- fullmatch=re.fullmatch,
- sub=re.sub,
- compile=re.compile,
- split=re.split,
- escape=re.escape,
- I=re.I,
- S=re.S,
- IGNORECASE=re.IGNORECASE,
- MULTILINE=re.MULTILINE,
- DOTALL=re.DOTALL,
- ),
- "json": SimpleNamespace(dumps=json.dumps, loads=json.loads),
- "html": SimpleNamespace(escape=html.escape),
- "Exception": Exception,
+ **module_shims(),
"ErrorCode": ErrorCode,
"otp": _code_block_otp_builtin,
"solve_captcha": _bind_code_block_solve_captcha(None, None),
@@ -5516,6 +5480,7 @@ class CodeBlock(Block):
_code_block_safe_print,
parameters=app.AGENT_FUNCTION.serialize_codeblock_parameters(parameters or {}),
)
+ safe_vars["__builtins__"]["print"] = safe_vars["print"]
safe_vars["solve_captcha"] = _bind_code_block_solve_captcha(organization_id, workflow_run_id)
safe_vars["otp"] = partial(
_code_block_otp_builtin,
diff --git a/tests/unit/test_code_block_sandbox.py b/tests/unit/test_code_block_sandbox.py
index cb49f3bb7..48f8637bd 100644
--- a/tests/unit/test_code_block_sandbox.py
+++ b/tests/unit/test_code_block_sandbox.py
@@ -20,7 +20,12 @@ from playwright.async_api import TimeoutError as PlaywrightTimeoutError
import skyvern.forge.sdk.workflow.models.block as block_module
from skyvern.config import settings
-from skyvern.forge.sdk.workflow.code_block_safety import is_safe_script_code
+from skyvern.forge.sdk.workflow.code_block_safety import (
+ ALWAYS_DENIED_BUILTINS,
+ SANDBOX_ONLY_BUILTINS,
+ is_safe_script_code,
+ safe_builtins,
+)
from skyvern.forge.sdk.workflow.exceptions import InsecureCodeDetected, MissingJinjaVariables
from skyvern.forge.sdk.workflow.models.block import (
CODE_BLOCK_TAB_OPEN_FAILURE_REASON,
@@ -454,15 +459,16 @@ class TestIsSafeCodeAcceptsLegitimateCode:
def test_exposes_safe_iteration_and_regex_aliases(self) -> None:
safe_vars = CodeBlock.build_safe_vars()
-
- assert safe_vars["enumerate"] is enumerate
- assert safe_vars["isinstance"] is isinstance
- assert safe_vars["any"] is any
- assert safe_vars["all"] is all
- assert safe_vars["max"] is max
- assert safe_vars["min"] is min
- assert safe_vars["sum"] is sum
- assert safe_vars["sorted"] is sorted
+ sandbox_builtins = safe_vars["__builtins__"]
+
+ assert sandbox_builtins["enumerate"] is enumerate
+ assert sandbox_builtins["isinstance"] is isinstance
+ assert sandbox_builtins["any"] is any
+ assert sandbox_builtins["all"] is all
+ assert sandbox_builtins["max"] is max
+ assert sandbox_builtins["min"] is min
+ assert sandbox_builtins["sum"] is sum
+ assert sandbox_builtins["sorted"] is sorted
assert safe_vars["re"].I == safe_vars["re"].IGNORECASE
def test_try_except(self) -> None:
@@ -508,15 +514,17 @@ class TestBuildSafeVars:
def test_float_in_safe_vars(self) -> None:
safe_vars = CodeBlock.build_safe_vars()
- assert "float" in safe_vars
- assert safe_vars["float"] is float
+ assert "float" not in safe_vars
+ assert safe_vars["__builtins__"]["float"] is float
- def test_builtins_mapping_is_minimal(self) -> None:
- safe_vars = CodeBlock.build_safe_vars()
- assert set(safe_vars["__builtins__"]) == {"__build_class__", "__name__"}
+ def test_builtins_mapping_is_the_declared_policy(self) -> None:
+ sandbox_builtins = set(CodeBlock.build_safe_vars()["__builtins__"])
+ assert sandbox_builtins == set(safe_builtins()) | {"__build_class__", "__name__"}
+ assert sandbox_builtins.isdisjoint(ALWAYS_DENIED_BUILTINS | SANDBOX_ONLY_BUILTINS)
+ assert "__import__" not in sandbox_builtins
def test_expected_builtins_present(self) -> None:
- safe_vars = CodeBlock.build_safe_vars()
+ sandbox_builtins = CodeBlock.build_safe_vars()["__builtins__"]
expected = {
"len",
"range",
@@ -535,9 +543,14 @@ class TestBuildSafeVars:
"min",
"sum",
"sorted",
+ "zip",
+ "map",
+ "filter",
+ "ValueError",
+ "KeyError",
}
for name in expected:
- assert name in safe_vars, f"{name} missing from safe_vars"
+ assert name in sandbox_builtins, f"{name} missing from __builtins__"
def test_json_is_restricted_namespace(self) -> None:
safe_vars = CodeBlock.build_safe_vars()
@@ -570,7 +583,13 @@ class TestBuildSafeVars:
def test_exception_available(self) -> None:
safe_vars = CodeBlock.build_safe_vars()
- assert safe_vars["Exception"] is Exception
+ assert safe_vars["__builtins__"]["Exception"] is Exception
+
+ def test_datetime_is_restricted_namespace(self) -> None:
+ safe_vars = CodeBlock.build_safe_vars()
+ assert safe_vars["datetime"].date(2026, 9, 13).isoformat() == "2026-09-13"
+ assert safe_vars["datetime"].UTC is UTC
+ assert not hasattr(safe_vars["datetime"], "now")
def test_no_safe_var_exposes_dangerous_module(self) -> None:
"""No value in safe_vars should be a module that has subprocess/OS capabilities."""
@@ -1244,6 +1263,52 @@ async def wrapper({default_args}):
with pytest.raises(NameError, match="open"):
await fn()
+ @pytest.mark.asyncio
+ @pytest.mark.parametrize("name", sorted(ALWAYS_DENIED_BUILTINS | SANDBOX_ONLY_BUILTINS))
+ async def test_denied_builtins_raise_name_error(self, name: str) -> None:
+ fn = self._exec_user_code(f"x = {name}")
+ with pytest.raises(NameError, match=name):
+ await fn()
+
+ @pytest.mark.asyncio
+ async def test_common_builtins_execute(self) -> None:
+ fn = self._exec_user_code(
+ "paired = dict(zip(labels, values))\n"
+ "try:\n"
+ " raise ValueError('x')\n"
+ "except ValueError:\n"
+ " caught = 'value'\n"
+ "day = datetime.date(2026, 9, 13).isoformat()\n",
+ parameters={"labels": ["a", "b"], "values": [1, 2]},
+ )
+ result = await fn()
+ assert result["paired"] == {"a": 1, "b": 2}
+ assert result["caught"] == "value"
+ assert result["day"] == "2026-09-13"
+
+ @pytest.mark.asyncio
+ async def test_parameters_shadow_builtin_names(self) -> None:
+ now = datetime.now(UTC)
+ block = CodeBlock(
+ label="shadow_block",
+ code="return {'zip_value': zip, 'len_value': len}",
+ output_parameter=OutputParameter(
+ parameter_type=ParameterType.OUTPUT,
+ key="shadow_output",
+ description="test output",
+ output_parameter_id="op_shadow",
+ workflow_id="w_test",
+ created_at=now,
+ modified_at=now,
+ ),
+ )
+
+ user_function = block.generate_async_user_function(
+ block.code, MagicMock(), parameters={"zip": "94105", "len": "persisted-len"}
+ )
+
+ assert await user_function() == {"zip_value": "94105", "len_value": "persisted-len"}
+
@pytest.mark.asyncio
async def test_parameters_cannot_override_sandbox_internals(self) -> None:
"""Workflow parameters must not overwrite sandbox-controlled names."""
diff --git a/tests/unit/test_mcp_block_tools.py b/tests/unit/test_mcp_block_tools.py
index 124ab446a..a058d3ef9 100644
--- a/tests/unit/test_mcp_block_tools.py
+++ b/tests/unit/test_mcp_block_tools.py
@@ -9,11 +9,13 @@ from pathlib import Path
import pytest
from skyvern.cli.mcp_tools.blocks import (
+ CODE_BLOCK_RUNTIME_TOPIC,
WORKFLOW_KNOWLEDGE_TOPIC_HEADERS,
skyvern_block_schema,
skyvern_block_validate,
skyvern_workflow_knowledge,
)
+from skyvern.forge.sdk.workflow.models.block import CodeBlock
@pytest.mark.asyncio
@@ -21,11 +23,28 @@ async def test_workflow_knowledge_lists_available_topics_without_returning_the_d
result = await skyvern_workflow_knowledge()
assert result["ok"] is True
- assert result["data"]["topics"] == list(WORKFLOW_KNOWLEDGE_TOPIC_HEADERS)
- assert result["data"]["count"] == len(WORKFLOW_KNOWLEDGE_TOPIC_HEADERS)
+ assert result["data"]["topics"] == [*WORKFLOW_KNOWLEDGE_TOPIC_HEADERS, CODE_BLOCK_RUNTIME_TOPIC]
+ assert result["data"]["count"] == len(WORKFLOW_KNOWLEDGE_TOPIC_HEADERS) + 1
assert "A Skyvern workflow is defined" not in json.dumps(result)
+async def test_workflow_knowledge_renders_the_code_block_runtime_names_from_the_executor() -> None:
+ result = await skyvern_workflow_knowledge(topics=[CODE_BLOCK_RUNTIME_TOPIC])
+
+ assert result["ok"] is True
+ content = result["data"]["sections"][CODE_BLOCK_RUNTIME_TOPIC]["content"]
+ safe_vars = CodeBlock.build_safe_vars()
+ for name in ("zip", "ValueError", "sorted"):
+ assert name in safe_vars["__builtins__"]
+ assert name in content
+ assert "open" not in safe_vars["__builtins__"]
+ assert "- datetime: UTC, date, datetime, timedelta, timezone" in content
+ assert "- html: escape" in content
+ assert "{{current_date}}" in content
+ assert "solve_captcha" in content
+
+
@pytest.mark.asyncio
async def test_workflow_knowledge_returns_only_the_requested_authoritative_sections() -> None:
result = await skyvern_workflow_knowledge(topics=["workflow_parameters", "error_handling_and_retries"])