How do I move the WAF rules I prepared in a test environment to production?

Short answer

The rule set is moved per host group, with a file: in the host group of the test vService, a JSON is taken with Export on the Page Types screen, and it is loaded into the target host group of the live vService with Import. Because Import replaces all the page types of the target group, the set in production is first backed up with Export. To keep the rules in production and add only the paths prepared in the test, Export (OpenAPI) and Import (OpenAPI) are used; this is a merge: the rule with the same path is replaced with the one in the document and the others stay, but because the document that TR7 produces also carries the Any paths rule, the Any paths of production is replaced with the one in the document. Only the rule list is included in the file; the name, the pattern and the mode of the host group, the vService WAF settings such as the protection level, Checks, the blocking page, the body limits and the learning settings, and the OWASP Rules and Signature & Rule Library changes are made separately in production; the settings can be transferred with the waf options commands in WEB-CLI. Before the load, the live host group is set to Monitor Mode, and if no false blocking is seen, it is returned to Blocking Mode. The files are device-independent; test and production can be on different TR7 devices.

Problem: The Rules Prepared in the Test Have to Be Transferred to Production Without Errors

The rule set was learned in the test environment, or prepared manually and tried out. The same rules have to be transferred to the live vService without being re-entered manually, without exposing the live traffic to false blocking, and in a way that allows returning to the previous state when needed.

Solution: Three Methods

Methods 1 and 2 move the rule set and are alternatives to each other; Method 3 is used after them to transfer the vService WAF settings that are not included in the rule file.

Your situation	Suitable method
Fully replacing the rule set of the live group with the test set	Method 1: Export and Import
Keeping the rules in production and adding or updating the paths prepared in the test	Method 2: Export (OpenAPI) and Import (OpenAPI)
Also transferring the vService WAF settings such as the protection level and the blocking page	Method 3: Transferring the WAF settings with WEB-CLI
Planning the release process of an application version	How should I include the WAF in my application release process?

Method 1: Export and Import Recommended

• How it works The rule set of the test group (the page types, Any paths and the Check fields inspections) is taken into a file and loaded in place of the set of the live group (What happens to existing rules when I Import (full replacement)?).
• Where it is opened On both vServices: Left Monitor Panel → WAF-Protected vServices → vService → WAF Management → mode card → N page types
• Requirement WAF protection enabled on both vServices; modify permission in the WAF area (Export also requires this permission)
• vService type HTTP

Step-by-Step Configuration

1

Adım 1 Open the Page types screen of the test group

On the test vService, the WAF Management tab is opened and the N page types row on the mode card of the host group to be moved is clicked (accessing the screen).

2

Adım 2 Export the test set

The Export button on the toolbar is clicked; the file is downloaded without a confirmation being asked (export steps).

3

Adım 3 Open the target host group window in production (if needed)

If the rules are to be loaded in production not into the default group but into a separate domain name group, and this group does not exist: on the WAF Management tab of the live vService, the plus icon on the Virtual Host Groups band is clicked; the window titled Add opens (How is a Host Group added; what goes into the Virtual Host Patterns field?). If the target group already exists, steps 3–7 are skipped. The name, the patterns and the mode of the group are not in the rule file.

4

Adım 4 Enter the name of the group

The name of the group is written in the Virtual Host Group Name field.

5

Adım 5 Select Monitor mode

In the WAF Mode field, Monitor mode is selected; the field comes preselected with the default mode of the vService.

6

Adım 6 Enter the live domain names

The live domain names are written in the Virtual Host Patterns field.

7

Adım 7 Add the group

The Add button at the bottom of the window is clicked. 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.

8

Adım 8 Open the Page types screen of the live group

On the WAF Management tab of the live vService, the N page types row on the mode card of the target group is clicked.

9

Adım 9 Back up the live set

The Export button is clicked; the downloaded file is kept for a return.

10

Adım 10 Open the mode window of the live group

On the WAF Management tab, the Edit text on the title strip of the mode card of the target group is clicked. If the group was created with Monitor mode in steps 3–7, steps 10–12 are skipped.

11

Adım 11 Select Monitor mode

In the WAF Mode field, Monitor mode is selected. In this mode, attacks are recorded but not blocked (How do I use Monitor mode to weed out false positives?).

12

Adım 12 Save the mode

The Edit button at the bottom of the window is clicked. 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.

13

Adım 13 Click the Import button

On the Page types screen of the live group, the Import button is clicked; the file picker opens (import steps).

14

Adım 14 Select the test file

2. The .json file downloaded in that step is selected.

15

Adım 15 Confirm the import

Yes is clicked at the Are you sure? question. If the file is corrupted (Corrupted WAF rules file) or contains an invalid pattern (Invalid WAF pattern (...)), the import is rejected and the existing set does not change. On a successful load, there is no 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.

16

Adım 16 Monitor Event Logs during Monitor mode

On the Event Logs tab of the live vService, the records that the new rules trigger in the real traffic are examined; false positives are corrected (How do I allow a request that was blocked by mistake?). If the problem is big, the file from step 9 is imported in the same way and the previous set is returned to.

17

Adım 17 Open the mode window again

When no false positive remains, the Edit text on the title strip of the mode card is clicked.

18

Adım 18 Select Blocking mode

In the WAF Mode field, Blocking Mode is selected.

19

Adım 19 Save Blocking mode

The Edit button at the bottom of the window is clicked. 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.

Verification

1Rule listTR7 side

The counter on the mode card and the Page types list of the live group are compared with those of the test group.

ExpectedThe N page types count and the paths are the same as in the test group

2User LogsTR7 side

