Watchlist Integration

The Watchlist Integration APIs are broken down into the following sections:

• Read APIs for Integration with FortiGate Firewalls

  • Get IPs

  • Get Domains

  • Get Hash

• Generic Read APIs

  • Get All Watch Lists

  • Get Watch List Entries Count

  • Get Watch List by Watch List ID

  • Get Watch List by Watch List Entry Value

  • Get Watch List by Watch List Entry ID

  • Get Watch List Entry by Watch List Entry ID

• Update APIs

  • Update State of Watch List Entry by Watch List Entry ID

  • Update State of Watch List Entry by Watch List Entry Value

  • Update Last Seen Time of Watch List Entry by Watch List Entry ID

  • Update Last Seen Time of Watch List Entry by Watch List Entry Value

  • Update Count of Watch List Entry by Watch List Entry ID

  • Update Count of Watch List Entry by Watch List Entry Value

  • Add Watch List Entry(s) to Watch List Groups

  • Save Watch List Groups with Watch List Entry(s)

  • Update Specific Watch List Entry

• Delete APIs

  • Delete Watch List Entry by ID

  • Delete Watch List by ID

• JSON Object Formats

  • Watch List Entry JSON

  • Watch List JSON

Refer to Example Usage for Watchlist Integration examples.

Read APIs for Integration with FortiGate Firewalls

The following Read APIs return the content in a simplified way to make it easy for the requestor to process the results. FortiGate firewalls can use these APIs natively as a threat feed (For details, see FortiGate/FortiOS Cookbook Threat feeds).

• GET IPs

• GET Domains

• GET Hash

Get IPs

Use this GET API to retrieve list of watch list IPs with given watch list name. For use with FortiGate.

Release Added: 6.6.0

Input Credentials

User name and password of Supervisor account, or Organization specific user name and password, Organization name.

Request Path Parameter

Output

Get Domains

Use this GET API to retrieve list of watch list domains with given watch list name. For use with FortiGate.

Release Added: 6.6.0

Input Credentials

User name and password of Supervisor account, or Organization specific user name and password, Organization name.

Request Path Parameter

Output

Get Hash

Use this GET API to retrieve list of Hash (only MD5, SHA1 and SHA256 hash) with given watch list name. For use with FortiGate.

Release Added: 6.6.0

Input Credentials

User name and password of Supervisor account, or Organization specific user name and password, Organization name.

Request Path Parameter

Output

Generic Read APIs

These GET APIs are available to retrieve watch lists from the FortiSIEM database.

• Get All Watch Lists

• Get Watch List Entries Count

• Get Watch List by Watch List ID

• Get Watch List by Watch List Entry Value

• Get Watch List by Watch List Entry ID

• Get Watch List Entry by Watch List Entry ID

Get All Watch Lists

This API retrieves all the watch lists from FSIEM database.

Release Added: 6.3.0

Output

{
      "response": [{
            "topGroup": false,
            "entries": [
                {
                    "lastSeen": 1613719690008,
                    "naturalId": "PVVol_A001_A000356_POWER2_1613719690011",
                    "dataCreationType": "SYSTEM",
                    "firstSeen": 1613719690008,
                    "count": 10,
                    “custId”: 1,
                    "triggeringRules": "Datastore Space Warning",
                    "description": "WL Des",
                    "id": 889401,
                    "state": "Enabled",
                    "entryValue": "PVVol_A001_A000356_POWER2",
                    "expiredTime": 0,
                    "ageOut": "1d"
                },
                {
                    "lastSeen": 1613719690000,
                    "naturalId": "PVVol_A001_A000356_POWER2_1613719690011",
                    "dataCreationType": "SYSTEM",
                    "firstSeen": 1613719000000,
                    "count": 100,
                    "triggeringRules": "Datastore Space Warning",
                                  "description": "WL Des Testing again",
                    "id": 889402,
                    “custId”: 1,
                    "state": "Disabled",
                    "entryValue": "PVVol_A001_A000356_POWER2",
                    "expiredTime": 0,
                    "ageOut": "10d"
                }
            ],
            "isCaseSensitive": null,
            "dataCreationType": null,
            "displayName": "",
            "valueType": “STRING”,
            "description": null,
            "id": 0,
            “custId”: 1,
            "valuePattern": null,
            "ageOut": null
        },
                       {
            "topGroup": true,
            "entries": null,
            "isCaseSensitive": false,
            "dataCreationType": "USER",
            "displayName": "Test WL Group2",
            "valueType": “STRING”,
            "description": "Testing",
            "id": 897300,
            "valuePattern": null,
            "ageOut": "1w"
        }
    ],
    "status": "Success"
}

