Jump to content
We've recently updated our Privacy Statement, available here ×
  • This documentation is an older version of JasperReports Server Security Guide. View the latest documentation.

    To block potential security threats like cross-site scripting and SQL injection, the security framework validates all user input and values passed to reports. Input validation prevents input with dangerous side-effects like malicious scripts and queries.

    As of JasperReports Server 6.1, input validation has been superseded by output escaping, a more effective mechanism. The input validation mechanism is still used for validating SQL queries.

    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 your business data contains tags, you need to update the security configuration to allow them.
    SQL queries should start with SELECT and have no comments. Multiple queries separated by semi-colons (;) are also prohibited. If your reports or Domains have such queries, you need to either change them or update the security configuration to allow them.

    If users see recurring errors, 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 the security framework to modify security rules or turn off the security restrictions, based on their perceived threat level.


    Input validation rules were added to comply with security guidelines for web applications. Turning off input validation or modifying the validation rules may make the server more vulnerable to web attacks.

    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 security 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

    As of JasperReports Server 6.1, only SQL query validation is enabled by default when installing JasperReports Server. The input validation mechanism is still available, and you can enable it if needed. To turn off one or more of the protection features:

    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.


    true <default>


    Turns SQL query validation on or off in the server. Any other value besides case-insensitive “false” is equivalent to true.

    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>


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

    Set these properties to messages and error codes that match the rest of your application. The goal is to display a message that attackers will not recognize as a security error, yet one that administrators can uniquely identify in the logs.

    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.

    Editing Input Validation Rules

    Input validation rules determine what input is allowed when users send information to the server. This information generally consists of parameter-value pairs, for example the fields of an input form. For each known parameter-value pair, an input validation rule determines:

    What characters are allowed in the parameter name.
    What characters are allowed for the input value.
    The maximum length allowed for the parameter name and the input value (one limit applies to both separately).
    Whether the value can be blank.

    Allowed characters are determined by a regular expression called a validator. Validators are named regular expressions that can be used in any number of input validation rules. Although one validator can be used in several rules, each validation rule should be as specific as possible to the allowable input.

    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.

    1. Locate the "SECURITY FAILURE" message in your logs. For more information about logs, see "Configuring System Logs" in the JasperReports Server Administrator Guide. The log message contains the name of the parameter and context where the parameter was used.
    2. Make a backup copy of the file <js-webapp>/WEB-INF/classes/esapi/security.properties, then open it for editing.
    3. Locate the parameter name and context. For example, this is the input validation rule for the entities parameter on the Manage Roles page:


    The input validation rule has the following format:


    4. Modify the rule to allow your input:
    a. Usually, you need to change the value validator to one that allows your input characters. Select a value validator from the file <js-webapp>/WEB-INF/classes/esapi/validation.properties that allows your input, or create one as described in the next section.
    b. If your input is atypically long, increase the character limit.
    c. Do not change any other part of the rule.
    5. Save your changes and redeploy the JasperReports Server webapp, or restart your application server.


    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.

    Creating Validator Expressions

    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.


    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.

    1. Make a backup copy of the file <js-webapp>/WEB-INF/classes/esapi/validation.properties, then open it for editing.
    2. Locate the validator used in the input validation rule you want to modify, for example the Alpha validator expression allows for any letters in any language:


    3. Copy the entire rule on a new line and give it a new name with the following format:


    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, for example:


    4. Use the new value validator name in your input validation rule, as described in the previous procedure.
    5. Save your changes and redeploy the JasperReports Server webapp, or restart your application server.

    Validating New Input Parameters

    If you customize JasperReports Server to accept new input parameters, you must add the corresponding input validation rules to maintain server security.

    1. Make a backup copy of the file *<js-webapp>/WEB-INF/classes/esapi/security.properties*, then open it for editing.
    2. Create a new input validation rule in the following format:


    The context is the string that will appear in the log when a security validation error occurs, so make sure it contains the exact parameter name.

    3. Look at existing rules in the file <js-webapp>/WEB-INF/classes/esapi/validation.properties to find validators for the parameter name and value that allow your new input. If necessary, create new validator expressions as described in the previous procedure.
    4. Save your changes and redeploy the JasperReports Server web app, or restart your application server.

    Query Validation

    Query validation is a special case of input validation, where the server ensures that all queries being issued by the server meet a preset pattern for a safe query. When query validation is enabled, all queries in reports and Domains use the following validator:


    As a result:

    SQL comments are forbidden.
    Ensure that you have only one executable query statement per query. Multiple queries separated by semi-colons (;) will be rejected. The following example will cause a security error:

    SELECT f1,f2 FROM tbl_1 WHERE f1=f2; SELCT f3 from tbl_2;

    Queries for reports must retrieve data only, in other words, use only the SELECT statement. The following statements are forbidden:


    If you want to use stored procedures, you must add the following validator to the file <js-webapp>/WEB-INF/classes/esapi/validation.properties:


    And then modify the validation rule for the corresponding parameter or field where you want to allow stored procedure calls. If you want to allow stored procedure calls in addition to select statements, specify multiple validation rules as shown in section Editing Input Validation Rules.

    When SQL validation fails, the logs contain the message described in Customizing Security Error Messages, such as the following:

    2011-11-21 13:54:28,007 ERROR ValidatorImpl,"http-bio-8090"-exec-12:48 - An error has occurred. Please contact your system administrator. (6632)

    org.owasp.esapi.errors.ValidationException: SQL_Query_Executor_context: Invalid input. Please conform to regex ^s*((?i)select)s+[^;]+$ with a maximum length of 50000

    Further Configuration

    The configuration files contain some miscellaneous default settings for the security framework. 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...