The Input Validation Filter acts as a first line of defense with configurable rules to protect Blackboard Learn. It is, in a sense, like a firewall for Blackboard Learn. It verifies that user requests coming in are safe by sanitizing the data through a default ruleset. An advantage of the Input Validation Filter is speed. This feature provides you with cross-site scripting fixes much faster than the traditional patching process. Traditional patches can have various dependency issues or may need to be rolled back. Providing fixes through the Input Validation Filter is a much cleaner and faster way of delivering patches, as they are provided directly through the Software Updates Center.
A single Blackboard Learn instance can process many application HTTP requests daily (such as submit assignment, save assignment, log in to the system, log out of the system, and so on). For each request, Blackboard Learn is responsible for verifying that the code processing these requests contains the correct values. Through rulesets, the Input Validation Filter outlines a series of well-defined data fields within Blackboard Learn (for example, the Course ID field) and explicitly lists criteria and patterns that are acceptable entries for each field. These are defined in the default ruleset. If data entered does not match the rule criteria, the system reacts to this according to the value set up for the "on-fail" attribute. To learn more about this attribute, see Attributes and Descriptions.
The default ruleset is not modifiable, but you can create a custom ruleset based on the default ruleset to protect proprietary or third-party Building Blocks. You can view the default ruleset to see the rules that are protecting your system. You can view parameters for various Blackboard Learn pages, the values allowed for these, and what happens if constraints fail to be met. Custom rulesets allow you to define which Building Blocks to apply the filter to on their system and quickly resolve security issues without having to wait for a new version of the affected Building Block.
Access input validation filter
The Input Validation Filter is installed and enabled by default for Blackboard Learn Release 9.1 Service Pack 10 and later.
Access the Input Validation Filter feature on the Administrator Panel. Select Security > Input Validation Filter.
Default ruleset
Blackboard Learn uses the default ruleset to more quickly resolve security issues. The default ruleset defines restrictions for what parameters and data types are required for a given path in various Blackboard Learn pages. It also defines how the system will react if incorrect value types are entered. For example, a student is entering a course ID. According to the rule, course IDs must contain only numeric characters, but a student maliciously manipulates the request to send in an alphanumeric value or a script. The way in which Blackboard Learn reacts to this malicious input is defined in the rule's "on-fail" attribute. To learn more about this attribute, see Attributes and Descriptions.
Select Default Ruleset. From here, you can:
- Select Download Ruleset (xml) to download and view the default ruleset. Use this as a model for creating a custom ruleset.
- Select Download Schema (xsd) to download the schema definition for the default ruleset. This defines the format required for creating a custom ruleset.
- View the date at the top of the Default Ruleset page. This tells you when the default ruleset was last updated in the system.
Rules in the default ruleset have been developed based on the following standards. You must develop a custom ruleset based on these standards as well for custom rules to be processed by the system.
Required and optional rule attributes
| Required vs. Optional | Format |
|---|---|
| Required attributes | <rule path="..." parameter="..."/> |
| Optional (but desired) attributes | <rule path="..." parameter="..." constraint="..." on-fail="..."/>
or: <rule path="..." parameter="..." constraint-name="..." on-fail="..."/> |
| Optional attributes | <rule path="..." parameter="..." constraint="..." on-fail="..." min-version="..." max-version="..."/>
or: <rule path="..." parameter="..." constraint-name="..." on-fail="..." min-version="..." max-version="..."/> |
Attributes and descriptions
Custom rulesets are optional. You can create a custom ruleset based on the default ruleset to add protections to proprietary or third-party Building Blocks or to override a rule in the default ruleset by leveraging the rule prioritization capability.
Custom rulesets allow you to define which Building Blocks to apply the filter to on your system and solve issues specific to your system or in advance of a solution from Blackboard. If you decide to create a custom ruleset, it runs in tandem with the default ruleset.
Creating a custom ruleset
To create a custom ruleset:
- On the Administrator Panel, under Security, select Input Validation Filter.
- Select Custom Ruleset.
- Select Download Ruleset (xml) to save the default ruleset to your local system. You can modify this as needed, and use it as a springboard for creating your custom ruleset.
- Select Download Schema (xsd) to save the schema, using this as a guide for how to format rules in your custom ruleset. To learn more, see default ruleset.
- Go to the Custom Ruleset page and select Upload to browse to and upload your new custom ruleset.
- After you have uploaded your custom ruleset, three new options appear:
- Replace Allows you to replace an active custom ruleset and upload a new one. This option takes you to the Upload Custom Ruleset page.
- Delete: Allows you to delete your custom ruleset.
- Download: Allows you to save your custom ruleset to your local system and continue editing it.
Custom ruleset preservation
- Administrators must maintain a separate backup copy of any custom rulesets.
- If the Input Validation Filter Building Block is deleted and then reinstalled, custom rulesets are not retained.
- If the Input Validation Filter Building Block is updated, the existing custom ruleset is retained and remains active.
Rule priority
A rule conflict is defined as two rules that have the same values for the path and parameter attribute. The default ruleset and the custom ruleset run in tandem. Therefore, in the event of a rule conflict between rulesets, rule priority is given to a custom ruleset over the default ruleset. If a custom rule and a default rule are both defined for the same path attribute and parameter attribute, then the rule declared last, regardless of other attributes like "on-fail," will be the active one.
Conflicts are considered extremely rare and would only be introduced by a custom ruleset. To avoid a conflict and match how you expect the system to perform, ensure that the custom rule's path and parameter attribute are not the same as another rule in the default ruleset or the custom ruleset. Alternatively, to leverage the use of rule priorities and conflicts, define a rule in the custom ruleset to override the behavior in a default ruleset.
No system warning will occur if a conflict is defined because it will use a rule closer to the bottom of the file.
| Scenario | System Action |
|---|---|
| If a rule in the custom ruleset conflicts with a rule in the custom ruleset... |
|
| If a rule in the custom ruleset conflicts with a rule in the default ruleset... |
|
Understanding the log file
Blackboard recommends that you monitor activity related to this security control. You can monitor activity related to the default and custom rulesets by looking at the following log file:
Blackboard_Home/logs/bb-input-validation-filter-log.txt
By viewing this log, you can monitor any rule violations that have occurred on your system.
Event types
The following table describes the event types logged.
A severity of 0 is informational, 2 is a low alert, and 8 is a high alert.
| Event Code | Severity | Definition |
|---|---|---|
| 18 | 0 | Input Validation Filter Building Block Configuration File Update Succeeded.
This relates to uploading a custom ruleset. |
| 18 | 6 | Input Validation Filter Building Block Configuration File Update Failed.
This relates to uploading a custom ruleset. |
| 19 | 2 | Input Validation Filter Building Block Rule Violation Detected and Logged.
This indicates suspicious activity. |
| 20 | 6 | Input Validation Filter Building Block Rule Violation Detected and HTML Escaped.
This indicates suspicious activity. |
| 21 | 6 | Input Validation Filter Building Block Rule Violation Detected and Safe HTML Filtered.
This indicates suspicious activity. |
| 22 | 8 | Input Validation Filter Building Block Rule Violation Detected and Exception Thrown.
This indicates suspicious activity. |
Log format
The log format is key value pairs. These are delimited by "|".
Log field list
The log file contains 24 fields.
| Field # | Field | Sample Value | Description |
|---|---|---|---|
| 1 | Event time | timestamp=MMM dd yyyy HH:mm:ss.SSS zzz | |
| 2 | Vendor, Company | app_vend=blackboard | |
| 3 | Product Name | app_name=learn | |
| 4 | Product Version | app_ver=9.1.80000.0 | |
| 5 | Event Code | evt_code=18 | Possible values:
|
| 6 | Event Name | evt_name=rule violated | Possible values:
|
| 7 | Event Severity | sev=0 | Possible values:
|
| 8 | Event Category | cat=input validation | |
| 9 | Event Destination Host | dhost=blackboard.myschool.edu | |
| 10 | Event Outcome | outcome=successful|failure | Possible values:
|
| 11 | Event Client IP Address | src_ip=10.1.1.1 | |
| 12 | Event Source User ID | suid=_1_1 | |
| 13 | Event Source Username | suser=administrator | |
| 14 | Event Source Session ID | session_id=## | Note: This is not the session ID value that is usually stored in a cookie for session management. This is an alternate representation of the value that corresponds to the values in the BBLEARN.SESSIONS database table. |
| 15 | Event Message | msg=rule violated and logged | Possible values:
|
| 16 | Event Client Browser User Agent | http_useragent=Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/534.30 (KHTML, like Gecko) Chrome/12.0.742.91 Safari/534.30 | |
| 17 | Action Taken | act=htmlescape|exception|safehtml|log |
Possible values:
|
| 18 | Rule Path | rpath=/some/random/path | |
| 19 | Rule Parameter | rparam=course_type | |
| 20 | Constraint | cs=m/(Org|Course)/ | |
| 21 | Constraint Name | csn=validId | |
| 22 | Event Request URL | request=/some/random/path | |
| 23 | Event Request Parameter Value | requestval=gibberish | |
| 24 | Event Sanitized Parameter Value | cleanval= |
