Smarter by Design.Simpler for Business
TR7Enterprise Application Delivery & Security Platform
How do I add my own custom rule (regex)?
Short answer
For all vServices, Add is clicked on the Signature & Rule Library screen; for a single vService only, it is clicked on the OWASP Rules screen of that vService. In the Add Custom Rule window, a Name unique within the layer, an optional Description, State (default Enabled), Score (default Medium), Inspection Scopes (default Path; at least one scope) and Pattern (Regex) are entered. While the pattern is being typed, it is compiled in the signature engine on the device and the result appears below the field; with the trial icon on the right of the field, it is tried on sample inputs without saving. When Accept is clicked, the pattern is compiled again; if it cannot be compiled or the name is used in the same layer, the save is rejected and the window stays open. The rule ID is assigned automatically (1,000,000–4,999,999 in global rules, 5,000,000–9,999,999 in vService-specific rules), the rule is written to the Custom Rules category and is applied without a separate deployment step.
Problem: An Application-Specific Pattern Is Not in the Library
An application-specific request pattern (e.g. attempts to call a closed management path, or an attack form specific to the application's own parameters) is not caught by the built-in signatures; a signature needs to be defined with a self-written regular expression.
Solution: Two Methods
The two methods use the same form; the difference is the layer the rule is written to.
| Your situation | Suitable method |
|---|---|
| The rule should run on all vServices with WAF protection on | Method 1: Global custom rule |
| The rule should run on a single vService only | Method 2: vService-specific rule |
Method 1: Global Custom Rule Recommended
- How it works The rule is written to the global layer and enters the inspection of every vService with WAF protection on. A vService can change the state of this rule for itself only, with Change State on its own OWASP Rules screen.
- Where it is opened Configuration Menu → WAF → Signature & Rule Library → Add
- Requirement WAF license; full permission in the WAF area
- Scope Device-wide
Step-by-Step Configuration
1
Adım 1 Open the library screen
The Configuration Menu is opened with the TR7 logo at the bottom left and WAF → Signature & Rule Library is clicked (how to access).
2
Adım 2 Open the add form
Add on the toolbar is clicked; the Add Custom Rule window opens.
3
Adım 3 Enter the name and the description
The name of the rule is written in the Name field (e.g. Legacy admin path); the name is required and must be unique in the same layer. Description is optional; it appears in the list and in the preview.
4
Adım 4 Select the state and the score
State comes as Enabled by default; to try the rule in production without blocking, Monitor is selected. Score comes as Medium by default; at the default Very tight protection level, Medium and above reach the threshold with a single hit (Can I change a signature's score (Low / Medium / High / Very High)?).
5
Adım 5 Select the scopes
In the Inspection Scopes list, the sections in which the pattern will be searched for are checked: Path, Query, Header, Form, JSON, XML, Raw. By default, Path is checked; at least one scope must remain. The switch at the beginning of the list checks or unchecks all the scopes together (What is the "Inspection Scopes" field for when adding a custom rule?).
6
Adım 6 Write the pattern
The pattern is written in the Pattern (Regex) field; as an example, a pattern that catches calls to a closed management path in the Path scope:
text
^/legacy-admin(/|$)During typing, after a short wait, Compiled by the signature engine and the size of the compiled signature, or the error text of the engine, appear below the field. The WAF badge on the right of the field states that the pattern will run in the signature engine. The pattern is case-sensitive and can be at most 4,096 characters; the supported syntax: Which regex syntax is supported in custom rules (backreference, lookaround); can I test a rule before saving it?
7
Adım 7 Try the pattern
The trial (flask) icon on the right of the field is clicked and a sample input is written. For the pattern above, Matches this input appears for the /legacy-admin/users input, and No match for the /legacy-administrator and /Legacy-Admin inputs.
8
Adım 8 Save
Accept is clicked; while there is an unresolved error in the form, the button is disabled. The device compiles the pattern again during the save: if it cannot be compiled, the Invalid WAF pattern error appears, and if the name is used in the same layer, the Custom rule name "…" already exists error appears, and the window stays open. On a successful save, the rule is applied without a separate deployment step; in a cluster setup, it is also sent to the peer device with the default auto-sync, and if Manual Sync Mode is on, it is sent to the peer device manually. The signature database is compiled separately on each device.
Verification
1ListTR7 side
The list shows the global custom rules after the built-in signatures; the new row is colored in a green tone and written in italic, and the day it was added appears in the Date column.
Expected
ID 1,000,000–4,999,999 · Type Custom2Matching requestClient side
While the host group is in Blocking mode, a request that matches the pattern is sent; if Monitor was selected for State, the request passes and a record is created in Event Logs.
Command: curl -sI https://www.example.com/legacy-admin/
Expected
Enabled + Medium (Very tight): blocking response · Monitor: normal response and an Event Logs recordMethod 2: vService-Specific Rule
- How it works The rule is written only to the layer of this vService; it is not listed in Signature & Rule Library or on the OWASP Rules screen of other vServices.
- Where it is opened Left Monitor Panel → WAF-Protected vServices → vService → WAF Management → the OWASP Rules link in the signature summary strip → Add
- Requirement WAF protection on for the vService; modify permission in the WAF area
- vService type HTTP
Step-by-Step Configuration
1
Adım 1 Open the WAF screen of the vService
In the Left Monitor Panel, the WAF-Protected vServices tab is selected and the vService is clicked.
2
Adım 2 Open the OWASP Rules screen
On the WAF Management tab, the OWASP Rules → link at the bottom right of the signature summary strip is clicked; the OWASP Rules tab opens (how to access).
3
Adım 3 Open the add form
Add on the toolbar is clicked; the Add Custom Rule window opens.
4
Adım 4 Fill in the form
The Name, Description, State, Score, Inspection Scopes and Pattern (Regex) fields are filled in as in steps 3–7 of Method 1, and the pattern is tried. The name must be unique only among the rules of this vService.
5
Adım 5 Save
Accept is clicked; only the rule set of this vService is compiled again, and the inspection of the other vServices is not affected.
Verification
1ListTR7 side
The ID of the new row at the end of the OWASP Rules list is examined; this rule does not appear in Signature & Rule Library.
Expected
ID 5,000,000–9,999,999Common Mistakes
- Selecting a wider scope than necessary. The pattern is scanned separately in every selected section; in the sections where it is not meaningful, false positives and the inspection cost increase.
- Taking the new rule into production directly with Enabled. First, the hits are monitored in the Monitor state (How do I try a new signature in production without risk (Monitor state)?).
- Forgetting the uppercase/lowercase variants. There is no case-insensitivity option in the form; the variants are written in the pattern with a character set (e.g.
[Ll]egacy). - Using lookaround or backreferences. The signature engine does not compile these structures; the pattern cannot be saved.
- Trying to move signatures with the page type Import. Import on the Page Types screen moves only page types; custom signature rules do not go into this file, and there is no signature library command in WEB-CLI.
How it is done in the documentation
