Jinja2 Documentation

# Jinja

« API | Sandbox | Template Designer Documentation »

# Sandbox

The Jinja2 sandbox can be used to evaluate untrusted code. Access to unsafe attributes and methods is prohibited.

Assuming env is a `SandboxedEnvironment` in the default configuration the following piece of code shows how it works:

    >>> env.from_string("{{ func.func_code }}").render(func=lambda:None)
    u''
    >>> env.from_string("{{ func.func_code.do_something }}").render(func=lambda:None)
    Traceback (most recent call last):
      ...
    SecurityError: access to attribute 'func_code' of 'function' object is unsafe.

class `jinja2.sandbox.` `SandboxedEnvironment`([options])

  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.

  If the template tries to access insecure code a `SecurityError` is raised. However also other exceptions may occour during the rendering so the caller has to ensure that all exceptions are catched.

  `is_safe_attribute`(obj, attr, value)
    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 `is_internal_attribute()` function.
  `is_safe_callable`(obj)
    Check if an object is safely callable. Per default a function is considered safe unless the unsafe_callable attribute exists and is True. Override this method to alter the behavior, but this won’t affect the unsafe decorator from this module.

class `jinja2.sandbox.` `ImmutableSandboxedEnvironment`([options])
  Works exactly like the regular SandboxedEnvironment but does not permit modifications on the builtin mutable objects list, set, and dict by using the `modifies_known_mutable()` function.

exception `jinja2.sandbox.` `SecurityError`
  Raised if a template tries to do something insecure if the sandbox is enabled.

`jinja2.sandbox.` `unsafe`(f)

  Mark a function or method as unsafe:

      @unsafe
      def delete(self):
          pass

`jinja2.sandbox.` `is_internal_attribute`(obj, attr)

  Test if the attribute given is an internal python attribute. For example this function returns True for the func_code attribute of python objects. This is useful if the environment method `is_safe_attribute()` is overriden.

      >>> from jinja2.sandbox import is_internal_attribute
      >>> is_internal_attribute(lambda: None, "func_code")
      True
      >>> is_internal_attribute((lambda x:x).func_code, 'co_code')
      True
      >>> is_internal_attribute(str, "upper")
      False

`jinja2.sandbox.` `modifies_known_mutable`(obj, attr)

  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 (sets.Set, UserDict.* etc.) and with Python 2.6 onwards the abstract base classes MutableSet, MutableMapping, and MutableSequence.

      >>> modifies_known_mutable({}, "clear")
      True
      >>> modifies_known_mutable({}, "keys")
      False
      >>> modifies_known_mutable([], "append")
      True
      >>> modifies_known_mutable([], "index")
      False

  If called with an unsupported object (such as unicode) False is returned.

      >>> modifies_known_mutable("foo", "upper")
      False

Note

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.

Also the sandbox is only as good as the configuration. We stronly recommend only passing non-shared resources to the template and use some sort of whitelisting for attributes.

Also keep in mind that templates may raise runtime or compile time errors, so make sure to catch them.