Fortinet black logo

Notification via API

Notification via API

You can also query for incidents via a REST API.

This REST API based caller makes an HTTP(S) request with an input XML. An output XML is returned. Since the number of returned results can be large, the requester has to first get the total number of results, and then get the results one chunk at a time.

This REST API based caller makes an HTTP(S) request with an input XML that defines the query. Since a query can take some time and the number of returned results can be large, the query works as follows

  1. Caller submits the query and gets a Query Id back from FortiSIEM. This is done via Request API.
  2. Caller polls for query progress and waits until the query is completed. This is done via Polling API
  3. When the query is completed, Caller gets the results via Results API.
    1. Caller gets the total number of query results and the query result fields.
    2. Caller gets the results - one chunk at a time.

Request API Specifications

Release Added

5.1

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/query/eventQuery
Input Parameters XML file containing the query parameters
Input Credentials
  • Enterprise deployments: Username and password of any FortiSIEM account
  • Service Provider deployments: Username and password of Super account for getting incidents for all organizations. If incidents for a specific organization are needed, then an organization-specific account and an organization name is needed.
Output queryId or an error code if there is a problem in handling the query or the query format.

Polling API Specifications

The request will poll until the server completes the query.

Release Added

5.1

Input URLhttps://<FortiSIEM_Supervisor_IP>/phoenix/rest/query/progress/<queryId>
Outputprogress (pct)
Until progress reaches 100, at which point the server completes the query, you must continue polling the server. This is because the server may need to aggregate the results or insert meta-information before sending the results.

Results API Specifications

Release Added

5.1

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/query/events/<queryId>/<begin>/<end>
Output totalCount (first time) and an XML containing the incident attributes.
For the first call, begin = 0 and end can be 1000. You must continuously query the server by using the same URL, but increasing the begin and end until the totalCount is reached

Incident Attribute List

bizService,eventType,phCustId,incidentClearedReason,incidentTicketStatus,incidentLastSeen,eventSeverity,incidentTicketUser,hostIpAddr,eventName,phEventCategory,incidentTicketId,count,incidentDetail,incidentSr c,eventSeverityCat,incidentFirstSeen,incidentViewUsers,incidentComments,incidentClearedUser,incidentNoti Recipients,incidentId,phRecvTime,incidentStatus,incidentViewStatus,incidentTarget,incidentRptIp

Incident Notification XML Schema

The following is the schema for incident notification output file:

<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="incident">
<xs:complexType>
<xs:sequence>
	<xs:element type="xs:string" name="name"/>
	<xs:element type="xs:string" name="description"/>
	<xs:element type="xs:string" name="displayTime"/>
	<xs:element type="xs:string" name="incidentSource"/>
	<xs:element name="incidentTarget">
		<xs:complexType>
			<xs:sequence>
				<xs:element name="entry">
				<xs:complexType>
				<xs:simpleContent>
					<xs:extension base="xs:string">
					<xs:attribute type="xs:string" name="attribute"/>
					<xs:attribute type="xs:string" name="name"/>
				</xs:extension>
				</xs:simpleContent>
			</xs:complexType>
		</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="incidentDetails">
<xs:complexType>
<xs:sequence>
<xs:element name="entry"> <xs:complexType>
		<xs:simpleContent>
			<xs:extension base="xs:float">
				<xs:attribute type="xs:string" name="attribute"/>
					<xs:attribute type="xs:string" name="name"/>
						</xs:extension>
							</xs:simpleContent>
							</xs:complexType>
						</xs:element>
					</xs:sequence>
				</xs:complexType>
				</xs:element>
			<xs:element type="xs:string" name="affectedBizSrvc"/>
			<xs:element type="xs:string" name="identityLocation"/>
		</xs:sequence>
		<xs:attribute type="xs:short" name="incidentId"/>
		<xs:attribute type="xs:string" name="ruleType"/>
		<xs:attribute type="xs:byte" name="severity"/>
		<xs:attribute type="xs:byte" name="repeatCount"/>
		<xs:attribute type="xs:string" name="organization"/>
		<xs:attribute type="xs:string" name="status"/>
	</xs:complexType>
	</xs:element>
</xs:schema>

Refer to Example Usage for incident notification via API.

Notification via API

