Configuring API Discovery

API Discovery policies allow FortiADC to automatically discover external API endpoints from HTTP/HTTPS requests and responses that have passed through API validity checks, wherein the API is parsed for information including the Host, Paths, parameters and their schemas from query requests or entity bodies, as well as classify parameters that match PII (Personal Identifiable Information) signatures. API Discovery also supports manually imported OAS files compliant with OpenAPI 3.0 and Swagger 2.0 standard to parse and discover as internal API endpoints that can also be matched by incoming API requests or responses. The discovered external and internal API endpoints can then be directly applied in API security rules based on the Host, Path, and request rate. Once the API requests and responses pass the API validity check that matches the rule, the specified security action will be triggered to protect against the malicious APIs.

API Discovery is based on VDOMs, where API endpoints are discovered and stored per VDOM. The total API endpoints database size for each VDOM is 1 GB.

API Discovery is based on VDOMs, where API endpoints are discovered and stored per VDOM.

Basic API Discovery workflow

API Discovery policies depend entirely on internal or external API endpoints to function. For external API endpoints to be discovered, the API Discovery policy must be referenced in a WAF Profile used in an active virtual server. Follow the basic workflow below to deploy API Discovery.

Basic steps:

1. Create and enable an API Discovery policy to enable automatic discovery for external API endpoints. For details, see Configuring automatic discovery for external API endpoints.
2. Reference the API Discovery policy in a WAF Profile. Once the WAF Profile is used in a virtual server, external API endpoints will be discovered from HTTP/HTTPS requests and responses. For details, see Configuring a WAF Profile.
3. Optionally, import an OAS file to parse and discovery as internal API endpoints. For details, see Manually import internal API endpoints.
4. Optionally, check and refresh the API View page for automatically discovered API endpoints.
5. Optionally, check the API Threats page under FortiView > Data Analytics to view all discovered API endpoints that have triggered attacks.

API endpoints database in API View

From the API View tab, you can view your database of discovered internal and external API endpoints. You can refresh the page to view newly discovered external API endpoints.

Each API endpoint is parsed for the following key elements:

API Information	Description
Host	The name of the protected host that the Host: field of an HTTP request must be in to match the API Discovery policy. Example: 110.ztnatest02.com Note: Maximum supported length of Host is 255 characters.
Base_URL	The base_url consists of the prefix HTTP/HTTPS and the Host. Example: http://110.ztnatest02.com Note: Maximum supported length of Base_URL is 255 characters.
Path	The resource path of the API. Example: /api/test
API Endpoint	The API endpoint is organized and displayed as the Path with HTTP method. Example: GET: /api/test
Parameter	Parsed from the HTTP query request or entity body. Example: path, required, internal

API View endpoint organization

Each API endpoint entry is identified and stored by its HTTP method and path. However, each entry is maintained per method, so in cases where endpoints share the same path but use different HTTP methods, a separate entry will be maintained per HTTP method.

API endpoints will be displayed in a simplified view when four or more requests that have a different integer as the last sub-path are discovered. In which case, the endpoints will be simplified and reorganized as a single endpoint template with the following specifications:

• The Path of the endpoint will be similar to /v1/users/{users_id}.

• An extra parameter will be generated, named “users_id” with a label “required”.

Supported API types and HTTP methods for API Discovery

• RESTful API — GET/POST/PUT with XML/JSON, or DELETE

• SOAP API — POST with SOAP+XML

• OAS file types — JSON or YAML

Prerequisites for APIs to be discovered