On the live device, Field = WAF and Action type = Import are filtered on the User Logs screen.

ExpectedN WAF rules are imported from file for group@vService

Method 2: Export (OpenAPI) and Import (OpenAPI)

• How it worksExport (OpenAPI) gives the rule set as an OpenAPI 3.0 document; the document carries the full configuration of every rule in a TR7-specific section. Import (OpenAPI) merges the document into the target group: for every path in the document, if there is a rule with the same path, it is fully replaced with the one in the document; otherwise it is added; the rules that are not in the document are not touched. The Any paths configuration in the TR7 document replaces the Any paths of the target group.
• Where it is opened The Page types screen of the test group → Export (OpenAPI) · the Page types screen of the live group → Import (OpenAPI)
• Requirement WAF protection enabled on both vServices; modify permission in the WAF area; the target host group must exist in production
• vService type HTTP

Step-by-Step Configuration

1

Adım 1 Export the test group as an OpenAPI document

On the Page types screen of the test group, the Export (OpenAPI) button is clicked; the .json document whose name contains _openapi_ is downloaded without a confirmation being asked (export steps).

2

Adım 2 Prepare production

Steps 3–12 of Method 1 are carried out: if needed, the target group is created, the live set is backed up with the plain Export, and the group is set to Monitor mode. An exact return is possible only with the plain Export file.

3

Adım 3 Click the Import (OpenAPI) button

On the Page types screen of the live group, the Import (OpenAPI) button is clicked; the file picker opens.

4

Adım 4 Select the document

1. The document downloaded in that step is selected; .json, .yaml and .yml files are accepted.

5

Adım 5 Confirm the import

Yes is clicked at the Are you sure? question. At the end of the operation, the OpenAPI import: N path applied notification is shown; if there is a conversion warning, it is added to the notification (validation and errors). 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. Then the traffic is monitored and Blocking mode is returned to with steps 16–19 of Method 1.

Verification

1Rule listTR7 side

The Page types list of the live group is examined.

ExpectedThe old paths in production are in place; the paths from the test are added or updated

Method 3: Transferring the WAF Settings with WEB-CLI

• How it works The vService WAF settings that are not included in the rule file (protection level, Checks, Whitelist & Blacklist, blocking page, body limits, learning, report and notification settings) are read on the test vService with waf options show and written to the live vService with waf options update (waf options · Command Summary). In the interface, the same settings are entered one by one from the WAF Management cards of the live vService.
• Where it is openedWEB-CLI → waf options
• Requirement CLI access and modify permission in the WAF area for the user. If test and production are on different devices, the reading is done in the WEB-CLI of the test device and the writing in the WEB-CLI of the live device.
• Scope vService WAF settings; OWASP rules and Signature & Rule Library changes are not moved with these commands

Step-by-Step Configuration

1

Adım 1 Read the settings of the test vService

waf options show poolId <test-vService>

2

Adım 2 Write the settings to the live vService

The fields that differ are written with the same names; in the example, the protection level is set to Very tight (4) and Blocking Status Code to 403 (writable fields):

waf options update poolId <live-vService> --owaspProtectionLevel 4 --blockingStatusCode 403 --syncWithDefaultFwRules false

--syncWithDefaultFwRules is not a stored setting but a write trigger: only when true is written is the Any paths rule rebuilt with its default definition; if it is not written in the command, the rule set is not touched. The false in the command states this explicitly (Sync with Default WAF Rules; basic inspections).

If the same settings are to be written to multiple live vServices: Can I change the WAF settings or host group mode of several vServices at once?

3

Adım 3 Repeat the signature changes in production

The status, score or custom rule changes made on the OWASP Rules screen of the test vService are made in the same way on the OWASP rules screen of the live vService. If the test and live vServices are on the same device, the change can be made once in Signature & Rule Library and applied to all WAF-protected vServices (How do I fix the same false positive on several vServices at once (global layer)?). On different devices, the Signature & Rule Library changes are made separately on the live device.

Verification

1SettingsTR7 side

The waf options show outputs or the WAF Management cards on the two vServices are compared.

ExpectedThe OWASP protection level and Blocking page cards are the same on the two vServices

Common Mistakes

• Doing an Import without backing up the live set. Import and Import (OpenAPI) cannot be undone; the previous state of production can be returned to only with the Export file taken beforehand.
• Thinking that the live Any paths will be kept with Import (OpenAPI). The document that TR7 produces also carries Any paths; the exclusions taught to Any paths in production are replaced with the ones in the document. If only specific paths are to be added, the Any paths rule is reviewed after the Import.
• Thinking that the settings and the mode are moved as well. The rule file does not carry the mode of the host group, the protection level, Checks, the blocking page or the learning settings (Can I export a host group's rule set as JSON and move it to another environment; which settings are not included in the file?).
• Loading directly into a group in Blocking mode. New rules are first tried out in Monitor mode on the live traffic.
• Loading into the wrong group. The file does not carry which group it was taken from; the rules of the group on whose Page types screen the Import is done change.
• Looking for an Export/Import command in WEB-CLI. Rule file transfer is only in the interface; in WEB-CLI, rules are added one by one with waf fw-rules and waf rule-parts (Can I manage the WAF with WEB-CLI; which operations are not available in WEB-CLI?).

How it is done in the documentation

• Export · The Export Steps
• Import · The Import Steps
• Export (OpenAPI) · The Comparison with the Plain Export
• Import (OpenAPI) · The Conversion of the Document into Rules

Related questions

• Can I export a host group's rule set as JSON and move it to another environment; which settings are not included in the file?
• Can I back up my WAF rules?
• How should I include the WAF in my application release process?