How should I include the WAF in my application release process?

Short answer

Because the WAF rule set holds the expected request format of the application, every release is also a change for the WAF; steps are added to the release process in three stages (recommended life cycle). Before the release: the rule set of the host group is backed up with Export on the Page Types screen; if the API definition has changed, the new endpoints are added with Import (OpenAPI); the test team browses the new release with the Teacher identity (the TR7-LEARN header or cookie value, or Teacher IP), or browses it with the Conditional Learning identity and then Analysis & Learning is run with Combine with Old Rules selected. During the release: for big changes, the WAF Mode value of the related host group is temporarily set to Monitor Mode; this step can be tied to the release script with the waf host-groups update command in WEB-CLI. After the release: the false positives that fall on the new paths in Event Logs are taught with Allow / Teach, a wrong learning is undone with Revert Learning on the Log tab of the vService, and when the records are cleaned up, the group is set to Blocking Mode again. Teacher and Conditional learning are meaningful only in groups in Monitor or Blocking mode; the applying of Analysis & Learning cannot be undone, so the Export backup is always the first step.

Problem: New Pages Are Blocked After Every Release

The rule set knows the pages, parameters and value limits of the previous release. When a new screen, endpoint or parameter is added, these requests fall to the Any paths rule because they do not match any page type, or they get caught on the learned limits; if the host group is in Blocking mode, users are blocked right after the release. For the diagnosis of the symptom: New pages are blocked after I released a new version; what should I do?

Place in the Process

Stage	Step	Method
Before the release	Back up the rule set	Method 1, steps 1–2
Before the release	If the API definition has changed, add the new endpoints	Method 2
Before the release	Teach the browsing of the test team	Method 1 with Teacher, or Method 3 with Conditional learning and analysis
During the release	Set the host group temporarily to Monitor mode	Method 4, or Method 5 with WEB-CLI
After the release	Teach the false positives, undo if needed, return to Blocking mode	Method 6

If a new domain name goes into production, a separate host group is opened with Learning mode for that domain name and it learns its own rule set: How is a Host Group added; what goes into the Virtual Host Patterns field?

Solution: Six Methods

The methods are not alternatives to each other; they are used together according to the stage of the release. To teach the test browsing, Teacher (Method 1) or Conditional learning (Method 3) is selected: the difference between the two is on the What is the difference between Conditional Learning and Teacher; when should I use which? page.

Your situation	Suitable method
The test team will browse the new release; the triggered false positives should be taught automatically	Method 1: Teacher
I have the OpenAPI definition of the new release	Method 2: Import (OpenAPI)
The page types for the new screens should be produced from the browsing	Method 3: Conditional learning + Analysis & Learning
The release is done manually; I don't want blocking during the transition	Method 4: Temporary Monitor mode from the interface
The release is done with a script or a pipeline	Method 5: Temporary Monitor mode with WEB-CLI
The release is complete; there are false positives in the records	Method 6: Event Logs → Allow / Teach

Method 1: Teacher Recommended

• How it works Requests that carry the Teacher identity are not blocked whatever their scores are (a request whose scan exceeds the time limit is also passed); the violations they trigger are taught to the rule set at the interval selected with Teaching Frequency. In this way, the rule set is updated while the test team browses the new release, and the protection continues for the other users.
• Where it is opened Left Monitor Panel → WAF-Protected vServices → vService → WAF Management → Learning Methods card
• Requirement Modify permission in the WAF area · the host group in Monitor or Blocking mode (in a group in Learning mode and in a request that carries the Conditional learning identity, the learning record takes priority and no Teacher record is created)
• vService type HTTP
• Identity The header or cookie name is always TR7-LEARN; the value is written in the field on the form. IPv4 addresses or blocks separated by spaces are entered in the Teacher IP field.

Step-by-Step Configuration

1

Adım 1 Open the Page Types screen

On the WAF Management tab, the N page types link on the mode card of the host group is clicked; the Page Types tab of the group opens.

2

Adım 2 Back up the rule set

Export on the toolbar is clicked; the rule set of the group is downloaded as a JSON file. If there are multiple host groups, it is repeated for every group (Can I back up my WAF rules?).

