Jump to content
  • 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 submit malicious code in fields of the UI, such as a resource description, so that the code is executed when the field is displayed again. As of JasperReports Server 6.1, all output in the UI is escaped so that no malicious code can run. For example, if an attacker inserts the <script ...> tag, the HTML contains <script ...> that is displayed but will not run as code. If you see <script ... > in the UI, that means someone is probing the server, and you should monitor user access.

    Another way that malicious scripts may be loaded onto the server is inside JRXML files, especially interactive chart properties, and other files within a JasperReport. Output escaping also blocks unwanted scripts from running inside reports. Still, it is always good practice to limit the number of users with ROLE_ADMINISTRATOR, which grants permission to upload JasperReports and other files to the server through the repository or through Jaspersoft Studio.

    Before output escaping, the security framework implemented an input validation mechanism to block cross-site scripting. Input validation scans all fields and input through the UI as they are being submitted. By default, input validation is now turned off, but the mechanism remains in the server and can be turned on and customized if needed.

    Configuring Input Validation

    For example, when input validation is turned on, administrators can monitor the server logs to search for evidence of attempted security breaches. However, input that was allowed in previous versions of the server may be blocked, and users may see errors when entering values. In particular, parameter names and values can't have tags (< and >). If users see recurring errors with input validation, administrators can examine logs to determine what input is not allowed. Preferably, users should modify their input to remove special characters that are security risks. If that's not feasible, administrators can configure input validation to allow characters needed in your business applications.

    Input validation is complex and configured in the following files:




    Top-level configuration for enabling or disabling input validation.


    Text of validation error messages shown to users.


    Defines the input validation rules for each field of the server’s web pages and report input.


    Defines the regular expressions used in input validation rules.


    Input validation is based on UTF-8 encoded input. Make sure your application server is configured for UTF-8 URIs as described in the JasperReports Server Administrator Guide

    To turn input validation on or off:

    Input Validation

    Configuration File






    false <default>

    Turns field input validation on or off for the server web application. Any other value besides case-insensitive “false” is equivalent to true.

    Query validation uses the same mechanism as input validation, but it remains turned on by default in the server configuration. Query validation and input validation use the same configuration files, but they can be turned on and off independently. Leave query validation turned on to protect the server and your databases from SQL injection. For more information, see Protecting Against SQL Injection.

    The following sections describe how to configure input validation, assuming that you have enabled it.

    Customizing Security Error Messages

    When input validation blocks input that violates a security rule, the server displays a generic error. By default, security messages are intentionally generic to avoid alerting potential attackers to security errors.

    We highly recommend that external deployments customize the security error messages to be unique, yet still generic. You can change both the message and the error number. Choose any combination of numbers or letters so administrators can easily search the logs to detect security violations.

    Input Validation Messages

    Configuration File





    An error has occurred. Please contact your system administrator. (5321)<default>

    If you translate your application into other languages, be sure to create a locale-specific copy of this file and translate these messages as well.

    Understanding Input Validation

    Input validation has rules and regular expressions to determine what input is allowed when users submit information to the server on a UI page. Each input, field, or parameter has its own rule so that it can be verified according to the expected input.

    An input validation rule names the UI field and a regular expression that is applied to its value. Input validation rules are defined in the following file:

    Input Validation Rules

    Configuration File






    Each input validation rule has the following format:



    <parameter> is the HTML name of the field being submitted.
    <nameValidator> determines what characters are allowed in the parameter name.
    [!]<valueValidator> determines what characters are allowed [or not] for the input value.
    <charLimit> is the maximum length allowed for the parameter name and the input value (one limit applies to both separately).
    <blankAllowed> determines whether the value can be blank.
    <parameter>-<context> is the string that appears in the log if this rule is broken.

    The validators are regular expressions defined in the following file. Although one validator can be used in several rules, each validation rule should be as specific as possible to the allowable input.

    Validator Expressions

    Configuration File






    The validators are Java-based regular expressions that specify characters allowed (whitelist) or forbidden (blacklist), depending on how they're used in a validation rule. Each validator definition has the following format:


    Customizing Rules and Expressions

    The predefined input validation rules in JasperReports Server are designed to allow all data and normal user input, while blocking potential attacks on the server. If your data or your user input causes security errors (false positives), you may choose to modify the input validation rules to allow your input. Also, if you customize JasperReports Server to accept new input parameters, you must add the corresponding input validation rules to maintain server security.

    To add or modify input validation rules and expressions:

    1. Make a backup copy of the file .../WEB-INF/classes/esapi/security.properties, then open it for editing.
    2. If you added a parameter to the UI, copy the rule for a similar parameter. If you have false positive errors, locate the rule by its parameter name or context string in your log file.
    3. Modify the rule to allow your input:
    a. Usually, you need to change the second validator to one that allows your input characters. Select a value validator from the file .../WEB-INF/classes/esapi/validation.properties that allows your input, or create one as described in the next step.
    b. If your input is atypically long, increase the character limit.
    c. Do not change any other part of the rule.
    4. If you want to create a new validator expression:


    Do not modify the default validator expressions provided with the server. We have thoroughly tested these expressions to provide reasonable input validation security while allowing for the general use of the application. Also, a validator can be used in several input validation rules, so modifying them may have unintended consequences. You should always create new validators with new names.

    a. Make a backup copy of the file .../WEB-INF/classes/esapi/validation.properties, then open it for editing.
    b. Copy an existing validator, then give the copy a new name and expression, for example:


    c. Remember to use double backslashes () in properties files for single backslashes in the expression. You should also use the p{} syntax to match international letters and their accent marks.
    5. Save the files, and restart the server or redeploy its web application.


    Try to keep the character limit as close to the expected value as possible.
    Try to use a validator as close to the expected values as possible. If a parameter's value is expected to be numbers only, use the Numeric validator.
    Most validators are whitelists that specify allowed character patterns. A validator may be preceded by an exclamation point (!) to indicate that everything but those values is permitted. When used with a validator that matches characters or words, this syntax implements a blacklist. Some rules are easier to define as whitelists, others as blacklists.
    If a parameter can have radically different values or the same parameter is used in different situations, you can apply more than one rule to that parameter. To do this, simply copy a parameter rule and add incremental integers to the parameter name. For example:


    Updated to:





    With multiple rules for the same parameter, each rule is applied in the order listed until one passes (equivalent to a logical OR). If they all fail, the input is blocked and the user is notified with the generic error message. The rules that fail still appear as security warnings in the logs. Use numbering in the context names, as shown above, to easily identify these false-positive messages. When using multiple rules, define the most used rule or the most permissive rule first to optimize validation and reduce false-positive log messages.

    Further Configuration

    The configuration files contain some miscellaneous default settings for the input validation. In particular they define default action for input that has no validation rules. Changing these defaults is possible but not recommended:

    Advanced Input Validation

    Configuration File



    Default Value



    SECURITY for [%s] is OFF

    If security is turned OFF, this message will be logged. This message in the logs can alert administrators if the security configuration has been tampered with.


    No rule for parameter [%s]. Using
    default validation on input=[%s].

    If a request parameter is not previously known, this message is logged.


    Security configuration [%s]
    cannot be loaded.

    If there is an error in the security configuration files, this message is logged. This is a severe error and should be resolved by the administrator.

    Configuration File



    Default Value




    If an input parameter has no defined validation rule, this rule is applied. The validator for values, AlphaNumPunctuation-Brackets is fairly permissive, and can be changed to something more restrictive. The DEFAULT property name is a keyword and should never be changed.

    User Feedback

    Recommended Comments

    There are no comments to display.

    This is now closed for further comments

  • Create New...