Fortinet black logo

Integration API Guide

Watchlist Integration

Watchlist Integration

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

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

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 URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/ip?name=<watchlist_name>

Input Credentials

  • Enterprise deployments: User name and password of any FortiSIEM account that has the appropriate access. Use "super" as the organization for Enterprise deployments.
    Curl example: curl -k -u super/admin:Admin*123
  • Service Provider deployments: User name and password of Super Global account or Organization specific account and name. Make sure that the account has the appropriate access.
    Curl example with super organization: curl -k -u super/admin:Admin*123
    If querying for a specific organization, replace "super" with the organization name.

Request Path Parameter

Field

Type

Description

Name String Watch list name

Output

Response Status

Response

Success: When the request succeeds (HTTP response code 200), an empty set or a list of list separated IPs is returned.

Example:

10.0.0.1

145.12.14.75

172.30.58.10

Error: When the request fails (HTTP response code not 200).
  1. Response contains failed reason.
    Example: Wrong watchlist name error.
    {"response":"DyWatchList@DNS was not found","status":"Failed"}

  2. Response empty.

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 URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/domain?name=<watchlist_name>

Input Credentials

  • Enterprise deployments: User name and password of any FortiSIEM account that has the appropriate access. Use "super" as the organization for Enterprise deployments.
    Curl example: curl -k -u super/admin:Admin*123
  • Service Provider deployments: User name and password of Super Global account or Organization specific account and name. Make sure that the account has the appropriate access.
    Curl example with super organization: curl -k -u super/admin:Admin*123
    If querying for a specific organization, replace "super" with the organization name.

Request Path Parameter

Field

Type

Description

Name String Watch list name

Output

Response Status

Response

Success: When the request succeeds (HTTP response code 200), empty set or a list of list separated domains is returned

Example:

Google.com

Fortinet.com

Host.fsm-ip.com

Error: When the request fails (HTTP response code not 200).
  1. Response contains failed reason.
    Example: Wrong watchlist name error.
    {"response":"DyWatchList@DNS was not found","status":"Failed"}

  2. Response empty.

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 URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/hash?name=<watchlist_name>

Input Credentials

  • Enterprise deployments: User name and password of any FortiSIEM account that has the appropriate access. Use "super" as the organization for Enterprise deployments.
    Curl example: curl -k -u super/admin:Admin*123
  • Service Provider deployments: User name and password of Super Global account or Organization specific account and name. Make sure that the account has the appropriate access.
    Curl example with super organization: curl -k -u super/admin:Admin*123
    If querying for a specific organization, replace "super" with the organization name.

Request Path Parameter

Field

Type

Description

Name String Watch list name

Output

Response Status

Response

Success: When the request succeeds (HTTP response code 200), an empty set or a list of list separated hash (only get MD5, SHA1 and SHA256 hash) is returned.

Example:

771ab1c7c8e5c4ad1113ec58a41cc697

73e5eb7be756f6264gyy6e8c22ff5x97fb1fab17

D4C9D9059326271A89CE57FCAF328ED673F46BE33469FF979E8AB8DD501E554F

Error: When the request fails (HTTP response code not 200).
  1. Response contains failed reason.
    Example: Wrong watchlist name error.

    {"response":"DyWatchList@DNS was not found","status":"Failed"}

  2. Response empty.

Generic Read APIs

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

Get All Watch Lists

This API retrieves all the watch lists from FSIEM database.

Release Added: 6.3.0

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/all

Output

Response Status

Response

Success

{
      "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"
}

Failure

