Configuring a threat feed

A threat feed can be configured on the Security Fabric > External Connectors page. After clicking Create New, there are four threat feed options available: FortiGuard Category, IP Address, Domain Name, and Malware Hash. When configuring the threat feed settings, the Update method can be either a pull method (External Feed) or a push method (PUSH API).

This topic includes three example threat feed configurations:

• Configuring a threat feed with an external feed update

• Configuring threat feed authentication

• Configuring a threat feed with a push API update

When multi VDOM mode is enabled, threat feed external connectors can be defined in the global VDOM or within a VDOM. See Threat feed connectors per VDOM for example configurations.

Configuring a threat feed with an external feed update

The threat feed will periodically fetch entries from the URI using HTTP or HTTPS.

To configure the threat feed in the GUI:

1. Go Security Fabric > External Connectors and click Create New.

2. In the Threat Feeds section, select the required feed type.

3. Configure the connector settings:

   Status	Enable/disable the connector.
   Name	Enter a name for the threat feed connector.
   Update method	Select External Feed.
   URI of external resource	Enter the link to the external resource file. HTTP, HTTPS, and STIX protocols are supported.
   HTTP basic authentication	Enable/disable basic HTTP authentication. When enabled, enter the username and password in the requisite fields. See Configuring threat feed authentication for more information.
   Refresh Rate	The time interval to refresh the external resource, in minutes (1 - 43200, default = 5). The applicable threat feed will be triggered to refresh between 0 minutes and the configured value. When the refresh is triggered, if another task is being processed be the schedule worker, the refresh task will be added to the queue.
   Comments	Optionally, enter a description of the connector.

4. Click OK.

To configure the threat feed in the CLI:

config system external-resource
    edit <name>
        set status {enable | disable}
        set type {category | address | domain | malware}
        set category <integer, 192-221>
        set update-method {feed | push}
        set username <string>
        set password <string>
        set comments <string>
        *set resource <resource-uri>
        set user-agent <string>
        set server-identity-check {none | basic | full}
        set refresh-rate <integer>
        set source-ip <ip address>
        set interface-select-method {auto | sdwan | specify}
    next
end

The parameter marked with an asterisk (*) is mandatory and must be filled in. The category parameter must be set when the type is either category or domain. Other parameters have either default values or are optional.

To improve the security of the connection, it is recommended to enable server certificate validation (server-identity-check) either in basic or full mode.

Configuring threat feed authentication

Threat feed external connectors support username and password authentication.

The HTTP basic authentication field is only visible when the Update method is set to External Feed.

To enable username and password authentication in a threat feed connector:

1. Go Security Fabric > External Connectors.

2. Click Create New, or edit an existing threat feed connector.

3. Enable HTTP basic authentication.

4. Enter the Username and Password.

   

5. Click OK.

HTTP header

Additional headers can be included in the user-agent field. Use \r\n to separate the URL headers, for example:

# set user-agent "Firefox\r\nheader1: test1\r\nheader2: test2"

