Trellix McAfee ESM

LAST UPDATED: AUG 5, 2025

Overview

Trellix McAfee ESM (ESM) is a SIEM solution that can collect logs from various sources and correlate events for investigation and incident response.

D3 SOAR is providing REST operations to function with Trellix McAfee ESM.

Trellix McAfee ESM is available for use in:

D3 SOAR	V12.7.83.0+
Category	SIEM
Deployment Options	Option I, Option III

Connection

To connect to Trellix McAfee ESM from D3 SOAR, please follow this part to collect the required information below:

Parameter	Description	Example
Server URL	The server URL of the McAfee ESM instance.	https://*****
Username	The username to access McAfee ESM.	NGCP
Password	The password credential to access McAfee ESM.	Decit**
Version	The API version to use for the connection.	v2

Configuring Trellix McAfee ESM to Work with D3 SOAR

Log in to McAfee ESM with your credentials.
Click on the hamburger icon to reveal the sidebar menu. Select System Properties.
To configure System Properties, you must have the ESM Administrator App installed on your computer. If you have not already done so, click Download .exe (Windows). If the ESM Administrator App is already installed, click Launch.
1. After you have downloaded the .exe file, run and install it. Click Finish to complete the installation.
Go back to McAfee ESM, and click Launch. A pop-up window will appear asking for permission to open ESM_Administrator_App. Select Open ESM_Administrator_App. You will be directed to the ESM Administrator App.
In the ESM Administrator App, click on the hamburger icon to reveal the sidebar menu. Select System Properties > Users and Groups.
You will be prompted to enter a password. Input your account login password and click OK.
Click Add to create a new user. Input a Username, and set your Password. Grant Administrator Rights, then click OK.
Input your account login password in the popup to save this user.

You will be able to find the created user account from the user list. The created account is ready for configuring an integration connection in D3 SOAR.

Configuring D3 SOAR to Work with Trellix McAfee ESM

Log in to D3 SOAR.
Find the Trellix McAfee ESM integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type Trellix McAfee ESM in the search box to find the integration, then click it to select it.
4. Click New Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Trellix McAfee ESM.
1. Connection Name: The desired name for the connection.
2. Site: The site on which to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
3. Recipient site for events from connections Shared to Internal Sites: This field is displayed when Share to Internal Sites is selected for the Site field, allowing selection of the internal site for deploying the integration connection.
4. Agent Name (Optional): The proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
5. Description (Optional): The description for the connection.
6. Tenant (Optional): When configuring the connection from a master tenant site, users can choose the specific tenant sites with which to share the connection. Once this setting is enabled, users can filter and select the desired tenant sites from the dropdowns to share the connection.
7. Configure User Permissions: Defines which users have access to the connection.
8. Active: The checkbox that enables the connection to be used when selected.
9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  
  1. Input your McAfee ESM Server URL.
  2. Input your McAfee ESM Username.
  3. Input your McAfee ESM Password.
  4. Input your Version. The default value is v2.
10. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Refer to the password vault connection guide if needed.
11. Connection Health Check: Periodically checks the connection status by scheduling the Test Connection command at the specified interval (in minutes). Available only for active connections, this feature also allows configuring email notifications for failed attempts.
Test the connection.
1. Click on the Test Connection button to verify credentials and connectivity. A success alert displays Passed with a green checkmark. If the connection fails, review the parameters and retry.
2. Click OK to close the alert window.
3. Click Add to create and add the configured connection.

Commands

Trellix McAfee ESM includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, users can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the Trellix McAfee ESM API, refer to the Trellix McAfee ESM API reference at https://<Server Address>/rs/esm/v2/help.

Note for Time-related parameters

The input format of time-related parameters may vary based on user account settings, which may cause the sample data in commands to differ from what is displayed. To adjust the time format, follow these steps:

Navigate to Configuration > Application Settings. Select Date/Time Format.
Choose the desired date and time format, then click on the Save button.

The selected time format will now be visible when configuring Date/Time command input parameters.

Acknowledge Triggered Alarm

Marks a triggered alarm as acknowledged.

READER NOTE

The parameter Alarm IDs is required to run this command.

Run the Get Triggered Alarms command to obtain Alarm IDs. Alarm IDs can be found in the returned raw data at the path $.id.

Input

