Microgateway Custom Resources

The CR AccessControlPolicy is a Direct Attached Policy for the Kubernetes Gateway API. It specifies the options to perform access control with an Airlock Microgateway.

The CR APIProtection contains the configuration for API security.

The CR ContentSecurityPolicy is a Direct Attached Policy for the Kubernetes Gateway API. It specifies the options to secure an upstream web application with a Microgateway. It does so by referencing various other CRs that cover different aspects of web application security.

The CR CSRFProtection provides the configuration options for cross-site request forgery (CSRF) protection.

The CR CustomResponse defines a custom response which allows to customize the error pages.

The CR CustomResponsePolicy is a Direct Attached Policy for the Kubernetes Gateway API. It defines a rule-based policy for replacing responses with custom responses.

The CR DenyRules configures request filtering using Airlock built-in and custom deny rules. Deny rules establish a negative security model. They define prohibited patterns that, when a match is found in a request, lead to it being blocked from reaching the upstream web application.

Different security levels can be configured on global and deny rule levels. This makes it possible to configure the balanced processing of requests with a high level of security and a low number of false positives simultaneously.

Override global settings for specific deny rules
For fine–tuning, i.e., to reduce the number of false positives, the security level or the threat handling mode for individual deny rules may be configured differently from the global settings. To do so, configure non–global security levels for deny rules using the ruleKeys or the types element.

Deny rule exceptions
Deny rule exceptions can be defined for different data elements.

Note that exceptions will only reduce blocks if the configured exception covers all data elements that trigger deny rules.

For example, if an exception is configured to unblock search parameters, a request containing a search and a language parameter could still be blocked if the language parameter triggers a deny rule. The same mechanism applies to other blocked data elements such as parameters, headers or JSON data.

Deny rule exceptions for JSON content
Body data of requests with content–type header application/json are parsed as JSON content and might cause false positives. Deny rule exceptions can be defined for JSON keys or values based on the access log information. Additionally, exceptions can be restricted to a defined JSONPath. In the JSONPath expressions, wildcards (*) can be used, like in this JSONPath syntax reference.

Example:

{ 
  "books": [ 
    { 
      "title": "DevSecOps Starters Guide", 
      "author": "Joe Bloggs", 
      "stars": 723 
    }, 
    { 
      "title": "JSONPath for Geeks", 
      "author": "Jane Smith", 
      "stars": 27 
    } 
  ] 
}

This JSON example contains 6 key–value pairs (aka leaves), 3 pairs for each book. The values of the JSON leaves can be filtered with the corresponding JSONPath from the following table.

JSONPath          | Value 
––––––––––––––––––|–––––––––––––––––––––––––––– 
$.books[0].title  | "DevSecOps Starters Guide", 
$.books[0].author | "Joe Bloggs", 
$.books[0].stars  | 723 
$.books[1].title  | "JSONPath for Geeks", 
$.books[1].author | "Jane Smith", 
$.books[1].stars  | 27

For instance, an exception for all books of authors named Joe can be configured as follows.

Example:

apiVersion: microgateway.airlock.com/v1alpha1
kind: DenyRules
metadata:
  name: my–webapp
 spec: 
  request: 
    builtIn:
      exceptions: 
        – blockedData: 
            json: 
              jsonPath: $.books[*].author 
              value: 
                matcher: 
                  contains: Joe

Custom deny rules
Custom deny rules can be configured to complement the built–in deny rules.

The CR EnvoyCluster is an additional Envoy Cluster resource that is added to those defined by the Airlock Microgateway. The CR allows configuring additional clusters if a native Envoy HTTP filter relies on it. For the CR EnvoyCluster, the Envoy configuration language must be used.

The CR EnvoyHTTPFilter is an additional Envoy HTTP Filter resource that is added to those defined by the Airlock Microgateway. If a feature is available as a native Envoy HTTP filter but is missing in the Microgateway CRs, the CR EnvoyHTTPFilter can be used to prepend the native Envoy HTTP filter. For the CRs EnvoyHTTPFilter and EnvoyCluster, the Envoy configuration language must be used.
For an example targeting debugging, see article Recording HTTP traffic.

The CR EnvoyExtensionPolicy is a Direct Attached Policy for the Kubernetes Gateway API. It allows extending the raw Envoy configuration of the Airlock Microgateway Engine with e.g., custom filters or clusters.

The CR GatewayParameters defines the configuration settings for deploying a Gateway in Kubernetes, including options for logging, service type, deployment strategy, and resource management.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: gateway–secure
  namespace: airlock–gateway