{
     "response": "Reason for failure",
     "status": "Failed"
}

Get Watch List Entries Count

This API gives the count of watch list entries in any watch list group.

Release Added: 6.3.0

Output

{
	    "response": {
	        "entry_count": 6
	    },
	   "status": "Success"
}

{
	    "response": "Reason for failure",
	    "status": "Failed"
}

Get Watch List by Watch List ID

This API retrieves a specific watch list with given watch list ID.

Release Added: 6.3.0

Request Path Parameter

Output

{
    "response": [
        {
            "topGroup": true,
            "entries": [
                {
                    "lastSeen": null,
                    "naturalId": "172.30.57.65_1616469746578",
                    "dataCreationType": null,
                    "firstSeen": null,
                    "count": null,
                    "triggeringRules": null,
                    "description": "Testing",
                    "id": 888900,
                    “custId”: 1,
                    "state": "Enabled",
                    "entryValue": "172.30.57.65",
                    "expiredTime": null,
                    "ageOut": "1w"
                },
                {
                    "lastSeen": null,
                    "naturalId": "PVVol_A001_A000356_POWER23_1616480669538",
                    "dataCreationType": null,
                    "firstSeen": null,
                    "count": null,
                    "triggeringRules": "Datastore Space Warning",
                    "description": null,
                    "id": 889400,
                    “custId”: 1,
                    "state": "Enabled",
                    "entryValue": "PVVol_A001_A000356_POWER23",
                    "expiredTime": null,
                    "ageOut": "1d"
                }
            ],
            "isCaseSensitive": false,
            "dataCreationType": "USER",
            "displayName": "Test WL Group",
            "valueType": “STRING”,
            "description": "",
            "id": 881750,
             “custId”: 1,
            "valuePattern": null,
            "ageOut": "1w"
        }
    ],
    "status": "Success"
}

{
    "response": "DyWatchList@<watch_list_id>  was not found",
    "status": "Failed"
}

{
    "response": "DyWatchList@<watch_list_id>  was not found",
    "status": "Failed"
}

Get Watch List by Watch List Entry Value

This API retrieves watch lists which contains a watch list entry with given entry value.

Release Added: 6.3.0

Request Parameters

Output

{
    "response": [
        {
            "topGroup": true,
            "entries": [
                {
                    "lastSeen": null,
                    "naturalId": "172.30.57.65_1616469746578",
                    "dataCreationType": null,
                    "firstSeen": null,
                    "count": null,
                    "triggeringRules": null,
                    "description": "Testing",
                    "id": 888900,
                    "state": "Enabled",
                    "entryValue": "172.30.57.65",
                    "expiredTime": null,
                    "ageOut": "1w"
                },
                {
                    "lastSeen": null,
                    "naturalId": "PVVol_A001_A000356_POWER23_1616480669538",
                    "dataCreationType": null,
                    "firstSeen": null,
                    "count": null,
                    "triggeringRules": "Datastore Space Warning",
                    "description": null,
                    "id": 889400,
                    "state": "Enabled",
                    "entryValue": "PVVol_A001_A000356_POWER23",
                    "expiredTime": null,
                    "ageOut": "1d"
                }
            ],
            "isCaseSensitive": false,
            "dataCreationType": "USER",
            "displayName": "Test WL Group",
            "valueType": “STRING”,
            "description": "",
            "id": 881750,
            "valuePattern": null,
            "ageOut": "1w"
        }
    ],
    "status": "Success"
}

{
     "response": "Reason for failure",
     "status": "Failed"
}

{
     "response":  "No such Watch List with entry value:  <entryValue> and watch list name: <watchlistName>",
     "status": "Failed"
}

Get Watch List by Watch List Entry ID

This API retrieves a specific watch list which contains a watch list entry with given entry ID.

Release Added: 6.3.0

Request Path Parameters

Output

