Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 95 lines (68 sloc) 3.536 kb
5cdc1ac @mitsuhiko documentation update
authored
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
9adf937 @mitsuhiko Updated documentation for operator intercepting
authored
17 API
18 ---
5cdc1ac @mitsuhiko documentation update
authored
19
20 .. module:: jinja2.sandbox
21
22 .. autoclass:: SandboxedEnvironment([options])
9adf937 @mitsuhiko Updated documentation for operator intercepting
authored
23 :members: is_safe_attribute, is_safe_callable, default_binop_table,
24 default_unop_table, intercepted_binops, intercepted_unops,
25 call_binop, call_unop
5cdc1ac @mitsuhiko documentation update
authored
26
522cad6 @mitsuhiko added `ImmutableSandboxedEnvironment`.
authored
27 .. autoclass:: ImmutableSandboxedEnvironment([options])
28
5cdc1ac @mitsuhiko documentation update
authored
29 .. autoexception:: SecurityError
30
31 .. autofunction:: unsafe
32
33 .. autofunction:: is_internal_attribute
522cad6 @mitsuhiko added `ImmutableSandboxedEnvironment`.
authored
34
d71fff0 @mitsuhiko improved sandbox and updated setup.py
authored
35 .. autofunction:: modifies_known_mutable
9bb7e47 @mitsuhiko some more documentation updates and minor code cleanups. Additionally T...
authored
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
6e22357 @jet-sun correct typo
jet-sun authored
45 Also the sandbox is only as good as the configuration. We strongly
9bb7e47 @mitsuhiko some more documentation updates and minor code cleanups. Additionally T...
authored
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.
9adf937 @mitsuhiko Updated documentation for operator intercepting
authored
51
52 Operator Intercepting
53 ---------------------
54
55 .. versionadded:: 2.6
56
3fc008b @jwilk fix a bunch of typos in the documentation
jwilk authored
57 For maximum performance Jinja2 will let operators call directly the type
9adf937 @mitsuhiko Updated documentation for operator intercepting
authored
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.
Something went wrong with that request. Please try again.