Skip to main content
pdf?stylesheet=default
Blackboard Help

Input Validation Filter

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.

Accessing 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.

Click 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.

Click Default Ruleset. From here, you can:

  • Click Download Ruleset (xml) to download and view the default ruleset. Use this as a model for creating a custom ruleset.
  • Click 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

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:

  1. On the Administrator Panel, under Security, click Input Validation Filter.
  2. Click Custom Ruleset.
  3. Click 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.
  4. Click 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.
  5. Go to the Custom Ruleset page and click Upload to browse to and upload your new custom ruleset.
  6. After you have uploaded your custom ruleset, three new options appear:
    1. Replace Allows you to replace an active custom ruleset and upload a new one. This option takes you to the Upload Custom Ruleset page.
    2. Delete: Allows you to delete your custom ruleset.
    3. 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 coy 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 tthat 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.

Note:  No system warning will occur if a conflict is defined because it will use a rule closer to the bottom of the file.

Conflict Scenarios
Scenario System Action
If a rule in the custom ruleset conflicts with a rule in the custom ruleset...
  • The conflicting rule closer to the bottom of the file is used.
  • The conflicting rule in the custom ruleset, above the other conflicting rule in the custom ruleset, is ignored.
If a rule in the custom ruleset conflicts with a rule in the default ruleset...
  • The conflicting rule in the custom ruleset is used.
  • The conflicting rule in the default ruleset is ignored.

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

Teh following table describes the event types logged.

Note:  A severity of 0 is informational, 2 is a low alert, and 8 is a high alert.

Event Types
Event Code Severity Definition
18 0 Input Validation Filter Building Block Configuration File Update Succeeded.

Note:  This relates to uploading a custom ruleset.

18 6 Input Validation Filter Building Block Configuration File Update Failed.

Note:  This relates to uploading a custom ruleset.

19 2 Input Validation Filter Building Block Rule Violation Detected and Logged.

Note:  This indicates suspicious activity.

20 6 Input Validation Filter Building Block Rule Violation Detected and HTML Escaped.

Note:  This indicates suspicious activity.

21 6 Input Validation Filter Building Block Rule Violation Detected and Safe HTML Filtered.

Note:  This indicates suspicious activity.

22 8 Input Validation Filter Building Block Rule Violation Detected and Exception Thrown.

Note:  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.

Log 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:
  • 18
  • 19
  • 20
  • 21
  • 22
6 Event Name evt_name=rule violated Possible values:
  • rule update succeeded
  • rule update failed
  • rule violated and html escaped
  • rule violated and safe html filtered
  • rule violated and logged
  • rule violated and exception thrown
7 Event Severity sev=0 Possible values:
  • 0
  • 2
  • 6
  • <li">8
8 Event Category cat=input validation  
9 Event Destination Host dhost=blackboard.myschool.edu  
10 Event Outcome outcome=successful|failure Possible values:
  • success
  • failure
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:
  • rule update succeeded
  • rule update failed
  • rule violated and html escaped
  • rule violated and safe HTML filtered
  • rule violated and logged
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:

  • htmlescape
  • exception
  • safehtml
  • log
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=