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.

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.

More on 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.

Find the Input Validation Filter feature at Administrator Panel > Security > Input Validation Filter.

Default ruleset

Blackboard Learn uses the default ruleset to 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.

Learn more about attributes and descriptions

Go to Administrator Panel > Security > Input Validation Filter and 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

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.

Create a custom ruleset

  1. On the Administrator Panel, under Security, select Input Validation Filter.
  2. Select Custom Ruleset.
  3. 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.
  4. 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.
  5. Go to the Custom Ruleset page and select 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 copy of any custom rulesets.
  • If the Input Validation Filter Building Block is removed 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.

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.