3

Adım 3 Open the Learning Methods window

On the WAF Management tab, the pencil icon (Edit) of the Learning Methods card is clicked (Learning methods Edit screen).

4

Adım 4 Define the Teacher identity

The Teacher switch is turned on; the identity of the test team is entered in the Teacher Header, Teacher Cookie or Teacher IP field. From the Teaching frequency list, 1 minutes, 2 minutes, 5 minutes, 30 minutes or 1 hours is selected; its default value is None, and while None is selected, the Teacher records do not turn into rules (What should the name of the Teacher Header or cookie be (TR7-LEARN); which name is used for Conditional Learning (TR7-ANALYZE)?).

5

Adım 5 Save

The Edit button at the bottom of the window is clicked; the setting is applied without a separate deployment step. In a cluster setup, the change is also sent to the peer device with the default auto-sync; if Manual Sync Mode is on, it is sent with Synchronize. The test team browses the new release, for example by adding the TR7-LEARN: <value> header to every request. When the release is finished, Teacher is turned off in the same window and saved with Edit.

Verification

1Teacher historyTR7 side

On the Teacher Tracking tab of the vService, the Teacher history view is selected.

ExpectedLearning rows for the new paths browsed

Requests that come with the Teacher identity and exceed the threshold appear in Event Logs with the "Not blocked — Teacher header matched" (or Teacher cookie, Teacher IP) decision, according to the identity that recognized them.

Method 2: Import (OpenAPI)

• How it works Every path in the OpenAPI 3.0 or Swagger 2.0 file is converted into a page type and merged with the existing rule set: the rules that are not in the document are not touched, and a rule with the same path as a path in the document is fully replaced with the rule derived from the document (converting the document to rules).
• Where it is openedWAF Management → the mode card of the host group → N page types → Import (OpenAPI)
• Requirement The API definition of the new release with the .json, .yaml or .yml extension; modify permission in the WAF area
• vService type HTTP

Step-by-Step Configuration

1

Adım 1 Back up the rule set

With steps 1–2 of Method 1, Export is done for the rule set of the group. Because the manually made and learned settings in the rules with the same path will change in the import, this file is the way back.

2

Adım 2 Select the definition file

Import (OpenAPI) on the Page types toolbar is clicked and the definition file is selected in the file picker that opens.

3

Adım 3 Confirm

The "Are you sure?" question is confirmed with Yes. At the end of the operation, a notification appears that summarizes how many paths were applied and the conversion warnings, if any; the rules are applied without a separate deployment step and are synchronized in a cluster as in Method 1. Details: Can I generate API protection rules automatically from my OpenAPI definition?

Verification

1Page typesTR7 side

The new endpoints are looked for in the Page types list; paths with template parameters such as {id} appear with the * glob.

ExpectedOpenAPI import: N path applied

Method 3: Conditional Learning + Analysis & Learning

• How it works Requests that carry the Conditional Learning identity are written to the learning record without being blocked, even if the group is in Blocking mode (a request whose scan exceeds the time limit is also not blocked, but it is not written to the learning record). After the browsing is finished, Analysis & Learning produces page types from these records; when Combine with old rules is selected, the existing rules are kept and the new pages are added (What is the difference between "Create New Rules" and "Combine with Old Rules" in the analysis?).
• Where it is openedWAF Management → Learning Methods card; the Analysis & Learning row on the mode card of the host group
• Requirement Modify permission in the WAF area. The applying of an analysis cannot be undone with Revert learning; the Export backup must have been taken beforehand.
• vService type HTTP
• Identity The header or cookie name is always TR7-ANALYZE; the value is written in the field on the form.

Step-by-Step Configuration

1

Adım 1 Back up the rule set

With steps 1–2 of Method 1, Export is done for the rule set of the group.

2

Adım 2 Open the Learning Methods window

The pencil icon (Edit) of the Learning Methods card is clicked.

3

Adım 3 Define the Conditional learning identity

The Conditional Learning switch is turned on; the identity of the test team is entered in the Conditional Learning Header, Conditional Learning Cookie or Conditional Learning IP field (Can I still keep learning certain traffic while in Blocking mode (Conditional Learning)?).

