Merge branch 'sandbox-jinja-templating-backport' into 'wayflow-25.4.x'

[Backport] Restricted sandboxed jinja templating

Author: nasseur

.gitignore

@@ -12,7 +12,6 @@ licenses_example/choosealicense.com
 .idea/
 *.iml
 .gradle/
-venv/
 .venv-*
 lib64/
 bin/
@@ -201,3 +200,8 @@ Thumbs.db
 
 *.pklz
 *.sqlite
+
+
+# environment variables such as private keys
+*env/
+examples/*

VERSION

@@ -1 +1 @@
-26.1.0.dev0
+25.4.3

docs/wayflowcore/source/core/changelog.rst

@@ -1,6 +1,20 @@
 Changelog
 =========
 
+WayFlow 25.4.3
+--------------
+
+Security
+^^^^^^^^
+
+* **Stricter environment for jinja templates rendering:**
+
+  We now use a stricter version of the SandboxedEnvironment for rendering jinja templates.
+  No access to object attributes is allowed, only key-based access to python dictionaries and main jinja LoopContext properties are allowed.
+
+  Check the guide on :ref:`How to write secure prompts with Jinja templating <securejinjatemplating>` for more information.
+
+
 WayFlow 25.4.2
 --------------
 

docs/wayflowcore/source/core/code_examples/howto_prompttemplate.py

@@ -69,7 +69,7 @@
 prompt_text = """You are a helpful assistant. Answer the user questions.
 For context, the conversation was:
 {% for msg in __CHAT_HISTORY__ %}
-{{ msg.message_type.value }} >> {{msg.content}}
+{{ msg.message_type }} >> {{msg.content}}
 {%- endfor %}
 
 Just answer the user question.
@@ -203,7 +203,7 @@ def some_tool(param1: Annotated[str, "name of the user"]) -> Annotated[str, "too
 # .. start-###_With_custom_structured_generation
 text_template = """Extract information about a person. The person is 65 years old, named Johnny.
 Just return a json document that respects this JSON Schema:
-{{__RESPONSE_FORMAT__.to_json_schema() | tojson }}
+{{__RESPONSE_FORMAT__ | tojson }}
 
 Reminder: only output the required json document, no need to repeat the title of the description, just the properties are required!
 """

docs/wayflowcore/source/core/howtoguides/agents.rst

@@ -41,6 +41,11 @@ Sometimes, there is contextual information relevant to the conversation.
 Assume a user is interacting with the assistant named "Jerry."
 To make the assistant more context-aware, define a variable or expression in the ``custom_instruction`` Jinja template, and pass it when creating the conversation:
 
+.. note::
+
+    Jinja templating introduces security concerns that are addressed by WayFlow by restricting Jinja's rendering capabilities.
+    Please check our guide on :ref:`How to write secure prompts with Jinja templating <securejinjatemplating>` for more information.
+
 .. literalinclude:: ../code_examples/howto_agents.py
     :language: python
     :start-after: .. start-conversation:

docs/wayflowcore/source/core/howtoguides/conditional_flows.rst

@@ -154,6 +154,11 @@ For scenarios requiring branching based on more advanced conditions, consider us
     :start-after: .. start-##_Branching_with_a_template
     :end-before: .. end-##_Branching_with_a_template
 
+.. note::
+
+    Jinja templating introduces security concerns that are addressed by WayFlow by restricting Jinja's rendering capabilities.
+    Please check our guide on :ref:`How to write secure prompts with Jinja templating <securejinjatemplating>` for more information.
+
 Pattern 3: Branching using an LLM
 ---------------------------------
 

docs/wayflowcore/source/core/howtoguides/promptexecutionstep.rst

@@ -89,6 +89,162 @@ You can instruct the agent to generate specific outputs, and use them in the ``A
     :start-after: .. start-agent:
     :end-before: .. end-agent
 
+How to write secure prompts with Jinja templating
+=================================================
+
+.. _securejinjatemplating:
+
+`Jinja2 <https://jinja.palletsprojects.com/en/stable/intro/>`_ is a fast and flexible templating engine for Python,
+enabling dynamic generation of text-based formats by combining templates with data.
+
+However, enabling all Jinja templating capabilities poses some security challenges.
+For this reason, WayFlow relies on a stricter implementation of the Jinja's SandboxedEnvironment for higher security.
+Every callable is considered unsafe, and every attribute and item access is prevented, except for:
+
+* The attributes ``index0``, ``index``, ``first``, ``last``, ``length`` of the ``jinja2.runtime.LoopContext``;
+* The entries of a python dictionary (only native type is accepted);
+* The items of a python list (only native type is accepted).
+
+You should never write a template that includes a function call, or access to any internal attribute or element of
+an arbitrary variable: that is considered unsafe, and it will raise a ``SecurityException``.
+
+Moreover, WayFlow performs additional checks on the inputs provided for rendering.
+In particular, only elements and sub-elements that are of basic python types
+(``str``, ``int``, ``float``, ``bool``, ``list``, ``dict``, ``tuple``, ``set``, ``NoneType``) are accepted.
+In any other case, a ``SecurityException`` is raised.
+
+What you can write
+------------------
+
+Here's a set of common patters that are accepted by WayFlow's restricted Jinja templating.
+
+Templates that access variables of base python types:
+
+  .. code-block:: python
+
+    my_var: str = "simple string"
+    template = "{{ my_var }}"
+    # Expected outcome: "simple string"
+
+Templates that access elements of a list of base python types:
+
+  .. code-block:: python
+
+    my_var: list[str] = ["simple string"]
+    template = "{{ my_var[0] }}"
+    # Expected outcome: "simple string"
+
+Templates that access dictionary entries of base python types:
+
+  .. code-block:: python
+
+    my_var: dict[str, str] = {"k1": "simple string"}
+    template = "{{ my_var['k1'] }}"
+    # Expected outcome: "simple string"
+
+    my_var: dict[str, str] = {"k1": "simple string"}
+    template = "{{ my_var.k1 }}"
+    # Expected outcome: "simple string"
+
+Builtin functions of Jinja, like ``length`` or ``format``:
+
+  .. code-block:: python
+
+    my_var: list[str] = ["simple string"]
+    template = "{{ my_var | length }}"
+    # Expected outcome: "1"
+
+Simple expressions:
+
+  .. code-block:: python
+
+    template = "{{ 7*7 }}"
+    # Expected outcome: "49"
+
+``For`` loops, optionally accessing the ``LoopContext``:
+
+  .. code-block:: python
+
+    my_var: list[int] = [1, 2, 3]
+    template = "{% for e in my_var %}{{e}}{{ ', ' if not loop.last }}{% endfor %}"
+    # Expected outcome: "1, 2, 3"
+
+``If`` conditions:
+
+  .. code-block:: python
+
+    my_var: int = 4
+    template = "{% if my_var % 2 == 0 %}even{% else %}odd{% endif %}"
+    # Expected outcome: "even"
+
+Our general recommendation is to avoid complex logic in templates, and to pre-process the data you want to render instead.
+For example, in case of complex objects, in order to comply with restrictions above, you should conveniently
+transform them recursively into a dictionary of entries of basic python types (see list of accepted types above).
+
+What you cannot write
+---------------------
+
+Here's a set of common patters that are **NOT** accepted by WayFlow's restricted Jinja templating.
+
+Templates that access arbitrary objects:
+
+  .. code-block:: python
+
+    my_var: MyComplexObject = MyComplexObject()
+    template = "{{ my_var }}"
+    # Expected outcome: SecurityException
+
+Templates that access attributes of arbitrary objects:
+
+  .. code-block:: python
+
+    my_var: MyComplexObject = MyComplexObject(attribute="my string")
+    template = "{{ my_var.attribute }}"
+    # Expected outcome: SecurityException
+
+Templates that access internals of any type and object:
+
+  .. code-block:: python
+
+    my_var: dict = {"k1": "my string"}
+    template = "{{ my_var.__init__ }}"
+    # Expected outcome: SecurityException
+
+Templates that access non-existing keys of a dictionary:
+
+  .. code-block:: python
+
+    my_var: dict = {"k1": "my string"}
+    template = "{{ my_var['non-existing-key'] }}"
+    # Expected outcome: SecurityException
+
+Templates that access keys of a dictionary of type different from ``int`` or ``str``:
+
+  .. code-block:: python
+
+    my_var: dict = {("complex", "key"): "my string"}
+    template = "{{ my_var[('complex', 'key')] }}"
+    # Expected outcome: SecurityException
+
+Templates that access callables:
+
+  .. code-block:: python
+
+    my_var: Callable = lambda x: f"my value {x}"
+    template = "{{ my_var(2) }}"
+    # Expected outcome: SecurityException
+
+    my_var: list = [1, 2, 3]
+    template = "{{ len(my_var) }}"
+    # Expected outcome: SecurityException
+
+    my_var: MyComplexObject = MyComplexObject()
+    template = "{{ my_var.to_string() }}"
+    # Expected outcome: SecurityException
+
+
+For more information, please check our :doc:`Security considerations page <../security>`.
+
 Recap
 =====
 

docs/wayflowcore/source/core/misc/glossary.rst

@@ -228,12 +228,17 @@ Prompt Template
 ===============
 
 A prompt template is a standardized prompt structure with placeholders for variable inputs, designed to maintain consistency across similar queries
-while allowing for customization. WayFlow uses jinja-style placeholders to specify the input variables to the prompt (for more information check
-the `reference of jinja2 <https://jinja.palletsprojects.com/en/stable/templates>`_).
+while allowing for customization. WayFlow uses Jinja-style placeholders to specify the input variables to the prompt (for more information check
+the `reference of Jinja2 <https://jinja.palletsprojects.com/en/stable/templates>`_).
 
 See the :doc:`Tutorials and Use-Case Examples <../tutorials/index>` for concrete examples, or check the
 :ref:`TemplateRenderingStep API reference <templaterenderingstep>`.
 
+.. note::
+
+    Jinja templating introduces security concerns that are addressed by WayFlow by restricting Jinja's rendering capabilities.
+    Please check our guide on :ref:`How to write secure prompts with Jinja templating <securejinjatemplating>` for more information.
+
 Prompt templates can be used in WayFlow components that use LLMs, such as :ref:`Agents <agent>` and the :ref:`PromptExecutionStep <promptexecutionstep>`.
 
 Properties

docs/wayflowcore/source/core/security.rst

@@ -487,6 +487,21 @@ Jinja 2's automatic HTML-escaping is **disabled by design** in WayFlow to:
 
 This preserves model fidelity/latency but removes default XSS/code-injection safeguards.
 
+WayFlow relies on a stricter implementation of the Jinja's SandboxedEnvironment for security reasons.
+Every callable is considered unsafe, and every attribute access is prevented, except for:
+
+* The attributes ``index0``, ``index``, ``first``, ``last``, ``length`` of the ``jinja2.runtime.LoopContext``;
+* The entries of a python dictionary (only native type is accepted);
+* The items of a python list (only native type is accepted).
+
+You should never write a template that includes a function call, or access to any internal attribute or element of
+an arbitrary variable: that is considered unsafe, and it will raise a ``SecurityException``.
+
+Moreover, WayFlow performs additional checks are performed on the inputs provided for rendering.
+In particular, only elements and sub-elements that are of basic python types
+(``str``, ``int``, ``float``, ``bool``, ``list``, ``dict``, ``tuple``, ``set``, ``NoneType``)
+are accepted. In any other case, a ``SecurityException`` is raised.
+
 .. important::
 
    **Never render the raw output of a WayFlow step directly to a browser.**

docs/wayflowcore/source/core/tutorials/basic_flow.rst

@@ -120,6 +120,11 @@ Parameters in a Jinja template look like this: ``{{this_is_a_template_parameter}
 other sources, such as the input parameters schemas of the ``tool`` for the ``ToolExecutionStep``. There will be one input descriptor for each
 parameter in the template, with a name taken from the parameter. Similarly, there will be one input descriptor for each parameter required by a ``tool``.
 
+.. note::
+
+    Jinja templating introduces security concerns that are addressed by WayFlow by restricting Jinja's rendering capabilities.
+    Please check our guide on :ref:`How to write secure prompts with Jinja templating <securejinjatemplating>` for more information.
+
 Output descriptors can also be considered names for a step's outputs. For many steps, there will be a default name for each output. For example,
 for a ``ToolExecutionStep`` the default name for the output of the step is ``ToolExecutionStep.TOOL_OUTPUT``.