Protections and strategies

Protections and strategies let you apply security as code. The x-42c extensions enable you to provide instructions to API Firewall on how your APIs should be treated and protected. This way, security is becomes the source code of the API, not as a separate afterthought.

Protections

Protections are the base units of API Protection. A protection defines a workflow of assertions — actions that API Firewall executes — as well as the parameters that these assertions require.

A protections is made of two parts:

  • Protection type: A protection type equals the name of the protection and gathers its operation logic. This logic is implemented as a workflow of assertions, operations that API Firewall can execute, such as a HTTP call or a comparison of values. The protection type defines an interface that contains the imported attributes, their parameters, and the exported attributes.
  • Protection profile: A protection profile gathers the parameters that are passed to the protection type in a specific use case. These are the variables that modify the behavior of the protection.

This example image shows how a protection has two parts inside it: a protection type and a protection profile.

For more details on the available protections and what they do, see Protections

Strategies

Protections can be combined to form strategies. A strategy is a set of protections that API Firewall applies to API traffic in the defined sequence when processing requests or responses.

This example image shows a strategy that consists of three protections inside it. All protections include both protection type and protection profile. The protections are marked with numbers 1—3 to represent the linear sequence of execution.

Extensions

Protections and strategies are applied directly to the OpenAPI definition of your API using the 42Crunch x-42c vendor extensions to the OpenAPI Specification (OAS).

You declare all protections you want to use under x-42c-protections in the section x-42c-components from where they are referenced whenever they are needed. If required, you can also define protections directly in the strategy you apply. However, we recommend reusing the protections through references as much as possible, you might not know which ones you want to reuse later.

...
"x-42c-components": {
    "x-42c-protections": {         
        "my-sec-headers": {
            "protection-type": {
                "name": "x-42c-security-headers_v0.1"
            },
            "protection-profile": {
                "sts.max-age": 3600
            }
        },
        "my-sec-headers-200": {
            "protection-type": {
                "name": "x-42c-security-headers_v0.1"
            },
            "protection-profile": {
                "sts.max-age": 7200
            }
        }
    }
}
...

The individual protections are grouped into protection strategies under the extension x-42c-strategy:

...
"x-42c-strategy":{
    "name": "my-default-response-strategy",
    "protections": [
        {
            "$ref": "#/x-42c-components/x-42c-protections/my-sec-headers"
        }
    ]
}
...

You can add the extensions either in the editor of your choice when designing the API, or in Security Editor in 42Crunch Platform when Security Audit has given you insights into what kind of protection your API would need. For more details, see Apply security as code.

When the API Firewall instance protecting the API starts, a compiler component in API Firewall loads the API definition enriched with the security information. The compiler then builds the sequences of actions that the firewall executes on incoming requests and outgoing responses based on the protection strategies you have applied to your API.

Note Pay attention to the order that you define for strategies and protections. If there is a set logical order in which API Firewall must perform some actions (for example, one protection requires the result of another one) you must reflect this order when putting the sequence for protections together. The compiler in API Firewall enforces whatever order you have defined and does not consider if it is logical or not.

For more details on available x-42c extensions, see x-42c extensions.

Global strategies and local strategies

Protection strategies can be applied to the whole API on the global level, or to specific operations or even specific HTTP responses that are more sensitive in nature. This way, you can apply robust security exactly where it is needed.

When specified on the top level of your API definition, the extension x-42c-strategy defines global protection strategies that apply their protections to the whole API. Global strategies are defined separately for request and response processing with the extensions x-42c-request-strategies and x-42c-response-strategies, so the extension x-42c-strategy is always nested within one of these. You can also further refine which operations (methods/verbs) or which response status codes the strategies and their protections apply to.

...
"x-42c-response-strategies": [
    {
        "x-42c-strategy":{
            "name": "my-default-response-strategy",
            "protections": [
                {
                    "$ref": "#/x-42c-components/x-42c-protections/my-sec-headers"
                }
            ]
        }
    }
],
...       

To apply a protection strategy to a particular operation or response, you can add the extension x-42c-local-strategy to the element you want and define the protection strategy for it. You can also use the optional field compose to provide additional instructions to the compiler on the order of the local and global strategy:

  • override: The local strategy completely overrides the global strategy. This is the default value unless otherwise specified in the local strategy in the operation or response.
  • addBefore: The local strategy is applied before the global strategy.
  • addAfter: The local strategy is applied after the global strategy.

Note Pay attention to the order that you define for global and local strategies. If you need the result of one strategy to stand, be careful not to change it by what is run after it.

...
"paths": {
    "/api/login": {
        "post": {
            ...
            "responses": {
                "200": {
                    "x-42c-local-strategy": {
                        "name": "my-strategy-login-200",
                        "compose": "override",
                        "x-42c-strategy": {
                            "protections": [
                                {
                                    "$ref": "#/components/x-42c-protections/my-sec-headers-200"
                                },
                            ...
                            ]
                        }
                    }
                }
            }
        }
    }
...