McAfee Enterprise Security Manager (ESM) is a security information and event management (SIEM) solution that delivers actionable intelligence and integrations to prioritize, investigate, and respond to threats.
This document provides information about the McAfee ESM connector, which facilitates automated interactions, with a McAfee ESM server using FortiSOAR™ playbooks. Add the McAfee ESM connector as a step in FortiSOAR™ playbooks and perform automated operations, such as creating or editing a case in McAfee based on an alarm, or retrieving details of a specific case from McAfee ESM.
Connector Version: 2.3.0
FortiSOAR™ Version Tested on: 5.0.0
McAfee ESM Versions Tested on: 9.x and 10.3.0
Authored By: Fortinet
Certified: Yes
Following enhancements have been made to the McAfee ESM Connector in version 2.3.0:
Note: The configuration parameters for the McAfee ESM connector in version 2.3.0 is different from the earlier versions, therefore, in this case, the connector configurations of the previous version will be unavailable and you are required to reconfigure this connector.
All connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and use the yum command to install connectors:
yum install cyops-connector-mcafee-esm
For the detailed procedure to install a connector, click here.
The FortiSOAR™ forwarder script is built to forward alarm events from McAfee ESM into FortiSOAR™ for remediation, escalation, and case management. You can then track correlated events according to the information from McAfee ESM and enrich the information with additional data, such as affected asset context and reports. The FortiSOAR™ forwarder script is bundled in the mcafee.tgz
connector bundle in the scripts
directory (/opt/cyops-integrations/integrations/connectors/mcafee-esm_2_0_0/scripts
).
You can configure the script to run as an external script on a separate machine and allow an ssh connection over port 22 having python installed. You cannot keep this script in the same instance where McAfee ESM is running since McAfee ESM does not allow an external script to run on the same instance as the ESM.
It is recommended that you configure the FortiSOAR™ forwarder script on a CyOP’s instance and open port 22 from the McAfee ESM instance. The following sections specify the process of configuring the FortiSOAR™ forwarder.
If using the FortiSOAR™ instance for running FortiSOAR™ forwarder, please copy the script folder:
cp -R /opt/cyops-integrations/integrations/connectors/mcafee-esm_2_0_0/scripts /home/scripts/
Then change the permissions of the new script folder to csadmin:
chmod -R 755 /home/csadmin
chown csadmin:csadmin scripts
Note: For the CyOPs ™ forwarder script to execute, ensure that python package requests
are installed. If you are using an independent Linux server then install the requests
package by default using the following command: sudo yum install python-pip
sudo pip install requests
For Basic Authentication: Log on to the FortiSOAR™ UI and create a user with appropriate permissions, based on the actions you want to perform in the FortiSOAR™ playbook with the forwarded event data, for example, create an alert or event. Store the username and password, which you will require in step 3 of the procedure.
For HMAC Authentication: Log on to the FortiSOAR™ UI and create an appliance with appropriate permissions, based on the actions you want to perform in the FortiSOAR™ playbook with the forwarded event data, for example, create an alert or event. Store the public and private keys, which you will require in step 3 of the procedure.
Perform the following steps on the host where you want to install the script:
opt/cyops-integration/connector/mcafee-esm_2_0_0/script
connector bundle, copy the cyops_forwarder.py
and config.py
scripts to the host machine. Copy both the scripts to the same folder.cyops_forwarder.py
to point to your FortiSOAR™ instance.config.py
file (considering Basic Auth):cyops_host_uri
cyops_username
cyops_password
full URI
of the instance is generated using the above information.full_uri
in step 2.<path to python> cyops_forwarder.py {“asasa”: “1”, “assa”: “2”}
{“asasa”: “1”, “assa”: “2”}
.System Properties
dialog, select Alarms.Alarm Settings
dialog as per your requirements.On the Execute Remote Command Configurations
dialog, configure the following parameters:
<Python Path> <Script Name> <Params>
, where<Python Path>
is the path where your python file is located.<Script Name>
is the name of your forwarder script.<Params>
are the parameters you want to pass to the script.python {{Script File Path in Server}} '{"event_id":"[$Event ID]"
"alarm_name":"[$Alarm Name]",
"condition_type":"[$Condition Type]",
"description":"[$Alarm Note]",
"escalated_severity":"[Escalated Severity]",
"alarm_severity":"[$Alarm Severity]",
"alarm_status":"[$Alarm Status]",
"alarm_trigger_date":"[$Trigger Date]"
"alarm_device_name":"[$Device Name]",
"alarm_source_ip":"[$Source IP]",
"alarm_assignee":"[$Alarm Assignee]",
"case_name":"[$Case Name]",
"alarm_escallation_date":"[$Escalation Date]",
"alarm_Escallation_enabled":"[$Escalation Enabled]",
"alarm_escallated_assignee":"[$Escalated Assignee]",
"event_device_type":"[$Device Type]",
"is_alert": true}'
is_alert
value determines whether an alert or an incident will be created in the CyOP™.Click OK and Finish.
The forwarder script is now configured to send data to FortiSOAR™.
The logs of the script are located in same folder and host as the forwarder_script
, which is /opt/cyops-integrations/integrations/connectors/mcafee-esm_2_0_0/scripts/
folder. Logs get saved as errorlog_YYYY-MM-DD.txt
. The logs save all the details about the script errors and successes.
For the procedure to configure a connector, click here.
In FortiSOAR™, on the Connectors page, click the McAfee ESM connector row, and in the Configure tab enter the required configuration details.
Parameter | Description |
---|---|
Server URL | URL of the McAfee ESM server on which you will perform the automated operations. |
Username | Username who has a right to configure custom applications on the McAfee ESM REST endpoint on which you will perform the automated operations. |
Password | Password of the username who has a right to configure custom applications on the McAfee ESM REST endpoint on which you will perform the automated operations. |
API Version | API Version that you want to use with the McAfee ESM connector. You can choose between 9.x or 10.x. |
Verify SSL | Specifies whether the SSL certificate for the server is to be verified or not. By default, this option is set as True . |
The following automated operations can be included in playbooks, and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:
Function | Description | Annotation and Category |
---|---|---|
Parse URL | Parses the McAfee ESM alarm details that are being passed to FortiSOAR™ and returns a Success message if all the parameters are in the correct JSON format and the details are parsed successfully. | parse_body Miscellaneous |
Create Case | Creates a case in McAfee ESM using the input we get from a McAfee ESM alert. | create_ticket Investigation |
Get Cases | Retrieves a list of cases that have their status as "Open" from McAfee ESM. | get_cases Investigation |
Get Case Details | Retrieves details of a specific case from McAfee ESM based on the case ID you have specified. | get_cases Investigation |
Update Case | Updates an existing case in McAfee ESM using the input we get from a McAfee ESM alert. | update_ticket Investigation |
Add WatchList Values | Add values to a watchlist that exist on McAfee ESM based on the watchlist ID you have specified. Note: This call is not supported for hidden watchlists, for example, GTI. |
add_watchlist_values Investigation |
Get WatchLists | Retrieves basic information on all watchlists or specific watchlists (based on input parameters you have specified) from McAfee ESM. | get_watchlists Investigation |
Get WatchList Values |
Retrieves watchlist values from McAfee ESM based on the watchlist name you have specified | get_watchlist_values Investigation |
Delete WatchList | Deletes a watchlist from McAfee ESM based on the watchlist ID you have specified. Note: This call is not supported for hidden watchlists, for example, GTI. |
delete_watchlist Investigation |
Delete WatchList Values | Deletes values from a watchlist that exist on McAfee ESM based on the watchlist ID you have specified. Note: This call is not supported for hidden watchlists, for example, GTI. |
delete_watchlist_values Investigation |
Get Alarms | Retrieves a list of all triggered alarms or specific triggered alarms (based on the username and other input parameters you have specified) from McAfee ESM. | list_alarms Investigation |
Get Alarm Detail | Retrieves granular information about a specific alarm from McAfee ESM based on the Alarm ID you have specified. | get_alarm_detail Investigation |
Acknowledge Alarm | Marks a triggered alarm as "Acknowledged" on McAfee ESM based on the triggered alarm IDs you have specified. | acknowledge_alarm Investigation |
Unacknowledge Alarm | Marks a triggered alarm as "Unacknowledged" on McAfee ESM based on the triggered alarm IDs you have specified. | unacknowledge_alarm Investigation |
Get Event Detail | Retrieves granular information about a specific event from McAfee ESM based on the event ID you have specified. | get_event_detail Investigation |
Get Data Source List | Retrieves a list of defined data sources from McAfee ESM based on the Device ID you have specified. | get_data_source_list Investigation |
Get Data Source Details | Retrieves details of a specific data source from McAfee ESM based on the data source ID you have specified. | get_data_source_details Investigation |
Get Device Tree | Retrieves the basic device tree structure, with only basic properties loaded, from McAfee ESM. Each entry in the returned list is a root node in the tree. | get_device_tree Investigation |
Add Note to event | Adds a note to a specific event on McAfee ESM based on the event ID you have specified. | add_note_to_event Investigation |
None.
The output contains the following populated JSON schema:
{
"alarm_trigger_date": "",
"alarm_severity": "",
"alarm_source_ip": "",
"alarm_escallated_assignee": "",
"event_message": "",
"alarm_name": "",
"condition_type": "",
"event_last_time": "",
"alarm_device_name": "",
"alarm_escallation_date": "",
"case_name": "",
"device_id": "",
"alarm_Escallation_enabled": "",
"alarm_severity_mode": "",
"alarm_status": "",
"alarm_assignee": "",
"event_id": "",
"escalated_severity": "",
"event_device_type": "",
"description": ""
}
Parameter | Description |
---|---|
Case Assignee | Owner of the case. The owner must be present in the McAfee ESM system. |
Summary | Name of the case to be created. |
Status | Status of the case to be created. |
Case Severity | Severity of the case to be created. |
Alarm Trigger Date | Date on which the alarm will be triggered. |
Event IDs | List of event IDs of the triggered alarm. |
Organization ID | ID of the organization who owns the case. The organization must have an ID present in the McAfee ESM system. |
Note: Only parameters that can be edited are listed here, you can retain the default values for the remaining parameters.
The output contains the following populated JSON schema:
{
"return": {
"value": ""
}
}
None.
The output contains the following populated JSON schema:
{
"return": [
{
"severity": "",
"statusId": {
"value": ""
},
"openTime": "",
"id": {
"value": ""
},
"summary": ""
}
]
}
Parameter | Description |
---|---|
Case ID | ID of the case whose details you want to retrieve from McAfee ESM. |
The output contains the following populated JSON schema:
{
"return": {
"assignedTo": "",
"history": [
{
"content": "",
"changes": [],
"username": "",
"timestamp": "",
"action": ""
},
{
"content": "",
"changes": [],
"username": "",
"timestamp": "",
"action": ""
}
],
"dataSourceList": [
{
"id": ""
}
],
"id": {
"value": ""
},
"orgId": "",
"severity": "",
"notes": [
{
"content": "",
"changes": [
{
"changeType": "",
"changes": []
}
],
"username": "",
"timestamp": "",
"action": ""
}
],
"openTime": "",
"deviceList": [
{
"id": ""
}
],
"closeTime": "",
"noteAdded": "",
"eventList": [
{
"message": "",
"lastTime": "",
"id": {
"value": ""
}
}
],
"statusId": {
"value": ""
},
"summary": ""
}
}
Parameter | Description |
---|---|
Case ID | ID of the case to be modified. |
Case Assignee | Owner of the case that you want to modify. The owner must be present in the McAfee ESM system. |
Status | Status of the case to be updated. |
Case Severity | Severity of the case to be updated. |
Summary | Name of the case to be updated. |
Notes | Additional notes that you might want to add while updating the case. |
Event IDs | List of event IDs of the alarm associated with the event. |
Note: Only parameters that can be edited are listed here, you can retain the default values for the remaining parameters.
The JSON output contains the case id of the case updated in McAfee ESM.
The output contains the following populated JSON schema:
{
"message": ""
}
Parameter | Description |
---|---|
Watchlist | Name of the watchlist to which you want to add values on McAfee ESM. |
Values | List of string values that you want to add to the specified watchlist. |
The output contains the following populated JSON schema:
{
"
ignored
": [],ValuesList
"addedValuesList
": []
}
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criteria is applied, and an unfiltered list is returned. Also, if you are using this operation with the 9.x version of the McAfee ESM API, then the operation will return all the Watchlists, i.e., the filters do not get applied for the 9.x version.
Parameter | Description |
---|---|
Version 10,x+ | Select this checkbox if you are using a 10.x and later version of the McAfee ESM API. Once you select this checkbox, then you can optionally specify the following parameters:
|
The output contains the following populated JSON schema:
{
"return": [
{
"dynamic": "",
"hidden": "",
"name": "",
"active": "",
"id": "",
"source": "",
"scored": "",
"errorMsg": "",
"type": {
"name": "",
"id": ""
},
"valueCount": "",
"customType": {
"name": "",
"id": ""
}
}
]
}
Parameter | Description |
---|---|
Watchlist | Name of the watchlist whose values you want to retrieve from McAfee ESM. |
Position | (Optional) Starting position of reading data from the specified watchlist |
Count | (Optional) Number of values to read from the McAfee ESM server |
The output contains the following populated JSON schema:
{
"return": {
"bytesRead": "",
"data": "",
"fileSize": ""
}
}
Parameter | Description |
---|---|
Watchlist | Name of the watchlist that you want to delete from McAfee ESM. |
The output contains the following populated JSON schema:
{
"message": ""
}
Parameter | Description |
---|---|
Watchlist | Name of the watchlist from which you want to delete values on McAfee ESM. |
Values | List of string values that you want to delete from the specified watchlist. |
The output contains the following populated JSON schema:
{
"ignoredValuesList": [],
"removedValuesList": []
}
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criteria is applied, and an unfiltered list is returned.
Parameter | Description |
---|---|
Assigned User | Username that was assigned to handle this triggered alarm whose list you want to retrieve from McAfee ESM. |
Time Range | Time range based on which you want to filter the list of alarms retrieved from McAfee ESM for this operation. You can choose from the available options: Custom, 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, or Previous Year. Note: If you select the option as Custom, you need to pass the Start Date and the End Date. |
Page Size | Number of alarms to return per page. By default, this is set as 500. |
Page Number | Set which page of alarm we want to return in the response. By default, this is set as 1. |
The output contains the following populated JSON schema:
{
"return": [
{
"acknowledgedUsername": "",
"assignee": "",
"conditionType": "",
"id": {
"value": ""
},
"acknowledgedDate": "",
"alarmName": "",
"triggeredDate": "",
"severity": "",
"summary": ""
}
]
}
Parameter | Description |
---|---|
Alarm ID | ID of the alarm whose details you want to retrieve from McAfee ESM. |
The output contains the following populated JSON schema:
{
"return": {
"percentAbove": "",
"timeFilter": "",
"healthMonStatus": "",
"queryId": "",
"caseName": "",
"conditionType": "",
"events": [
{
"eventCount": "",
"protocol": "",
"lastTime": "",
"eventSubType": "",
"destIp": "",
"severity": "",
"ruleMessage": "",
"eventId": "",
"sourceIp": ""
}
],
"summary": "",
"maximumConditionTriggerFrequency": "",
"triggeredDate": "",
"offsetMinutes": "",
"acknowledgedUsername": "",
"useWatchlist": "",
"iocId": "",
"events_detail": [
{
"srcZone": "",
"sigText": "",
"lastTime": "",
"note": "",
"object": "",
"vlan": "",
"destPort": "",
"srcPort": "",
"eventId": "",
"app": "",
"iocId": "",
"domain": "",
"remedyTicketTime": "",
"alertId": "",
"remedyCaseId": "",
"agg2Name": "",
"agg3Name": "",
"destIp": "",
"eventCount": "",
"ruleName": "",
"ipsId": "",
"protocol": "",
"asnGeoDestId": "",
"cases": [],
"customTypes": [
{
"formatedValue": "",
"definedFieldNumber": "",
"fieldName": "",
"fieldId": "",
"unformattedValue": ""
},
{
"formatedValue": "",
"definedFieldNumber": "",
"fieldName": "",
"fieldId": "",
"unformattedValue": ""
}
],
"flowId": "",
"destZone": "",
"command": "",
"remedyAnalyst": "",
"duration": "",
"iocName": "",
"archiveId": "",
"sigDesc": "",
"srcInterfaceId": "",
"agg1Name": "",
"destInterface": "",
"firstTime": "",
"severity": "",
"agg3Value": "",
"srcUser": "",
"destInterfaceId": "",
"srcNetworkDeviceId": "",
"flowSessionId": "",
"trusted": "",
"srcInterface": "",
"destGuid": "",
"reviewed": "",
"srcNetworkDevice": "",
"destNetworkDevice": "",
"asnGeoSrcId": "",
"sessionId": "",
"destUser": "",
"srcAsnGeo": "",
"normDesc": "",
"agg2Value": "",
"sigId": "",
"deviceTime": "",
"sequence": 0,
"normId": "",
"srcGuid": "",
"subtype": "",
"host": "",
"destNetworkDeviceId": "",
"destAsnGeo": "",
"normMessage": "",
"srcIp": "",
"srcMac": "",
"agg1Value": "",
"deviceName": "",
"destMac": ""
}
],
"severity": "",
"caseId": "",
"alretRateMin": "",
"id": {
"value": ""
},
"escalatedDate": "",
"description": "",
"matchField": "",
"assigneeId": "",
"iocName": "",
"filters": "",
"actions": "",
"matchValue": "",
"alertRateCount": "",
"alarmName": "",
"assignee": "",
"acknowledgedDate": "",
"percentBelow": ""
}
}
Parameter | Description |
---|---|
Alarm ID | ID of the triggered alarm id that you want to mark as "Acknowledged" on McAfee ESM. For example, [{"value": 0}] |
The output contains the following populated JSON schema:
{
"message": ""
}
Parameter | Description |
---|---|
Alarm ID | ID of the triggered alarm id that you want to mark as "Unacknowledged" on McAfee ESM. For example, [{"value": 0}] |
The output contains the following populated JSON schema:
{
"message": ""
}
Parameter | Description |
---|---|
Event ID | ID of the event whose details you want to retrieve from McAfee ESM. |
The output contains the following populated JSON schema:
{
"duration": "",
"agg2Name": "",
"flowSessionId": "",
"sigId": "",
"agg1Name": "",
"srcInterface": "",
"srcPort": "",
"destNetworkDevice": "",
"remedyCaseId": "",
"eventCount": "",
"agg3Name": "",
"destInterface": "",
"agg1Value": "",
"firstTime": "",
"destAsnGeo": "",
"srcGuid": "",
"destZone": "",
"destUser": "",
"destIp": "",
"domain": "",
"srcInterfaceId": "",
"ipsId": "",
"severity": "",
"cases": [],
"iocId": "",
"trusted": "",
"subtype": "",
"sessionId": "",
"srcNetworkDeviceId": "",
"remedyAnalyst": "",
"asnGeoSrcId": "",
"agg3Value": "",
"srcUser": "",
"agg2Value": "",
"customTypes": [
{
"fieldName": "",
"unformattedValue": "",
"fieldId": "",
"definedFieldNumber": "",
"formatedValue": ""
},
{
"fieldName": "",
"unformattedValue": "",
"fieldId": "",
"definedFieldNumber": "",
"formatedValue": ""
}
],
"flowId": "",
"srcAsnGeo": "",
"normId": "",
"app": "",
"destGuid": "",
"destNetworkDeviceId": "",
"destInterfaceId": "",
"deviceName": "",
"srcMac": "",
"destMac": "",
"sigDesc": "",
"note": "",
"destPort": "",
"srcIp": "",
"srcNetworkDevice": "",
"normMessage": "",
"remedyTicketTime": "",
"host": "",
"normDesc": "",
"object": "",
"srcZone": "",
"reviewed": "",
"vlan": "",
"asnGeoDestId": "",
"sigText": "",
"protocol": "",
"iocName": "",
"sequence": "",
"ruleName": "",
"alertId": "",
"archiveId": "0",
"deviceTime": "",
"command": "",
"lastTime": ""
}
Parameter | Description |
---|---|
Device ID | ID of the receiver whose data source list you want to retrieve from McAfee ESM. |
The output contains the following populated JSON schema:
{
"return": []
}
Parameter | Description |
---|---|
Data Source ID | ID of the data source whose details you want to retrieve from McAfee ESM. |
The output contains the following populated JSON schema:
{
"return": ""
}
None.
The output contains the following populated JSON schema:
{
"return": [
{
"children": [],
"addDeleteRight": "",
"name": "",
"type": "",
"id": {
"id": ""
}
}
]
}
Parameter | Description |
---|---|
Event ID | ID of the event to which you want to add a note on McAfee ESM. |
Note | Note that you want to add to the specified event on McAfee ESM. |
The output contains the following populated JSON schema:
{
"message": ""
}
The Sample - McAfee ESM - 2.3.0
playbook collection comes bundled with the McAfee ESM connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the McAfee ESM connector.
Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.
This generally occurs in the case of self-signed SSL certificates. If you are using self-signed certificates for testing or staging, keep in mind this problem will not occur in productio, and you might need to switch the certificates on or off.
Resolution:
Ensure that the SSL certificates are trusted or that SSL checking is turned off in the wrapper script. This is not advised for production instances.
There are many reasons for a playbook failure, for example, if a required field is null
in the target module record, or there are problems with the Playbook Appliance keys.
Resolution:
Investigate the reason for failure using the Running Playbooks tab in the Playbook Administration
page. Review the step in which the failure is being generated and the result of the step, which should contain the trace of the error. Once you have identified the error and if you cannot troubleshoot the error, contact CyberSponse support for further assistance.
McAfee Enterprise Security Manager (ESM) is a security information and event management (SIEM) solution that delivers actionable intelligence and integrations to prioritize, investigate, and respond to threats.
This document provides information about the McAfee ESM connector, which facilitates automated interactions, with a McAfee ESM server using FortiSOAR™ playbooks. Add the McAfee ESM connector as a step in FortiSOAR™ playbooks and perform automated operations, such as creating or editing a case in McAfee based on an alarm, or retrieving details of a specific case from McAfee ESM.
Connector Version: 2.3.0
FortiSOAR™ Version Tested on: 5.0.0
McAfee ESM Versions Tested on: 9.x and 10.3.0
Authored By: Fortinet
Certified: Yes
Following enhancements have been made to the McAfee ESM Connector in version 2.3.0:
Note: The configuration parameters for the McAfee ESM connector in version 2.3.0 is different from the earlier versions, therefore, in this case, the connector configurations of the previous version will be unavailable and you are required to reconfigure this connector.
All connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and use the yum command to install connectors:
yum install cyops-connector-mcafee-esm
For the detailed procedure to install a connector, click here.
The FortiSOAR™ forwarder script is built to forward alarm events from McAfee ESM into FortiSOAR™ for remediation, escalation, and case management. You can then track correlated events according to the information from McAfee ESM and enrich the information with additional data, such as affected asset context and reports. The FortiSOAR™ forwarder script is bundled in the mcafee.tgz
connector bundle in the scripts
directory (/opt/cyops-integrations/integrations/connectors/mcafee-esm_2_0_0/scripts
).
You can configure the script to run as an external script on a separate machine and allow an ssh connection over port 22 having python installed. You cannot keep this script in the same instance where McAfee ESM is running since McAfee ESM does not allow an external script to run on the same instance as the ESM.
It is recommended that you configure the FortiSOAR™ forwarder script on a CyOP’s instance and open port 22 from the McAfee ESM instance. The following sections specify the process of configuring the FortiSOAR™ forwarder.
If using the FortiSOAR™ instance for running FortiSOAR™ forwarder, please copy the script folder:
cp -R /opt/cyops-integrations/integrations/connectors/mcafee-esm_2_0_0/scripts /home/scripts/
Then change the permissions of the new script folder to csadmin:
chmod -R 755 /home/csadmin
chown csadmin:csadmin scripts
Note: For the CyOPs ™ forwarder script to execute, ensure that python package requests
are installed. If you are using an independent Linux server then install the requests
package by default using the following command: sudo yum install python-pip
sudo pip install requests
For Basic Authentication: Log on to the FortiSOAR™ UI and create a user with appropriate permissions, based on the actions you want to perform in the FortiSOAR™ playbook with the forwarded event data, for example, create an alert or event. Store the username and password, which you will require in step 3 of the procedure.
For HMAC Authentication: Log on to the FortiSOAR™ UI and create an appliance with appropriate permissions, based on the actions you want to perform in the FortiSOAR™ playbook with the forwarded event data, for example, create an alert or event. Store the public and private keys, which you will require in step 3 of the procedure.
Perform the following steps on the host where you want to install the script:
opt/cyops-integration/connector/mcafee-esm_2_0_0/script
connector bundle, copy the cyops_forwarder.py
and config.py
scripts to the host machine. Copy both the scripts to the same folder.cyops_forwarder.py
to point to your FortiSOAR™ instance.config.py
file (considering Basic Auth):cyops_host_uri
cyops_username
cyops_password
full URI
of the instance is generated using the above information.full_uri
in step 2.<path to python> cyops_forwarder.py {“asasa”: “1”, “assa”: “2”}
{“asasa”: “1”, “assa”: “2”}
.System Properties
dialog, select Alarms.Alarm Settings
dialog as per your requirements.On the Execute Remote Command Configurations
dialog, configure the following parameters:
<Python Path> <Script Name> <Params>
, where<Python Path>
is the path where your python file is located.<Script Name>
is the name of your forwarder script.<Params>
are the parameters you want to pass to the script.python {{Script File Path in Server}} '{"event_id":"[$Event ID]"
"alarm_name":"[$Alarm Name]",
"condition_type":"[$Condition Type]",
"description":"[$Alarm Note]",
"escalated_severity":"[Escalated Severity]",
"alarm_severity":"[$Alarm Severity]",
"alarm_status":"[$Alarm Status]",
"alarm_trigger_date":"[$Trigger Date]"
"alarm_device_name":"[$Device Name]",
"alarm_source_ip":"[$Source IP]",
"alarm_assignee":"[$Alarm Assignee]",
"case_name":"[$Case Name]",
"alarm_escallation_date":"[$Escalation Date]",
"alarm_Escallation_enabled":"[$Escalation Enabled]",
"alarm_escallated_assignee":"[$Escalated Assignee]",
"event_device_type":"[$Device Type]",
"is_alert": true}'
is_alert
value determines whether an alert or an incident will be created in the CyOP™.Click OK and Finish.
The forwarder script is now configured to send data to FortiSOAR™.
The logs of the script are located in same folder and host as the forwarder_script
, which is /opt/cyops-integrations/integrations/connectors/mcafee-esm_2_0_0/scripts/
folder. Logs get saved as errorlog_YYYY-MM-DD.txt
. The logs save all the details about the script errors and successes.
For the procedure to configure a connector, click here.
In FortiSOAR™, on the Connectors page, click the McAfee ESM connector row, and in the Configure tab enter the required configuration details.
Parameter | Description |
---|---|
Server URL | URL of the McAfee ESM server on which you will perform the automated operations. |
Username | Username who has a right to configure custom applications on the McAfee ESM REST endpoint on which you will perform the automated operations. |
Password | Password of the username who has a right to configure custom applications on the McAfee ESM REST endpoint on which you will perform the automated operations. |
API Version | API Version that you want to use with the McAfee ESM connector. You can choose between 9.x or 10.x. |
Verify SSL | Specifies whether the SSL certificate for the server is to be verified or not. By default, this option is set as True . |
The following automated operations can be included in playbooks, and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:
Function | Description | Annotation and Category |
---|---|---|
Parse URL | Parses the McAfee ESM alarm details that are being passed to FortiSOAR™ and returns a Success message if all the parameters are in the correct JSON format and the details are parsed successfully. | parse_body Miscellaneous |
Create Case | Creates a case in McAfee ESM using the input we get from a McAfee ESM alert. | create_ticket Investigation |
Get Cases | Retrieves a list of cases that have their status as "Open" from McAfee ESM. | get_cases Investigation |
Get Case Details | Retrieves details of a specific case from McAfee ESM based on the case ID you have specified. | get_cases Investigation |
Update Case | Updates an existing case in McAfee ESM using the input we get from a McAfee ESM alert. | update_ticket Investigation |
Add WatchList Values | Add values to a watchlist that exist on McAfee ESM based on the watchlist ID you have specified. Note: This call is not supported for hidden watchlists, for example, GTI. |
add_watchlist_values Investigation |
Get WatchLists | Retrieves basic information on all watchlists or specific watchlists (based on input parameters you have specified) from McAfee ESM. | get_watchlists Investigation |
Get WatchList Values |
Retrieves watchlist values from McAfee ESM based on the watchlist name you have specified | get_watchlist_values Investigation |
Delete WatchList | Deletes a watchlist from McAfee ESM based on the watchlist ID you have specified. Note: This call is not supported for hidden watchlists, for example, GTI. |
delete_watchlist Investigation |
Delete WatchList Values | Deletes values from a watchlist that exist on McAfee ESM based on the watchlist ID you have specified. Note: This call is not supported for hidden watchlists, for example, GTI. |
delete_watchlist_values Investigation |
Get Alarms | Retrieves a list of all triggered alarms or specific triggered alarms (based on the username and other input parameters you have specified) from McAfee ESM. | list_alarms Investigation |
Get Alarm Detail | Retrieves granular information about a specific alarm from McAfee ESM based on the Alarm ID you have specified. | get_alarm_detail Investigation |
Acknowledge Alarm | Marks a triggered alarm as "Acknowledged" on McAfee ESM based on the triggered alarm IDs you have specified. | acknowledge_alarm Investigation |
Unacknowledge Alarm | Marks a triggered alarm as "Unacknowledged" on McAfee ESM based on the triggered alarm IDs you have specified. | unacknowledge_alarm Investigation |
Get Event Detail | Retrieves granular information about a specific event from McAfee ESM based on the event ID you have specified. | get_event_detail Investigation |
Get Data Source List | Retrieves a list of defined data sources from McAfee ESM based on the Device ID you have specified. | get_data_source_list Investigation |
Get Data Source Details | Retrieves details of a specific data source from McAfee ESM based on the data source ID you have specified. | get_data_source_details Investigation |
Get Device Tree | Retrieves the basic device tree structure, with only basic properties loaded, from McAfee ESM. Each entry in the returned list is a root node in the tree. | get_device_tree Investigation |
Add Note to event | Adds a note to a specific event on McAfee ESM based on the event ID you have specified. | add_note_to_event Investigation |
None.
The output contains the following populated JSON schema:
{
"alarm_trigger_date": "",
"alarm_severity": "",
"alarm_source_ip": "",
"alarm_escallated_assignee": "",
"event_message": "",
"alarm_name": "",
"condition_type": "",
"event_last_time": "",
"alarm_device_name": "",
"alarm_escallation_date": "",
"case_name": "",
"device_id": "",
"alarm_Escallation_enabled": "",
"alarm_severity_mode": "",
"alarm_status": "",
"alarm_assignee": "",
"event_id": "",
"escalated_severity": "",
"event_device_type": "",
"description": ""
}
Parameter | Description |
---|---|
Case Assignee | Owner of the case. The owner must be present in the McAfee ESM system. |
Summary | Name of the case to be created. |
Status | Status of the case to be created. |
Case Severity | Severity of the case to be created. |
Alarm Trigger Date | Date on which the alarm will be triggered. |
Event IDs | List of event IDs of the triggered alarm. |
Organization ID | ID of the organization who owns the case. The organization must have an ID present in the McAfee ESM system. |
Note: Only parameters that can be edited are listed here, you can retain the default values for the remaining parameters.
The output contains the following populated JSON schema:
{
"return": {
"value": ""
}
}
None.
The output contains the following populated JSON schema:
{
"return": [
{
"severity": "",
"statusId": {
"value": ""
},
"openTime": "",
"id": {
"value": ""
},
"summary": ""
}
]
}
Parameter | Description |
---|---|
Case ID | ID of the case whose details you want to retrieve from McAfee ESM. |
The output contains the following populated JSON schema:
{
"return": {
"assignedTo": "",
"history": [
{
"content": "",
"changes": [],
"username": "",
"timestamp": "",
"action": ""
},
{
"content": "",
"changes": [],
"username": "",
"timestamp": "",
"action": ""
}
],
"dataSourceList": [
{
"id": ""
}
],
"id": {
"value": ""
},
"orgId": "",
"severity": "",
"notes": [
{
"content": "",
"changes": [
{
"changeType": "",
"changes": []
}
],
"username": "",
"timestamp": "",
"action": ""
}
],
"openTime": "",
"deviceList": [
{
"id": ""
}
],
"closeTime": "",
"noteAdded": "",
"eventList": [
{
"message": "",
"lastTime": "",
"id": {
"value": ""
}
}
],
"statusId": {
"value": ""
},
"summary": ""
}
}
Parameter | Description |
---|---|
Case ID | ID of the case to be modified. |
Case Assignee | Owner of the case that you want to modify. The owner must be present in the McAfee ESM system. |
Status | Status of the case to be updated. |
Case Severity | Severity of the case to be updated. |
Summary | Name of the case to be updated. |
Notes | Additional notes that you might want to add while updating the case. |
Event IDs | List of event IDs of the alarm associated with the event. |
Note: Only parameters that can be edited are listed here, you can retain the default values for the remaining parameters.
The JSON output contains the case id of the case updated in McAfee ESM.
The output contains the following populated JSON schema:
{
"message": ""
}
Parameter | Description |
---|---|
Watchlist | Name of the watchlist to which you want to add values on McAfee ESM. |
Values | List of string values that you want to add to the specified watchlist. |
The output contains the following populated JSON schema:
{
"
ignored
": [],ValuesList
"addedValuesList
": []
}
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criteria is applied, and an unfiltered list is returned. Also, if you are using this operation with the 9.x version of the McAfee ESM API, then the operation will return all the Watchlists, i.e., the filters do not get applied for the 9.x version.
Parameter | Description |
---|---|
Version 10,x+ | Select this checkbox if you are using a 10.x and later version of the McAfee ESM API. Once you select this checkbox, then you can optionally specify the following parameters:
|
The output contains the following populated JSON schema:
{
"return": [
{
"dynamic": "",
"hidden": "",
"name": "",
"active": "",
"id": "",
"source": "",
"scored": "",
"errorMsg": "",
"type": {
"name": "",
"id": ""
},
"valueCount": "",
"customType": {
"name": "",
"id": ""
}
}
]
}
Parameter | Description |
---|---|
Watchlist | Name of the watchlist whose values you want to retrieve from McAfee ESM. |
Position | (Optional) Starting position of reading data from the specified watchlist |
Count | (Optional) Number of values to read from the McAfee ESM server |
The output contains the following populated JSON schema:
{
"return": {
"bytesRead": "",
"data": "",
"fileSize": ""
}
}
Parameter | Description |
---|---|
Watchlist | Name of the watchlist that you want to delete from McAfee ESM. |
The output contains the following populated JSON schema:
{
"message": ""
}
Parameter | Description |
---|---|
Watchlist | Name of the watchlist from which you want to delete values on McAfee ESM. |
Values | List of string values that you want to delete from the specified watchlist. |
The output contains the following populated JSON schema:
{
"ignoredValuesList": [],
"removedValuesList": []
}
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criteria is applied, and an unfiltered list is returned.
Parameter | Description |
---|---|
Assigned User | Username that was assigned to handle this triggered alarm whose list you want to retrieve from McAfee ESM. |
Time Range | Time range based on which you want to filter the list of alarms retrieved from McAfee ESM for this operation. You can choose from the available options: Custom, 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, or Previous Year. Note: If you select the option as Custom, you need to pass the Start Date and the End Date. |
Page Size | Number of alarms to return per page. By default, this is set as 500. |
Page Number | Set which page of alarm we want to return in the response. By default, this is set as 1. |
The output contains the following populated JSON schema:
{
"return": [
{
"acknowledgedUsername": "",
"assignee": "",
"conditionType": "",
"id": {
"value": ""
},
"acknowledgedDate": "",
"alarmName": "",
"triggeredDate": "",
"severity": "",
"summary": ""
}
]
}
Parameter | Description |
---|---|
Alarm ID | ID of the alarm whose details you want to retrieve from McAfee ESM. |
The output contains the following populated JSON schema:
{
"return": {
"percentAbove": "",
"timeFilter": "",
"healthMonStatus": "",
"queryId": "",
"caseName": "",
"conditionType": "",
"events": [
{
"eventCount": "",
"protocol": "",
"lastTime": "",
"eventSubType": "",
"destIp": "",
"severity": "",
"ruleMessage": "",
"eventId": "",
"sourceIp": ""
}
],
"summary": "",
"maximumConditionTriggerFrequency": "",
"triggeredDate": "",
"offsetMinutes": "",
"acknowledgedUsername": "",
"useWatchlist": "",
"iocId": "",
"events_detail": [
{
"srcZone": "",
"sigText": "",
"lastTime": "",
"note": "",
"object": "",
"vlan": "",
"destPort": "",
"srcPort": "",
"eventId": "",
"app": "",
"iocId": "",
"domain": "",
"remedyTicketTime": "",
"alertId": "",
"remedyCaseId": "",
"agg2Name": "",
"agg3Name": "",
"destIp": "",
"eventCount": "",
"ruleName": "",
"ipsId": "",
"protocol": "",
"asnGeoDestId": "",
"cases": [],
"customTypes": [
{
"formatedValue": "",
"definedFieldNumber": "",
"fieldName": "",
"fieldId": "",
"unformattedValue": ""
},
{
"formatedValue": "",
"definedFieldNumber": "",
"fieldName": "",
"fieldId": "",
"unformattedValue": ""
}
],
"flowId": "",
"destZone": "",
"command": "",
"remedyAnalyst": "",
"duration": "",
"iocName": "",
"archiveId": "",
"sigDesc": "",
"srcInterfaceId": "",
"agg1Name": "",
"destInterface": "",
"firstTime": "",
"severity": "",
"agg3Value": "",
"srcUser": "",
"destInterfaceId": "",
"srcNetworkDeviceId": "",
"flowSessionId": "",
"trusted": "",
"srcInterface": "",
"destGuid": "",
"reviewed": "",
"srcNetworkDevice": "",
"destNetworkDevice": "",
"asnGeoSrcId": "",
"sessionId": "",
"destUser": "",
"srcAsnGeo": "",
"normDesc": "",
"agg2Value": "",
"sigId": "",
"deviceTime": "",
"sequence": 0,
"normId": "",
"srcGuid": "",
"subtype": "",
"host": "",
"destNetworkDeviceId": "",
"destAsnGeo": "",
"normMessage": "",
"srcIp": "",
"srcMac": "",
"agg1Value": "",
"deviceName": "",
"destMac": ""
}
],
"severity": "",
"caseId": "",
"alretRateMin": "",
"id": {
"value": ""
},
"escalatedDate": "",
"description": "",
"matchField": "",
"assigneeId": "",
"iocName": "",
"filters": "",
"actions": "",
"matchValue": "",
"alertRateCount": "",
"alarmName": "",
"assignee": "",
"acknowledgedDate": "",
"percentBelow": ""
}
}
Parameter | Description |
---|---|
Alarm ID | ID of the triggered alarm id that you want to mark as "Acknowledged" on McAfee ESM. For example, [{"value": 0}] |
The output contains the following populated JSON schema:
{
"message": ""
}
Parameter | Description |
---|---|
Alarm ID | ID of the triggered alarm id that you want to mark as "Unacknowledged" on McAfee ESM. For example, [{"value": 0}] |
The output contains the following populated JSON schema:
{
"message": ""
}
Parameter | Description |
---|---|
Event ID | ID of the event whose details you want to retrieve from McAfee ESM. |
The output contains the following populated JSON schema:
{
"duration": "",
"agg2Name": "",
"flowSessionId": "",
"sigId": "",
"agg1Name": "",
"srcInterface": "",
"srcPort": "",
"destNetworkDevice": "",
"remedyCaseId": "",
"eventCount": "",
"agg3Name": "",
"destInterface": "",
"agg1Value": "",
"firstTime": "",
"destAsnGeo": "",
"srcGuid": "",
"destZone": "",
"destUser": "",
"destIp": "",
"domain": "",
"srcInterfaceId": "",
"ipsId": "",
"severity": "",
"cases": [],
"iocId": "",
"trusted": "",
"subtype": "",
"sessionId": "",
"srcNetworkDeviceId": "",
"remedyAnalyst": "",
"asnGeoSrcId": "",
"agg3Value": "",
"srcUser": "",
"agg2Value": "",
"customTypes": [
{
"fieldName": "",
"unformattedValue": "",
"fieldId": "",
"definedFieldNumber": "",
"formatedValue": ""
},
{
"fieldName": "",
"unformattedValue": "",
"fieldId": "",
"definedFieldNumber": "",
"formatedValue": ""
}
],
"flowId": "",
"srcAsnGeo": "",
"normId": "",
"app": "",
"destGuid": "",
"destNetworkDeviceId": "",
"destInterfaceId": "",
"deviceName": "",
"srcMac": "",
"destMac": "",
"sigDesc": "",
"note": "",
"destPort": "",
"srcIp": "",
"srcNetworkDevice": "",
"normMessage": "",
"remedyTicketTime": "",
"host": "",
"normDesc": "",
"object": "",
"srcZone": "",
"reviewed": "",
"vlan": "",
"asnGeoDestId": "",
"sigText": "",
"protocol": "",
"iocName": "",
"sequence": "",
"ruleName": "",
"alertId": "",
"archiveId": "0",
"deviceTime": "",
"command": "",
"lastTime": ""
}
Parameter | Description |
---|---|
Device ID | ID of the receiver whose data source list you want to retrieve from McAfee ESM. |
The output contains the following populated JSON schema:
{
"return": []
}
Parameter | Description |
---|---|
Data Source ID | ID of the data source whose details you want to retrieve from McAfee ESM. |
The output contains the following populated JSON schema:
{
"return": ""
}
None.
The output contains the following populated JSON schema:
{
"return": [
{
"children": [],
"addDeleteRight": "",
"name": "",
"type": "",
"id": {
"id": ""
}
}
]
}
Parameter | Description |
---|---|
Event ID | ID of the event to which you want to add a note on McAfee ESM. |
Note | Note that you want to add to the specified event on McAfee ESM. |
The output contains the following populated JSON schema:
{
"message": ""
}
The Sample - McAfee ESM - 2.3.0
playbook collection comes bundled with the McAfee ESM connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the McAfee ESM connector.
Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.
This generally occurs in the case of self-signed SSL certificates. If you are using self-signed certificates for testing or staging, keep in mind this problem will not occur in productio, and you might need to switch the certificates on or off.
Resolution:
Ensure that the SSL certificates are trusted or that SSL checking is turned off in the wrapper script. This is not advised for production instances.
There are many reasons for a playbook failure, for example, if a required field is null
in the target module record, or there are problems with the Playbook Appliance keys.
Resolution:
Investigate the reason for failure using the Running Playbooks tab in the Playbook Administration
page. Review the step in which the failure is being generated and the result of the step, which should contain the trace of the error. Once you have identified the error and if you cannot troubleshoot the error, contact CyberSponse support for further assistance.