Editing and viewing machine learning models for API paths

The system learns the parameters and body for each API path in the domain and lists them in the Path List tab. You can view and edit the learned data.

To edit the parameters and body of an API path:

1. Go to API Protection > ML Based API Protection.
2. Select the API protection policy which includes the API paths.
3. Click Edit to enter into the Edit API Protection Configuration page.
4. Click the domain name in the API Path column in Domain List.
   
5. Select the Path List tab.
6. Click the row of a specific path, then click Edit; Or double click the desired row.
   
7. Configure the following settings.
   

   Action	Select the action FortiWeb takes when attack is verified for each of the following situations: Alert—Accepts the request 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 Period Block 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.
   Sample Count	Specify the number of samples that the system will collect for this API path.

8. Check the parameters learned by the machine learning model. If some parameters are missing, you can click Create New to add them.
   
9. 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 } For more information, refer to Supported parameter and body structure.

10. Check the request body learned by the machine learning model. You can click Edit to modify them. For more information, refer to Supported parameter and body structure.
    
    
11. 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 supports the following types in parameter:

• boolean

• number

• string

• object (one level)

FortiWeb 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)

From 7.0.2, the string type hostname is not enabled by default, because it may lead to false positives. To enable it, run the following command: config waf api-learning-policy edit <api-protection-policy_ID> set data-format date-time date time email hostname ipv4 ipv6 end end

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 API 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" }

]

}

Viewing API path data

The system collects data such as URL Hits By Return Code and HTTP/HTTPS Request History for each API path.

To view the API path data:

1. Go to API Protection > ML Based API Protection.
2. Select the API protection policy which includes the API paths.
3. Click Edit to enter into the Edit API Protection Configuration page.
4. Click the domain name in the API Path column in Domain List.
   
5. Click the row of a specific path, then click .
   
6. You will see the following data for the API path:
   1. Overview information such as the start time to collect samples for this API path, the number of violations, the model status, etc.
   2. URL Hits by Return Code: The number of hits on this API path.
   3. HTTP/HTTPS Request History: The number of HTTP and HTTPS requests over the last 24 hours.
   4. API Protection Events: The API Protection events, such as sample collection, model running, new endpoints, along with the time periods when these events take place.