4

Adım 4 Save the identity

The Edit button at the bottom of the window is clicked; the setting is applied without a separate deployment step and is synchronized in a cluster as in Method 1. The test team browses the new release with this identity; the time of the browsing is noted.

5

Adım 5 Open the analysis window

The Analysis & Learning row on the mode card of the host group is clicked; the New Analyze window opens (new analysis).

6

Adım 6 Define the analysis

Analyze Date is selected so that it covers the browsing period; at the first opening, the last 3 months come up, and at later openings, the range last selected for that vService is remembered. The Ignore Old Rules switch under Advanced is set to the Combine with old rules position; the window comes in the Create new rules position at every opening, and this option builds a new rule set in place of the existing one. Rule Creating Mode is left the same as the existing policy; when the analysis is applied, this value is also written to the Rule Creation Policy setting in Learning methods.

7

Adım 7 Start the analysis

Start Analyzing is clicked; a progress bar appears on the mode card. When the analysis is finished, a New badge appears on the row.

8

Adım 8 Open the result

The New badge is clicked; the preview of the analysis result opens.

9

Adım 9 Examine the suggestions

Edit in the preview is clicked; on the Analyze Page Types screen, the suggested page types are examined and narrowed down (How do I generate rules from past traffic with Analysis & Learning?). The paths that come out of the analysis result are checked; only the paths for which a WAF rule will be created should remain in the list. It is recommended that unknown or suspicious paths be selected in the tree and removed from the analysis with Exclude from Analysis; these paths are added to the Excluded paths list and do not produce rules.

10

Adım 10 Apply

Apply is clicked and the "Are you sure?" question is confirmed with Yes; the rules are applied without a separate deployment step and are synchronized in a cluster as in Method 1. The applying is based on the rule set at the moment the analysis was started; changes made to the rules manually or through learning after the analysis started are lost in the applying. When the work is finished, the Conditional learning identity fields are emptied while the switch is on and saved with Edit, and only after that is the switch turned off and saved again.

Verification

1Mode cardTR7 side

The page type count and the Analysis & Learning row on the mode card of the host group are examined.

ExpectedThe page type count has increased; Applied badge on the row

Method 4: Temporary Monitor Mode from the Interface

• How it works In a host group in Monitor Mode, requests that exceed the threshold are not blocked and continue to be written to Event Logs. During the release, the violations that the new release triggers are seen without affecting the user.
• Where it is openedWAF Management → the mode card of the host group → Edit on the title strip
• Requirement Modify permission in the WAF area
• vService type HTTP

Step-by-Step Configuration

1

Adım 1 Open the host group window

On the WAF Management tab, the Edit text on the title strip of the mode card of the host group that the release will affect is clicked (WAF mode Edit screen).

2

Adım 2 Select Monitor mode

In the WAF Mode field, Monitor mode is selected.

3

Adım 3 Save

The Edit button at the bottom of the window is clicked; the mode is applied without a separate deployment step and is synchronized in a cluster as in Method 1. When the release is complete and the records in Event Logs are cleaned up with Method 6, Blocking Mode is selected with the same steps (When should I move from Learning to Monitor and from Monitor to Blocking?).

Verification

1Mode card and recordTR7 side

The title of the mode card and the Action value of the new records in Event Logs are examined.

ExpectedMonitor mode · Not blocked — Monitor mode

Method 5: Temporary Monitor Mode with WEB-CLI

• How it works The release script sets the host group to Monitor mode before the release and to Blocking mode after the release (waf host-groups examples).
• Where it is openedWEB-CLI or an SSH connection to the same CLI
• Requirement Modify permission in the WAF area; if the script will connect over SSH, Access CLI over SSH on for the user
• vService type HTTP

Step-by-Step Configuration

1

Adım 1 Get the ID of the group

The host groups of the vService and their IDs are listed:

waf host-groups list poolId <vService>

2

Adım 2 Set to Monitor before the release

waf host-groups update poolId <vService> id <group> --mode monitor

3

Adım 3 Return to Blocking after the release

After the records in Event Logs are examined with Method 6:

