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. kubectl get sidecargateways.microgateway.airlock.com  
NAME          STATUS   AGE 
webapp   Active   8m28s
webapp2   Error    8m47s

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

  • 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 and binary data (jpgs, gifs, ...). XML, YAML and form-url-encoded data are allowed.

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

  • The OpenAPI feature does currently not support the following:
  • Content-Types other than JSON, i.e., XML, YAML, form-url-encoded are unsupported. Content with one of these content types is passed unchecked.
  • Multipart requests.
  • Callback definitions.
  • OpenAPI schema in YAML format.
  • Complex validators:
    • Binary validators for bodies that are not JSON, XML, YAML, or form-url-encoded are unsupported.
    • Validators for header values, cookie values, path and query parameters are unsupported.

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.