{
    "response": {
        "topGroup": true,
        "entries": [
            {
                "lastSeen": null,
                "naturalId": "172.30.57.65_1616469746578",
                "dataCreationType": null,
                "firstSeen": null,
                "count": null,
                "triggeringRules": null,
                "description": "Testing",
                "id": 888900,
                "state": "Enabled",
                "entryValue": "172.30.57.65",
                "expiredTime": null,
                "ageOut": "1w"
            },
            {
                "lastSeen": null,
                "naturalId": "PVVol_A001_A000356_POWER23_1616480669538",
                "dataCreationType": null,
                "firstSeen": null,
                "count": null,
                "triggeringRules": "Datastore Space Warning",
                "description": null,
                "id": 889400,
                "state": "Enabled",
                "entryValue": "PVVol_A001_A000356_POWER23",
                "expiredTime": null,
                "ageOut": "1d"
            }
        ],
        "isCaseSensitive": false,
        "dataCreationType": "USER",
        "displayName": "Test WL Group",
        "valueType": "STRING",
        "description": "",
        "id": 881750,
        "valuePattern": null,
        "ageOut": "1w"
    },
    "status": "Success"
}

{
	    "response": "Reason for failure",
	    "status": "Failed"
}

{
    "response": " No such watch list exists",
    "status": "Failed"
}

Get Watch List Entry by Watch List Entry ID

This API retrieves a specific watch list entry given entry ID.

Release Added: 6.3.0

Request Path Parameters

Output

{
    "response": {
        "lastSeen": null,
        "naturalId": "172.30.57.65_1616469746578",
        "dataCreationType": null,
        "firstSeen": null,
        "count": null,
        "triggeringRules": null,
        "description": "Testing",
        "id": 888900,
        "state": "Enabled",
        "entryValue": "172.30.57.65",
        "expiredTime": null,
        "ageOut": "1w"
    },
    "status": "Success"
}

{
	    "response": "Reason for failure",
	    "status": "Failed"
}

{

"response": " No such watch list entry exists",

"status": "Failed"

}

Update APIs

These POST APIs are available to update watch lists from the FortiSIEM database.

• Update State of Watch List Entry by Watch List Entry ID

• Update State of Watch List Entry by Watch List Entry Value

• Update Last Seen Time of Watch List Entry by Watch List Entry ID

• Update Last Seen Time of Watch List Entry by Watch List Entry Value

• Update Count of Watch List Entry by Watch List Entry ID

• Update Count of Watch List Entry by Watch List Entry Value

• Add Watch List Entry(s) to Watch List Groups

• Save Watch List Groups with Watch List Entry(s)

• Update Specific Watch List Entry

Update State of Watch List Entry by Watch List Entry ID

This API allows user to update watch list entry state (i.e., make it active/inactive).

Release Added: 6.3.0

Request Path Parameters

Request Parameters

Output

{
    "response": {
        "lastSeen": null,
        "naturalId": "172.30.57.65_1616469746578",
        "dataCreationType": null,
        "firstSeen": null,
        "count": null,
        "triggeringRules": null,
        "description": "Testing",
        "id": 888900,
        "state": "Disabled",
        "entryValue": "172.30.57.65",
        "expiredTime": null,
        "ageOut": "1w"
    },
    "status": "Success"
}

{
	    "response": "Reason for failure",
	    "status": "Failed"
}

{
	    "response": "Can't update state of watch list entry - No such watch list entry exists",
	    "status": "Failed"
}

Update State of Watch List Entry by Watch List Entry Value

This API allows user to update the watch list entry state (i.e., make it active/inactive). This API requires a watch list group name where a required watch list entry exists.

Release Added: 6.3.0

Request Parameters

Output

{
    "response": {
        "lastSeen": null,
        "naturalId": "PVVol_A001_A000356_POWER23_1616480669538",
        "dataCreationType": null,
        "firstSeen": null,
        "count": 10,
        "triggeringRules": "Datastore Space Warning",
        "description": null,
        "id": 889400,
        "state": "Disabled",
        "entryValue": "PVVol_A001_A000356_POWER23",
        "expiredTime": null,
        "ageOut": "1d"
    },
    "status": "Success"
}

{
	    "response": "Reason for failure",
	    "status": "Failed"
}

{
	    "response": "Can't update state of watch list entry - No such watch list entry exists",
	    "status": "Failed"
}

Update Last Seen Time of Watch List Entry by Watch List Entry ID

This API allows user to update watch list entry’s last seen time.

Release Added: 6.3.0

Request Path Parameters

Request Parameters

Output

