Event request

Requests information about existing events using an HTTP GET request. You can also apply filters to requests.

GET https://<cm_address>/wsapis/{v1.2.0|v2.0.0}/events?<filters>

Availability

This command is available on the following appliances:

Central Management System
Network Security

Required headers:

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

Parameters

address—The IP address of the Trellix 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 two formats:
- application/xml—(Default) If content type is not specified, events are delivered in the XML format.
- application/json—Specify this option to receive events 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
`duration`	Specifies the time interval to search. This filter is used with the `end_time` filter. If the duration is not specified, the system defaults to `duration=12_hours, end_time=current_time` Syntax: `duration=time_interval` `1_hour` `2_hours` `6_hours` `12_hours` `24_hours` `48_hours` Example: `duration=1_hour&end_time=2015-01-24T16: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`. 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=2015-01-24T16:30:00.000-07:00`
`event_type`	The type of event. The value must be set to `Ips Event`. Example:`event_type=Ips Event`
`mvx_correlated_only`	Boolean. Specifies whether to include all IPS events or MVX-correlated events only. Default: false. Example: `mvx_correlated_only=true`

Example request with no filtering

Note

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

GET https://xxx.xxx.xxx.xxx:443/wsapis/v1.2.0/events?mvx_correlated_only=false

Request headers:

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

Example request with filtering

This example specifies the event type, end time, and duration.

GET https://xxx.xxx.xxx.xxx:443/wsapis/v1.2.0/events?duration=48_hours&end_time=2015-05-23T01:08:04.000-00:00&event_type=Ips%20Event'

Request headers:

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

Event response

After the event request is received, your appliance validates the API-Token and returns the requested data.

HTTP/1.1 [Response Code] [Response Message]
Date: [Date]
Content-Type: [Content-Type]
X-FeApi-Token: [API-Token]
X-FeClient-Token: [Client-Token]

Response fields

Response Code—A standard HTML response code.
- 200—Request successful.
- 400—Request unsuccessful because the filter value was invalid.
- 500—Request unsuccessful because the server encountered a problem.
Response Message—A standard HTML response message.
- OK—Request successful.
- Bad Request—Request unsuccessful because the filter value was invalid.
- Internal Server Error—Request unsuccessful because the server encountered a problem.
Date—Standard HTML date format.

Example response (XML)

HTTP/1.1 200 OK
Date: Fri, 20 Sep 2015 08:00:00 GMT

Body:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<eventsResponse>
   <eventType>Ips Events</eventType>
   <events>
	<event>
	   <actionTaken>1</actionTaken>
	   <attackMode>server</attackMode>
	   <dstIp>xx.xx.xx.xx</dstIp>
	   <dstMac>00:00:50:40:00:44</dstMac>
	   <dstPort>34352</dstPort>
	   <eventId>982377</eventId>
	   <interfaceId>3</interfaceId>
	   <occurred>2015-10-06T14:03:22-07:00</occurred>
	   <protocol>6</protocol>
	   <ruleName>MySQL XML Functions Scalar XPath Denial of Service</ruleName>
	   <sensorId>7</sensorId>
	   <severity>7</severity>
	   <signatureIden>85302536</signatureIden>
	   <signatureMatchCnt>1</signatureMatchCnt>
	   <signatureRev>4</signatureRev>
	   <srcIp>xxx.x.xxx.xxx</srcIp>
	   <srcMac>00:00:00:50:40:55</srcMac>
	   <srcPort>3306</srcPort>
	   <vlan>0</vlan>
	   <vmVerified>true</vmVerified>
	</event>
...,
...,
...,
	<event>
	   <actionTaken>33</actionTaken>
	   <attackMode>client</attackMode>
	   <dstIp>xx.xxx.xxx.xxx</dstIp>
	   <dstMac>00:50:56:f7:db:db</dstMac>
	   <dstPort>80</dstPort>
	   <eventId>982380</eventId>
	   <interfaceId>3</interfaceId>
	   <occurred>2015-10-06T14:32:17-07:00</occurred>
	   <protocol>6</protocol>
	   <ruleName>Windows Executable Download As Image File</ruleName>
	   <sensorId>7</sensorId>
	   <severity>7</severity>
	    <signatureIden>85305176</signatureIden>
	   <signatureMatchCnt>1</signatureMatchCnt>
	   <signatureRev>19</signatureRev>
	   <srcIp>xxx.xxx.xxx.xxx</srcIp>
	   <srcMac>00:0c:29:81:69:4f</srcMac>
	   <srcPort>1174</srcPort>
	   <vlan>0</vlan>
	   <vmVerified>true</vmVerified>
	</event>
   </events>
</eventsResponse>

Example response including all IPS events (JSON)

{
  "eventType":"Ips Events",
  "events":[
    {
      "eventId":11,
      "occurred":"2018-11-01T15:43:56-07:00",
      "srcIp":"28.188.24.38",
      "srcPort":1057,
      "dstIp":"85.6.103.48",
      "dstPort":80,
      "vlan":0,
      "signatureMatchCnt":1,
      "signatureIden":85305159,
      "signatureRev":17,
      "severity":7,
      "vmVerified":true,
      "srcMac":"d6:96:0a:84:24:15",
      "dstMac":"00:50:56:e5:3f:c5",
      "ruleName":"Trojan.Ramnit Infected Page Download",
      "sensorId":"raj-nx",
      "cveId":null,
      "actionTaken":33,
      "attackMode":"client",
      "interfaceId":4,
      "protocol":6,
      "incidentId":1989
    },
    {
      "eventId":12,
      "occurred":"2018-11-01T15:44:20-07:00",
      "srcIp":"59.252.28.97",
      "srcPort":1079,
      "dstIp":"11.41.112.187",
      "dstPort":80,
      "vlan":0,
      "signatureMatchCnt":1,
      "signatureIden":85311177,
      "signatureRev":3,
      "severity":5,
      "vmVerified":true,
      "srcMac":"00:20:18:11:ff:02",
      "dstMac":"02:75:ac:9f:b4:c0",
      "ruleName":"Rig Exploit Kit File Download",
      "sensorId":"raj-nx",
      "cveId":null,
      "actionTaken":33,
      "attackMode":"client",
      "interfaceId":4,
      "protocol":6,
      "incidentId":null
    },
    {
      "eventId":7,
      "occurred":"2018-11-01T15:39:54-07:00",
      "srcIp":"75.65.20.45",
      "srcPort":49195,
      "dstIp":"20.65.68.181",
      "dstPort":8080,
      "vlan":0,
      "signatureMatchCnt":1,
      "signatureIden":85301264,
      "signatureRev":15,"severity":7,
      "vmVerified":true,
      "srcMac":"00:20:18:11:01:65",
      "dstMac":"00:01:6c:a9:2f:27",
      "ruleName":"Adobe Multiple Products Embedded JBIG2 Stream Buffer Overflow",
      "sensorId":"raj-nx",
      "cveId":"cve,CVE-2009-0658",
      "actionTaken":33,
      "attackMode":"client",
      "interfaceId":4,
      "protocol":6,
      "incidentId":null
    }
  ]
}

cURL code sample: events

The following code sample can be copied and executed from any command-line interface that includes the cURL library. This sample builds on the authentication cURL code sample.

Note

In this sample, line breaks are added for readability. Remove these line breaks before you paste the code sample into your command-line tool.

curl -G -qgsSkH --no-progress-bar --header "X-FeApi-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" https://xxx.xxx.xxx.xxx:443/wsapis/v1.2.0/events --data-urlencode "duration=48_hours" --data-urlencode "end_time=2015-09-23T01:08:04.000-00:00" --data-urlencode "event_type=Ips Event"

This cURL sample includes the following options:

-G—This option specifies an HTTP GET request.
-q—This option specifies that the curlrc config file is not read or used. Although this is an optional setting, Trellix recommends that you include this option.
-g—This option turns off the URL globbing parser. Although this is an optional setting, Trellix recommends that you include this option.
-s—This option turns off the progress meter and error message. Although this is an optional setting, Trellix recommends that you include this option.
-S—When used with the -s option, this option shows error messages if your cURL switch fails. Although this is an optional setting, Trellix recommends that you include this option.
-k—This option explicitly allows cURL to perform insecure SSL connections and transfers. This allows you to test your SSL connection without installing a CA certificate.
-H—This option allows you to specify a custom header with the --header switch.
--no-progress-bar—This option suppresses the cURL download progress bar, which can interfere with the request.
--header "X-FeApi-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"—This custom header provides the API-Token that was returned during the authentication request. In the authentication cURL code sample, this token was included in the auth.txt file. Replace the token value in the code sample with the token value received in the response to your authentication request.
Note
By default, the X-FeApi-Token times out after 15 minutes of inactivity.
https://xxx.xxx.xxx.xxx:443/wsapis/v1.2.0/events—The event request URL. Replace the IP address xxx.xxx.xxx.xxx with the IP address of your appliance.
--data-urlencode "duration=48_hours"—This option specifies the time interval to search.
--data-urlencode "end_time=2015-09-23T01:08:04.000-00:00"—This option specifies the end time of the search.
--data-urlencode "event_type=Ips Event"—This option specifies the type of event.

Results

This code sample returns XML-formatted event data from your appliance. If you do not receive any event data and you did not encounter an error message, check your appliance to see whether any event data is available.