Trellix Enterprise Security Manager
This Connector integrates Trellix Enterprise Security Manager v2's Rest API with Swimlane Turbine.
Prerequisites
The Trellix ESM requires a host, username and password for authentication.
Capabilities
The Trellix ESM connector has the following capabilities:
- Add Watchlist Values
- Execute Query Detail
- Get Alarms
- Get Correlated Event for ID
- Get Event Details
- Get Query Results
- Get Query Status
- Get Triggered Alarms
- Get Triggered Alarm Details
- Get Watchlist
- Query IPs
- Remove Watchlist Values
- Total Events
Notes
- The IP query may take some time while Trellix ESM processes the request.
- This connector supports product version: 10.0, 10.1, 10.2, 10.3, 11.1, 11.3
Configurations
Trellix ESM HTTP Basic Authentication
Authenticates using username and password.
Configuration Parameters
Parameter | Description | Type | Required |
|---|---|---|---|
url | A target Url. | string | Required |
username | Username | string | Required |
password | Password | string | Required |
verify_ssl | Verify SSL certificate | boolean | Optional |
http_proxy | A proxy to route requests through. | string | Optional |
Actions
Add Watchlist Values
Adds specified values to a watchlist in Trellix Enterprise Security Manager using provided JSON body data.
Endpoint
- URL: /sysAddWatchlistValues
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
watchlist | number | Optional | ID of the watchlist. |
values | array | Optional | List of string values to be added to a watchlist. |
Input Example
{"json_body":{"watchlist":0,"values":[""]}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output Example
{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Wed, 13 Dec 2023 20:37:23 GMT"},"reason":"OK","json_body":{}}
Execute Query Detail
Executes a detailed query in Trellix Enterprise Security Manager to retrieve specific event information.
Endpoint
- URL: /qryExecuteDetail
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.type | string | Optional | The type of query to execute, either EVENT or FLOW. |
parameters.reverse | boolean | Optional | Whether to reverse the order of the results. |
config | object | Optional | The parameters to apply to the query including filters, ordering, fields, etc. |
config.timeRange | string | Optional | Parameter for Execute Query Detail |
config.customStart | string | Optional | Parameter for Execute Query Detail |
config.customEnd | string | Optional | Parameter for Execute Query Detail |
config.order | array | Optional | Parameter for Execute Query Detail |
config.order.direction | string | Optional | Parameter for Execute Query Detail |
config.order.field | object | Optional | Parameter for Execute Query Detail |
config.order.field.name | string | Optional | Name of the resource |
config.order.field.typeBits | number | Optional | Type of the resource |
config.order.field.id | string | Optional | Unique identifier |
config.includeTotal | boolean | Optional | Parameter for Execute Query Detail |
config.fields | array | Optional | Parameter for Execute Query Detail |
config.fields.name | string | Optional | Name of the resource |
config.fields.typeBits | number | Optional | Type of the resource |
config.fields.id | string | Optional | Unique identifier |
config.filters | array | Optional | Parameter for Execute Query Detail |
config.filters.type | string | Optional | Type of the resource |
config.filters.field | object | Optional | Parameter for Execute Query Detail |
config.filters.field.name | string | Optional | Name of the resource |
config.filters.operator | string | Optional | Parameter for Execute Query Detail |
config.filters.values | array | Optional | Value for the parameter |
config.filters.values.type | string | Optional | Type of the resource |
config.filters.values.watchlist | number | Optional | Value for the parameter |
Input Example
{"parameters":{"type":"EVENT","reverse":false},"json_body":{"config":{"timeRange":"CUSTOM","customStart":"2020-03-11T11:30:12.583Z","customEnd":"2020-03-11T11:30:12.584Z","order":[{"direction":"ASCENDING","field":{"name":"","typeBits":0,"id":"ab456df"}}],"includeTotal":false,"fields":[{"name":"","typeBits":0,"id":"ab456df"}],"filters":[{"type":"EsmFieldFilter","field":{"name":""},"operator":"IN","values":[{"type":"EsmWatchlistValue","watchlist":0}]}],"limit":0,"offset":0,"netmask":""}}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output Example
{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Wed, 13 Dec 2023 20:37:23 GMT"},"reason":"OK","json_body":{}}
Fetch Alarms
Fetch triggered alarms
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
timeRange | string | Optional | The time period for the search. |
customStart | string | Optional | If the timeRange argument is set to CUSTOM, the start time for the time is considered. range. |
customEnd | string | Optional | If the timeRange argument is set to CUSTOM, the end time for the time is considered. range. |
Input Example
{"timeRange":"CURRENT_YEAR"}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output Example
{"status_code":200,"response_headers":{},"reason":"OK","json_body":[{"ID":42710,"acknowledgedDate":"2020-06-24T11:32:08Z","acknowledgedUsername":"","alarmName":"Alarm Test","assignee":"ANALYST","conditionType":22,"severity":50,"summary":"Event rate exceeded 10 by 17","triggeredDate":"2020-06-24T13:05:43Z"}]}
Get Correlated Event for ID
Retrieve source events and flows associated with a specified correlated event ID in Trellix ESM.
Endpoint
- URL: /qryGetCorrEventDataForID
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.queryType | string | Optional | Either EVENT or FLOW depending on the events needed. |
eventId | string | Optional | The event ID whose source events are needed. |
fields | array | Optional | The list of fields to provide in the returned rows. |
fields.name | string | Optional | Name of the resource |
fields.typeBits | number | Optional | Type of the resource |
fields.id | string | Optional | Unique identifier |
Input Example
{"parameters":{"queryType":"EVENT"},"json_body":{"eventId":"","fields":[{"name":"","typeBits":0,"id":"ab456df"}]}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output Example
{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Wed, 13 Dec 2023 20:37:23 GMT"},"reason":"OK","json_body":{}}
Get Event Details
Retrieve detailed alert data from Trellix Enterprise Security Manager using a specific event ID.
Endpoint
- URL: /ipsGetAlertData
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
id | string | Optional | The IPSIDAlertID of the event. |
Input Example
{"json_body":{"id":""}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output Example
{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Wed, 13 Dec 2023 20:37:23 GMT"},"reason":"OK","json_body":{}}
Get Query Results
Retrieve the results of a specified query from Trellix Enterprise Security Manager.
Endpoint
- URL: /qryGetResults
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.startPos | number | Optional | The start position of the requested data. |
parameters.numRows | number | Optional | The number of rows requested. |
resultID | string | Optional | The result ID whose data is being requested. |
Input Example
{"parameters":{"startPos":0,"numRows":3},"json_body":{"resultID":"123456789000"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output Example
{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Wed, 13 Dec 2023 20:37:23 GMT"},"reason":"OK","json_body":{}}
Get Query Status
Retrieve the execution status of a specific query in Trellix Enterprise Security Manager using the resultID.
Endpoint
- URL: /qryGetStatus
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
resultID | string | Optional | The ID of the results, gotten from the EsmActiveQuery returned from qryExecuteQuery(). |
Input Example
{"json_body":{"resultID":"123456789000"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output Example
{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Wed, 13 Dec 2023 20:37:23 GMT"},"reason":"OK","json_body":{}}
Get Triggered Alarm Details
Retrieve detailed information for a specific triggered alarm in Trellix Enterprise Security Manager using the alarm's ID.
Endpoint
- URL: /notifyGetTriggeredNotificationDetail
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
id | number | Optional | The alarm to get the details for. |
Input Example
{"json_body":{"id":0}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output Example
{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Wed, 13 Dec 2023 20:37:23 GMT"},"reason":"OK","json_body":{}}
Get Triggered Alarms
Retrieve a paged list of triggered alarms from Trellix Enterprise Security Manager.
Endpoint
- URL: /alarmGetTriggeredAlarms
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.triggeredTimeRange | string | Optional | Filter the list of alarms by those that where triggered in this time range. |
parameters.customStart | string | Optional | If triggeredTimeRange is CUSTOM, start time for the time range (ignored if triggeredTimeRange is not CUSTOM). |
parameters.customEnd | string | Optional | If triggeredTimeRange is CUSTOM, end time for the time range (ignored if triggeredTimeRange is not CUSTOM). |
parameters.status | string | Optional | Can be (case sensitive) 'acknowledged', 'unacknowledged', "" or null -> all (default is null). |
parameters.pageSize | string | Optional | The number of alarms to return per page (default is 1000, max is 5000). |
parameters.pageNumber | string | Optional | which page of alarms we want to return (default is 1). |
assignedUser | object | Optional | The userid assigned to handle this triggered alarm (default is current user). |
assignedUser.username | string | Optional | Name of the resource |
assignedUser.id | number | Optional | Unique identifier |
assignedUser.locked | boolean | Optional | Parameter for Get Triggered Alarms |
assignedUser.loggedInCount | number | Optional | Count value |
assignedUser.email | string | Optional | Parameter for Get Triggered Alarms |
assignedUser.emailId | number | Optional | Unique identifier |
assignedUser.sms | string | Optional | Parameter for Get Triggered Alarms |
assignedUser.smsId | number | Optional | Unique identifier |
assignedUser.master | boolean | Optional | Parameter for Get Triggered Alarms |
assignedUser.admin | boolean | Optional | Parameter for Get Triggered Alarms |
assignedUser.alias | string | Optional | Parameter for Get Triggered Alarms |
assignedUser.type | string | Optional | Type of the resource |
assignedUser.groups | array | Optional | Parameter for Get Triggered Alarms |
Input Example
{"parameters":{"triggeredTimeRange":"CUSTOM","customStart":"2020-03- 11T11:30:12.546Z","customEnd":"2020-03-11T11:30:12.546Z","status":"acknowledged","pageSize":"1000","pageNumber":"1"},"json_body":{"assignedUser":{"username":"david","id":0,"locked":false,"loggedInCount":0,"email":"[email protected]","emailId":0,"sms":"","smsId":0,"master":false,"admin":false,"alias":"","type":"POWER","groups":[0]}}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output Example
{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Wed, 13 Dec 2023 20:37:23 GMT"},"reason":"OK","json_body":{}}
Get Watchlist
Retrieves basic information for all watchlists within the Trellix Enterprise Security Manager system.
Endpoint
- URL: /sysGetWatchlists
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.hidden | boolean | Optional | Whether to show hidden watchlists. |
parameters.dynamic | boolean | Optional | Whether to show dynamic watchlists. |
parameters.writeOnly | boolean | Optional | Whether to only show modifiable watchlists. |
parameters.indexedOnly | boolean | Optional | Whether to show indexed watchlists. |
filters | array | Optional | List of fields/types used to filter the list of watchlists returned. |
filters.name | string | Optional | Name of the resource |
filters.id | number | Optional | Unique identifier |
Input Example
{"parameters":{"hidden":false,"dynamic":false,"writeOnly":false,"indexedOnly":false},"json_body":{"filters":[{"name":"david","id":0}]}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output Example
{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Wed, 13 Dec 2023 20:37:23 GMT"},"reason":"OK","json_body":{}}
Query IPs
Retrieve All Events Correlating to an IP Address.
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
target_ip | string | Required | Parameter for Query IPs |
time_range | string | Required | Parameter for Query IPs |
custom_start | string | Optional | Parameter for Query IPs |
custom_end | string | Optional | Parameter for Query IPs |
limit | number | Optional | Parameter for Query IPs |
Input Example
{"target_ip":"8.8.8.8","time_range":"CURRENT_YEAR","limit":50}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output Example
{"status_code":200,"response_headers":{},"reason":"OK","json_body":[{"firstTime":42710,"lastTime":"2020-06-24T11:32:08Z","eventCount":20,"srcIP":"8.8.8.8","dstIP":"0.0.0.0","protocol":"HTTP","dSIDSigID":"50","ruleMSG":"Event rate exceeded 10 by 17","userIDSrc":"","eventID":1}]}
Remove Watchlist Values
Removes specified values from a watchlist in Trellix Enterprise Security Manager, requiring a 'watchlist' parameter.
Endpoint
- URL: /sysRemoveWatchlistValues
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
watchlist | number | Optional | ID of the watchlist. |
values | array | Optional | List of string values to be removed from a watchlist. |
Input Example
{"json_body":{"watchlist":0,"values":[""]}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output Example
{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Wed, 13 Dec 2023 20:37:23 GMT"},"reason":"OK","json_body":{}}
Total Events
Retrieve Total Events Correlating to an IP Address.
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
target_ip | string | Required | Parameter for Total Events |
time_range | string | Required | Parameter for Total Events |
custom_start | string | Optional | Parameter for Total Events |
custom_end | string | Optional | Parameter for Total Events |
limit | number | Optional | Parameter for Total Events |
Input Example
{"target_ip":"8.8.8.8","time_range":"CURRENT_YEAR","limit":50}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output Example
{"status_code":200,"response_headers":{},"reason":"OK","json_body":{}}
Response Headers
Header | Description | Example |
|---|---|---|
content-length | The length of the response body in bytes | 140 |
content-type | The media type of the resource | application/json |
Date | The date and time at which the message was originated | Wed, 13 Dec 2023 20:37:23 GMT |