Skip to content

API Specification Enforcement Setup

This article describes how to enable and configure your API protection based on your uploaded API specification.

Step 1: Upload specification

  1. In the API Specifications section in US Cloud or EU Cloud, click Upload specification.

  2. Set specification upload parameters and start uploading.

    Upload specification

Note that you will not be able to start configuring API specification enforcement, until the specification file is successfully uploaded.

Step 2: Set actions for violations of policies

  1. Click the API specification enforcement tab.

    Rogue API detection

    • Besides applying security policies, specifications may be used by API Discovery module for the rogue API detection. The tab is displayed if API Discovery is enabled.
    • Before using the specification for applying security policies, it is recommended to use it for searching the rogue (shadow, zombie and orphan) APIs using API Discovery. This way you will be able to understand how much your specification differs from the actual requests of your clients - these differences will most probably cause blocking related requests after applying security policies.

  2. Select Use for API specification enforcement.

  3. Specify host or endpoint for which you want to activate policy violation actions.

    • Note that if you incorrectly specify to which endpoints the uploaded specification should be applied, there will be many false positive events.
    • If you have several specifications that apply to the same host, but to different endpoints (for example domain.com/v1/api/users/ and domain.com/v1/api/orders/), you must indicate to which endpoints the specification should be applied.
    • If you add a specification to a host, and then add another specification to individual endpoints of this host, both specifications will be applied to these endpoints.
    • The value can be configured via the URI constructor or advanced edit form.

  4. Set how the system should react if requests violate your specification.

    Specification - use for applying security policies

    Details on possible violations:

    • Requesting an undefined endpoint - a request targets the endpoint not presented in your specification
    • Requesting endpoint with undefined parameter - a request contains the parameter not presented for this endpoint in your specification
    • Requesting endpoint without required parameter - a request does not contain the parameter or its value that are marked as required in your specification
    • Requesting endpoint with invalid parameter value - a request parameter's value in not in correspondence with its type/format defined by your specification
    • Requesting endpoint without authentication method - a request does not contain the information about the authentication method
    • Requesting endpoint with invalid JSON - a request contains an invalid JSON

    The system can perform the following actions in case of found inconsistency:

    • Block - block a request and put in the Attacks section as blocked

      Filtration mode

      The Wallarm node will block requests only when the blocking filtration mode is enabled for target endpoint - otherwise, Monitor action will be performed.

    • Monitor - mark a request as incorrect, but do not block, put it in the Attacks section as monitored

    • Not tracked - do nothing

    Note that several specifications can be used for setting policies. In case when one request falls on two different specifications (the same policy and different actions in different specifications), the following will happen:

    • Block and Block - the request will be blocked and two events will be added to the Attacks section with status Blocked pointing at the reason of blocking and at the fact that the request violated two different specifications.
    • Monitor and Block - the request will be blocked and one event will be added to the Attacks section with status Blocked explaining the reason of blocking.
    • Monitor and Monitor - the request will not be blocked and two events will be added to the Attacks section with status Monitoring pointing at the fact that specific policy was violated.

    When using the specification for setting security policies for the first time, it is recommended to set Monitor as a reaction to make sure that the specification is applied to the necessary endpoints and detects real errors.

Step 3: Configure specific cases or disable

You need additional configuration when using API Specification Enforcement with the NGINX-based Wallarm nodes installed with:

You need to:

  1. Add the following snippet in the NGINX configuration files, in each server section where API Specification Enforcement should run:

    location ~ ^/wallarm-apifw(.*)$ {
    wallarm_mode off;
    proxy_pass http://127.0.0.1:8088$1;
    error_page 404 431         = @wallarm-apifw-fallback;
    error_page 500 502 503 504 = @wallarm-apifw-fallback;

    allow 127.0.0.0/8;
    deny all;
}
location @wallarm-apifw-fallback {
    wallarm_mode off;
    return 500 "API FW fallback";
}

  2. As API Specification Enforcement does not support gRPC, if some of your nodes or locations/servers use gRPC, disable API Specification Enforcement for them as described below.

Disabling

In some cases that may be necessary to disable the API Specification Enforcement functionality for some parts of your API. This can be done:

Troubleshooting

After installation of the Wallarm node version 4.10.4 or later, in Docker or NGINX log files, you may obtain the following error messages related to API Specification Enforcement, like:

2024/04/26 15:12:53 [error] 42#42: *15 Please modify your Nginx configuration in order to enable OpenAPI Enforcement
Put the next snippet into 'server' block with server_name '<SERVER_NAME>':
== begin of the config snippet ===

<CONFIG_SNIPPET>

== end of the config snippet ===
, client: 127.0.0.1, server: <SERVER_NAME>, request: "GET / HTTP/1.1", host: "127.0.0.1"```

If you get this message:

  • Ignore it if you do not intend to use API Specification Enforcement

  • To properly configure API Specification Enforcement and/or remove error messages, place <CONFIG_SNIPPET> described in Step 3 into server section(s) with mentioned <SERVER_NAME>.