Can I generate API protection rules automatically from my OpenAPI definition?

Q: Can I generate API protection rules automatically from my OpenAPI definition?

Yes. Import (OpenAPI) on the Page Types screen reads an OpenAPI 3.0 or Swagger 2.0 definition (.json, .yaml, .yml) and produces one page type for each path: templates such as {id} turn into a glob (/users/*), operations into the Allowed Methods list, query and header parameters into allow lists, parameters that are required in all operations into required lists, length, pattern and fixed value list restrictions into value inspections, and the field names of the body schema into the JSON, XML or form allow list. The import is merged with the existing rules; a rule with the same path is replaced with the one in the document, and the other rules are kept; with a third-party document the Any Paths rule is kept as well (a document produced by TR7's Export (OpenAPI) also replaces the Any Paths rule). In terms of API protection there are three limits: in JSON and XML bodies only the top-level field names are written to the list, nested paths count as violations because they are not in the list and are added manually; no required field is produced for JSON and XML; undefined endpoints continue to be inspected with Any Paths, and for them to be rejected the Allowed Methods value of the Any Paths rule is additionally set to None. For this reason a backup is taken with Export before the import, and then the rules are tried with real traffic in Monitor mode. There is no OpenAPI import command in WEB-CLI.

Short answer

Yes. Import (OpenAPI) on the Page Types screen reads an OpenAPI 3.0 or Swagger 2.0 definition (.json, .yaml, .yml) and produces one page type for each path (the conversion of the document into rules): templates such as {id} turn into a glob (/users/*), operations into the Allowed Methods list, query and header parameters into allow lists, parameters that are required in all operations into required lists, length, pattern and fixed value list restrictions into value inspections, and the field names of the body schema into the JSON, XML or form allow list. The import is merged with the existing rules; a rule with the same path is replaced with the one in the document, and the other rules are kept; with a third-party document the Any Paths rule is kept as well (a document produced by TR7's Export (OpenAPI) also replaces the Any Paths rule). In terms of API protection there are three limits: in JSON and XML bodies only the top-level field names are written to the list, nested paths count as violations because they are not in the list and are added manually; no required field is produced for JSON and XML; undefined endpoints continue to be inspected with Any Paths, and for them to be rejected the Allowed methods value of the Any Paths rule is additionally set to None. For this reason a backup is taken with Export before the import, and then the rules are tried with real traffic in Monitor mode. There is no OpenAPI import command in WEB-CLI.

Problem: The API Definition Is Ready, and Writing the Rule Set Manually Is Not Wanted

The endpoint, method and parameter list of the API is already written in the OpenAPI definition. Learning this list from traffic takes time and can miss rarely used endpoints; writing it manually, on the other hand, carries the risk of errors. Import (OpenAPI) sets up the positive security model directly from the document without waiting for the traffic to be learned (use cases). The general use of the screen and the conversion details are on the Can I generate rules automatically from my OpenAPI / Swagger file? page; this page describes how to bring the imported rule set to a state that actually protects the API.

What is produced from the document:

Item in the document	Rule produced	Note
Path (`/pet/{petId}`)	Page type (`/pet/*`, glob)	The `servers` prefix is not added to the path
Operations (get, post…)	Allowed Methods = Multiple Methods	Methods that are not in the document become violations
Query and header parameters	Allowed Query Parameters, Allowed Headers	Path and cookie parameters are ignored
`required: true` parameter	Required Query Parameters, Required Headers	Only if it is required in all operations of the path
`minLength`, `maxLength`, `pattern`, `enum`, number types	Value length and value pattern in the argument rule	Unsupported regex features are dropped and a warning is given
JSON, XML or form body schema	Allowed JSON Keys, Allowed XML Keys, Allowed Form Fields	Only the top-level field names of the schema; required fields only for form
Every new rule	Path length 1–8192, Path depth ≤ 256, OWASP on	Default path restrictions

Solution

The import is a single step; after it, three completions are made: nested JSON paths are added, undefined endpoints are closed and the rule set is tried in Monitor mode. The prerequisites of the operation are that WAF is on in the vService (How do I enable WAF protection on a vService?) and, if the API is on a separate domain name, that it has its own host group (How is a Host Group added; what goes into the Virtual Host Patterns field?).

Import (OpenAPI) and Completion

How it works The document is converted into page types and merged with the existing rules; then the inspections that cannot be produced from the document are completed manually.
Where it is opened Left Monitor Panel → WAF-Protected vServices → vService → WAF Management → the N page types row on the mode card of the host group → Import (OpenAPI)
Requirement An OpenAPI 3.0 or Swagger 2.0 file; modify permission in the WAF area
vService type HTTP

Step-by-Step Configuration

Adım 1 Check the Checks settings

In the Left Monitor Panel → WAF-Protected vServices → vService → WAF Management tab, the pencil icon of the Checks card is clicked. Structure Checks and Argument Checks must be checked. If the longest parameter or field list in the document exceeds the Max. Allowed Arguments value (default 25), the value is increased; a list that exceeds it is silently disabled for that rule. If a change was made, Edit is clicked.

Adım 2 Open the Page Types screen

In the WAF Management tab, the N page types row below the mode card of the API's host group is clicked (accessing the screen).

Adım 3 Take a backup

Export on the toolbar is clicked; the rule set is downloaded as a JSON file. Since the rules with the same path as the paths in the document will be replaced, this backup is the only way back (operational best practices).

Adım 4 Select the definition file

Import (OpenAPI) on the toolbar is clicked and the definition file is selected from the file picker.

Adım 5 Confirm the import

The Are you sure? question is confirmed with Yes (the import steps). As a result, the "OpenAPI import: N path applied" notification appears; if there are warnings (dropped regex patterns, paths without operations), they are listed in the notification and are read. If the file cannot be parsed or a pattern is not supported, the whole import is rejected and the existing rules do not change (the validation and the errors).

Adım 6 Open the rule that carries a nested body

The rule of the endpoint whose body contains a nested object is clicked; in the detail panel on the right, the JSON tab is selected and Edit Common Rule for JSON is clicked (JSON common rule).

Adım 7 Add the inner paths to the list

The inner paths are added to the Allowed JSON Keys list with dots. For example, for the {"user":{"name":"…","email":"…"}} body the import writes only user; user.name and user.email are added. An array index does not lengthen the path (Can I allow only specific keys in JSON; how are nested key paths written?). For XML bodies, the same completion is made in the XML tab.

Adım 8 Save the JSON rule

Edit in the form is clicked. Steps 6–8 are repeated for every endpoint that carries a nested body.

Adım 9 Open the Any Paths rule for editing

The italic Any Paths row in the list is selected and Edit on the toolbar is clicked. A third-party document does not change the Any Paths rule.

Adım 10 Close the undefined endpoints

Allowed Methods = None is selected. Paths that are not in the document but must be reachable (documentation, paths probed by external monitoring systems) are first added with their own page types (How do I set up a positive security model for an API (allowed endpoints, methods, parameters)?).

Adım 11 Save Any Paths

Edit in the form is clicked; the WAF configuration is produced again and applied.

Adım 12 Put the host group into Monitor mode

In the WAF Management tab, on the mode card of the host group, the Edit text at the bottom right corner of the title strip is clicked, WAF Mode = Monitor Mode is selected and saved with Edit. When no violations remain for legitimate requests in Event Logs, Blocking Mode is selected via the same path (When should I move from Learning to Monitor and from Monitor to Blocking?). In a cluster, the changes are sent to the peer device with the default auto-sync; if Manual Sync Mode is on, they are sent with Synchronize.

Verification

1Generated rulesPage Types

The paths in the document appear in the list; templated paths are highlighted as glob. The method and allow lists are read in the Path, Query, Header and JSON tabs of the rule's detail panel.

ExpectedOne rule per path; N page types on the mode card increased

2Legitimate trafficMonitor mode · Event Logs

During the Monitor period, the Attacks tab of the Event Logs records is checked for the API's real requests.

ExpectedNo Allowed JSON keys, Allowed query parameters or Allowed methods record

If there is a record, the violation row shows the path or parameter that is missing from the list; the related list is completed or the record is taught with Allow / Teach.

Common Mistakes

Switching directly to Blocking mode after the import

Since nested JSON and XML paths are not in the list, legitimate requests that send a nested body produce a 24-point Allowed JSON Keys violation and are blocked in Blocking mode. The rule set is first tried in Monitor mode.

Assuming that Any Paths has also been narrowed. A third-party document does not touch the Any Paths rule; endpoints that are not in the document continue to be inspected with Any Paths.
Expecting required fields in a JSON body. Required lists are produced only for query, header and form; there is no required key inspection for JSON and XML.
Expecting a pattern inspection on number-type fields. The value pattern produced for number and boolean types is not applied to number and boolean values in JSON; JSON value inspections are applied only to text values.
Not increasing Max. Allowed Arguments for large schemas. The allow list of a rule whose list exceeds this limit is disabled without a warning.
Not taking an Export backup. Manual customizations in rules with the same path are lost with the import; there is no undo step.
Using an old definition. Rules are produced for endpoints that have been removed, and new endpoints are not covered; the document is imported again with every API version. Importing the same document again does not produce duplicate rules.

How it is done in the documentation

Can I generate API protection rules automatically from my OpenAPI definition? ​

Problem: The API Definition Is Ready, and Writing the Rule Set Manually Is Not Wanted ​

Solution ​

Import (OpenAPI) and Completion ​

Step-by-Step Configuration ​

Verification ​

Common Mistakes ​