Fortinet black logo

Administration Guide

API patterns and paths

API patterns and paths

After an API protection policy is created, the system will start collecting API requests to all the URL paths in the domain. It parses the data and then learns the parameter and body of the API requests.

Restricting API learning to specific API paths

The system by default learns API requests to all the URL paths of the domain. If you want to restrict the learning to certain API paths, you can add API learning patterns so that only the URL paths matching the specified pattern will be learned.

To add an API learning pattern:

  1. Go to Machine Learning > API Protection.
  2. Select the API protection policy for which you want to edit its API pattern.
  3. Click Edit to enter into the Edit API Protection Configuration page.
  4. Click the number in the API Path column in Domain List.
  5. Under API Learning Patterns, click Create New.
  6. For URL Type, select whether the API pattern must contain a literal URL (Simple String), or a regular expression designed to match multiple URLs (Regular Expression).
  7. For URL Expression, type either:
    1. The literal URL, such as /folder1/index.htm that the HTTP request must contain in order to match the rule, or use wildcards to match multiple URLs, such as /folder1/* or /folder1/*/index.htm. The URL must begin with a slash ( / ).
    2. A regular expression, such as ^/*\.jsp\?uid\=(.*), matching all and only the URLs to which the rule should apply. The pattern does not require a slash ( / ); however, it must at least match URLs that begin with a slash, such as /profile.cfm.

      Do not include the domain name, such as www.example.com, which is configured separately in the Host drop-down list.

      To create and test a regular expression, click the >> (test) icon. This opens the Regular Expression Validator window where you can fine-tune the expression. For details, see Regular expression syntax and Cookbook regular expressions.

  8. Click OK.

Editing machine learning models for API paths

The system learns the parameters and body for each API path in the domain and lists them under Machine Learning Models for API Paths. You can view and edit the learned data.

To edit the parameters and body of an API path:

  1. Go to Machine Learning > 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 number in the API Path column in Domain List.
  5. Under Machine Learning Models for API Paths, click the row of a specific path, then click Edit; Or double click the desired row.
  6. 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 CountSpecify the number of samples that the system will collect for this API path.
  7. Check the parameters learned by the machine learning model. If some parameters are missing, you can click Create New to add them.
  8. Configure the following settings for the parameter:
    NameEnter a name for the parameter.
    DescriptionEnter 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.

  9. 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.

  10. 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)

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 Machine Learning > 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 number in the API Path column in Domain List.
  5. Under Machine Learning Models for API Paths, 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.

API patterns and paths

After an API protection policy is created, the system will start collecting API requests to all the URL paths in the domain. It parses the data and then learns the parameter and body of the API requests.

Restricting API learning to specific API paths

The system by default learns API requests to all the URL paths of the domain. If you want to restrict the learning to certain API paths, you can add API learning patterns so that only the URL paths matching the specified pattern will be learned.

To add an API learning pattern:

  1. Go to Machine Learning > API Protection.
  2. Select the API protection policy for which you want to edit its API pattern.
  3. Click Edit to enter into the Edit API Protection Configuration page.
  4. Click the number in the API Path column in Domain List.
  5. Under API Learning Patterns, click Create New.
  6. For URL Type, select whether the API pattern must contain a literal URL (Simple String), or a regular expression designed to match multiple URLs (Regular Expression).
  7. For URL Expression, type either:
    1. The literal URL, such as /folder1/index.htm that the HTTP request must contain in order to match the rule, or use wildcards to match multiple URLs, such as /folder1/* or /folder1/*/index.htm. The URL must begin with a slash ( / ).
    2. A regular expression, such as ^/*\.jsp\?uid\=(.*), matching all and only the URLs to which the rule should apply. The pattern does not require a slash ( / ); however, it must at least match URLs that begin with a slash, such as /profile.cfm.

      Do not include the domain name, such as www.example.com, which is configured separately in the Host drop-down list.

      To create and test a regular expression, click the >> (test) icon. This opens the Regular Expression Validator window where you can fine-tune the expression. For details, see Regular expression syntax and Cookbook regular expressions.

  8. Click OK.

Editing machine learning models for API paths

The system learns the parameters and body for each API path in the domain and lists them under Machine Learning Models for API Paths. You can view and edit the learned data.

To edit the parameters and body of an API path:

  1. Go to Machine Learning > 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 number in the API Path column in Domain List.
  5. Under Machine Learning Models for API Paths, click the row of a specific path, then click Edit; Or double click the desired row.
  6. 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 CountSpecify the number of samples that the system will collect for this API path.
  7. Check the parameters learned by the machine learning model. If some parameters are missing, you can click Create New to add them.
  8. Configure the following settings for the parameter:
    NameEnter a name for the parameter.
    DescriptionEnter 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.

  9. 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.

  10. 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)

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 Machine Learning > 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 number in the API Path column in Domain List.
  5. Under Machine Learning Models for API Paths, 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.