Guide to using Auto Escape


Auto Escape is an optional mode of execution in the Template System developed to provide a better defense against cross-site scripting (XSS) in web applications. In this mode, the Template System assumes responsibility for applying the proper escaping modifiers for each variable in your template (and templates it may include). As such, the template developer no longer needs to manually apply escaping modifiers to each variable, a process which is repetitive and error-prone particularly in larger and more complex applications.

In order for the Template System to properly determine the escaping modifiers to apply to variables, it activates a built-in HTML-aware parser during template initialization. The parser scans the template to determines the context in which each variable is being emitted. The scanning is performed at initialization-time only hence does not contribute to processing costs at template expansion time.

Refer to Security Considerations for additional security information on escaping directives and their use according to the context in which content is being expanded.

Current Status

Auto Escape currently supports well HTML and Javascript templates. It also provides very basic support for CSS, JSON and XML templates where it applies the corresponding escaping modifier but without utilizing a parser. We may in the future provide parsers specific to these contexts and modifiers for them that are finer-grained.


This section provides more background on Auto Escape. Refer to How to Auto Escape for information on how to leverage this mode in your application.

Using template modifiers

In the simplest case, where you only want to use template-modifiers to achieve html-safety (that is, you only use html_escape, url_query_escape, and so forth), you can stop specifying template-modifiers in your template at all. The Auto Escape mode will generate the modifiers on its own and perform the correct escaping. You can observe the modifiers it applied to your variables using the provided command-line tool diff_tpl_auto_escape.

If you need other types of modifiers, including your own custom modifiers, you can still specify them in your template and they will continue to work just the same. The Auto Escape mode will simply apply the appropriate escaping modifiers after your own.

Other reasons for manually specifying variable modifiers include:

  1. To indicate a variable is safe. You may add the :none modifier as the last modifier for a given variable, in which case the Auto Escape mode will leave it untouched and not apply escaping directives to it. Use only when you are sure the variable is trusted to be safe from XSS.
  2. To select a different escaping modifier from a list of equivalent modifiers. Certain modifiers are equivalent from an escaping point of view in that they would all ensure given content is safe when escaped in a specific context. The Auto Escape mode choses the most common escaping modifier for that use but allows you to indicate a different choice as shown below:

    TemplateContextPrimary Modifier Accepted alternatives
    TC_HTML :html_escape
    • :pre_escape
    • :html_escape_with_arg=snippet
    • :html_escape_with_arg=attribute
    • :url_query_escape
    TC_XML :xml_escape
    • :html_escape
    • :html_escape_with_arg=attribute

  3. To add additional escaping modifiers. The Template System will never remove escaping directives you explicitly specify.

Escaping Contexts

The table belows indicates which modifier Auto-Escape selects to escape a given variable, based on the context of the variable being inserted and, possibly, on more specific information such as whether the variable is inside quotation marks. The table only applies for the well-supported TemplateContext values (currently TC_HTML and TC_JS).

In a few cases, we do not have a modifier that is both safe against XSS and respecting of the semantics of the variable therefore we fail the template initialization. An error is logged indicating the cause of the failure.

ContextHTML Quoted? ExamplesAction Performed
Regular HTML Body and HTML commentsAny
<p>Hello {{USER}}</p>
Escape USER using :html_escape
In URL attribute: Starts at pos 0Yes
<img src="{{URL}}">;
Escape URL using :url_escape_with_arg=html
In URL attribute: OtherYes
<a href="/foo?q={{QUERY}}">
Escape QUERY using :html_escape
In URL attribute: Starting at pos 0No
<form action={{URL}}>
Fail template initialization
In URL attribute: OtherNo
<a href=/foo?q={{QUERY}}>My Link</a>
Escape QUERY using :url_query_escape
In STYLE attributeYes
<div style="{{STYLE}}">
Escape STYLE using :cleanse_css
In STYLE attributeNo
<div style={{STYLE}}>
Fail template initialization
In Javascript attribute: String literalYes
<a href="url" onclick="doFoo('{{ARG}}');">
Escape ARG using :javascript_escape
In Javascript attribute: Non-string literalYes
<a href="url" onclick="doFoo({{ARG}});">
Escape ARG using :javascript_escape_with_arg=number
In Javascript attribute: AnyNo
<a href="url" onclick=doFoo('{{ARG}}');>
Fail template initialization.
In all other attributesYes
<b class="{{CLASS}}">
Escape CLASS using :html_escape
In all other attributesNo
<table border={{BORDER}}>
Escape BORDER using ::html_escape_with_arg=attribute
In Javascript code: In a string literalAny
<script>var a = '{{VALUE}}';</script>
Escape VALUE using :javascript_escape
In Javascript code: Non-string literalAny
<script>var a = {{VALUE}};</script>
Escape VALUE using :javascript_escape_with_arg=number


The Auto Escape mode is designed to be simple to use and to produce correct correct escaping with minimal input. It does however come with restrictions governing the use of this template system.


A new filename convention

The Auto Escape feature codifies simple conventions of template filenames:

  1. CSS templates optionally include, in their filename, the keywords style or stylesheet or css.
  2. Javascript templates optionally include, in their filename, the keywords js or javascript.

If we find one of these keywords in the filename but it does not match the template type given, we log a warning.

Development Tools

diff_tpl_auto_escape: Escaping Modifier Comparaison tool for Templates

If you currently apply escaping modifiers to variables in your template, you may be interested in diff_tpl_auto_escape. This tool compares escaping modifiers applied to each variable in a template against the modifiers that Auto Escape would have selected and emits information on a mismatch. Cases where it may be helpful include:

  1. You are considering switching to Auto-Escape and would like to know whether your variables will be escaped differently.
  2. You want to continue manually escaping all variables but would like some validation that your escaping is correct. Consider using the --dump_templates command-line option described below.

Consider the example below of an HTML template with two variables, USER which is escaped properly and ID which is not.

    <p>Hello {{USER:h}}</p>
    <script>var id = '{{ID:h}}'; alert(id);</script>

Running diff_tpl_auto_escape on this template will emit one line for variable ID indicating the mismatch and how the escaping you provided would be modified under Auto-Escape. Note that by default, the tool will not output information for variables that do not have escaping modifiers applied to them in your template. In that case you may want to provide the --dump_templates command-line option.

Important command line flags:

For a full list of command line flags, run diff_tpl_auto_escape --help.

Jad Boutros