# OpenAPI

# Concept

OpenAPIs are used in Workflows to validate traffic by enforcing an OpenAPI2 (opens new window) descriptor.

Example of OpenAPI:

---
apiVersion: core/v1beta
kind: OpenAPI
metadata:
  name: my-openapi
spec:
  format: yaml
  source: |-
    swagger: '2.0'
    info:
      title: sample openapi
      version: 1.0.0
    basePath: "/store/v1"
    paths:
      "/products":
        GET:
          summary: List products
          operationId: listProducts
          parameters:
          - name: limit
            in: query
            required: false
            allowEmptyValue: false
            type: integer
            format: int32
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# Usage

To use a OpenAPI in a workflow, use the following call:

ActionSitemapValidation(Args{"sitemap": "${params.openapi}"})
1

The function returns a boolean attribute sitemap.blocked than can be checked.

Some optional policy options allow you to adjust the behaviour of the Sitemap Validation node.

# Fields

  • format: the format of the source (yaml or json)
  • source: the content in OpenAPI2 specification format
  • policy_match: Defines the matching behavior of the validation node when static and dynamic paths exist for the same resource. The value "any" allows dynamic paths to be checked when static paths have not been able to match the method and path of the request. The value "strict" allows dynamic paths only when no static path has been found to match the method and path of the request. If a static path is not able to match a request because of the parameters, the validation will not check the dynamic paths to match the request and the validation will fail. Default: "any".
  • policy_header: Defines the validation behavior regarding headers. The "definedOnly" value will allow validation of headers defined in the OpenAPI2 specification. The "acceptUndefined" value will allow undeclared headers to be accepted by the validation node. Default: "acceptUndefined".
  • policy_query: Defines the validation behavior regarding query parameters. The "definedOnly" value will only allow validation of query parameters defined in the OpenAPI2 specification used by the validation node. Unknown parameters will automatically make validation fails. The "acceptUndefined" value will allow undeclared query parameters to be accepted by the validation node. Default: "definedOnly".
  • policy_formdata: Defines the validation behavior regarding form data parameters (also called post data parameters). The "definedOnly" value will allow validation of form data parameters defined in the OpenAPI2 specification. The "acceptUndefined" value will allow undeclared form data parameters to be accepted by the validation node. Default: "definedOnly".
  • policy_body: Defines the validation behavior regarding the request body. The "definedOnly" value will allow validation of body defined in the OpenAPI2 specification. The "acceptUndefined" value will allow undeclared body to be accepted by the validation node. Default: "definedOnly".

# Import

You can import an OpenAPI2 file to generate a configuration file that can be used later:

appsecctl create openapi my-openapi --from-file openapi2.yaml > my-openapi.yaml
1

# OpenAPI2 limitations

  • file and array parameter types are not taken into account, such parameters will be considered as string parameters (warnings are visible in container logs).
  • only parameter formats explicitely defined in OpenAPI2 specification are accepted, other valuyes will be dropped (a warning is visible in container logs).
  • path definitions are not taken into account.
  • external referencies are not taken into account.

# OpenAPI2 extensions

  • The X-ACCEPT-ALL operation can be used as operation wildcard (accepts all request methods).
  • The x-policy options allows to define the policy options within your OpenAPI2 data.
x-policy: 
  match: any
  header: definedOnly
  query: definedOnly
  formData: definedOnly
  body: definedOnly
1
2
3
4
5
6
Last Updated: 10/12/2021, 9:48:24 AM