Alert request

You can request existing alert profiles using an HTTP GET request. You can also apply filters to requests. To view existing alerts, send the following HTTP GET request URL and headers:

GET https://<address>/wsapis/[v1.2.0|v2.0.0]/alerts?<filters>

Availability

This command is available on the following appliances:

Central Management System
Malware Analysis
Email Security — Server
File Protect
Network Security

Headers:

X-FeApi-Token: [API-Token]
X-FeClient-Token: [Client-Token]
Accept: [Content-Type]

Options

address—The IP address of the appliance running the Web Services API.
API-Token—This token authenticates the session. By default, the session times out after 15 minutes of inactivity.
Client-Token—(Optional) This client token is provided by Trellix. For more information about the client token, contact your sales representative.
Content-Type—(Optional) You can request responses in one of two alert formats:
- application/xml—(Default) If content type is not specified, alerts are delivered in the XML format.
- application/json—Specify this option to receive alerts in JSON format.
  Note
  The JSON output uses the pretty-print format, which includes line breaks between values.

Filters

Use the filters in the following table to limit your request.

Filter	Description
`alert_id`	Specifies the ID number of the alert to retrieve. Syntax: `?alert_id=id_number` or `/alert/id_number` Example: `alerts?alert_id=13705` or `alerts/alert/13705`
`alert_limit_override`	Overrides the limit of the number of alerts. Syntax: `?alert_limit_override=<true or false>` Example: `alerts?alert_limit_override=true`
`callback_domain`	Searches for alerts that include callbacks to the specified domain. Syntax: `callback_domain=domain` Example: `callback_domain=onecompany.com`
`dst_ip`	The destination IPv4 address related to the malware alert. Syntax: `dst_ip=ip_address` Example: `dst_ip=xxx.xxx.xxx.xxx`
`duration`	Specifies the time interval to search. This filter is used with either the `start_time` or `end_time` filter. If duration, start time, and end time are not specified, the system defaults to `duration=48_hours`, `end_time=current_time`. If only duration is specified, the `end_time` defaults to current time. Note You cannot specify both a `start_time` filter and an `end_time` filter in the same request. Syntax: `duration=time_interval` `1_hour` `2_hours` `6_hours` `12_hours` `24_hours` `48_hours` Example: `duration=1_hour&start_time=2017-06-21T16:30:00.000-07:00`
`end_time`	Specifies the end time of the search. This filter is used with the `duration` filter. If the `end_time` is specified but not the `duration`, the system defaults to `duration=12_hours`, ending at the specified `end_time`. Note You cannot specify both a `start_time` filter and an `end_time` filter in the same request. Syntax: `end_time=YYYY-MM-DDTHH:mm:ss.sss-OH:om` `YYYY`—Year (1900 and later) `MM`—Month (01-12) `DD`—Day (01-31) `HH`—Hour (01-24) `mm`—Minutes (01-59) `ss.sss`—Seconds (01-59.999) `OH:om`—Time offset from UTC Example: `duration=1_hour&end_time=2017-06-21T16:30:00.000-07:00`
`file_name`	The name of the malware file. Syntax: `file_name="file_name"` Example: `file_name="Trojan.Zlob"`
`file_type`	The malware file type. Syntax: `file_type=file_type` Example: `file_type=com`
`include_oschanges`	Includes or removes OS changes. Syntax: `alerts?include_oschanges=<true or false>` Example: `alerts?include_oschanges=false`
`info_level`	Specifies the level of information to be returned. The default is `concise`. `concise` `normal` `extended` Syntax: `info_level=option` Example: `info_level=normal` Note When using API v1.2.0 at info_level normal or extended, the response includes ATI data. This information is not included in the response when using v2.0.0. To retrieve ATI data for the specific alert ID, use the ATI details request.
`limit`	Specifies the number of alerts to be returned. Syntax: `limit=number_of_alerts` Example: `alerts?limit=20`
`malware_name`	The name of the malware object. Syntax: `malware_name=name` Example: `malware_name=trojan.exe`
`malware_type`	The type of the malware object: `domain_match` `malware_callback` `malware_object` `web_infection` `infection_match` `riskware-infection` `riskware-callback` `riskware-object` Syntax: `malware_type=name` Example: `malware_type=malware_object` cURL example: `curl -kqg -H "$c" "https://<base>/v2.0.0/alerts?include_riskware=true&malware_type=riskware-callback"`
`md5`	Searches for alerts that include a specific MD5 hash. Note The `md5` filter is not time dependent; it does not default to `duration=12_hours`. Syntax: `md5=md5hash` Example: `md5=8bc944dbd052ef51652e70a5104492e3` Note The system tests for a valid MD5 hash. Using this filter without a qualified MD5 hash will return a 400 Bad Request response.
`offset`	Offset is the starting point from where the alert listing will start. If the offset is zero, the returned alerts list will start from the first alert. If the offset is 5, the returned alerts list will start from the 5th alert. Syntax: `offset=alert_number` Example: `alerts?offset=10`
`recipient_email`	The email address of the malware object receiver. This filter does not default to `duration=12_hours`. Syntax: `recipient_email=email_address` Example: `recipient_email=jane.doe@somecompany.com`
`sender_email`	The email address of the malware object sender. This filter does not default to `duration=12_hours`. Syntax: `sender_email=email_address` Example: `sender_email=jane.doe@somecompany.com`
`src_ip`	The source IPv4 address related to the malware alert. Syntax: `src_ip=ip_address` Example: `src_ip=xxx.xxx.xxx.xxx`
`start_time`	Specifies the start time of the search. This filter is used with the `duration` filter. If the `start_time` is specified but not the `duration`, the system defaults to `duration=12_hours`, starting at the specified `start_time`. Note You cannot specify both a `start_time` filter and an `end_time` filter in the same request. Syntax: `start_time=YYYY-MM-DDTHH:mm:ss.sss-OH:om` `YYYY`—Year (1900 and later) `MM`—Month (01-12) `DD`—Day (01-31) `HH`—Hour (01-24) `mm`—Minutes (01-59) `ss.sss`—Seconds (01-59.999) `OH:om`—Time offset from UTC Example: `duration=1_hour&start_time=2017-06-21T16:30:00.000-07:00`
`url`	Searches for a specific alert URL. Syntax: `url=url` Example: `url=http://cms/alerts/list?id=3`

Example request with no filtering

Note

In this example, the searchʼs duration filter will be set to 12_hours (default), and the end_time filter will be set to the current time (default).

GET https://xxx.xxx.xxx.xxx:443/wsapis/v2.0.0/alerts?

Request headers:

X-FeApi-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-FeClient-Token: BigDataInc

Example request with filtering

This example specifies the start time and duration.

GET https://xxx.xxx.xxx.xxx:443/wsapis/v2.0.0/
alerts?start_time=2018-07-03T21:19:01:39:000%2b00:00&duration=2_hours

Request headers:

X-FeApi-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-FeClient-Token: BigDataInc