Fortinet black logo

CLI Reference

waf api-learning-policy

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-learning-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 | standby}

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>

next

end

Variable

Description Default
<api-learning-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.

No default

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.

standby—Selecting standby 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

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-learning-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 | standby}

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>

next

end

Variable

Description Default
<api-learning-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.

No default

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.

standby—Selecting standby 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