Configuring API Protection Policy

The machine learning based API Protection learns the REST API data structure from user traffic samples and then build a mathematical model to screen out malicious API requests.

It analyzes the method, URL, and endpoint data of the API request samples to generate an API data structure file for your application. This file describes the URL pattern and schema of endpoint data. If the incoming API request violates the data structure, it will be detected as an attack.

API Protection supports JSON request body.

API Protection policies are part of a server policy. They are created on the Policy > Sever Policy page. All API Protection policies that you have created are displayed on the Machine Learning > API Protection page, where you can edit them to your preference.

To configure an API Protection policy:

1. Click Machine Learning > API Protection .
2. Double-click the server policy that contains the desired API Protection policy (or highlight it and then click the Edit button on top of the page) to open it. The Edit API Protection Configuration page opens, which breaks down API Protection policy into several sections, each of which has various parameters you can use to configure the policy.
3. Add domains to be protected by the API Protection Policy.
   1. Click Create. The Allow sample collection for domains page will open.
   2. Enter the host address. You can enter the exact string or use wildcard to match multiple domains.
   3. Click OK.

   The system will start building API Protection model when 100 API request samples are collected for the specified domain. You can change the sample count through set start-training-cnt <int> in config waf api-learning-policy.

4. Configure the action that FortiWeb will take when it detects malicious API requests.

5. Action	All requests are scanned first by HMM and then by Threat model. Double click the cells in the Action Settings table to choose the action FortiWeb takes when attack is verified for each of the following situations: Alert—Accepts the connection and generates an alert email and/or log message. Alert & Deny—Blocks the request (or resets the connection) and generates an alert and/or log message. Block Period—Blocks the request for a certain period of time.
   Block Period	Enter the number of seconds that you want to block the requests. The valid range is 1–3,600 seconds (1 hour). This option only takes effect when you choose Block Period in Action.
   Severity	Select the severity level for this anomaly type. The severity level will be displayed in the alert email and/or log message.
   Trigger Action	Select a trigger policy that you have set in Log&Report > Log Policy > Trigger Policy. If potential or definite anomaly or HTTP Method Violation is detected, it will trigger the system to send email and/or log messages according to the trigger policy.

6. Add IP ranges in the Source IP list, then select Trust or Black to allow or disallow collecting traffic data samples from these IP addresses.
   1. Trust: The system will collect samples only from the IP ranges in the Source IP list.
   2. Block: The system will collect sample from any IP addresses except the ones in the Source IP list

   Whether selecting Trust or Black, if you leave the Source IP list blank, the system will collect traffic data samples from any IP addresses.

7. Select the name of the URL Replacer Policy that you have created in Machine Learning Templates.

   If web applications have dynamic URLs or unusual parameter styles, you must adapt URL Replacer Policy to recognize them.

   If you have not created an URL Replacer Policy yet, you can leave this option empty for now, and then edit this policy later when the URL Replacer Policy is created. For more information on URL Replacer Policy, see Configure a URL replacer rule

8. Click OK when done.

The system collects samples for the specified domains and analyzes the parameter, body, and the response structure of API requests to all the API paths in the domain.

To view the data structure learned for each API path and adjust its action and sample count settings, perform the following steps:

1. Click the number in the API Path column in Domain List.
   
2. Under Machine Learning Models for API Paths, click the row of a specific path, then click Edit; Or double click the desired row.
   
3. Configure the Action, Block Period, Severity, and Sample count settings which apply only to this specific API path.
4. Check the request and response body learned by the system. You can click Edit to modify them.
   
5. If the machine learning model missed some parameters in the API request, you can click Create New to add them.
   
6. Configure the following settings for the parameter:
   

   Name	Enter a name for the parameter.
   Description	Enter a brief description for this parameter.
   In	Currently FortiWeb only support adding the query parameters in API schema. The path parameters in API schema is not supported yet.
   Required	True: This parameter is required. If the API request doesn't contain this parameter, it will be detected as a violation. False: This parameter is optional.
   Schema	Enter the data structure of this parameter. For example: { "type": "string", "maxLength": 5, "minLength": 1 }

7. Click OK.