Input Parameter	Required/Optional	Description	Example
Alarm IDs	Required	The ID(s) of triggered alarm(s) to mark as acknowledged. Alarm IDs can be obtained using the Get Triggered Alarms command.	[*****]

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Acknowledge Triggered Alarm failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Trellix McAfee ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Alarm IDs Not Found.

Error Sample Data

Acknowledge Triggered Alarm failed.

Status Code: 404.

Message: Alarm IDs Not Found.

Add Values To Watchlist

Adds values to watchlists. Note: Hidden watchlists (e.g. GTI) are not supported.

READER NOTE

The parameter Watchlist IDs required to run this command.

Run the List Watchlists command to obtain Watchlist IDs. Watchlist IDs can be found in the raw data at the path $.[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Watchlist IDs	Required	The ID(s) of the watchlist(s) to add values to. Watchlist IDs can be obtained using the List Watchlists command.	[*****]
Values	Required	The string value(s) to add to the specified watchlist(s).	["*...","...","...*"]

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Add Values To Watchlist failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Trellix McAfee ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Watchlist IDs Not Found.

Error Sample Data

Add Values To Watchlist failed.

Status Code: 404.

Message: Watchlist IDs Not Found.

Add Watchlist

Adds watchlists to the system.

READER NOTE

If you input an existing Watchlist Name in the system, an error will return. Use the List Watchlists command to return a list of watchlists to check for duplicates.

Input

Input Parameter	Required/Optional	Description	Example
Watchlist Names	Required	The names of the new watchlists.	NewWatchlist
Watchlist Type	Required	The watchlist type to assign the new watchlists to.	Port

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Add Watchlist failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Trellix McAfee ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: ERROR_DuplicateName.

Error Sample Data

Add Watchlist failed.

Status Code: 400.

Message: ERROR_DuplicateName.

Delete Triggered Alarm

Deletes specified triggered alarms in the system.

READER NOTE

The parameter Alarm IDs is required to run this command.

Run the Get Triggered Alarms command to obtain Alarm IDs. Alarm IDs can be found in the raw data at the path $.[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Alarm IDs	Required	The ID(s) of triggered alarm(s) to delete. Alarm IDs can be obtained using the Get Triggered Alarms command.	[*****]

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Delete Triggered Alarm failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Trellix McAfee ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Alarm IDs Not Found.

Error Sample Data

Delete Triggered Alarm failed.

Status Code: 404.

Message: Alarm IDs Not Found.

Edit Watchlist

Edits the properties of a watchlist (except watchlist type). Note: Hidden watchlists (e.g. GTI) are not supported.

READER NOTE

Watchlist ID is a required parameter to run this command.

Run the List Watchlists command to obtain Watchlist ID. Watchlist IDs can be found in the raw data at the path $.[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Watchlist ID	Required	The ID of the watchlist to edit. Watchlist ID can be obtained using the List Watchlists command.	*****
Active Status	Optional	The active status of the watchlist.	1
Watchlist Type	Optional	The updated type of the watchlist.	DstIP
Scored Category	Optional	Puts the watchlist in the scored category.	False
Dynamic Category	Optional	Puts the watchlist in the dynamic category.	False
Hidden Status	Optional	Sets the watchlist to hidden.	False
Watchlist Name	Required	The updated name of the watchlist.	wl100t1

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Edit Watchlist failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Trellix McAfee ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: ERROR_InsufficientRights.

Error Sample Data

Edit Watchlist failed.

Status Code: 400.

Message: ERROR_InsufficientRights.

Fetch Event

Returns events from McAfee ESM based on the specified criteria.

READER NOTE

Input parameter Fields is optional to run this command.

Run the List Available Select Fields command to obtain Fields. Fields can be found in the raw data at the path $.[*].name.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Required	The start time of the time range to fetch events in UTC time.	2022-09-22 00:00
End Time	Optional	The end time of the time range to fetch events in UTC time.	2022-11-23 00:00
Fields	Optional	The comma-separated list of the additional fields to return in the response data. The available fields can be obtained using the List Available Select Fields command. The following fields are returned by default: ASNGeoDst ASNGeoSrc AvgSeverity DSIDSigID DstIP DstMac DstPort EventCount FirstTime IPSID IPSIDAlertID LastTime GUIDDst GUIDSrc SessionID SigID SrcIP SrcMac SrcPort ZoneDst ZoneSrc Rule_NDSNormSigID.msg	Rule.NormID, VLan
Search Condition	Required	The JSON-formatted query to filter results. Refer to the McAfee ESM API documentation at https://<Server Address>/rs/esm/v2/help/types/EsmFieldFilter for more information about the query syntax.	[ { "type": "EsmFieldFilter", "field": { "name": "DstIP" }, "operator": "CONTAINS", "values": [ { "type": "EsmBasicValue", "value": "*****" } ] } ]
Tolerance Scope	Optional	The tolerance scope (the default value is 10) in minutes of the query to fetch events between start and end time to avoid the loss of events. Events will be fetched between {Start Time - Tolerance Scope, End Time}.	10

Output

To view the sample output data for all commands, refer to this article.

Fetch Event Field Mapping

Please note that Fetch Event commands require event field mapping. Field mapping plays a key role in the data normalization process part of the event pipeline. Field mapping converts the original data fields from the different providers to the D3 fields which are standardized by the D3 Model. Please refer to Event and Incident Intake Field Mapping for details.

If you require a custom field mapping, click +Add Field to add a custom field mapping. You may also remove built-in field mappings by clicking x. Please note that two underscore characters will automatically prefix the defined Field Name as the System Name for a custom field mapping. Additionally, if an input Field Name contains any spaces, they will automatically be replaced with underscores for the corresponding System Name.

The Trellix McAfee ESM integration in D3 SOAR has two pre-configured field mappings: Default Event Source and ESM Alarm Events. Only the default field mapping will be used for the Fetch Event command. Both the default field mapping and ESM Alarm Events mapping can be used for the Fetch Incident command.

Default Event Source
The Default Event Source is the default set of field mappings that are applied when this fetch event command is executed. For out-of-the-box integrations, you will find a set of field mapping provided by the system. Default event source provides field mappings for common fields from fetched events. The default event source has a “Main Event JSON Path” (i.e., $.return) that is used to extract a batch of events from the response raw data. Click Edit Event Source to view the “Main Event JSON Path”.
- Main Event JSON Path: $.return

The Main Event JSON Path determines the root path where the system starts parsing raw response data into D3 event data. The JSON path begins with $, representing the root element. The path is formed by appending a sequence of child elements to $, each separated by a dot (.). Square brackets with nested quotation marks ([‘...’]) should be used to separate child elements in JSON arrays.

For example, the root node of a JSON Path is return. The child node denoting the FirstTime field would be FirstTime. Putting it together, the JSON Path expression to extract the FirstTime is $.return.FirstTime.

ESM Alarm Events
Configures the field mapping which are specific to the ESM Alarm Events. If a source field in the field mapping is not found, the corresponding field mapping will be ignored. As the data of the ESM Alarm Events have a character that the value of the isAlarmEvent field is true, the ESM Alarm Events can be defined by the Search String: {$.isAlarmEvent}=true. Click Edit Event Source to view the Search String.

The pre-configured field mappings are detailed below:

Field Name	Source Field
Default Event Source (Main Event JSON Path: $.return)
Unique Event Key	*{EventID}-{__FirstTime}-{__LastTime}
ASNGeoDst	.ASNGeoDst
ASNGeoSrc	.ASNGeoSrc
Severity	.AvgSeverity
Event code	.DSIDSigID
Destination IP address	.DstIP
Destination MAC	.DstMac
Destination port	.DstPort
Aggregated / Correlated Event count	.EventCount
GUIDDst	.GUIDDst
GUIDSrc	.GUIDSrc
IPSID	.IPSID
IPSIDAlertID	.IPSIDAlertID
Rule name	.AlertData.ruleName
Session ID	.SessionID
Signature ID	.SigID
Source IP address	.SrcIP
Source MAC address	.SrcMac
Source port	.SrcPort
Destination zone	.ZoneDst
Source zone	.ZoneSrc
FirstTime	.FirstTime
LastTime	.LastTime
Event Type	.['Rule_NDSNormSigID.msg']
Start Time	.FirstTimeLocal
End Time	.LastTimeLocal
Description	.AlertData.normDesc
ESM Alarm Events (Search String: {$.isAlarmEvent}=true) The search string format is {jsonpath}=value. If the value of the isAlarmEvent key is true in the event object under raw data, then the ESM Alarm Events will use the field mapping below.
Unique Event Key	.eventId
Rule name	.ruleName
Severity	.severity
Destination IP address	.destIp
Destination MAC	.destMac
Destination port	.destPort
Signature ID	.sigId
Device	.deviceName
Source username	.srcUser
Hostname	.host
Source IP address	.srcIp
Source MAC address	.srcMac
Source port	.srcPort
Event Type	.ruleName
Start Time	.firstTimeLocal
End Time	.lastTimeLocal
Description	.normMessage

READER NOTE

*{EventID}-{__FirstTime}-{__LastTime}

In D3 SOAR, the events from Trellix McAfee ESM will be predefined with {EventID}-{__FirstTime}-{__LastTime} as the Unique Event Key.

Please note that the source type for Event Type is defined as Placeholder. {EventID}-{__FirstTime}-{__LastTime} is a default mapping value provided by D3.
{EventID}-{__FirstTime}-{__LastTime} will be auto filled by the Event Code, FirstTime and LastTime field mappings.
See Source Field Type from Event and Incident Intake Field Mapping for more details on event field mapping field types.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Fetch Event failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Trellix McAfee ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid fields.

Error Sample Data

Fetch Event failed.

Status Code: 400.

Message: Invalid Fields.

Fetch Incident

Returns incidents from McAfee ESM based on the specified criteria.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Required	The start time of the time range to fetch incidents in UTC time.	2022-09-22 00:00
End Time	Optional	The end time of the time range to fetch incidents in UTC time.	2022-11-23 00:00
Tolerance Scope	Optional	The tolerance scope (the default value is 10) in minutes of the query to fetch incidents between start and end time to avoid the loss of incidents. Incidents will be fetched between {Start Time - Tolerance Scope, End Time}.	0
Event Search Condition	Optional	The query to filter results. Refer to the McAfee ESM API documentation at https://<Server Address>/rs/esm/v2/help/types/EsmFieldFilter for more information about the query syntax.	[ { "type": "EsmFieldFilter", "field": { "name": "DstIP" }, "operator": "CONTAINS", "values": [ { "type": "EsmBasicValue", "value": "*****" } ] } ]
Create Incidents Only When Events Match Search Conditions	Optional	The option to only create incidents when events in the alarms match the event search conditions. The default value is False.	False
Number of Incident(s) Fetched	Optional	The maximum number of incidents to return. The default value is 10.	10

Output

To view the sample output data for all commands, refer to this article.

Incident Field Mapping

For this integration, the default incident fields in D3 SOAR are fixed with no built-in source fields. Users can specify the source fields as needed.

Event and Incident Intake Field Mapping

Please note that incident and event intake commands require both Event Field and Incident Field Mapping. These field mappings are the default event/incident field mappings for D3 system integrations. You can edit the provided mappings or create custom mappings as needed. Please refer to Event and Incident Intake Field Mapping for more details.

Incident Main JSON Path: $

Field Name	Source Field
Title	User to define
Description	User to define
Severity	User to define, default is “Low”
Incident Type *	User to define, default is the first Incident form in D3 SOAR system
Incident Creator	User to define
Incident Owner	User to define
Incident Playbook	User to define
Due In Date	User to define
Unique Key	User to define
Tactics	User to define
Techniques	User to define

Event Field Mapping

Main Event JSON Path

$.return

The event field mapping in Fetch Incident is the same as the one in Command Fetch Event.

Please refer to the command Fetch Event for detail.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Fetch Incident failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Trellix McAfee ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid Search Condition.

Error Sample Data

Fetch Incident failed.

Status Code: 400.

Message: Invalid Search Condition.

Fetch Related Events

Returns related events from McAfee ESM based on the specified criteria.

READER NOTE

The parameter Fields is optional to run this command.

Run the List Available Select Fields command to obtain Fields. Fields can be found in the raw data at the path $.[*].name.

Input

Input Parameter	Required/Optional	Description	Example
Related Hours	Optional	The number of hours before the current time to fetch related incidents. If this parameter is not defined, the default value is 1.	1
Fields	Optional	The comma-separated list of the additional fields to return in the response data. The available fields can be obtained using the List Available Select Fields command.	IPSIDAlertID,DstIP,SrcIP,NormID
Search Condition	Required	The JSON-formatted query to filter results. Refer to the McAfee ESM API documentation at https://<Server Address>/rs/esm/v2/help/types/EsmFieldFilter for more information about the query syntax.	[{"type":"EsmFieldFilter","field":{"name":"DstIP"},"operator":"CONTAINS","values":[{"type":"EsmBasicValue","value":"*****"}]}]
Tolerance Scope	Optional	The tolerance scope (the default value is 10) in minutes of the query to fetch events between start and end time to avoid the loss of events. Events will be fetched between {Start Time - Tolerance Scope, End Time}.	10

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Fetch Related Events failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Trellix McAfee ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid Fields.

Error Sample Data

Fetch Related Events failed.

Status Code: 400.

Message: Invalid Fields.

Get Alarm Event Details

Returns details of the specified triggered alarm event(s).

READER NOTE

The parameter Event IDs is required to run this command.

You should already have your desired Event IDs on hand to run this command. If you don’t, you may use the Fetch Event command with defined filters to retrieve the desired Event IDs. Event IDs can be found in the raw data at the path $.return.[*].IPSIDAlertID

Input

Input Parameter	Required/Optional	Description	Example
Event IDs	Required	The ID(s) of the triggered alarm event(s) to retrieve details. Event IDs can be obtained using the Fetch Event command.	["***\|***"]

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Alarm Event Details failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Trellix McAfee ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Event Ids Not Found.

Error Sample Data

Get Alarm Event Details failed.

Status Code: 404.

Message: Event IDs Not Found.

Get Alarm Events

Retrieves a list of triggered alarms.

READER NOTE

The parameter Alarm IDs is required to run this command.

Run the Get Triggered Alarms command to obtain Alarm IDs. Alarm IDs can be found in the raw data at the path $.[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Alarm IDs	Required	The ID(s) of triggered alarm(s) to return. Triggered alarm IDs can be obtained using the Get Triggered Alarms command.	["*****"]

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Alarm Events failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Trellix McAfee ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Alarm IDs Not Found.

Error Sample Data

Get Alarm Events failed.

Status Code: 404.

Message: Alarm IDs Not Found.

Get Triggered Alarms

Returns a list of triggered alarms based on the specified criteria.

READER NOTE

If you select CUSTOM for the Triggered Time Range parameter and do not define the Start Time and End Time parameters, the current datetime will be used.

Input

Input Parameter	Required/Optional	Description	Example
Username	Optional	The assignee username to filter the returned alarms. The default user is the user used to configure the integration connection.	admin
Triggered Time Range	Required	The time range of the alarms’ triggered time to filter results. The dropdown list provides an option to specify a custom time range, defined using the Start Time and End Time parameters. You can also select a predefined triggered time range from the list (e.g. LAST_MINUTE and LAST_10_MINUTES).	CUSTOM
Start Time	Optional	The start time of the custom time range to retrieve alarms in UTC time if the Triggered Time Range parameter is set to CUSTOM. If this field is left empty, the current date and time will be used.	2022-12-01 00:00
End Time	Optional	The end time of the custom time range to retrieve alarms in UTC time if the Triggered Time Range parameter is set to CUSTOM. If this field is left empty, the current date and time will be used.	2022-12-06 00:00
Alarm Status	Optional	The alarm status to filter results. The valid options are All, Acknowledged and Unacknowledged.	All
Page Size	Optional	The maximum number (up to 5,000) of alarms to return on each result page. The default value is 5.	5
Page Number	Optional	The number of result pages to return. The default value is 1.	1

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Triggered Alarms failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Trellix McAfee ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: ERROR_InsufficientRights.

Error Sample Data

Get Triggered Alarms failed.

Status Code: 400.

Message: ERROR_InsufficientRights.

Get Watchlist Detail

Returns detailed information on the specified watchlist(s).

READER NOTE

The parameter Watchlist IDs is required to run this command.

Run the List Watchlists command to obtain Watchlist IDs. Watchlist IDs can be found in the raw data at the path $.[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Watchlist IDs	Required	The ID(s) of the watchlist(s) to retrieve information from. Watchlist IDs can be obtained using the List Watchlists command.	[*****]

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Watchlist Detail failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Trellix McAfee ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Watchlist IDs Not Found.

Error Sample Data

Get Watchlist Detail failed.

Status Code: 404.

Message: Watchlist IDs Not Found.

Get Watchlist Values

Returns the values of the specified watchlist(s). Note: Hidden watchlists (e.g. GTI) are not supported.

READER NOTE

The parameter Watchlist IDs is required to run this command.

Run the List Watchlists command to obtain Watchlist IDs. Watchlist IDs can be found in the raw data at the path $.[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Watchlist IDs	Required	The ID(s) of the watchlist(s) to return values for. Watchlist IDs can be obtained using the List Watchlists command.	[*****]

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Watchlist Values failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Trellix McAfee ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Watchlist IDs Not Found.

Error Sample Data

Get Watchlist Values failed.

Status Code: 404.

Message: Watchlist IDs Not Found.

Get IPS Correlated Raw Events

Returns correlated raw events for the specified alert event.

READER NOTE

Alert ID is an optional parameter to run this command.

You should already have your desired Alert IDs on hand to run this command. If you don’t, you may use the Fetch Event command with defined filters to retrieve the desired Alert IDs. Alert IDs can be found in the raw data at the path $return.[*].IPSIDAlertID.

Input

Input Parameter	Required/Optional	Description	Example
Alert ID	Optional	The ID of the alert to get the correlated raw events. Alert IDs can be obtained using the Fetch Event command.	***\|49***5

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get IPS Correlated Raw Events failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Trellix McAfee ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Alert ID Not Found.

Error Sample Data

Get IPS Correlated Raw Events failed.

Status Code: 404.

Message: Alert ID Not Found.

List Available Select Fields

Returns the list of available fields to query.

Input

N/A

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Available Select Fields failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Trellix McAfee ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: ERROR_InsufficientRights.

Error Sample Data

List Available Select Fields failed.

Status Code: 400.

Message: ERROR_InsufficientRights.

List Users

Returns the list of all users.

Input

N/A

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Users failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Trellix McAfee ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: ERROR_InsufficientRights.

Error Sample Data

List Users failed.

Status Code: 400.

Message: ERROR_InsufficientRights.

List Watchlists

Returns watchlists and their corresponding information.

Input

Input Parameter	Required/Optional	Description	Example
Showing hidden watchlist	Required	Enables hidden watchlists to be listed. If you select True, both hidden and non-hidden watchlists will be returned.	False
Showing dynamic watchlist	Required	Enables dynamic watchlists to be listed. If you select True, both dynamic and non-dynamic watchlists will be returned.	False
Showing writeOnly watchlist	Required	Enables write-only (modifiable) watchlists to be listed. If you select True, both write-only and non-write-only watchlists will be returned.	False
Showing indexedOnly watchlist	Required	Enables indexed watchlists to be listed. If you select True, both indexed and non-indexed watchlists will be returned.	False

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Watchlists failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Trellix McAfee ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: ERROR_InsufficientRights.

Error Sample Data

List Watchlists failed.

Status Code: 400.

Message: ERROR_InsufficientRights.

Query

Get results from a given index based on a query.

READER NOTE

The parameter Fields is an optional parameter to run this command.

Run the List Available Select Fields command to obtain Fields. Fields can be found in the raw data at the path $.[*].name.

Input

Input Parameter	Required/Optional	Description	Example
Time Range	Optional	The time range to filter results. There is an option to specify a custom time range (CUSTOM), defined using the Start Time and End Time parameters. You can also specify one of the following predefined time ranges: LAST MINUTE LAST 10 MINUTES LAST 30 MINUTES LAST HOUR CURRENT_DAY PREVIOUS_DAY LAST_24_HOURS LAST_2_DAYS LAST_3_DAYS CURRENT_WEEK PREVIOUS_WEEK CURRENT_MONTH PREVIOUS_MONTH CURRENT_QUARTER PREVIOUS_QUARTER CURRENT_YEAR PREVIOUS_YEAR	CUSTOM
Start Time	Optional	The start time of the custom time range to retrieve results in UTC time if the Time Range parameter is set to CUSTOM. If this field is left empty, the current date and time will be used.	2022-*****-01 00:00
End Time	Optional	The end time of the custom time range to retrieve results in UTC time if the Time Range parameter is set to CUSTOM. If this field is left empty, the current date and time will be used.	2022-*****-06 00:00
Filters	Optional	The array of filters in JSON format.	[{"type":"EsmFieldFilter","field":{"name":"EventID"},"operator":"NUMERIC_EQUALS","values":[{"type":"EsmBasicValue","value":"*****"}]}]
Fields	Optional	The key fields to return in the response data. A list of fields can be obtained using the List Available Select Fields command.	["Channel","EventID"]
Query Type	Optional	The event type to query. The default value is EVENT.	EVENT
Offset	Optional	The offset value to query results. The default value is 0.	0
Limit	Optional	The maximum number of rows to display in the query results.	5
Maximum Wait Time	Optional	The maximum number of tries to retrieve the status for the query. Each try has a 5-second interval. The default value is 10.	10

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Query failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Trellix McAfee ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Fields Not Found.

Error Sample Data

Query failed.

Status Code: 404.

Message: Fields Not Found.

Remove Values From Watchlist

Removes values from watchlists. Note: Hidden watchlists (e.g. GTI) are not supported.

READER NOTE

The parameter Watchlist IDs is required to run this command.

Run the List Watchlists command to obtain Watchlist IDs. Watchlist IDs can be found in the raw data at the path $.[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Watchlist IDs	Required	The ID(s) of the watchlist(s) to remove values from. Watchlist IDs can be obtained using the List Watchlists command.	[*****]
Values	Required	The string value(s) to remove from the specified watchlist(s).	["*...*"]

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Remove Values From Watchlist failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Trellix McAfee ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Watchlist IDs Not Found.

Error Sample Data

Remove Values From Watchlist failed.

Status Code: 404.

Message: Watchlist IDs Not Found.

Remove Watchlist

Removes watchlists from the system. Note: Hidden watchlists (e.g. GTI) are not supported.

READER NOTE

The parameter Watchlist IDs is required to run this command.

Run the List Watchlists command to obtain Watchlist IDs. Watchlist IDs can be found in the raw data at the path $.[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Watchlist IDs	Required	The ID(s) of the watchlist(s) to remove. Watchlist IDs can be obtained using the List Watchlists command.	[*****]

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Remove Watchlist failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Trellix McAfee ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Watchlist IDs Not Found.

Error Sample Data

Remove Watchlist failed.

Status Code: 404.

Message: Watchlist IDs Not Found.

Search ESM Alarms

Searches and returns alarms in McAfee ESM based on the specified criteria.

READER NOTE

If no input parameters are defined, the command will run successfully with no returned results.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Optional	The start time of the time range to search for alarms in UTC time.	2022-09-21 00:00
End Time	Optional	The end time of the time range to search for alarms in UTC time.	2022-11-23 00:00
Key Names	Optional	The keys to return in the response data. The key names are the keys in the returned raw data. Define this parameter to return only select fields.	["alarmName"]
Filters	Optional	The filters to search for alarms.	["Windows Event Failed to Logon"]

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Search ESM Alarms failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Trellix McAfee ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Key Names Not Found.

Error Sample Data

Search ESM Alarms failed.

Status Code: 404.

Message: Key Names Not Found.

Unacknowledge Triggered Alarm

Marks a triggered alarm as unacknowledged.

READER NOTE

The parameter Alarm IDs is required to run this command.

Run the Get Triggered Alarms command to obtain Alarm IDs. Alarm IDs can be found in the raw data at the path $.[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Alarm IDs	Optional	The ID(s) of triggered alarm(s) to mark as unacknowledged. Triggered alarm IDs can be obtained using the Get Triggered Alarms command.	[*****]

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Unacknowledge Triggered Alarm failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Trellix McAfee ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Alarm ID Not Found.

Error Sample Data

Unacknowledge Triggered Alarm failed.

Status Code: 404.

Message: Alarm ID Not Found.

Test Connection

Allows you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

Output Type

Description

Return Data Type

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

More details about an error can be viewed in the Error tab.

String

Error Handling

If the Return Data is failed, an Error tab will appear in the Test Result window.

The error tab contains the responses from the third-party API calls including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Test Connection failed. Failed to check the connector.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Trellix McAfee ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: ERROR_InsufficientRights.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 400.

Message: ERROR_InsufficientRights.