waf api-learning-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 model describes the API data schema model of endpoint data. If the incoming API request violates the data structure, it will be detected as an attack.

Use this command to edit machine learning based API Protection policies.

To use this command, your administrator account’s access control profile must have either w or rw permission to the wafgrp area. For details, see Permissions.

Syntax

config waf api-learning-policy

edit <api-protection-policy_ID>

set policy-id <index>

set status {enable | disable}

set ip-list-type {Trust | Black}

set start-training-cnt <integer>

set url-replacer-policy <string>

set action-mlapi {alert | alert_deny | block-period | bypass}

set block-period-mlapi <integer>

set severity-mlapi {High | Medium | Low | Info}

set trigger-mlapi <datasource>

set schema-property {maximum | minimum | maxLength | minLength | maxItems | minItems}

set data-format {date-time | date | time | email | hostname | ipv4 | ipv6}

set de-duplication-all {enable | disable}

set de-duplication-count <integer>

set schema-required-ratio <integer>

set schema-ignored-ratio <integer>

end

Variable	Description	Default
<bot-detection-policy_id>	Specify the API protection policy ID.	`No default`
policy-id <index>	Specify the server policy ID to associate this API protection policy with.
status {enable \| disable}	Enable or disable API protection.	`enable`
ip-list-type {Trust \| Black}	Allow or deny sample collection from the Source IP list.	`trust`
start-training-cnt <integer>	The system will start building API Protection machine learning model if the sample count reaches the `start-training-cnt`.	`No default`
url-replacer-policy <datasource>	Specify the URL replacer policy you want to use. If your applications have dynamic URLs or unusual parameter styles, you must use URL Replacer Policy to recognize them. See waf machine-learning url-replacer-rule/policy for more information.	`No default`
action-mlapi {alert \| alert_deny \| block-period}	Choose the action FortiWeb takes when an API attack is detected. `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. `bypass`—Selecting `Bypass` will activate the continuous learning mode. The system will continuously adjust the API learning models to adapt to changes in the API schema. This includes scenarios such as the introduction of new APIs, modifications to existing parameters, etc. It is important to note that blocking violations is not supported in continuous learning mode at present. However, you can go to API View to download the learned schema, then upload it to API Validation, which allows you to block malformed API requests.	`alert_deny`
block-period-mlapi <integer>	Enter the number of seconds that you want to block the requests. The valid range is 1–3,600 seconds. This option only takes effect when you choose Period Block in Action.	`600`
severity-mlapi {High \| Medium \| Low \| Info}	Select the severity level for this anomaly type. The severity level will be displayed in the alert email and/or log message.	`High`
trigger-mlapi <datasource>	Select a trigger policy that you have set in Log&Report > Log Policy > Trigger Policy. If an API attack is detected, it will trigger the system to send email and/or log messages according to the trigger policy.	`No default`
schema-property {maximum \| minimum \| maxLength \| minLength \| maxItems \| minItems}	In the learned model, it could include these properties and data formats under the string type. Specify the schema properties that will be learned by the API Protection machine learning model.	`No default`
data-format {date-time \| date \| time \| email \| hostname \| ipv4 \| ipv6}	Specify the data format that will be learned by the API Protection machine learning model.	`No default`
schema-required-ratio <integer>	The `schema-required-ratio` is the threshold for the required type. If the percentage of samples including a certain field is over the `schema-required-ratio`, this field will be treated as the required type and learned in the final model.	`No default`
schema-ignored-ratio <integer>	If the percentage of samples including a certain field is lower than the `schema-required-ratio`, this field will be discarded in the final model.	`No default`