• The return code must be 200-299.
• The HTTP headers and corresponding entity body must have the following in the request/response:
  

  HTTP Method	Requirement
  GET	“Accept: application/json”, “Accept: application/xml” or “Accept: */*” in the request, and corresponding “Content-Type:” header with entity body in the response.
  PUT/POST	“Content-Type: application/json”, “Accept: application/xml” or “Accept: application/soap+xml” with corresponding entity body in the request.
  DELETE	No requirement; all DELETE requests can be discovered.

• For RESTful APIs: the last sub-path should not include the dot (.) character. SOAP API supports including the dot (.) in the last sub-path.

• For OpenAPI 3.0: servers and paths are required in the OAS file.

• For Swagger 2.0: host, paths & schemes are required in the OAS file.

API endpoint parameters

The API Discovery engine can parse through raw API data to extract information that make up an API endpoint.

Parameters can be parsed from the following API information:

Source	Parsed parameters
HTTP query request	Parameters can be parsed from the HTTP query request. For example: /query?username=admin&password=test username = admin password = test
Elements or keys in the entity body	For JSON API type, API Discovery parses up to 1 layer. For XML/SOAP API type, API Discovery parses up to 2 or 3 layers: If sub-elements have the same name, the schema of the elements will be recognized as an "array", and 3 layers of the nested parameters will be parsed. Otherwise, the parameters will be treated as an object, and only 2 layers of the nested parameters will be parsed.
Classification or labels of parameters	Position — requestBody, responseBody, query, path (for external API endpoints) Position (“in”) — query, path, header or cookie (for internal API endpoints) Required — the reorganized parameter {api_id} will be labeled as “required” (for external API endpoints); labeled if "required“ is true in files (for internal API endpoints) Source — external for API endpoints parsed from Automatic discovery, and internal for imported OAS files Description — added automatically for the template parameter (for external API endpoints); defined in the file (for internal API endpoints) Note: Maximum supported description length is 2048 characters.
PII (Personal Identifiable Information)	Scan name — Username, Password, Token Scan value — Credit Card Number, Email, URL, IP Address, GUID Scan name & value — CVV
Schema of parameters	String, number, integer, Boolean, object, array

Configuring automatic discovery for external API endpoints

External API endpoint discovery is automatically activated when the virtual server referencing the API Discovery policy receives API responses/requests. The API Discovery policy will automatically begin validating APIs and parsing endpoints to build your API endpoints database which can then be viewed in the API View page. From the API Discovery policy, you can add API Security rules to trigger alerts and actions against APIs identified as malicious through API Discovery.

The maximum number of API Discovery policies is 256.

To configure an API Discovery policy:

1. Go to Web Application Firewall > API Discovery.
   The configuration page displays the API Discovery tab.
2. Click Create New to display the configuration editor.
3. Configure the following settings:
   

   Setting	Description
   Name	Enter a unique API Discovery name. Valid characters should match regular expression /^[A-Za-z0-9.:_-]*$/. No space is allowed. Note: Once saved, the name of an Allowed Origin cannot be changed.
   API Discovery	Enable or disable the API Discovery configuration.

4. Click Save.
   Once the API Discovery configuration is saved, the API Security Rule section can be configured.
5. Under the API Security Rule section, click Create New to display the configuration editor.
   The maximum number of API security rules under one API Discovery policy is 256.
6. Configure the following API Security Rule settings:
   

   Setting	Description
   Host	Specify the HTTP Host header. This is required. Maximum length is 255 characters. Example: 192.168.0.253, [2001:1234::a41:6e]:8443, or demo.fortinet.com. Once the API Discovery policy is activated, the policy matches only if the Host header matches this value. Complete, exact matching is required. For example, www.example.com matches www.example.com but not www.example.com.hk.
   Path	Specify the API resource path. Text string and simple regex is supported. Example: /login. Begin with '/'.
   API Request Rate	Specify the allowable requests per second. Default: 0. Range: 0 - 100000000. Note: 0 means there is no limit.
   Action	Specify a WAF action object to apply when a bot is detected. See Configuring WAF Action objects. The default action is alert.
   Severity	Select the event severity to log when a bot is detected: High — Log as high severity events. Medium — Log as a medium severity events. Low — Log as low severity events. The default is Low.

7. Click Save.
   Once the API Security Rule configuration is saved, the dialog closes.
8. Click Save to update the API Discovery configuration with the API Security Rule changes.

After you have completed the API Discovery policy configuration, reference it in a WAF Profile that will be used in a virtual server.

If a previously enabled API Discovery policy is disabled, new API endpoints will not be discovered. However, the API security rules associated with that API Discovery policy will continue to work.

Manually import internal API endpoints

API Discovery supports manually imported OAS files compliant with OpenAPI 3.0 and Swagger 2.0 standard to parse and discover as internal API endpoints that can also be matched by incoming API requests or responses.

JSON and YAML file types are supported.

To import an OAS file:

1. Go to Web Application Firewall > API Discovery.
2. Click the API View tab.
3. Click Choose File to display the file upload dialog.
4. Locate and select the OAS file to import.
   After the OAS file is successfully imported, the file contents are parsed into internal API endpoints that can be viewed on the API View page.