{
     "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/cnt

Output

Response Status

Response

Success

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

Failure

{
	    "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/<watch_list_id>

Request Path Parameter

Field

Description

Replace <watch_list_id> with numeric value. Watch list id of a specific watch list.

Output

Response Status

Response

Success

{
    "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"
}

Failure

Ex: If ID contains non-numeric values (invalid data)

Status Code – 404 Not Found

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

Failure

Ex: If no match, Status Code – 200

{
    "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/value

Request Parameters

Field

Type

Description

entryValue

String

Entry value of watch list entry.

Output

Response Status

Response

Success

{
    "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"
}

Failure

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

Failure

Ex: If no match, Status Code – 200

{
     "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/byEntry/<watch_list_entry_id>

Request Path Parameters

Field

Type

Description

Replace <watch_list_entry_id> with specific watch list entry id

Long

Watch list entry id

Output

Response Status

Response

Success

{
    "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"
}

Failure

Ex: If ID contains non-numeric values (invalid data)

Status Code – 404 Not Found

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

Failure

Ex: If no match, Status Code – 200

{
    "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/<watch_list_entry_id>

Request Path Parameters

Field

Type

Description

Replace <watch_list_entry_id> with specific watch list entry id. Long Watch list entry id

Output

Response Status

Response

Success

{
    "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"
}

Failure

Ex: If ID contains non-numeric values (invalid data)

Status Code – 404 Not Found

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

Failure

Ex: If no match, Status Code – 200

{
"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

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

Release Added: 6.3.0

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/active/<watch_list_entry_id>

Request Path Parameters

Field

Type

Description

Replace <watch_list _entry_id> with specific watch list entry id Long Watch list entry id

Request Parameters

Field

Type

Description

state Boolean Set specific entry to true/false state.

Output

Response Status

Response

Success

{
    "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"
}

Failure

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

Failure

Ex – If no match, status code - 200

{
	    "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/active

Request Parameters

Field

Type

Description

watchlistId Long Watchlist ID

value

String

Entry value of watch list entry

state

Boolean

Set specific entry to true/false state

custId

Long

Customer ID

Output

Response Status

Response

Success

{
    "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"
}

Failure

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

Failure

Ex – If no match, status code - 200

{
	    "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/lastseen/<watch_list_entry_id>

Request Path Parameters

Field

Type

Description

Replace <watch_list_ entry _id> with specific watch list entry id Long Watch list entry id

Request Parameters

Field

Type

Description

lastSeenTime Long Long value of last seen time i.e. Unix timestamp

custId

Long

Customer ID

Output

Response Status

Response

Success

{
    "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"
}

Failure

Ex: If ID contains non-numeric values (invalid data)

Status Code – 404 Not Found

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

Failure

Ex – If no match, status code - 200

{
	    "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/lastseen

Request Parameters

Field

Type

Description

watchlistId

Long

Watchlist ID

value

String

Entry value of watch list entry

lastSeenTime Long Long value of last seen time i.e. Unix timestamp

custId

Long

Customer ID

Output

Response Status

Response

Success

{
    "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"
}

Failure

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

Failure

Ex – If no match, status code - 200

{
	    "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/count/<watch_list_entry_id>

Request Path Parameters

Field

Type

Description

Replace <watch_list_ entry _id> with specific watch list entry id

Long

Watch list entry id

Request Parameters

Field

Type

Description

count

Long

Count of watch list entry occurrence

Output

Response Status

Response

Success

{
    "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"
}

Failure

Ex: If ID contains non-numeric values (invalid data)

Status Code – 404 Not Found

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

Failure

Ex – If no match, status code - 200

{
	    "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/count

Request Parameters

Field

Type

Description

custId

Long

Customer ID

watchlistId

Long

Watchlist ID

value

String

Entry value of watch list entry

count

Long

Count of watch list entry occurrence

Output

Response Status

Response

Success

{
    "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"
}

Failure

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

Failure

Ex – If no match, status code - 200

{
	    "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/addTo

Request Parameters

Field

Type

Description

watchlistId

Long

Watchlist ID

Request Body

Field

Type

Description

Body JSON Array of Watch list entry objects Watch Entry
entryValue(required) String Watch List entry value
[
                    {
                        "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 Status

Response

Success

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

Failure

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

Failure

Ex: Invalid data format in request parameters

Status code - 200

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

Failure

Ex: If no entry value exists in Watchlist Entry

Status code - 200

{
    "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/save

Request Body

Field

Type

Description

Body JSON Object of Watch list with watch list entry Watch list with entry(s)
displayName (required) String Display name for watch list group
type (required) String Group type - ENUM

entryValue (required)

String

Entry value of DyWatchlistEntry

dataCreationType

String

Enum – {SYSTEM, USER}

If value is null – Default value will be ‘SYSTEM’

{
                                "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 Status

Response

Success

{
    "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"
}

Failure

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

Failure

Ex: If entry doesn’t have entry value

Response code - 200

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

Failure

Ex:

  • If display name is duplicate (already exists) or body doesn’t have filed –‘type’

  • Unrecognized fields in POST body

Response code - 200

{
    "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/save

Request Body

Field

Type

Description

Body JSON Object of Watch list with watch list entry Watch list entry
entryValue(required) String Watch list entry value

{
    "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 Status

Response

Success

{
    "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"
}

Failure

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

Failure

Ex: If entry doesn’t have entry value

Response code - 200

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

Delete APIs

The following POST Delete APIs are available.

Delete Watch List Entry by ID

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

Release Added: 6.3.0

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/delete

Request Body

Field

Type

Description

List of Long values Watch List Entry ids

Ex: [500000, 500001]

Output

Response Status

Response

Success

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

Failure

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

Failure

Ex: If any exception occurs

{
                  "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/delete

Request Body

Field

Type

Description

List of Long values Watch list ids

Ex: [500000, 500001]

Output

Response Status

Response

Success

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

Failure

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

Failure

Ex: If group is system defined group

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

Failure

Ex: If any exception occurs

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

JSON Object Formats

Watch List Entry JSON

Field

Type

Description

id Long Watch list entry id
firstSeen Long First seen time – Unix format
lastSeen Long Last seen time – Unix format
expiredTime Long Expiry time – Unix format
state String State of entry – Enabled/Disabled
naturalId String Unique ID of watch list entry
triggeringRules String FSM Rules – Comma separated
entryValue String Entry value of Watch list entry

description

String

Description

ageOut

String

Age out (Expiry)

count

Long

Occurrence count

dataCreationType

ENUM

[SYSTEM, USER]

Watch List JSON

Field

Type

Description

id Long Watch list group id
naturalId String Unique ID of watch list
isCaseSensitive Boolean
ageOut String Age out (Expiry)
entries List<WatchListEntry> List of Entries Refer to Watch List Entry JSON Table.
displayName String Display name of watch list group
name String Name of the watch list
description String Entry value of Watch list description
valueType

ENUM

Value type - STRING, IP, etc...

topGroup

Boolean

True/false

dataCreationType

ENUM

[SYSTEM, USER]

valuePattern

ENUM

[IP, IPRANGE, CIDR]

Watchlist Integration

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

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

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 URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/ip?name=<watchlist_name>

Input Credentials

  • Enterprise deployments: User name and password of any FortiSIEM account that has the appropriate access. Use "super" as the organization for Enterprise deployments.
    Curl example: curl -k -u super/admin:Admin*123
  • Service Provider deployments: User name and password of Super Global account or Organization specific account and name. Make sure that the account has the appropriate access.
    Curl example with super organization: curl -k -u super/admin:Admin*123
    If querying for a specific organization, replace "super" with the organization name.

Request Path Parameter

Field

Type

Description

Name String Watch list name

Output

Response Status

Response

Success: When the request succeeds (HTTP response code 200), an empty set or a list of list separated IPs is returned.

Example:

10.0.0.1

145.12.14.75

172.30.58.10

Error: When the request fails (HTTP response code not 200).
  1. Response contains failed reason.
    Example: Wrong watchlist name error.
    {"response":"DyWatchList@DNS was not found","status":"Failed"}

  2. Response empty.

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 URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/domain?name=<watchlist_name>

Input Credentials

  • Enterprise deployments: User name and password of any FortiSIEM account that has the appropriate access. Use "super" as the organization for Enterprise deployments.
    Curl example: curl -k -u super/admin:Admin*123
  • Service Provider deployments: User name and password of Super Global account or Organization specific account and name. Make sure that the account has the appropriate access.
    Curl example with super organization: curl -k -u super/admin:Admin*123
    If querying for a specific organization, replace "super" with the organization name.

Request Path Parameter

Field

Type

Description

Name String Watch list name

Output

Response Status

Response

Success: When the request succeeds (HTTP response code 200), empty set or a list of list separated domains is returned

Example:

Google.com

Fortinet.com

Host.fsm-ip.com

Error: When the request fails (HTTP response code not 200).
  1. Response contains failed reason.
    Example: Wrong watchlist name error.
    {"response":"DyWatchList@DNS was not found","status":"Failed"}

  2. Response empty.

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 URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/hash?name=<watchlist_name>

Input Credentials

  • Enterprise deployments: User name and password of any FortiSIEM account that has the appropriate access. Use "super" as the organization for Enterprise deployments.
    Curl example: curl -k -u super/admin:Admin*123
  • Service Provider deployments: User name and password of Super Global account or Organization specific account and name. Make sure that the account has the appropriate access.
    Curl example with super organization: curl -k -u super/admin:Admin*123
    If querying for a specific organization, replace "super" with the organization name.

Request Path Parameter

Field

Type

Description

Name String Watch list name

Output

Response Status

Response

Success: When the request succeeds (HTTP response code 200), an empty set or a list of list separated hash (only get MD5, SHA1 and SHA256 hash) is returned.

Example:

771ab1c7c8e5c4ad1113ec58a41cc697

73e5eb7be756f6264gyy6e8c22ff5x97fb1fab17

D4C9D9059326271A89CE57FCAF328ED673F46BE33469FF979E8AB8DD501E554F

Error: When the request fails (HTTP response code not 200).
  1. Response contains failed reason.
    Example: Wrong watchlist name error.

    {"response":"DyWatchList@DNS was not found","status":"Failed"}

  2. Response empty.

Generic Read APIs

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

Get All Watch Lists

This API retrieves all the watch lists from FSIEM database.

Release Added: 6.3.0

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/all

Output

Response Status

Response

Success

{
      "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"
}

Failure

{
     "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/cnt

Output

Response Status

Response

Success

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

Failure

{
	    "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/<watch_list_id>

Request Path Parameter

Field

Description

Replace <watch_list_id> with numeric value. Watch list id of a specific watch list.

Output

Response Status

Response

Success

{
    "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"
}

Failure

Ex: If ID contains non-numeric values (invalid data)

Status Code – 404 Not Found

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

Failure

Ex: If no match, Status Code – 200

{
    "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/value

Request Parameters

Field

Type

Description

entryValue

String

Entry value of watch list entry.

Output

Response Status

Response

Success

{
    "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"
}

Failure

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

Failure

Ex: If no match, Status Code – 200

{
     "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/byEntry/<watch_list_entry_id>

Request Path Parameters

Field

Type

Description

Replace <watch_list_entry_id> with specific watch list entry id

Long

Watch list entry id

Output

Response Status

Response

Success

{
    "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"
}

Failure

Ex: If ID contains non-numeric values (invalid data)

Status Code – 404 Not Found

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

Failure

Ex: If no match, Status Code – 200

{
    "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/<watch_list_entry_id>

Request Path Parameters

Field

Type

Description

Replace <watch_list_entry_id> with specific watch list entry id. Long Watch list entry id

Output

Response Status

Response

Success

{
    "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"
}

Failure

Ex: If ID contains non-numeric values (invalid data)

Status Code – 404 Not Found

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

Failure

Ex: If no match, Status Code – 200

{
"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

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

Release Added: 6.3.0

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/active/<watch_list_entry_id>

Request Path Parameters

Field

Type

Description

Replace <watch_list _entry_id> with specific watch list entry id Long Watch list entry id

Request Parameters

Field

Type

Description

state Boolean Set specific entry to true/false state.

Output

Response Status

Response

Success

{
    "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"
}

Failure

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

Failure

Ex – If no match, status code - 200

{
	    "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/active

Request Parameters

Field

Type

Description

watchlistId Long Watchlist ID

value

String

Entry value of watch list entry

state

Boolean

Set specific entry to true/false state

custId

Long

Customer ID

Output

Response Status

Response

Success

{
    "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"
}

Failure

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

Failure

Ex – If no match, status code - 200

{
	    "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/lastseen/<watch_list_entry_id>

Request Path Parameters

Field

Type

Description

Replace <watch_list_ entry _id> with specific watch list entry id Long Watch list entry id

Request Parameters

Field

Type

Description

lastSeenTime Long Long value of last seen time i.e. Unix timestamp

custId

Long

Customer ID

Output

Response Status

Response

Success

{
    "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"
}

Failure

Ex: If ID contains non-numeric values (invalid data)

Status Code – 404 Not Found

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

Failure

Ex – If no match, status code - 200

{
	    "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/lastseen

Request Parameters

Field

Type

Description

watchlistId

Long

Watchlist ID

value

String

Entry value of watch list entry

lastSeenTime Long Long value of last seen time i.e. Unix timestamp

custId

Long

Customer ID

Output

Response Status

Response

Success

{
    "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"
}

Failure

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

Failure

Ex – If no match, status code - 200

{
	    "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/count/<watch_list_entry_id>

Request Path Parameters

Field

Type

Description

Replace <watch_list_ entry _id> with specific watch list entry id

Long

Watch list entry id

Request Parameters

Field

Type

Description

count

Long

Count of watch list entry occurrence

Output

Response Status

Response

Success

{
    "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"
}

Failure

Ex: If ID contains non-numeric values (invalid data)

Status Code – 404 Not Found

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

Failure

Ex – If no match, status code - 200

{
	    "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/count

Request Parameters

Field

Type

Description

custId

Long

Customer ID

watchlistId

Long

Watchlist ID

value

String

Entry value of watch list entry

count

Long

Count of watch list entry occurrence

Output

Response Status

Response

Success

{
    "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"
}

Failure

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

Failure

Ex – If no match, status code - 200

{
	    "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/addTo

Request Parameters

Field

Type

Description

watchlistId

Long

Watchlist ID

Request Body

Field

Type

Description

Body JSON Array of Watch list entry objects Watch Entry
entryValue(required) String Watch List entry value
[
                    {
                        "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 Status

Response

Success

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

Failure

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

Failure

Ex: Invalid data format in request parameters

Status code - 200

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

Failure

Ex: If no entry value exists in Watchlist Entry

Status code - 200

{
    "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/save

Request Body

Field

Type

Description

Body JSON Object of Watch list with watch list entry Watch list with entry(s)
displayName (required) String Display name for watch list group
type (required) String Group type - ENUM

entryValue (required)

String

Entry value of DyWatchlistEntry

dataCreationType

String

Enum – {SYSTEM, USER}

If value is null – Default value will be ‘SYSTEM’

{
                                "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 Status

Response

Success

{
    "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"
}

Failure

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

Failure

Ex: If entry doesn’t have entry value

Response code - 200

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

Failure

Ex:

  • If display name is duplicate (already exists) or body doesn’t have filed –‘type’

  • Unrecognized fields in POST body

Response code - 200

{
    "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/save

Request Body

Field

Type

Description

Body JSON Object of Watch list with watch list entry Watch list entry
entryValue(required) String Watch list entry value

{
    "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 Status

Response

Success

{
    "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"
}

Failure

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

Failure

Ex: If entry doesn’t have entry value

Response code - 200

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

Delete APIs

The following POST Delete APIs are available.

Delete Watch List Entry by ID

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

Release Added: 6.3.0

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/entry/delete

Request Body

Field

Type

Description

List of Long values Watch List Entry ids

Ex: [500000, 500001]

Output

Response Status

Response

Success

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

Failure

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

Failure

Ex: If any exception occurs

{
                  "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

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/watchlist/delete

Request Body

Field

Type

Description

List of Long values Watch list ids

Ex: [500000, 500001]

Output

Response Status

Response

Success

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

Failure

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

Failure

Ex: If group is system defined group

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

Failure

Ex: If any exception occurs

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

JSON Object Formats

Watch List Entry JSON

Field

Type

Description

id Long Watch list entry id
firstSeen Long First seen time – Unix format
lastSeen Long Last seen time – Unix format
expiredTime Long Expiry time – Unix format
state String State of entry – Enabled/Disabled
naturalId String Unique ID of watch list entry
triggeringRules String FSM Rules – Comma separated
entryValue String Entry value of Watch list entry

description

String

Description

ageOut

String

Age out (Expiry)

count

Long

Occurrence count

dataCreationType

ENUM

[SYSTEM, USER]

Watch List JSON

Field

Type

Description

id Long Watch list group id
naturalId String Unique ID of watch list
isCaseSensitive Boolean
ageOut String Age out (Expiry)
entries List<WatchListEntry> List of Entries Refer to Watch List Entry JSON Table.
displayName String Display name of watch list group
name String Name of the watch list
description String Entry value of Watch list description
valueType

ENUM

Value type - STRING, IP, etc...

topGroup

Boolean

True/false

dataCreationType

ENUM

[SYSTEM, USER]

valuePattern

ENUM

[IP, IPRANGE, CIDR]