Import (OpenAPI)

What Is Import (OpenAPI)?

Import (OpenAPI) produces page types (WAF rules) from an OpenAPI or Swagger definition file. There are two typical uses:

• Setting up the protection from the application's own API definition: The OpenAPI document provided by the application team is imported; every path in the document is converted into a page type together with its method list and parameter schemas. Thus the positive security model is set up directly from the API document without waiting for the traffic to be learned.
• Restoring the TR7 output: When a document taken with Export (OpenAPI) is imported, the rules are restored losslessly from the section of the document that is specific to TR7 (including Any Paths).

The import is a merging, a rule with the same path is replaced

While Import replaces the existing rule set entirely, Import (OpenAPI) performs a merging: the existing rules that do not take place in the document are not touched. For every path in the document, on the other hand, if there is a rule with the same path, this rule is replaced entirely with the rule derived from the document (the customizations made manually on it are lost); if there is none, it is added as a new rule.

The Import Steps

1. The Import (OpenAPI) button on the toolbar is clicked and the definition file is selected from the file picker that opens; the .json, .yaml and .yml files are accepted.
2. The "Are you sure?" confirmation question is confirmed with the Yes button; if No is selected, no change is made.
3. The file is uploaded and converted. While the operation is going on, the button icon turns into a spinning icon and the other operations on the toolbar become passive temporarily.

At the end of the operation a notification that summarizes how many paths have been applied and, if there are any, the conversion warnings is shown: "OpenAPI import: N path applied" (with the "— k warning(s): ..." suffix and in orange color if there is a warning; at most the first eight warnings are listed in the notification). There is no additional deployment (deploy) step; the WAF configuration is automatically produced again and applied and the N Page Types number on the mode card increases with the new paths.

The Conversion of the Document into Rules

• The accepted formats: OpenAPI 3.0 (JSON or YAML) and Swagger 2.0 (it is automatically upgraded to 3.0 in the import).
• The path templates: The template parameters such as {petId} are converted into the * glob character that matches a single path segment; the rule takes place in the list as a glob rule. For example the /pet/{petId} document turns into the /pet/* rule.
• The server addresses: The servers addresses in the document are not applied to the paths as a prefix; the paths are taken as they are written in the document.
• The methods: The operations of the path turn into the Allowed Methods list of the rule.
• The parameters and the body: The query and header parameters are written into the Check Fields allow lists; the parameters that are required in all the operations become a required field. The schema restrictions (the length, the pattern, the fixed value list, the number types) are converted into field inspections. Among the body schemas the form, JSON and XML content types are processed; the other content types and the cookie parameters are ignored.
• The default restrictions: Every new rule produced from the document is created with the default path restrictions: Path Length 1–8192, Path Depth ≤ 256, the OWASP scanning on.
• Any Paths: A third-party document does not touch the Any Paths (catch-all) rule. If the document is a TR7 output, the Any Paths configuration carried in the document takes the place of that of the target group.

Importing again is safe

Importing the same document again does not produce duplicate rules; the paths take the place of their existing counterparts and the result stays the same.

The Validation and the Errors

• If the file cannot be parsed as OpenAPI/YAML, the import is rejected with the error text returned by the parser and the existing rule set does not change.
• If a field pattern in the document is not supported by the WAF engine, the whole of the import is rejected with the "Invalid WAF pattern (...)" error; the existing rule set does not change.
• The schema patterns that contain unsupported regex features (a back reference, a look-ahead/look-behind) are dropped in the rule production and are listed as a warning in the result notification; the relevant field still takes place in the allow list, without a pattern.
• The paths that have no operation are skipped and are reported as a warning.

Operational Best Practices

• A backup should be taken before the import. Since the existing rules that have the same path as the paths in the document will be replaced, the backup taken with Export beforehand is the only way back.
• The current API definition of the application should be used. An old definition produces rules for the endpoints that have been removed and does not cover the new endpoints; the requests coming to the paths that do not take place in the definition continue to be inspected with the Any Paths rule.
• The result notification and the produced rules should be reviewed. After the import the warnings (especially the dropped patterns) should be read and the produced rules should be checked in the list; the necessary fine adjustments are made with Edit.