{
    "response": {
        "lastSeen": 1612901760000,
        "naturalId": "PVVol_A001_A000356_POWER23_1616480669538",
        "dataCreationType": null,
        "firstSeen": null,
        "count": 10,
        "triggeringRules": "Datastore Space Warning",
        "description": null,
        "id": 889400,
        "state": "Disabled",
        "entryValue": "PVVol_A001_A000356_POWER23",
        "expiredTime": 1612988160000,
        "ageOut": "1d"
    },
    "status": "Success"
}

{
	    "response": "Reason for failure",
	    "status": "Failed"
}

{
	    "response": "Can't update last seen time of watch list entry - No such watch list entry exists",
	    "status": "Failed"
}

Update Last Seen Time of Watch List Entry by Watch List Entry Value

This API allows the user to update watch list entry’s last seen time. This API requires a watch list group name where the required watch list entry exists.

Release Added: 6.3.0

Request Parameters

Output

{
    "response": {
        "lastSeen": 1612901760001,
        "naturalId": "PVVol_A001_A000356_POWER23_1616480669538",
        "dataCreationType": null,
        "firstSeen": null,
        "count": 10,
        "triggeringRules": "Datastore Space Warning",
        "description": null,
        "id": 889400,
        "state": "Disabled",
        "entryValue": "PVVol_A001_A000356_POWER23",
        "expiredTime": 1612988160001,
        "ageOut": "1d"
    },
    "status": "Success"
}

{
	    "response": "Reason for failure",
	    "status": "Failed"
}

{
	    "response": "Can't update last seen time of watch list entry - No such watch list entry exists",
	    "status": "Failed"
}

Update Count of Watch List Entry by Watch List Entry ID

This API allows user to update watch list entry’s count.

Release Added: 6.3.0

Request Path Parameters

Request Parameters

Output

{
    "response": {
        "lastSeen": 1612901760001,
        "naturalId": "PVVol_A001_A000356_POWER23_1616480669538",
        "dataCreationType": null,
        "firstSeen": null,
        "count": 100,
        "triggeringRules": "Datastore Space Warning",
        "description": null,
        "id": 889400,
        "state": "Disabled",
        "entryValue": "PVVol_A001_A000356_POWER23",
        "expiredTime": 1612988160001,
        "ageOut": "1d"
    },
    "status": "Success"
}

{
	    "response": "Reason for failure",
	    "status": "Failed"
}

{
	    "response": "Can't update count of watch list entry - No such watch list entry exists",
	    "status": "Failed"
}

Update Count of Watch List Entry by Watch List Entry Value

This API allows user to update watch list entry’s count. This API requires watch list group name where required watch list entry exists.

Release Added: 6.3.0

Request Parameters

Output

{
    "response": {
        "lastSeen": 1612901760001,
        "naturalId": "PVVol_A001_A000356_POWER23_1616480669538",
        "dataCreationType": null,
        "firstSeen": null,
        "count": 100,
        "triggeringRules": "Datastore Space Warning",
        "description": null,
        "id": 889400,
        "state": "Disabled",
        "entryValue": "PVVol_A001_A000356_POWER23",
        "expiredTime": 1612988160001,
        "ageOut": "1d"
    },
    "status": "Success"
}

{
	    "response": "Reason for failure",
	    "status": "Failed"
}

{
	    "response": "Can't update count of watch list entry - No such watch list entry exists",
	    "status": "Failed"
}

Add Watch List Entry(s) to Watch List Groups

This API allows user to add watch list entry(s) to one or more watch list groups.

Release Added: 6.3.0

Request Parameters

Request Body

[
                    {
                        "inclusive": false,
                        "count": 10,
                        "custId": 1,
                        "triggeringRules": "Datastore Space Warning",
                        "entryValue": "PVVol_A001_A000356_POWER2",
                        "ageOut": "1d",
                        "lastSeen": 1613601369215,
                        "firstSeen": 1613601369215,
                        "disableAgeout": false,
                        "dataCreationType": "USER"
                    }
]

Output

{
    "response": "Successfully added to watch list - [IDs]",
    "status": "Success"
}

{
	    "response": "Reason for failure",
	    "status": "Failed"
}

{
    "response": " Error while adding entries to watch lists - Invalid data format",
    "status": "Failed"
}

{
    "response": “Error while adding entries to watch lists - WatchListEntry must have entryValue field",
    "status": "Failed"
}

Save Watch List Groups with Watch List Entry(s)

This API allows user to save one or more watch list groups to FSM database. Each watch list can contain one or more watch list entries.

Release Added: 6.3.0

Request Body

