Configuring XSS Protection¶

Cross-site scripting (XSS) is a security threat where attackers inject malicious data into the server so that the data is run as JavaScript when it is displayed in the UI. The Open Web Application Security Project (OWASP) lists cross-site scripting in Top 10 Most Critical Web Application Security Risks.

As of JasperReports Server 6.1, all output in the UI is escaped so that no malicious scripts can run. For example, if an attacker inserts the <script ...> tag into the text of a resource description, the HTML generated by the server contains <script ...> that is displayed but will not run as code. If you see <script ... > in the data shown in the UI it means someone is trying to inject a cross-site script on the server.

Before output escaping, the security framework implemented an input validation mechanism to block cross-site scripting. Input validation is now deprecated in JasperReports Server and no longer supported.

Like many modern web apps, JasperReports Server consists of interactive pages that use JavaScript to modify and update the page dynamically in the browser. To display this dynamic content, JavaScript inserts HTML snippets or raw data from the server into the page's static HTML. The static page is generated by JavaServer Pages (JSP) and HTML templates, which have mechanisms for output escaping to prevent XSS. JasperReports Server has additional mechanisms to escape the output in the dynamic content. Otherwise, it would be vulnerable to XSS. The dynamic output escaping blocks dangerous tags such as <script ...> and it removes dangerous attributes such as onmouseover.

The default configuration of JasperReports Server provides output escaping of both static and dynamic content, and thus protects the server from XSS. The output escaping mechanism for static content cannot be configured. However, for advanced uses, the output escaping mechanism for dynamic content can be configured to allow different HTML tags and block new attributes. The output escaping mechanism is implemented in .../scripts/runtime_dependencies/js-sdk/src/commom/util/xssUtil.js. It defines the tags that are allowed, called the tag whitelist, and HTML attributes that are blocked, called the attribute map. The following configuration properties can supplement or replace these defaults.

Configuring the Tag Whitelist¶

The tag whitelist specifies all HTML tags (elements) that are allowed in dynamic content sent to a user's browser, sometimes called asynchronous data. Tags not in the whitelist are escaped, meaning their < and > brackets are replaced with < and > so they are displayed as < and > but not interpreted as HTML. The default whitelist is defined in the xssUtil.js file. It allows the tags needed for the UI to be displayed and escapes tags such as <script ...> that create XSS vulnerabilities.

The xss.soft.html.escape.tag.whitelist property expands or replaces the default whitelist. It contains comma-separated tag names without < > brackets. If this property is not specified or the list is empty, the default whitelist in xssUtil.js applies.

In normal usage, the first character is + so that the specified tags are added to the default whitelist. For example, if you want to add blink and marquee to the list of allowed HTML tags, specify the following value:

xss.soft.html.escape.tag.whitelist=+blink,marquee

When + is omitted, this list replaces the entire default whitelist. For example, if you wish to block a tag that is specified in the default whitelist, copy all the default tags from xssUtil.js, and delete the ones you wish to block. Be very careful with this usage, because whitelisting the wrong tags can create vulnerabilities. Also, some parts of the UI depend on the default whitelist, and they may appear broken if they are removed from the whitelist.

Configuring the Attribute Map¶

Certain HTML attributes create XSS vulnerabilities because they switch to JavaScript context, for example onmouseover and the like. The attribute map defines which attributes are dangerous and how to replace them when performing output escaping of dynamic content, also called asynchronous data. It uses a map of case-insensitive regular expressions (regex syntax) and replacements to detect and neutralize such malicious HTML. The default map that is coded in xssUtil.js is equivalent to the following expression:

xss.soft.html.escape.attrib.map= {'\\\\bjavascript:': '', '\\\\bon(\\\\w+?)\\\\s*=': 'on$1=', '\\\\(':'(', \ '\\\\bsrcdoc\\\\s*=': 'srcdoc='}

When regex syntax appears in properties files, \ characters must be escaped. For example, \s appears as \\\\s.

For advanced use cases, you can modify this property by adding more pairs to the map. Copy the default map above and add the new regex and its safe replacement at the end. For example, to escape the string data:text/html by replacing it with nothing, use the following map:

xss.soft.html.escape.attrib.map= {'\\\\bjavascript:': '', '\\\\bon(\\\\w+?)\\\\s*=': 'on$1=', '\\\\(':'(', \ '\\\\bsrcdoc\\\\s*=': 'srcdoc=', '\\\\bdata:\\\\s*text/html\\\\b': ''}

Modify this property at your own risk. To work properly, the regex keys in the map must be very specific. Also, the replacement values in the map should never be the same as any regex keys, otherwise multiple replacements will happen, and the output will be corrupted in unpredictable ways.