Protections and security extensions

The OpenAPI Specification (OAS) offers a good standard for describing for REST APIs, what they can do, and how they should be used, but it does have its limitations. It concentrates on the mechanics of the API and describes the functional elements, but it does not offer much in terms of protecting your API.

42Crunch aims to plug this hole. Out of the box, API Firewall protects your API by automatically enforcing the API contract spelled out in your API definition on all API traffic, both incoming requests and outgoing responses. In addition, you can apply additional protections to your API (such as rate limiting, security headers, or JWT policies) with specific vendor extensions to the OAS: x-42c security extensions.

Protections apply security as code, making it part of the source code of the API, not a separate afterthought. They provide instructions to API Firewall on how your APIs should be treated and protected, and fine-tune the positive security model for the whole API or individual operations.

Protections

Protections are the base units of API Protection. A protection defines a workflow of actions that API Firewall executes as well as the parameters that these actions require. For example, a protection could apply rate limiting for incoming API calls, or apply security headers to outgoing responses.

Protections are applied in the order you define for them when you add them in your OpenAPI definition using the x-42c security extensions.

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

Security extensions

Security extensions are the mechanics of applying security as code. You add protections (themselves also x-42c extensions) directly to your OpenAPI definition and use security extensions to, for example, define the scope of the protection.

When you create a protection configuration for API Firewall to protect your API with, API Protection creates the configuration based on the OpenAPI definition of the API and enriches it with the security information from the protections. API Protection builds the sequences of actions that the firewall will execute on incoming requests and outgoing responses based on the protections you have applied to your API. This is the configuration that the API Firewall instance loads when it starts.

Protections are applied as strategies. A strategy is a set of protections that API Firewall applies to API traffic in the defined sequence when processing requests or responses. A strategy can contain only one protection, or as many as you want.

Regardless of how many protections you want to add, you define them under the extension x-42c-strategy. This extension indicates that a section on security measures begins here:

       x-42c-strategy:
         protections:
           - x-42c-request-limiter_0.1:
               # ...

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 on how to apply protections to your APIs, see Apply additional protections. For more details on the different security extensions, see x-42c extensions.

Local and global protections

The x-42c strategy extensions define the scope of the protection you apply. You can add protections to your API on three different levels:

• Locally to paths, operations, responses, or HTTP status codes in your API (the extension x-42c-local-strategy):

  /api/user/info:
      get:
          x-42c-local-strategy:
              x-42c-strategy:
                  protections:
                      - x-42c-request-limiter_0.1:
                          # ...

• On the global level of your API to all incoming requests (the extension x-42c-request-strategies):

  x-42c-request-strategies:
      - x-42c-strategy:
          protections:
              - x-42c-request-limiter_0.1:
                  # ...

• On the global level of your API to all outgoing responses (the extension x-42c-response-strategies):

  x-42c-response-strategies:
      - x-42c-strategy:
          protections:
              - x-42c-security-headers_0.1:
                  # ...

Defining local protections in individual operations is an easy way to start with protections and see how they work. It also gives the most granular control, but may be arduous in the long run, especially as APIs usually have plenty of different operations. It may therefore make more sense to define the baseline of protections for all requests and all responses, and then define local protections that replace the protections defined globally. This way, you can apply robust security exactly where it is needed.

Pay attention to the order that you define for 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. API Firewall enforces whatever order you have defined and does not consider if it is logical or not.