Can I generate rules automatically from my OpenAPI / Swagger file?

Short answer

Yes. Import (OpenAPI) on the Page Types screen reads an OpenAPI 3 or Swagger 2.0 document (.json, .yaml, .yml) and produces a page type for every path: path templates (/pet/{petId}) are converted into a glob rule with a * that matches a single segment (/pet/*), Allowed Methods is made up of the operations in the document, and Path Length 1–8192, Path Depth at most 256 and OWASP on come with it; query and header parameters are written to the allowed lists (the ones that are required in all operations to the required list), and only the top-level fields of the JSON, XML and form body schemas to the relevant Check Fields sections; nested objects and minimum/maximum are not transferred, and required in the body becomes a mandatory field only in a form body (converting the document into rules). Cookie parameters and servers addresses are not used. The import merges: a rule with the same path is replaced with the one produced from the document, the rules that are not in the document are preserved, and a third-party document does not touch Any Paths. Schema patterns that the engine does not support are dropped and reported as warnings. For the reverse, Export (OpenAPI) downloads the rule set as an OpenAPI document.

Problem: Writing API Rules Manually Takes Long

Allowed method and parameter rules are needed for dozens of endpoints of an API; the OpenAPI definition of the application already exists, and waiting for traffic for learning is not wanted. Requests that come to paths not included in the definition continue to be inspected with the Any Paths rule.

Solution: Two Methods

Your situation	Suitable method
Producing rules from the document	Method 1: Import (OpenAPI)
Getting the rule set as an OpenAPI document	Method 2: Export (OpenAPI)
Backing up the rule set one-to-one or moving it by full replacement	JSON Export / Import → 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?

Method 1: Import (OpenAPI) Recommended

• How it works Every path in the document is converted into a page type and merged with the existing list of the host group.
• Where it is opened Left Monitor Panel → WAF-Protected vServices → vService → WAF Management → the mode card of the host group → N page types → Import (OpenAPI)
• Requirement An OpenAPI 3 or Swagger 2.0 document (.json, .yaml, .yml); WAF protection enabled on the vService
• vService type HTTP vService with WAF protection enabled

Step-by-Step Configuration

1

Adım 1 Open the Page Types tab

In the Left Monitor Panel, the vService is clicked on the WAF-Protected vServices tab, the WAF Management tab is opened and the N page types row under the mode card of the host group where the API is located is clicked (accessing the screen).

2

Adım 2 Take a backup

Since the existing rules with the same path as the paths in the document will be replaced, the rule set of the group is first downloaded with Export.

3

Adım 3 Select the document

Import (OpenAPI) on the toolbar is clicked and a .json, .yaml or .yml document is selected from the file picker (the import steps).

4

Adım 4 Confirm

Yes is clicked in the Are you sure? question. When the operation ends, the OpenAPI import: N path applied notification shows how many paths were applied; if there is a conversion warning, the notification is shown as a warning (yellow) type and lists the first eight warnings. The rules are applied without a separate deployment step; in a cluster setup, they are also sent to the peer device with the default auto-sync, and if Manual Sync Mode is on, they are sent manually with Synchronize.

Reviewing the result

Paths with template parameters appear in the list as glob rules in the highlight color. When a rule is clicked, Allowed Methods is seen on the Path tab of the detail panel, and the allowed and required lists on the Query and Header tabs. The fields to which the patterns reported as dropped in the warning belong are left without a pattern; if needed, they are edited from the relevant tab. Since the document may not reflect the application one-to-one, the new rules are first tried with real traffic while the host group is in Monitor mode (Can I generate API protection rules automatically from my OpenAPI definition?).

Verification

1ListTR7 side

The Page types list and the N page types number on the mode card are examined.

ExpectedThe paths in the document in the list (e.g. /pet/*)

2Detail panelTR7 side

An API rule is clicked and the Path and Query tabs of the detail panel are examined.

ExpectedThe methods and parameters in the document

Method 2: Export (OpenAPI)

• How it works The rule set of the host group is downloaded as an OpenAPI 3 document; TR7 reads the document it produced itself back losslessly with Import (OpenAPI).
• Where it is opened Page types → Export (OpenAPI)
• Requirement WAF protection enabled on the vService
• vService type HTTP vService with WAF protection enabled

Step-by-Step Configuration

1

Adım 1 Open the Page Types tab

On the WAF Management tab, the N page types row of the host group is clicked.

2

Adım 2 Download the document

Export (OpenAPI) on the toolbar is clicked; no confirmation is asked, and the document is downloaded as .json. Glob paths are converted into the {param} template, and methods and parameters into OpenAPI fields; the full rule definition and the Any paths configuration are carried in the TR7-specific x-tr7-waf section of the document (the produced document). When this document is uploaded with Import (OpenAPI), the rules come losslessly and Any paths is replaced with the one in the document.

Verification

1DocumentClient side

The paths section of the downloaded document is examined.

ExpectedEvery page type is a path; globs in the {param} template

Common Mistakes

• Using a document that is not up to date. Endpoints that are not in the document do not get a separate rule and are inspected with Any paths.
• Expecting cookie and path parameters to get a separate inspection. Path parameters are converted into the * part of the glob; cookie parameters are not processed; the servers prefix is not added to the paths.
• Not reading the warnings. Dropped schema patterns leave the relevant field without a pattern.
• Thinking that Import (OpenAPI) is a full replacement. JSON Import replaces fully; Import (OpenAPI) merges (What happens to existing rules when I Import (full replacement)?).
• Importing without a backup. The manually made settings on the rules with the same path are replaced with the ones produced from the document; Export is taken first.

How it is done in the documentation

• Import (OpenAPI) · The Conversion of the Document into Rules
• Import (OpenAPI) · The Import Steps
• Import (OpenAPI) · The Validation and the Errors
• Export (OpenAPI) · The Produced Document

Related questions

• Can I generate API protection rules automatically from my OpenAPI definition?
• Can I apply schema-like checks (key list, depth, length) to JSON-bodied API requests?
• What happens to existing rules when I Import (full replacement)?