CR OpenAPI

Published APIs can be protected by configuring the corresponding OpenAPI specification in the Airlock Microgateway.
Even though the Airlock Microgateway default settings work well for most upstream web application services, enforcing a tight OpenAPI specification reduces the attack surface significantly. HTTP requests and responses are checked against the OpenAPI specification and will be blocked in case of a violation.

OpenAPI specifications are typically generated in an automated way by the API build pipeline. No reverse-engineering by security personnel is required and a DevSecOps process can be established.

This CR needs to be referenced in the CR ContentSecurity.

Prerequisites

A valid OpenAPI specification is required with the key openapi.json.

  • There are two main error cases with missing or faulty OpenAPI specifications:
  • If a specification cannot be parsed, an application log message is written, e.g., Failed to parse openapi config. JSON parse error: Missing a comma or '}'....
  • If an empty OpenAPI specification is configured, the access log message OpenAPI schema is empty is written and all requests are rejected.

Example configuration

  1. Create a ConfigMap with the key openapi.json in the application namespace based on an OpenAPI specification file.
    2. copy
    kubectl -n <my-app-namespace> \ 
  create cm <open-api-example> \  
  --from-file=openapi.json=<my-local-openapi-filename.json>
  2. This will result in a ConfigMap similar to the following example:
    3. Version: v1 
kind: ConfigMap 
metadata: 
  name: <open-api-example> 
data: 
    openapi.json: | { 
    "openapi": "3.0.0", 
    "info": { 
      "title": "Simple API overview", 
      "version": "2.0.0" 
    }, 
    "paths": { 
      "/": { 
        "get": {...} 
        .... 
  }
  3. Create the CR OpenAPI and reference it in the CR ContentSecurity. For a CR OpenAPI example, see CR OpenAPI reference documentation, tab Example.
  4. Check the status of your sidecargateways to verify that the configuration works as expected.
    Example:
    5. copy
    kubectl get sidecargateways.microgateway.airlock.com

Logging

In case of a problem in the configured OpenAPI specification, Airlock Microgateway logs information in the application log.

  • JSON syntax error in OpenAPI specification:
    • [2023-09-25 11:58:25.476][37802][warning][config] [airlock/extensions/filters/http/openapi/openapi_filter_config.cc:125] Failed to parse OpenAPI configuration "<OpenAPI-reference-name>": JSON parse error: Missing a name for object member. offset 36
  • OpenAPI syntax error:
    • [2023-09-25 11:59:49.918][38151][critical][main] [external/envoy/source/server/server.cc:134] error initializing config '  /home/jona/devel/airlock-microgateway-engine/config/openapi.yaml': Failed to parse OpenAPI configuration "<OpenAPI-reference-name>": Expected key "in" not found $.paths./WebApplication.post.parameters[0]

Feature scope and configuration options

  • The OpenAPI filter supports the validation of requests and responses:
  • Path
  • Query parameters
  • Headers
  • Cookies
  • JSON syntax and objects

    • Body content checks are only applied to JSON documents, form-urlencoded parameters, and binary data (jpgs, gifs, ...).

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

  • The OpenAPI feature does currently not support the following:
  • For requests with form-urlencoded parameters, additionalProperties can only be configured as a boolean.
  • XML and YAML content types are unsupported. These content types are passed unchecked, even when specified in a schema.
  • Multipart requests.
  • Callback definitions.
  • OpenAPI schema in YAML format.

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