waf host-groups update poolId <vService> id <group> --mode blocking

The mode change is applied without a separate deployment step and is synchronized in a cluster as in Method 1. If the groups of multiple vServices are to be changed with a single command, waf host-groups update-many is used: Can I change the WAF settings or host group mode of several vServices at once?

Verification

1Group recordTR7 side

The record of the group is displayed.

Command: waf host-groups show poolId <vService> <group>

ExpectedThe mode value is monitor; blocking after the release

Method 6: Event Logs → Allow / Teach

• How it works After the release, the records created on the new paths are selected and taught with Allow / Teach; the suggestion opens a new page rule or extends an existing rule. A wrong learning is undone with Revert Learning on the Log tab of the vService.
• Where it is opened Left Monitor Panel → WAF-Protected vServices → vService → Event Logs tab
• Requirement Modify permission in the WAF area; full permission in the WAF area for Revert learning
• vService type HTTP

Step-by-Step Configuration

1

Adım 1 Fetch the records after the release

On the Event Logs tab, the Date Range field of the server filter is selected from the moment of the release onward and Save & Get Logs is clicked.

2

Adım 2 Filter the new paths

On the Path tab of the filter strip, the paths of the new release are selected. With the attack name and the Learning Suggestion row on the Attacks tab, it is verified that the record is really a false positive.

3

Adım 3 Select the rows

The rows verified to be false positives are selected.

4

Adım 4 Teach

The Allow / Teach button on the toolbar is clicked; according to the selection, the button takes the name Allow, Teach or Allow / Teach.

5

Adım 5 Confirm

The "Are you sure?" question is confirmed with Yes; the rule changes are applied directly, synchronized in a cluster as in Method 1, and a learning record falls into the Log tab of the vService (How do I allow a request that was blocked by mistake?). If a wrong learning is noticed, Revert Learning under the record on the Log tab in the right panel of the Dashboard tab is used (Can I revert a learned rule?).

Verification

1Attacks columnTR7 side

The Attacks column of the taught rows is examined; the same request is repeated and it is checked whether a new record is created.

ExpectedThe first number drops; the row is green if all signatures have been taught

Common Mistakes

Applying an Analysis Cannot Be Undone

The applying of an Analysis & Learning result does not carry a Revert learning link. The Export file taken before the analysis and before Import (OpenAPI) is the only way back; the file is loaded with Page types → Import and replaces the whole rule set of the group (What happens to existing rules when I Import (full replacement)?).

• Setting the whole site to Learning mode after the release. In Learning mode, rule-based blocking stops and no Event Logs records are produced; the methods above are enough for the new pages (If the application changes after moving to Blocking, should I go back to Learning mode?).
• Running the analysis with the default Create new rules. This option builds a new rule set in place of the existing one; for a release update, Combine with Old Rules is selected.
• Using Teacher in a group in Learning mode. In Learning mode, the learning record takes priority; no Teacher record is created and Teacher history stays empty.
• Leaving Teaching frequency at None. The Teacher identity is recognized, but the records do not turn into rules (How long until Teacher traffic becomes a rule; is a single request enough?).
• Forgetting the Teacher or Conditional learning identity turned on. Requests that carry the identity are not blocked whatever their scores are; the Conditional learning identity continues to be recognized as long as the fields stay filled, even if the switch is turned off; anyone who knows the identity can bypass the protection. When the release is finished, the Teacher switch is turned off; the Conditional learning identity fields are emptied and saved while the switch is on, and only after that is the switch turned off.
• Reacting to the post-release increase without a plan. Managing an increase in false positives noticed after the release: False positives increased after an application update; what should I do?

How it is done in the documentation

• WAF Mode · Recommended Life Cycle
• Learning Methods · Teacher
• Analysis & Learning · Ignore Old Rules
• Import (OpenAPI) · The Import Steps
• AI Learning & Teacher Tracking · Reverting the Learning

Related questions

• New pages are blocked after I released a new version; what should I do?
• False positives increased after an application update; what should I do?
• What is the difference between Conditional Learning and Teacher; when should I use which?
• How do I move the WAF rules I prepared in a test environment to production?