ML Based API Protection
The AI-based API Protection builds mathematical models for Schema Protection and Threat Protection. The Schema Protection model learns the REST API data structure from user traffic samples and then compiles a schema file to screen out malformed API requests. The Threat Protection model learns the patterns of the parameter value in the API request body and then builds models to screen out requests which have abnormal values in its body.
Model Settings
To configure an API Protection rule:
- Go to API PROTECTION > ML Based API Protection.
You must have already enabled this module in Add Modules. See How to add or remove a module. - Select the Model Settings tab.
- Based on the samples collected, the system learns the patterns of the parameter value in the API request body and then builds Threat Protection models to screen out requests which have abnormal values in their body.
Select the action to take when abnormal parameter values are detected:- Alert: Accept the request and generate a log message.
- Alert&Deny: Block the request (or reset the connection) and generate a log message.
- Standby: Do not take any action.
Please note that in addition to the Threat Protection model that screens out API requests with abnormal parameter values, the system also builds an Schema Protection model to detect API requests which are malformed. It compiles an API schema file and screens out malformed API requests against the schema file. The Schema Protection data can be viewed in the API Collection tab.
- Configure the Data Collection Settings.
IP List Type - Trust: FortiWeb Cloud collects API request samples only from the Trust source IP addresses.
- Block: FortiWeb Cloud collects API request samples from all source IP addresses except the ones in the Block list.
If the IP List Type is Trust and the Source IP List is empty, FortiWeb Cloud will not collect samples from any Source IP address.
If the IP List Type is Block and the Source IP List is empty, FortiWeb Cloud will collect samples from all Source IP addresses.
The IP list only restricts where the samples come from. Once the model is built, requests from other source IP addresses will also be scanned by the IP Protection model.
Source IP List Click Create New to add the source IP list. This option is used together with IP List Type. API Learning Patterns If you want to limit the API protection learning to certain API paths, click Create New in the API Learning Patterns section, then enter either a string match API path or regular expression.
Please note that only the specified API paths will be protected by the API Protection module.
API Collection
To view and edit API paths learned by the Schema Protection model:
-
Go to API PROTECTION > ML Based API Protection.
You must have already enabled this module in Add Modules. See How to add or remove a module. - Select the API Collection tab. This page lists all the API paths learned by machine learning model.
Please note that the default action for Schema Protection is Standby. You can click into each API path and change the action. - Click the Edit icon
on the API path row to view and edit the parameter, request body, and response body learned by the model. - Select the action to take when malformed API request to this API path is detected.
- Alert: Accept the request and generate a log message.
- Alert&Deny: Block the request (or reset the connection) and generate a log message.
- Standby: Do not take any action.
- Click the Parameter tab under Request section, check the parameters learned by the machine learning model. If some parameters are missing, you can click Create Parameter to add them.
If you don't want certain parameter to be protected, click the Remove icon on the corresponding parameter row. - To edit the parameter, click the Edit icon of the parameter to be edited. Configure the following settings.
Name Enter a name for the parameter. Description Enter a brief description for this parameter. In Currently FortiWeb Cloud 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.
SchemaEnter the data structure of this parameter. For example:
{
"type": "string",
"maxLength": 5,
"minLength": 1
}
For more information, refer to Supported parameter and body structure.
- Click the body tab under Request section. Check the request body learned by the machine learning model. You can click Edit icon to modify them. For more information, refer to Supported parameter and body structure.
- Under Response section, check the response body to be sent to the client. You can click the Edit icon to modify them. For more information, refer to Supported parameter and body structure.
- Click OK.
Supported parameter and body structure
The parameters and the body schema should follow the API 2.0 specification. Refer to : https://swagger.io/specification/
FortiWeb Cloud supports the following types in parameter:
-
boolean
-
number
-
string
-
object (one level)
FortiWeb Cloud supports the following types in body:
-
boolean
-
number
-
string
-
array
-
object
For the "string" type in parameter and body, the following formats are supported:
-
data-time (rfc3339)
-
date (rfc3339)
-
time (rfc3339)
-
email (rfc5322)
-
hostname (rfc1034)
-
ipv4 (rfc2673)
-
ipv6 (rfc2373)
Examples:
{“type”: “string”,
"maxLength": 5,
"minLength": 1,
"pattern": "^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$"}
{“type”: “string”,
“format” : “email”
}
Please note the "format" and "pattern" can be learned by the Schema Protection model, but you can manually add it for the system to validate the API requests against.
{“type”: “number”,
"minimum": 0,
"maximum": 100
}
{“type”: “array”,
"items": {"type": "number"
}
"minItems": 2,
"maxItems": 3
}
{“type”: “object”,
"properties": {"number": { "type": "number" },"street_name": { "type": "string" }},
"required": [" number "]
}
Combined types in schema are supported. For example:
{"oneOf": [
{ "type": "number"},{ "type": "string" }]
}