<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Sandbox — Jinja2 2.7.2 documentation</title>
<link rel="stylesheet" href="_static/jinja.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '2.7.2',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="Jinja2 2.7.2 documentation" href="index.html" />
<link rel="next" title="Template Designer Documentation" href="templates.html" />
<link rel="prev" title="API" href="api.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="templates.html" title="Template Designer Documentation"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="api.html" title="API"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Jinja2 2.7.2 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="sandbox">
<h1>Sandbox<a class="headerlink" href="#sandbox" title="Permalink to this headline">¶</a></h1>
<p>The Jinja2 sandbox can be used to evaluate untrusted code. Access to unsafe
attributes and methods is prohibited.</p>
<p>Assuming <cite>env</cite> is a <tt class="xref py py-class docutils literal"><span class="pre">SandboxedEnvironment</span></tt> in the default configuration
the following piece of code shows how it works:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">env</span><span class="o">.</span><span class="n">from_string</span><span class="p">(</span><span class="s">"{{ func.func_code }}"</span><span class="p">)</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">func</span><span class="o">=</span><span class="k">lambda</span><span class="p">:</span><span class="bp">None</span><span class="p">)</span>
<span class="go">u''</span>
<span class="gp">>>> </span><span class="n">env</span><span class="o">.</span><span class="n">from_string</span><span class="p">(</span><span class="s">"{{ func.func_code.do_something }}"</span><span class="p">)</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">func</span><span class="o">=</span><span class="k">lambda</span><span class="p">:</span><span class="bp">None</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">SecurityError</span>: <span class="n">access to attribute 'func_code' of 'function' object is unsafe.</span>
</pre></div>
</div>
<div class="section" id="module-jinja2.sandbox">
<span id="api"></span><h2>API<a class="headerlink" href="#module-jinja2.sandbox" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="jinja2.sandbox.SandboxedEnvironment">
<em class="property">class </em><tt class="descclassname">jinja2.sandbox.</tt><tt class="descname">SandboxedEnvironment</tt><big>(</big><span class="optional">[</span><em>options</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#jinja2.sandbox.SandboxedEnvironment" title="Permalink to this definition">¶</a></dt>
<dd><p>The sandboxed environment. It works like the regular environment but
tells the compiler to generate sandboxed code. Additionally subclasses of
this environment may override the methods that tell the runtime what
attributes or functions are safe to access.</p>
<p>If the template tries to access insecure code a <a class="reference internal" href="#jinja2.sandbox.SecurityError" title="jinja2.sandbox.SecurityError"><tt class="xref py py-exc docutils literal"><span class="pre">SecurityError</span></tt></a> is
raised. However also other exceptions may occour during the rendering so
the caller has to ensure that all exceptions are catched.</p>
<dl class="method">
<dt id="jinja2.sandbox.SandboxedEnvironment.is_safe_attribute">
<tt class="descname">is_safe_attribute</tt><big>(</big><em>obj</em>, <em>attr</em>, <em>value</em><big>)</big><a class="headerlink" href="#jinja2.sandbox.SandboxedEnvironment.is_safe_attribute" title="Permalink to this definition">¶</a></dt>
<dd><p>The sandboxed environment will call this method to check if the
attribute of an object is safe to access. Per default all attributes
starting with an underscore are considered private as well as the
special attributes of internal python objects as returned by the
<a class="reference internal" href="#jinja2.sandbox.is_internal_attribute" title="jinja2.sandbox.is_internal_attribute"><tt class="xref py py-func docutils literal"><span class="pre">is_internal_attribute()</span></tt></a> function.</p>
</dd></dl>
<dl class="method">
<dt id="jinja2.sandbox.SandboxedEnvironment.is_safe_callable">
<tt class="descname">is_safe_callable</tt><big>(</big><em>obj</em><big>)</big><a class="headerlink" href="#jinja2.sandbox.SandboxedEnvironment.is_safe_callable" title="Permalink to this definition">¶</a></dt>
<dd><p>Check if an object is safely callable. Per default a function is
considered safe unless the <cite>unsafe_callable</cite> attribute exists and is
True. Override this method to alter the behavior, but this won’t
affect the <cite>unsafe</cite> decorator from this module.</p>
</dd></dl>
<dl class="attribute">
<dt id="jinja2.sandbox.SandboxedEnvironment.default_binop_table">
<tt class="descname">default_binop_table</tt><em class="property"> = {'//': <built-in function floordiv>, '%': <built-in function mod>, '+': <built-in function add>, '*': <built-in function mul>, '-': <built-in function sub>, '/': <built-in function truediv>, '**': <built-in function pow>}</em><a class="headerlink" href="#jinja2.sandbox.SandboxedEnvironment.default_binop_table" title="Permalink to this definition">¶</a></dt>
<dd><p>default callback table for the binary operators. A copy of this is
available on each instance of a sandboxed environment as
<tt class="xref py py-attr docutils literal"><span class="pre">binop_table</span></tt></p>
</dd></dl>
<dl class="attribute">
<dt id="jinja2.sandbox.SandboxedEnvironment.default_unop_table">
<tt class="descname">default_unop_table</tt><em class="property"> = {'+': <built-in function pos>, '-': <built-in function neg>}</em><a class="headerlink" href="#jinja2.sandbox.SandboxedEnvironment.default_unop_table" title="Permalink to this definition">¶</a></dt>
<dd><p>default callback table for the unary operators. A copy of this is
available on each instance of a sandboxed environment as
<tt class="xref py py-attr docutils literal"><span class="pre">unop_table</span></tt></p>
</dd></dl>
<dl class="attribute">
<dt id="jinja2.sandbox.SandboxedEnvironment.intercepted_binops">
<tt class="descname">intercepted_binops</tt><em class="property"> = frozenset([])</em><a class="headerlink" href="#jinja2.sandbox.SandboxedEnvironment.intercepted_binops" title="Permalink to this definition">¶</a></dt>
<dd><p>a set of binary operators that should be intercepted. Each operator
that is added to this set (empty by default) is delegated to the
<a class="reference internal" href="#jinja2.sandbox.SandboxedEnvironment.call_binop" title="jinja2.sandbox.SandboxedEnvironment.call_binop"><tt class="xref py py-meth docutils literal"><span class="pre">call_binop()</span></tt></a> method that will perform the operator. The default
operator callback is specified by <tt class="xref py py-attr docutils literal"><span class="pre">binop_table</span></tt>.</p>
<p>The following binary operators are interceptable:
<tt class="docutils literal"><span class="pre">//</span></tt>, <tt class="docutils literal"><span class="pre">%</span></tt>, <tt class="docutils literal"><span class="pre">+</span></tt>, <tt class="docutils literal"><span class="pre">*</span></tt>, <tt class="docutils literal"><span class="pre">-</span></tt>, <tt class="docutils literal"><span class="pre">/</span></tt>, and <tt class="docutils literal"><span class="pre">**</span></tt></p>
<p>The default operation form the operator table corresponds to the
builtin function. Intercepted calls are always slower than the native
operator call, so make sure only to intercept the ones you are
interested in.</p>
<p class="versionadded">
<span class="versionmodified">New in version 2.6.</span></p>
</dd></dl>
<dl class="attribute">
<dt id="jinja2.sandbox.SandboxedEnvironment.intercepted_unops">
<tt class="descname">intercepted_unops</tt><em class="property"> = frozenset([])</em><a class="headerlink" href="#jinja2.sandbox.SandboxedEnvironment.intercepted_unops" title="Permalink to this definition">¶</a></dt>
<dd><p>a set of unary operators that should be intercepted. Each operator
that is added to this set (empty by default) is delegated to the
<a class="reference internal" href="#jinja2.sandbox.SandboxedEnvironment.call_unop" title="jinja2.sandbox.SandboxedEnvironment.call_unop"><tt class="xref py py-meth docutils literal"><span class="pre">call_unop()</span></tt></a> method that will perform the operator. The default
operator callback is specified by <tt class="xref py py-attr docutils literal"><span class="pre">unop_table</span></tt>.</p>
<p>The following unary operators are interceptable: <tt class="docutils literal"><span class="pre">+</span></tt>, <tt class="docutils literal"><span class="pre">-</span></tt></p>
<p>The default operation form the operator table corresponds to the
builtin function. Intercepted calls are always slower than the native
operator call, so make sure only to intercept the ones you are
interested in.</p>
<p class="versionadded">
<span class="versionmodified">New in version 2.6.</span></p>
</dd></dl>
<dl class="method">
<dt id="jinja2.sandbox.SandboxedEnvironment.call_binop">
<tt class="descname">call_binop</tt><big>(</big><em>context</em>, <em>operator</em>, <em>left</em>, <em>right</em><big>)</big><a class="headerlink" href="#jinja2.sandbox.SandboxedEnvironment.call_binop" title="Permalink to this definition">¶</a></dt>
<dd><p>For intercepted binary operator calls (<a class="reference internal" href="#jinja2.sandbox.SandboxedEnvironment.intercepted_binops" title="jinja2.sandbox.SandboxedEnvironment.intercepted_binops"><tt class="xref py py-meth docutils literal"><span class="pre">intercepted_binops()</span></tt></a>)
this function is executed instead of the builtin operator. This can
be used to fine tune the behavior of certain operators.</p>
<p class="versionadded">
<span class="versionmodified">New in version 2.6.</span></p>
</dd></dl>
<dl class="method">
<dt id="jinja2.sandbox.SandboxedEnvironment.call_unop">
<tt class="descname">call_unop</tt><big>(</big><em>context</em>, <em>operator</em>, <em>arg</em><big>)</big><a class="headerlink" href="#jinja2.sandbox.SandboxedEnvironment.call_unop" title="Permalink to this definition">¶</a></dt>
<dd><p>For intercepted unary operator calls (<a class="reference internal" href="#jinja2.sandbox.SandboxedEnvironment.intercepted_unops" title="jinja2.sandbox.SandboxedEnvironment.intercepted_unops"><tt class="xref py py-meth docutils literal"><span class="pre">intercepted_unops()</span></tt></a>)
this function is executed instead of the builtin operator. This can
be used to fine tune the behavior of certain operators.</p>
<p class="versionadded">
<span class="versionmodified">New in version 2.6.</span></p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="jinja2.sandbox.ImmutableSandboxedEnvironment">
<em class="property">class </em><tt class="descclassname">jinja2.sandbox.</tt><tt class="descname">ImmutableSandboxedEnvironment</tt><big>(</big><span class="optional">[</span><em>options</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#jinja2.sandbox.ImmutableSandboxedEnvironment" title="Permalink to this definition">¶</a></dt>
<dd><p>Works exactly like the regular <cite>SandboxedEnvironment</cite> but does not
permit modifications on the builtin mutable objects <cite>list</cite>, <cite>set</cite>, and
<cite>dict</cite> by using the <a class="reference internal" href="#jinja2.sandbox.modifies_known_mutable" title="jinja2.sandbox.modifies_known_mutable"><tt class="xref py py-func docutils literal"><span class="pre">modifies_known_mutable()</span></tt></a> function.</p>
</dd></dl>
<dl class="exception">
<dt id="jinja2.sandbox.SecurityError">
<em class="property">exception </em><tt class="descclassname">jinja2.sandbox.</tt><tt class="descname">SecurityError</tt><big>(</big><em>message=None</em><big>)</big><a class="headerlink" href="#jinja2.sandbox.SecurityError" title="Permalink to this definition">¶</a></dt>
<dd><p>Raised if a template tries to do something insecure if the
sandbox is enabled.</p>
</dd></dl>
<dl class="function">
<dt id="jinja2.sandbox.unsafe">
<tt class="descclassname">jinja2.sandbox.</tt><tt class="descname">unsafe</tt><big>(</big><em>f</em><big>)</big><a class="headerlink" href="#jinja2.sandbox.unsafe" title="Permalink to this definition">¶</a></dt>
<dd><p>Marks a function or method as unsafe.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@unsafe</span>
<span class="k">def</span> <span class="nf">delete</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">pass</span>
</pre></div>
</div>
</dd></dl>
<dl class="function">
<dt id="jinja2.sandbox.is_internal_attribute">
<tt class="descclassname">jinja2.sandbox.</tt><tt class="descname">is_internal_attribute</tt><big>(</big><em>obj</em>, <em>attr</em><big>)</big><a class="headerlink" href="#jinja2.sandbox.is_internal_attribute" title="Permalink to this definition">¶</a></dt>
<dd><p>Test if the attribute given is an internal python attribute. For
example this function returns <cite>True</cite> for the <cite>func_code</cite> attribute of
python objects. This is useful if the environment method
<a class="reference internal" href="#jinja2.sandbox.SandboxedEnvironment.is_safe_attribute" title="jinja2.sandbox.SandboxedEnvironment.is_safe_attribute"><tt class="xref py py-meth docutils literal"><span class="pre">is_safe_attribute()</span></tt></a> is overridden.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">jinja2.sandbox</span> <span class="kn">import</span> <span class="n">is_internal_attribute</span>
<span class="gp">>>> </span><span class="n">is_internal_attribute</span><span class="p">(</span><span class="k">lambda</span><span class="p">:</span> <span class="bp">None</span><span class="p">,</span> <span class="s">"func_code"</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">is_internal_attribute</span><span class="p">((</span><span class="k">lambda</span> <span class="n">x</span><span class="p">:</span><span class="n">x</span><span class="p">)</span><span class="o">.</span><span class="n">func_code</span><span class="p">,</span> <span class="s">'co_code'</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">is_internal_attribute</span><span class="p">(</span><span class="nb">str</span><span class="p">,</span> <span class="s">"upper"</span><span class="p">)</span>
<span class="go">False</span>
</pre></div>
</div>
</dd></dl>
<dl class="function">
<dt id="jinja2.sandbox.modifies_known_mutable">
<tt class="descclassname">jinja2.sandbox.</tt><tt class="descname">modifies_known_mutable</tt><big>(</big><em>obj</em>, <em>attr</em><big>)</big><a class="headerlink" href="#jinja2.sandbox.modifies_known_mutable" title="Permalink to this definition">¶</a></dt>
<dd><p>This function checks if an attribute on a builtin mutable object
(list, dict, set or deque) would modify it if called. It also supports
the “user”-versions of the objects (<cite>sets.Set</cite>, <cite>UserDict.*</cite> etc.) and
with Python 2.6 onwards the abstract base classes <cite>MutableSet</cite>,
<cite>MutableMapping</cite>, and <cite>MutableSequence</cite>.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">modifies_known_mutable</span><span class="p">({},</span> <span class="s">"clear"</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">modifies_known_mutable</span><span class="p">({},</span> <span class="s">"keys"</span><span class="p">)</span>
<span class="go">False</span>
<span class="gp">>>> </span><span class="n">modifies_known_mutable</span><span class="p">([],</span> <span class="s">"append"</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">modifies_known_mutable</span><span class="p">([],</span> <span class="s">"index"</span><span class="p">)</span>
<span class="go">False</span>
</pre></div>
</div>
<p>If called with an unsupported object (such as unicode) <cite>False</cite> is
returned.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">modifies_known_mutable</span><span class="p">(</span><span class="s">"foo"</span><span class="p">,</span> <span class="s">"upper"</span><span class="p">)</span>
<span class="go">False</span>
</pre></div>
</div>
</dd></dl>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p>The Jinja2 sandbox alone is no solution for perfect security. Especially
for web applications you have to keep in mind that users may create
templates with arbitrary HTML in so it’s crucial to ensure that (if you
are running multiple users on the same server) they can’t harm each other
via JavaScript insertions and much more.</p>
<p>Also the sandbox is only as good as the configuration. We strongly
recommend only passing non-shared resources to the template and use
some sort of whitelisting for attributes.</p>
<p class="last">Also keep in mind that templates may raise runtime or compile time errors,
so make sure to catch them.</p>
</div>
</div>
<div class="section" id="operator-intercepting">
<h2>Operator Intercepting<a class="headerlink" href="#operator-intercepting" title="Permalink to this headline">¶</a></h2>
<p class="versionadded">
<span class="versionmodified">New in version 2.6.</span></p>
<p>For maximum performace Jinja2 will let operators call directly the type
specific callback methods. This means that it’s not possible to have this
intercepted by overriding <tt class="xref py py-meth docutils literal"><span class="pre">Environment.call()</span></tt>. Furthermore a
conversion from operator to special method is not always directly possible
due to how operators work. For instance for divisions more than one
special method exist.</p>
<p>With Jinja 2.6 there is now support for explicit operator intercepting.
This can be used to customize specific operators as necessary. In order
to intercept an operator one has to override the
<a class="reference internal" href="#jinja2.sandbox.SandboxedEnvironment.intercepted_binops" title="jinja2.sandbox.SandboxedEnvironment.intercepted_binops"><tt class="xref py py-attr docutils literal"><span class="pre">SandboxedEnvironment.intercepted_binops</span></tt></a> attribute. Once the
operator that needs to be intercepted is added to that set Jinja2 will
generate bytecode that calls the <a class="reference internal" href="#jinja2.sandbox.SandboxedEnvironment.call_binop" title="jinja2.sandbox.SandboxedEnvironment.call_binop"><tt class="xref py py-meth docutils literal"><span class="pre">SandboxedEnvironment.call_binop()</span></tt></a>
function. For unary operators the <cite>unary</cite> attributes and methods have to
be used instead.</p>
<p>The default implementation of <a class="reference internal" href="#jinja2.sandbox.SandboxedEnvironment.call_binop" title="jinja2.sandbox.SandboxedEnvironment.call_binop"><tt class="xref py py-attr docutils literal"><span class="pre">SandboxedEnvironment.call_binop</span></tt></a>
will use the <tt class="xref py py-attr docutils literal"><span class="pre">SandboxedEnvironment.binop_table</span></tt> to translate
operator symbols into callbacks performing the default operator behavior.</p>
<p>This example shows how the power (<tt class="docutils literal"><span class="pre">**</span></tt>) operator can be disabled in
Jinja2:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">jinja2.sandbox</span> <span class="kn">import</span> <span class="n">SandboxedEnvironment</span>
<span class="k">class</span> <span class="nc">MyEnvironment</span><span class="p">(</span><span class="n">SandboxedEnvironment</span><span class="p">):</span>
<span class="n">intercepted_binops</span> <span class="o">=</span> <span class="nb">frozenset</span><span class="p">([</span><span class="s">'**'</span><span class="p">])</span>
<span class="k">def</span> <span class="nf">call_binop</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">context</span><span class="p">,</span> <span class="n">operator</span><span class="p">,</span> <span class="n">left</span><span class="p">,</span> <span class="n">right</span><span class="p">):</span>
<span class="k">if</span> <span class="n">operator</span> <span class="o">==</span> <span class="s">'**'</span><span class="p">:</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">undefined</span><span class="p">(</span><span class="s">'the power operator is unavailable'</span><span class="p">)</span>
<span class="k">return</span> <span class="n">SandboxedEnvironment</span><span class="o">.</span><span class="n">call_binop</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">context</span><span class="p">,</span>
<span class="n">operator</span><span class="p">,</span> <span class="n">left</span><span class="p">,</span> <span class="n">right</span><span class="p">)</span>
</pre></div>
</div>
<p>Make sure to always call into the super method, even if you are not
intercepting the call. Jinja2 might internally call the method to
evaluate expressions.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper"><p class="logo"><a href="index.html">
<img class="logo" src="_static/jinja-small.png" alt="Logo"/>
</a></p>
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Sandbox</a><ul>
<li><a class="reference internal" href="#module-jinja2.sandbox">API</a></li>
<li><a class="reference internal" href="#operator-intercepting">Operator Intercepting</a></li>
</ul>
</li>
</ul>
<h3>Related Topics</h3>
<ul>
<li><a href="index.html">Documentation overview</a><ul>
<li>Previous: <a href="api.html" title="previous chapter">API</a></li>
<li>Next: <a href="templates.html" title="next chapter">Template Designer Documentation</a></li>
</ul></li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/sandbox.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
© Copyright 2008, Armin Ronacher.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
</div>
</body>
</html>
