Apply additional protections

API Firewall protects your APIs out of the box using a positive security model based on enforcing the constraints expressed in your OpenAPI definitions. On top of this, you can apply additional protections for your API directly in its API definition, adding security as code. The x-42c extensions enable you to provide instructions to API Firewall on how your APIs should be treated and protected.

You can apply the extensions to your OpenAPI definitions in the editor of your choice or in Security Editor in 42Crunch Platform. If you edit the API definitions outside the platform, remember to upload the updated API definition to the platform.

Add protections to your API definition

A protection defines a workflow of actions that API Firewall executes as well as the parameters that these actions require. 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.

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.

The following additional protections are available:

• Access control based on IP address range
• Client IP address override
• JWT validation
• Rate limiting by key
• Rate limiting by IP address
• Security headers

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

Add protections locally in your API

You can apply protections to paths, operations, responses, or even specific HTTP status codes as local strategies. This gives you a very granular control on the scope of the protections and lets you apply robust security exactly where it is needed. This is also a good way to start with protections and see how they work.

Local protections override protections applied on a higher level in your API. For example, if you have applied a protection both to a response and a particular HTTP status code, the protection applied to the status code will override the protection applied to the response.

1. Open your OpenAPI definition for editing, and go to the spot where you want to apply the protection.
2. Add the extension x-42c-local-strategy (see x-42c-local-strategy). This extension specifies that the protection applies only where it has been defined:

   /api/user/info:
       get:
           x-42c-local-strategy:

3. Add the extension x-42c-strategy. This extension indicates that a section on security measures (the protections) begins here:

   /api/user/info:
       get:
           x-42c-local-strategy:
               x-42c-strategy:

4. Add an array protections to gather all protections you want to add here:

   /api/user/info:
       get:
           x-42c-local-strategy:
               x-42c-strategy:
                   protections:
   

5. List the protections you want to include, and define at least the required parameters. For the full list of available protections and all their parameters, see Protections.
   
   For example, to add rate limiting, you specify the protection type x-42c-request-limiter_0.1 and define the values for the required parameters (here key, hits, and window):

   /api/user/info:
       get:
           x-42c-local-strategy:
               x-42c-strategy:
                   protections:
                       - x-42c-request-limiter_0.1:
                           key: req_limiter_login
                           hits: 2
                           window: 10
                       # ...

6. When you are ready, save the API definition.

The applied protections — or any changes you make to them later — take effect after you reconfigure API Firewall for the updated API. For more details, see Reconfigure API Protection.

You can find the details of the requests and responses that API Firewall blocked in the transaction logs through Trace Explorer or from the Protection tab of your API.

Applying protections locally is simple, but might be arduous in the long run, especially if your API has plenty of paths and operations. You might want to establish a baseline of protections for all requests and all responses, and use local protections for exceptions to these baselines.

Add protections to all incoming requests

Instead of separately defining protections that you always want to apply to requests from API consumers, you can define them on the global level of your API to apply them to all incoming API requests. You can then add exceptions to this baseline protection with the local protections.

1. To apply protections to all incoming requests, add the extension x-42c-request-strategies (see x-42c-request-strategies) on the top level of your API:

   #...
   x-42c-request-strategies:
   

2. Add the extension x-42c-strategy:

   #...
   x-42c-request-strategies:
       - x-42c-strategy:
   

3. Add an array protections containing the protections you want to apply, for example:

   #...
   x-42c-request-strategies:
       - x-42c-strategy:
           protections:
               - x-42c-request-limiter_0.1:
                   key: req_limiter_login
                   hits: 3
                   window: 15
               # ...
   

4. To restrict the protections to apply to only particular operations (methods), add a property operations and define an array of the verbs you want:

   #...
   x-42c-request-strategies:
       - operations:
           - post
           - put
         x-42c-strategy:
           protections:
               - x-42c-request-limiter_0.1:
                   key: req_limiter_login
                   hits: 3
                   window: 15
               # ...
   

   The protections now only apply to the listed operations (here POST and PUT).

5. When you are ready, save the API definition.

The applied protections — or any changes you make to them later — take effect after you reconfigure API Firewall for the updated API. For more details, see Reconfigure API Protection.

You can find the details of the requests and responses that API Firewall blocked in the transaction logs through Trace Explorer or from the Protection tab of your API.

Add protections to all outgoing responses

Instead of separately defining protections that you always want to apply to responses your API sends back to API consumers, you can define them on the global level of your API to apply them to all outgoing API requests. You can then add exceptions to this baseline protection with the local protections.

1. To apply protections to all outgoing responses, add the extension x-42c-response-strategies (see x-42c-response-strategies) on the top level of your API:

   #...
   x-42c-response-strategies:
   

2. Add the extension x-42c-strategy:

   #...
   x-42c-response-strategies:
       - x-42c-strategy:
   

3. Add an array protections containing the protections you want to apply. for example:

   #...
   x-42c-response-strategies:
       - x-42c-strategy:
           protections:
               - x-42c-security-headers_0.1: 
                   hsts.max_age: 7200
                   csp.policy: [default-src: 'self'; upgrade-insecure-requests; block-all-mixed-content]
                   mode: add-replace
               # ...
   

4. To restrict the protections to apply to only particular responses, add a property status and define an array of the responses you want:

   #...
   x-42c-response-strategies:
       - status:
           - default
           - 200
           - 500
         x-42c-strategy:
           protections:
               - x-42c-security-headers_0.1: 
                   hsts.max_age: 7200
                   csp.policy: [default-src: 'self'; upgrade-insecure-requests; block-all-mixed-content]
                   mode: add-replace
               # ...
   

   The protections now only apply to the listed responses.

5. When you are ready, save the API definition.

The applied protections — or any changes you make to them later — take effect after you reconfigure API Firewall for the updated API. For more details, see Reconfigure API Protection.

You can find the details of the requests and responses that API Firewall blocked in the transaction logs through Trace Explorer or from the Protection tab of your API.