Trellix McAfee ESM
LAST UPDATED: OCT 22, 2024
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 |
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. | D**ec**it** |
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.
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.
Navigate to Configuration on the top header menu.
Click on the Integration icon on the left sidebar.
Type Trellix McAfee ESM in the search box to find the integration, then click it to select it.
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.
Connection Name: The desired name for the connection.
Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
Agent Name (Optional): Specifies 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.
Description (Optional): Add your desired description for the connection.
Configure User Permissions: Defines which users have access to the connection.
Active: Check the tick box to ensure the connection is available for use.
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.Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active. To set up a connection health check, check the Connection Health Check tickbox. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.
Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.
Test the connection.
Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
Click OK to close the alert window.
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, you can execute these commands independently for playbook troubleshooting.
Integration API Note
For more information about the Trellix McAfee ESM API, please 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 your account settings. As a result, the sample data provided in our commands is different from what you see. To set your preferred time format, follow these steps:
Navigate to Configuration > Application Settings. Select Date/Time Format.
Choose your desired date and time format.
After that, you will be able to view your preferred time format when configuring the DateTime input parameters for commands.
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
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
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
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
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
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:
| 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
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
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
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
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
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
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
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
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
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
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
rror 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
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:
| 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
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
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
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
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
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
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. |