Jump to content
JasperReports 7.0 is now available ×
  • This documentation is an older version of JasperReports Server Security Guide. View the latest documentation.

    Cross-site scripting (XSS) is a security threat where attackers inject malicious data into the server so that the data is executed as JavaScript when it is displayed in the UI. The Open Web Application Security Project (OWASP) lists cross-site scripting in their 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 resourse 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, that 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 has to insert 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.


    The default configuration of the server provides secure XSS protection. Modifying the following configuration is for advanced use cases only and must be done correctly. When configured improperly, these settings may inadvertently break the server UI or silently disable XSS protection.

    Output Escaping

    Configuration File





    The whitelist is the list of HTML tags that will not be escaped when the server renders dynamic content to the UI. This property expands or replaces the default list in xssUtil.js. Specify comma-separated tag names without <> brackets. Use + as the first character to append to the default whitelist. If this property is not specified or the list is empty, the default whitelist applies. For details, see Configuring the Tag Whitelist.


    The attribute map determines which HTML attributes create vulnerabilities in dynamic content and how to replace them. This property defines a map of case-insensitive regular expressions (regex syntax) and replacements. When specified, it overrides the default map defined in xssUtil.js. If this property is absent or not set, the default map is used. For details, see Configuring XSS Protection.


    Note that these configurations only apply to XSS protection of dynamic content; they do not affect how static pages or static content are escaped when generated by the server.

    Configuring the Tag Whitelist

    The tag whitelist specifies all HTML tags (elements) that are allowed in the 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, and it allows the tags needed for the UI to be displayed and escapes any 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:

    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 of the default tags from xssUtil.js, then remove the one 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.


    Never add the script tag to the whitelist because it will disable output escaping of dynamic content.

    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:

    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:

    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.


    Never set the map to {} because this will disable HTML attribute escaping in dynamic content.

    User Feedback

    Recommended Comments

    There are no comments to display.

    This is now closed for further comments

  • Create New...