{
                                "description": "Servers, network or storage devices",
                                "displayName": "Resource Issues Test4","type": "DyWatchList",
                                "isCaseSensitive": false,
                                "dataCreationType": "USER",
                                "topGroup": false,
                                "valuePattern": null,
                                "valueType": "STRING",
                                "ageOut": "1d",
                                "custId": 1,
                                "entries": [{
                                                "inclusive": true,
                                                "entryValue": "PVVol_A001_A000356_5new",
                                                "ageOut": "1d",
                                                "count": 1,
                                                "custId": 1,
                                                "firstSeen": 1612901760000,
                                                "lastSeen": 1612901760000,
                                                "triggeringRules": "Datastore Space Warning",
                                                "dataCreationType": "USER"
                                }]
}

Output

{
    "response": [
        {
            "topGroup": false,
            "entries": [
                {
                    "lastSeen": 1612901760000,
                    "naturalId": "Nid",
                    "dataCreationType": "USER",
                    "firstSeen": 1612901760000,
                    "count": 1,
                    "triggeringRules": "Datastore Space Warning",
                    "description": null,
                    "id": 0,
                    "state": "Enabled",
                    "entryValue": null,
                    "expiredTime": null,
                    "ageOut": "1d"
                }
            ],
            "isCaseSensitive": null,
            "dataCreationType": "SYSTEM",
            "displayName": "Resource Issues Test WL Grp4",
            "valueType": "STRING",
            "description": "Servers, network or storage devices",
            "id": 899753,
            "valuePattern": null,
            "ageOut": null
        }
    ],
    "status": "Success"
}

{
	    "response": "Reason for failure",
	    "status": "Failed"
}

{
   "response" : "Error while saving watch lists - WatchListEntry must have entryValue field",
   "status" : "Failed"
}

{
    "response": "Failed to save watchlist",
    "status": "Failed"
}

Update Specific Watch List Entry

This API allows user to update any watch list entry. The JSON object of watch list entry must contain valid watch list entry id otherwise it will be saved as a new entry to ungrouped watch list.

Release Added: 6.3.0

Request Body

{
    "lastSeen": 1612901760002,
    "dataCreationType": "USER",
    "firstSeen": 1612901760001,
    "count": 100,
    "custId": 1
    "triggeringRules": "Datastore Space Warning",
    "description": "Testing again",
    "id": 889400,
    "inclusive": true,
    "entryValue": "PVVol_A001_A000356_POWER23",
    "expiredTime": 1612988160001,
    "ageOut": "2d",
}

Note: ID is mandatory to update watch list entry. If there is no id in JSON body, a new entry will be created.

Output

{
    "response": {
        "lastSeen": 1612901760002,
        "naturalId": "PVVol_A001_A000356_POWER23_1612901760002",
        "dataCreationType": "USER",
        "firstSeen": 1612901760001,
        "count": 100,
        "triggeringRules": "Datastore Space Warning",
        "description": "Testing again",
        "id": 889400,
        "state": "Enabled",
        "entryValue": "PVVol_A001_A000356_POWER23",
        "expiredTime": 1613074560002,
        "ageOut": "2d"
    },
    "status": "Success"
}

{
	    "response": "Reason for failure",
	    "status": "Failed"
}

{
    "response": "HTTP 400 Bad Request",
    "status": "Failed"
}

Delete APIs

The following POST Delete APIs are available.

• Delete Watch List Entry by ID

• Delete Watch List by ID

Delete Watch List Entry by ID

This API allows user to delete watch list entry(s).

Release Added: 6.3.0

Request Body

Output

{
               "response": "Deleted entries - [IDs]",
               "status": "Success"
}

{
	    "response": "Reason for failure",
	    "status": "Failed"
}

{
                  "response": " Error in deleting watch list entries – Exception message ",
	    "status": "Failed"
}

Delete Watch List by ID

This API allows user to delete watch list(s).

Release Added: 6.3.0

Request Body

Output

{
               "response": "Deleted watch lists - [IDs]",
               "status": "Success"
}

{
	    "response": "Reason for failure",
	    "status": "Failed"
}

{
                  "response": "Deleting system defined group is not allowed",
	    "status": "Failed"
}

{
                  "response": " Error in deleting watch lists – Exception message ",
	    "status": "Failed"
}

JSON Object Formats

• Watch List Entry JSON

• Watch List JSON

Watch List Entry JSON

Watch List JSON