spec:
  gatewayClassName: airlock–microgateway
  infrastructure:
    parametersRef:
      group: microgateway.airlock.com
      kind: GatewayParameters
      name: gateway-parameters-example
  listeners:
  – name: http–listener
    protocol: HTTP
    port: 80

Custom response configuration

Use spec.defaults.customResponses to customize the default HTTP responses returned to clients. The setting statusCodeCondition allows to specify which custom response should be served for a particular HTTP status code.

To override this behavior for a specific HTTPRoute, attach a CR CustomResponsePolicy to that route. The policy lets you define alternative responses or status code mappings and takes precedence over the defaults.

The CR GraphQL allows referencing a GraphQL schema resource. The schema of this ConfigMap resource must be compatible with GraphQL schema definition (Oct. 2021). Introspection and mutation queries are supported.

Not all configurational aspects of GraphQL–related traffic are configured in the CR GraphQL. Even without a referenced schema, CR DenyRules and CR Limits settings are applied to query requests and can be configured to block or restrict them.

GraphQL queries are identified with parameters and keys and must match the parser's requirements – see CR Parser.

In case of a problem, such as an error in the referenced GraphQL schema, Airlock Microgateway logs information in the application log.

Example:

[2024–06–12 14:08:43.436][125742][critical][main] [external/envoy/source/server/server.cc:414] error initializing config '  /home/mgw/airlock/airlock–microgateway–engine/config/graphql.yaml': Failed to parse GraphQL configuration "graphql_config": schema parse error: Parse error at 1:16 
Unexpected `abc[Name]` 
Expected `:`

Handling of large GraphQL schema files

Kubernetes ConfigMaps are limited to 1 MiB in total size. If the GraphQL schema file exceeds 1 MiB, it can be stored compressed and base64 encoded.

The CR HeaderRewrites is the Schema for the header rewrites API.

With the configuration options, request and response headers can be added to or removed from upstream and downstream traffic.

The content of this CR is split into two main sections request and response. Both sections can be complemented with custom rules.

The following actions can be configured for both built–in and custom rules:

Logging
Header rewrite actions are not displayed in the access log by default. The CR HeaderRewrites features an Integration operation mode that enriches the access log output with information and details not logged in Production mode. The additional log information are useful for application integration and fault–finding tasks, i.e., to discover potential header–related issues.

Note that the extended logging output of the Integration mode results in larger log messages and requires more storage.