You can also query for incidents via a REST API.

This REST API based caller makes an HTTP(S) request with an input XML. An output XML is returned. Since the number of returned results can be large, the requester has to first get the total number of results, and then get the results one chunk at a time.

This REST API based caller makes an HTTP(S) request with an input XML that defines the query. Since a query can take some time and the number of returned results can be large, the query works as follows

  1. Caller submits the query and gets a Query Id back from FortiSIEM. This is done via Request API.
  2. Caller polls for query progress and waits until the query is completed. This is done via Polling API
  3. When the query is completed, Caller gets the results via Results API.
    1. Caller gets the total number of query results and the query result fields.
    2. Caller gets the results - one chunk at a time.

Request API Specifications

Release Added

5.1

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/query/eventQuery
Input Parameters XML file containing the query parameters
Input Credentials
  • Enterprise deployments: Username and password of any FortiSIEM account
  • Service Provider deployments: Username and password of Super account for getting incidents for all organizations. If incidents for a specific organization are needed, then an organization-specific account and an organization name is needed.
Output queryId or an error code if there is a problem in handling the query or the query format.

Polling API Specifications

The request will poll until the server completes the query.

Release Added

5.1

Input URLhttps://<FortiSIEM_Supervisor_IP>/phoenix/rest/query/progress/<queryId>
Outputprogress (pct)
Until progress reaches 100, at which point the server completes the query, you must continue polling the server. This is because the server may need to aggregate the results or insert meta-information before sending the results.

Results API Specifications

Release Added

5.1

Input URL https://<FortiSIEM_Supervisor_IP>/phoenix/rest/query/events/<queryId>/<begin>/<end>
Output totalCount (first time) and an XML containing the incident attributes.
For the first call, begin = 0 and end can be 1000. You must continuously query the server by using the same URL, but increasing the begin and end until the totalCount is reached

Incident Attribute List

bizService,eventType,phCustId,incidentClearedReason,incidentTicketStatus,incidentLastSeen,eventSeverity,incidentTicketUser,hostIpAddr,eventName,phEventCategory,incidentTicketId,count,incidentDetail,incidentSr c,eventSeverityCat,incidentFirstSeen,incidentViewUsers,incidentComments,incidentClearedUser,incidentNoti Recipients,incidentId,phRecvTime,incidentStatus,incidentViewStatus,incidentTarget,incidentRptIp

Incident Notification XML Schema

The following is the schema for incident notification output file:

<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="incident">
<xs:complexType>
<xs:sequence>
	<xs:element type="xs:string" name="name"/>
	<xs:element type="xs:string" name="description"/>
	<xs:element type="xs:string" name="displayTime"/>
	<xs:element type="xs:string" name="incidentSource"/>
	<xs:element name="incidentTarget">
		<xs:complexType>
			<xs:sequence>
				<xs:element name="entry">
				<xs:complexType>
				<xs:simpleContent>
					<xs:extension base="xs:string">
					<xs:attribute type="xs:string" name="attribute"/>
					<xs:attribute type="xs:string" name="name"/>
				</xs:extension>
				</xs:simpleContent>
			</xs:complexType>
		</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="incidentDetails">
<xs:complexType>
<xs:sequence>
<xs:element name="entry"> <xs:complexType>
		<xs:simpleContent>
			<xs:extension base="xs:float">
				<xs:attribute type="xs:string" name="attribute"/>
					<xs:attribute type="xs:string" name="name"/>
						</xs:extension>
							</xs:simpleContent>
							</xs:complexType>
						</xs:element>
					</xs:sequence>
				</xs:complexType>
				</xs:element>
			<xs:element type="xs:string" name="affectedBizSrvc"/>
			<xs:element type="xs:string" name="identityLocation"/>
		</xs:sequence>
		<xs:attribute type="xs:short" name="incidentId"/>
		<xs:attribute type="xs:string" name="ruleType"/>
		<xs:attribute type="xs:byte" name="severity"/>
		<xs:attribute type="xs:byte" name="repeatCount"/>
		<xs:attribute type="xs:string" name="organization"/>
		<xs:attribute type="xs:string" name="status"/>
	</xs:complexType>
	</xs:element>
</xs:schema>

Refer to Example Usage for incident notification via API.