Sample request:

    HTTP request: http
    GET /filetypes/test.tar.gz HTTP/1.1
    Host: 172.17.219.10
    User-Agent: Firefox
    header1: test1
    header2: test2
    Accept: */*
    Connection: close

Threat feed external connectors use this functionality to support authentication using an API key. The API key authentication can only be configured in the CLI with the set user-agent command. The API key must be appended with user-agent in the following format: “user-agent\r\nAPI-Key:SecretAPIkey”. API keys are typically used for programmatic access to the resource by an authorized requester. See What Is an API Key in the Fortinet Cyber Glossary for more information.

To enable API key authentication in a threat feed connector:

1. Configure the threat feed. See Configuring a threat feed with an external feed update.

2. Configure the user-agent with an API key:

   config system external resources
       edit <name>
           set user-agent "Firefox\r\nAPI-Key:abcdef12345"
       next
   end

See Using the AusCERT malicious URL feed with an API key for an example.

Configuring a threat feed with a push API update

The threat feed receives entry updates from webhook requests to the FortiGate REST API. This method provides the code samples needed to perform add, remove, and snapshot operations.

In the following example, a FortiGuard Category threat feed is used to show the different API push options.

To configure the threat feed in the GUI:

1. Go to Security Fabric > External Connectors and click Create New.

2. In the Threat Feeds section, click FortiGuard Category.

3. Enter a name.

4. Set the Update method to Push API.

5. Click OK. The Threat Feed Push API Information pane opens that contains the following fields:

   • URL: the FortiGate's API URL to call in order to perform the update.

   • API admin key: when an API administrator user is configured on the FortiGate, an API admin key will be associated with the API administrator. Input the API key to see the final cURL request.

   • Push command: select one of three push methods.

     • Add: add the specified entries to the threat feed.

       

     • Remove: remove the specified entries from the threat feed.

       

     • Snapshot: replace the threat feed with all specified entries.

       

   • Entries: enter the entries separated by a comma (,) to be applied to the FortiGuard Category threat feed list.

   • Sample cURL request: copy this cURL command to perform the push API update on the FortiGate against the list (cccccccc).

   See REST API administrator for more information.

6. Copy the content in the Sample cURL request field (Add is used in this example).

7. Click OK.

8. On a client, generate the API request for the threat feed.

To configure the threat feed in the CLI:

config system external-resource
    edit "cccccccc"
        set update-method push
        set category 201
    next
end

To use the API in the CLI:

# diagnose system external-resource {push-add | push-remove | push-snapshot} <ext_name> <entry>

To use the API with a JSON file:

# diagnose sys external-resource push-api-json-commands
{
  "commands": [ <Array: Mandatory>
    { <Object: Mandatory>
         "name": <String: Mandatory, Example: "AWS_MALWARE_FEED">
      "command": <String: mandatory, Options: "add", "remove", "snapshot">,
      "entries": [ <Array: Mandatory>
        <String: Mandatory, Example: "10.100.1.1">
      ]
    }
  ]
}

Sample:

# diagnose sys external-resource push-api-json-commands '{"commands":[{"name":"test","command":"add","entries":["10.10.10.1","10.10.10.2"]},{"name":"test","command":"whatever","entries":["10.10.10.3","10.10.10.4"]}]}'
command returned: EXT_RESOURCE_PUSH_CMD_RETURN_OK
Returned json:
[
  {
    "name":"test",
    "command":"add",
    "status":"success"
  },
  {
    "name":"test",
    "command":"whatever",
    "error":"Invalid command.",
    "status":"error"
  }
]

To use the API with a Postman REST client:

1. Create an API administrator in FortiOS with write access.

2. Ensure the API token is generated.

3. Configure the external resource list as needed.

4. In the Postman client, create a new request, set the HTTP method to POST, enter the URL.

5. Configure the access token using one of the following methods:

   • To use the bearer token: click the Authorization tab, set the Type to Bearer, and enter the REST API administrator token.

   • To use the access_token parameter: click the Params tab and enter the access_token key-value pair (access_token and <key>).

6. Click the Body tab and configure the following:

   1. Select raw and set the input type to JSON.

   2. Insert the JSON data payload.

7. Click Send to send the POST request. If there is a response, the response body appears. For example,

   POST https://172.18.52.153/api/v2/monitor/system/external-resource/dynamic?access_token=g1mnfs8bzxk5hf8Qwcz4kx7yn3jHmG&vdom=vd1
   Content-Type: application/json
   User-Agent: PostmanRuntime/7.29.2
   Accept: */*
   Postman-Token: 04e10736-190e-4119-92e1-04e91bf99c10
   Host: 172.18.52.153
   Accept-Encoding: gzip, deflate, br
   Connection: keep-alive
   Content-Length: 485
   
   {
      "commands":[
         {
            "name":"ip",
            "command":"add",
            "entries":[
               "10.10.10.1",
               "10.10.10.2"
            ]
         },
         {
            "name":"fqdn",
            "command":"remove",
            "entries":[
               "10.10.10.1",
               "10.10.10.2"
            ]
         },
         {
            "name":"fortiguard",
            "command":"snapshot",
            "entries":[
               "10.10.10.1",
               "10.10.10.2"
            ]
         }
      ]
   }
   
   HTTP/1.1 200 OK
   date: Fri, 22 Jul 2022 21:10:39 GMT
   x-frame-options: SAMEORIGIN
   content-security-policy: frame-ancestors 'self'
   x-xss-protection: 1; mode=block
   cache-control: no-cache, must-revalidate
   content-length: 480
   content-type: application/json
   Connection: keep-alive
   
   {
      "http_method":"POST",
      "results":[
         {
            "name":"ip",
            "command":"add",
            "status":"success"
         },
         {
            "name":"fqdn",
            "command":"remove",
            "status":"success"
         },
         {
            "name":"fortiguard",
            "command":"snapshot",
            "status":"success"
         }
      ],
      "vdom":"vd1",
      "path":"system",
      "name":"external-resource",
      "action":"dynamic",
      "status":"success",
      "serial":"FG6H1E5819900000",
      "version":"v7.2.1",
      "build":1254
   }

Viewing the update history

To review the update history of a threat feed, go to Security Fabric > External Connectors, select a feed, and click Edit. The Last Update field shows the date and time that the feed was last updated.

Click View Entries to view the current entries in the list.