OpenAPI specification validation

Published APIs can be protected strongly by configuring their OpenAPI specification in Airlock Microgateway. This way, HTTP requests and responses are checked against the OpenAPI specification. In case of a violation, they will be blocked.

The illustration shows the filtering engine, which reads the OpenAPI specification at startup and validates the HTTP requests and responses against it.

Such a setup has the following advantages:

• Enforcing a tight OpenAPI specification reduces the attack surface significantly and provides strong security guarantees.
• OpenAPI specifications are typically generated in an automated way by the API build pipeline. No reverse-engineering by security personel is required and a DevSecOps process can be established.

• A valid premium license with the API Gateway feature is required to use this feature.

In the community edition, OpenAPI specification validation is only available in the "log only" mode. That is, violating HTTP requests or responses will not be blocked.

The OpenAPI filter supports the validation of parameters (path, query, header, cookie). All data types and their constraints such as enum, pattern, format, value ranges and length ranges, are supported. Body content checks are only applied to JSON documents and binary data.

• Requests not compliant with the specification are blocked and reported in the log using log_id WR-SG-BLOCK-115-00.
• OpenAPI features currently not supported are reported in the log upon configuration loading using a log message with log_id SY-SG-CONF-115-01.

The following OpenAPI features are currently not supported:

• Content-Types other than JSON
• Multipart requests
• Callbacks

API specification format must be in OpenAPI version 3.0 as JSON.

Specifications in other formats or versions, e.g., Swagger 2.0, must be converted prior to uploading. For Swagger to OpenAPI conversions, we recommend the Mermade converter, which is also available as a command-line tool.

To configure an OpenAPI specification on a Mapping, do the following:

1. Configure the DSL settings under apps[].mappings[].api_security.openapi.


For a comprehensive list of options for OpenAPI, please refer to the DSL reference.

2. Ensure that the OpenAPI specification file is available in the Microgateway configbuilder container.


This is described in External files in dedicated folders.

copy

apps:
  - virtual_host:
      name: api
      hostname: api.virtinc.com
    mappings:
      - name: webapp_api
        entry_path:
          value: /api/
        threat_handling: block
        api_security:
          ...
          openapi:
            spec_file: /config/webapp_api_openapi.json
        backend:
          name: api-service
          hosts:
            - name: api.intra.svc
              protocol: https
              port: 8443

The following log messages contain information about OpenAPI validation:

• During startup by the configuration loader
• SY-SG-CONF-115-00: Config Loader: Error parsing OpenAPI specification


{
   "@timestamp": "2021-06-28T12:42:26.155+0200",
   "program": "SG_master",
   "log_id": "SY-SG-CONF-115-00",
   "file": "/opt/airlock/gatekeeper/resource/openapi/openapi-45977c32e2bc1e0b938246eda440538c.json",
   "position": "offset 127",
   "message": "Config Loader: Error parsing OpenAPI
               specification:  JSON parse error: Missing a comma
               or '}' after an object member.",
    ...
 }

• file: filename of the document where the error occurred.
• position: denotes the position in the specification where the error was found.
• SY-SG-CONF-115-01: Config Loader: Unsupported OpenAPI feature


{
   "@timestamp": "2021-06-28T12:42:26.155+0200",
   "program": "SG_master",
   "log_id": "SY-SG-CONF-115-01",
   "file": "/opt/airlock/gatekeeper/resource/openapi/openapi-54ac97267e90f11f8c7efec813bdd287.json",
   "position": "$.paths./oauth2/authorization-servers/{authorizationServerId}/revoke.post.requestBody.content.application/x-www-form-urlencoded",
   "message": "Config Loader: Unsupported OpenAPI feature: 
               ... Therefore content with this content-type 
               will pass unfiltered.",
   ... 
 }

• file: filename of the document where the error occurred.
• position: denotes the position in the specification where the error was found.
• SY-SG-CONF-115-02: Config Loader: Config Loader: Error compiling pattern for OpenAPI string format


{
   "@timestamp": "2021-06-28T12:42:26.155+0200",
   "program": "SG_master",
   "log_id": "SY-SG-CONF-115-02",
   "message": "Config Loader: Error compiling  pattern for 
                OpenAPI string format \"creditcard\". Error: 
                Unexpected character in bracket expression.",
   ... 
 }

• SY-SG-CONF-115-03: Config Loader: Config Loader: Error compiling pattern for OpenAPI Content-Type matching


{
   "@timestamp": "2021-06-28T12:42:26.155+0200",
   "program": "SG_master",
   "log_id": "SY-SG-CONF-115-03",
   "message": "Config Loader: Error compiling pattern for 
               OpenAPI Content-Type matching 
               \"application[/json\". Error: Unexpected 
               character in bracket expression.",
   ... 
 }

• During request handling
• WR-SG-BLOCK-115: Noncompliant API usage


{
   "@timestamp": "2021-06-28T12:42:26.155+0200",
   "program": "SG_child",
   "log_id": "WR-SG-BLOCK-115",
   "th_mode": "BLOCK", 
   "attack_type": "Noncompliant API usage", 
   "block_type": "OpenAPI",
   "constraint": "Maximum value",
   "position": "RequestValidator.Body.user.prefs[1].score",   
   "message": "Value 11 is greater than 10",
   ... 
 }

• constraint: provides detailed information on the violated constraint.
• position: denotes the position in the validated request, document or parameter where a constraint was violated.
• WR-SG-REJECT-115: OpenAPI configuration is invalid


{
   "@timestamp": "2021-06-28T12:42:26.155+0200",
   "program": "SG_child",
   "log_id": "WR-SG-REJECT-115",
   "reject_type": "Config",
   "message": "OpenAPI configuration is invalid",
   ... 
 }

• The configuration could not be loaded correctly. Check the CONF-115 log messages for investigation and error analysis.

• Useful information for troubleshooting
• Check also the position key in the log message to understand the reason why the OpenAPI filter blocked or rejected an HTTP request/response or could not read the OpenAPI spec. file.
• For every request handled by the filtering engine, a log message with the "log_id": "WR-SG-SUMMARY" is logged. This log entry might also contain helpful information.

We provide the Airlock Reporting bundle which contains pre-defined saved searches and reports. The screenshots give an impression how violations will be shown.

Kibana (Airlock Reporting bundle)
The pre-defined visualization shows attacked by block type.	The pre-defined visualization shows non compliant API usages.
Pre-defined saved searches simplify analysis.

• OpenAPI spec. concept
• DSL reference