Using the REST API to push updates to external threat feeds 7.2.1

When configuring a FortiGuard Category, Malware Hash, IP Address, or Domain Name threat feed from the Security Fabric > External Connectors page, selecting the Push API update method provides the code samples needed to perform add, remove, and snapshot operations. The code samples can be used to perform updates on the external threat feeds.

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 in the FortiOS Administration Guide 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.

9. Go to Security Fabric > External Connectors and edit the connector.

10. In the right-side pane, click View Entries to view the list of entries 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} <feed_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)>,
      "command": <string (mandatory, "add", "remove", or "snapshot")>,
      "entries": [<array (mandatory)>
        <string (mandatory, such as "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
   }