Example log output in Integration mode:

   "airlock": { 
    "header_rewrites": { 
      "response": [ 
        { 
          "headers": [ 
            "content–type" 
          ], 
          "type": "remove–rule", 
          "applied_rules": [ 
            "Remove Content Type Response Header" 
          ], 
          "action": "remove" 
        } 
      ], 
      "request": [ 
        { 
          "type": "allow–rule", 
          "applied_rules": [ 
            "Standard Allowed Request Headers", 
            "Allow custom request headers", 
            "Propagate X–Forwarded–For to upstream" 
          ], 
          "action": "remove", 
          "headers": [ 
            "front–end–https", 
            "x–forwarded–host", 
            "x–forwarded–port", 
            "x–forwarded–proto", 
            "x–forwarded–server", 
            "x–real–ip", 
            "accept–encoding" 
          ] 
        } 
      ] 
    },

The CR IdentityPropagation specifies how the identity of the authenticated user is propagated from the Microgateway Engine to the back–end. For example, it is possible to set a header containing an OIDC idToken claim.

The CR JWKS provides the configuration for JSON Web Key Set providers and endpoints, including certificate verification settings.

The CR JWT configures client authentication via a JSON Web Token.

Airlock Microgateway performs various size checks on requests with a default configuration to repel denial of service (DoS) attacks. The CR Limits can be used to configure these limit checks on the root level. All limits are calculated in bytes.

Size limits like bodySize, nameLength , etc., can be specified in bytes or Kubernetes memory limit units.

Threat handling mode settings
When a request causes a block due to reaching the request size limit in Block mode, it is possible that the total request size is not fully logged. For example, it can happen that the actual parameter name length is not part of the logging information because the request size limit has already been reached before and the request is already blocked. This behavior is to mitigate the risk of being vulnerable to DoS attacks.

The logs may vary depending on the settings.threatHandlingMode. In Block mode, only the available information is logged to still protect against denial of service attacks. This could lead to some information being missing whereas in LogOnly mode, all limits–related information is logged.

The following examples show two types of limit violations, body size and JSON key length, in both threat–handling modes.
As expected, the body.size value is not shown in Block mode in opposition to the JSON key.length value (which requires parsing the JSON body for length calculation).

# body size, block 
 
    "limits": { 
      "matches": [ 
        { 
          "blocked_data": { 
            "body": {} 
          }, 
          "rule": "Built–in: Request body size", 
          "threat_handling_mode": "block" 
        } 
      ] 
    },

# body size, logOnly 
 
    "limits": { 
      "matches": [ 
        { 
          "blocked_data": { 
            "body": { 
              "size": 219 
            } 
          }, 
          "rule": "Built–in: Request body size", 
          "threat_handling_mode": "logOnly" 
        } 
      ] 
    },

# JSON key length, block 
 
    "limits": { 
      "matches": [ 
        { 
          "blocked_data": { 
            "json_key": { 
              "json_path": "$['username']", 
              "key": "username", 
              "length": 12 
            } 
          }, 
          "rule": "Built–in: JSON key length", 
          "threat_handling_mode": "block" 
        } 
      ] 
    },

# JSON key length, logOnly 
 
    "limits": { 
      "matches": [ 
        { 
          "blocked_data": { 
            "json_key": { 
              "json_path": "$['username']", 
              "key": "username", 
              "length": 12 
            } 
          }, 
          "rule": "Built–in: JSON key length", 
          "threat_handling_mode": "logOnly" 
        } 
      ] 
    }, 

The article Access log provides additional information listing all log fields including short descriptions.

Limit–based block and attack types in logs and metrics
In addition to the obvious block type limits, limit–based blocks (or potential blocks in LogOnly mode) can occur based on other Microgateway features that also make use of the configured limits and appear in logs and metrics. All configured limit types can trigger a single request block or multiple potential blocks in LogOnly mode.

For example, Airlock Microgateway Engine metrics can contain the following metric labels:

microgateway_http_downstream_rq_threats_blocked_total{block_type="graphql", attack_type="parameter_body_size", envoy_cluster_name="YourClusterName"}

The metrics block count in the example above has been triggered by a graphql query in a JSON body exceeding the parameter_body_size limit. The label metrics naming is closely related to the CR Limits configuration for intuitive understanding. For example, if a request exceeds the request.limited.general.bodySize value, the corresponding metric label for attack types would be general_body_size.

The CR ODICProvider specifies an OpenID Connect Provider (OP), such as Airlock IAM, with the required authorization and token validation endpoints.

The CR OIDCRelyingParty specifies how the Airlock Microgateway Engine interacts with an OpenID Provider (OP) such as Airlock IAM.

The CR OpenAPI contains the configuration for the OpenAPI specification.
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.

Feature scope and configuration options

Handling of large OpenAPI specification files

Kubernetes ConfigMaps are limited to 1 MiB in total size. If the OpenAPI specification file exceeds 1 MiB, it can be stored compressed and base64 encoded.

Logging

The CR Parser contains the configuration for content parsers (default and custom).
Airlock Microgateway Engine parses the request body before applying filters (deny rules, limits, OpenAPI, GraphQL) to a request's content. The parser selection is based on the Content–Type header.

GraphQL query parsing
The parser can identify and parse GraphQL queries from different types of requests.

The parameter names/JSON keys are “query”, “variables” and “operationName”, where the former is required for GraphQL query identification.

The key “operationName” is used as an identifier for logging if present.

The CR RedisProvider contains a client configuration for connecting to a Redis database. For caching session handling information, a Redis or Valkey database can be deployed within or outside the Microgateway cluster.

The CR SessionHandling contains the configuration for session handling and specifies the Redis database where sessions should be stored.

The CR Telemetry contains the configuration for telemetry (logging, metrics, and tracing).

The CR Telemetry can be used to customize the default log format of Airlock Microgateway.

The CR Telemetry reference documentation contains the default access log configuration and an example configuration. The default configuration can be used as a starting point for customization.

The access log format can be configured using the Envoy format dictionary style. Both command operators (i.e., standard Envoy and Microgateway) may be used in the configuration.

Log correlation:

If correlation.idSource is configured, the command operator LOG_CORRELATION contains the correlation ID extracted from idSource. The default access log format contains the field log_correlation using this command operator.

The CR TokenExchange configures an OAuth Token Exchange (RFC 8693). This feature may be used for authorizing the client or when the upstream backend requires a different token than the downstream JWT or OIDC Access Token.

{
  "airlock": {
    "access_control": {
      "policy": "policy_name",
      "authenticated": true,
      "authorized": true,
      "type": "jwt",
      "user_id": "...",
      "status": "complete",
      "details": {
        "jwt": {
          "token": { ... },
          ...
        },
        "token_exchange": {
          "sequence": [
            { "type": "jwt", "token": {"iss": "...", "sub": "..."}, "cached": true }
          ]
        }
      }
    }
  }
}