docs/sandbox.rst

   1 Sandbox
   2 =======
   3
   4 The Jinja2 sandbox can be used to evaluate untrusted code.  Access to unsafe
   5 attributes and methods is prohibited.
   6
   7 Assuming `env` is a :class:`SandboxedEnvironment` in the default configuration
   8 the following piece of code shows how it works:
   9
  10 >>> env.from_string("{{ func.func_code }}").render(func=lambda:None)
  11 u''
  12 >>> env.from_string("{{ func.func_code.do_something }}").render(func=lambda:None)
  13 Traceback (most recent call last):
  14   ...
  15 SecurityError: access to attribute 'func_code' of 'function' object is unsafe.
  16
  17 API
  18 ---
  19
  20 .. module:: jinja2.sandbox
  21
  22 .. autoclass:: SandboxedEnvironment([options])
  23     :members: is_safe_attribute, is_safe_callable, default_binop_table,
  24               default_unop_table, intercepted_binops, intercepted_unops,
  25               call_binop, call_unop
  26
  27 .. autoclass:: ImmutableSandboxedEnvironment([options])
  28
  29 .. autoexception:: SecurityError
  30
  31 .. autofunction:: unsafe
  32
  33 .. autofunction:: is_internal_attribute
  34
  35 .. autofunction:: modifies_known_mutable
  36
  37 .. admonition:: Note
  38
  39     The Jinja2 sandbox alone is no solution for perfect security.  Especially
  40     for web applications you have to keep in mind that users may create
  41     templates with arbitrary HTML in so it's crucial to ensure that (if you
  42     are running multiple users on the same server) they can't harm each other
  43     via JavaScript insertions and much more.
  44
  45     Also the sandbox is only as good as the configuration.  We stronly
  46     recommend only passing non-shared resources to the template and use
  47     some sort of whitelisting for attributes.
  48
  49     Also keep in mind that templates may raise runtime or compile time errors,
  50     so make sure to catch them.
  51
  52 Operator Intercepting
  53 ---------------------
  54
  55 .. versionadded:: 2.6
  56
  57 For maximum performace Jinja2 will let operators call directly the type
  58 specific callback methods.  This means that it's not possible to have this
  59 intercepted by overriding :meth:`Environment.call`.  Furthermore a
  60 conversion from operator to special method is not always directly possible
  61 due to how operators work.  For instance for divisions more than one
  62 special method exist.
  63
  64 With Jinja 2.6 there is now support for explicit operator intercepting.
  65 This can be used to customize specific operators as necessary.  In order
  66 to intercept an operator one has to override the
  67 :attr:`SandboxedEnvironment.intercepted_binops` attribute.  Once the
  68 operator that needs to be intercepted is added to that set Jinja2 will
  69 generate bytecode that calls the :meth:`SandboxedEnvironment.call_binop`
  70 function.  For unary operators the `unary` attributes and methods have to
  71 be used instead.
  72
  73 The default implementation of :attr:`SandboxedEnvironment.call_binop`
  74 will use the :attr:`SandboxedEnvironment.binop_table` to translate
  75 operator symbols into callbacks performing the default operator behavior.
  76
  77 This example shows how the power (``**``) operator can be disabled in
  78 Jinja2::
  79
  80     from jinja2.sandbox import SandboxedEnvironment
  81
  82
  83     class MyEnvironment(SandboxedEnvironment):
  84         intercepted_binops = frozenset(['**'])
  85
  86         def call_binop(self, context, operator, left, right):
  87             if operator == '**':
  88                 return self.undefined('the power operator is unavailable')
  89             return SandboxedEnvironment.call_binop(self, context,
  90                                                    operator, left, right)
  91
  92 Make sure to always call into the super method, even if you are not
  93 intercepting the call.  Jinja2 might internally call the method to
  94 evaluate expressions.