Configuring Input Validation

To block potential security threats such as cross-site scripting and SQL injection, the security framework has a powerful mechanism to validate all user input and values passed to reports. Input validation prevents values with dangerous side-effects such as malicious scripts and queries. Administrators can monitor the server logs to search for evidence of attempted security breaches.

However, input that was allowed in previous version of the server may be blocked, and users may see errors when entering values. In particular:

Parameter names and values cannot 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 cannot have 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 is 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 a complex mechanism that is 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 section UTF-8 Configuration.

Input validation is enabled by default when installing JasperReports Server. To turn off one or more of the protection features:

Input Validation

Configuration File






true <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 an error. By default, the security messages are intentionally generic so that potential attackers are not aware that they have triggered a security error.

Jaspersoft highly recommends 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 that 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 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.

Configuring 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 defines the following:

What characters are allowed in the parameter name.
What characters are allowed in the input value.
The maximum allowable length for the parameter name and the input value (the same 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. Even though validators can be used in several rules, each validation rule should be as specific as possible to the allowable input.

Editing Input Validation Rules

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 that was created by the security error. For more information about logs, see Configuring System Logs. 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/, 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/ that allows your input, or create one as described in the next section.
b. If your input is untypically 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 that is as close to the expected values as possible. If a parameter's value is expected to be numbers only, then use the Numeric validator.
Most validators are whitelists that specify character patterns that are allowed. A validator may be preceded by an exclamation mark (!) to indicate that everything but those values are 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, then 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, then 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 the validation and reduce false-positive log messages.

Creating Validator Expressions

The validators are Java-based regular expressions that specify which characters are allowed (whitelist) or forbidden (blacklist), depending on how it is used in a validation rule.

Do not modify the default validator expressions provided with the server. These expressions have been thoroughly tested by Jaspersoft 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/, 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 in order to maintain server security.

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


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

3. Look at existing rules in the file <js-webapp>/WEB-INF/classes/esapi/ 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 webapp, 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, only use 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/


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 section 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 does not have any defined validation rule, this validation 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.