Fortinet Document Library

Version:

Version:

Version:


Table of Contents

About the connector

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.

Version information

Connector Version: 2.0.0

FortiSOAR™ Version Tested on: 4.11.0-1161

McAfee ESM Versions Tested on: 10.3.0

Authored By: Fortinet

Certified: Yes

Release Notes for version 2.0.0

Following enhancements have been made to the McAfee ESM Connector in version 2.0.0:

  • Added the following operations and playbooks:
    • Get Cases 
    • Get Case Details
    • Add WatchList Values
    • Get WatchLists
    • Get WatchList Values
    • Delete WatchList
    • Delete WatchList Values
    • Acknowledge Alarm
    • Unacknowledge Alarm
    • Get Data Source List
    • Get Data Source Details
    • Get Device Tree
    • Add Note to event
  • Updated input parameters in the Create Case and Update Case  
    • Removed parameters Event Message and Event Last Time
    • Updated parameter name Case Name to Summary
    • Update parameter name Event ID to Event IDs

Installing the 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.

Prerequisites to configuring the connector

  • You must have the URL and credentials of McAfee ESM REST endpoint on which you will perform the automated operations. You must also have the credentials of a user, who has a right to configure custom applications on McAfee.
  • For forwarding event details from McAfee ESM to FortiSOAR™, you must configure the forwarding script to run with Python 3 as a standalone script. See the following Configuring the FortiSOAR™ forwarder section.
  • To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.
  • You must have port 22 open for the instance where the standalone script is installed and the port must be whitelisted to enable traffic from the McAfee ESM instance.

Configuring the FortiSOAR™ forwarder

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

Configuring the FortiSOAR™ forwarder

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:

  1. Install openssl-devel.
  2. Install Python 3.
  3. From the 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.
    Update the cyops_forwarder.py to point to your FortiSOAR™ instance.
    Edit the following lines in the config.py file (considering Basic Auth):
    cyops_host_uri
    cyops_username
    cyops_password
    The full URI of the instance is generated using the above information.
  4. To test the connectivity of the script, in FortiSOAR™ add a playbook with an Action trigger containing the same URL as in specified in the full_uri in step 2.
    Run the script as follows: <path to python> cyops_forwarder.py {“asasa”: “1”, “assa”: “2”}
    The script forwards the data to FortiSOAR™ in a JSON format with the arg name as the key and value as the value. The playbook should get triggered with the payload {“asasa”: “1”, “assa”: “2”}.
    Wrapper script connectivity test

Configuring the FortiSOAR™ forwarder script in McAfee ESM

  1. Log on to McAfee ESM and click Alarms in the navigation pane.
    McAfee ESM - Alarms option
  2. Click the Settings icon and in the System Properties dialog, select Alarms.
    McAfee ESM - System Properties dialog 
    This displays the list of alarms already configured in the system, along with an option to add a new alarm to the system.
    McAfee ESM - List of Alarms dialog
  3. Select an existing alarm or create a new one depending on your requirement.
    We are taking an example of editing an alarm, select an existing alarm and click Edit.
    McAfee ESM - Edit Alarms dialog
    The Alarm Settings dialog is displayed.
    McAfee ESM - Alarm Settings dialog
  4. Configure the parameters for the alarm in the Alarm Settings dialog as per your requirements.
    For example, On the Condition tab, define the condition based on which you want an alarm to be triggered. On the Device tab, configure the device to set up an alarm, by default, this is set to local. On the Actions tab, define an action to be taken once an alarm is triggered.
  5. To call the FortiSOAR™ forwarder script, on the Actions tab, select the Execute remote command option and click Configure.
    McAfee ESM - Alarm Settings dialog - Action Tab
  6. On the Execute Remote Command Configurations dialog, configure the following parameters:

    1. Host: The Host IP where your FortiSOAR™ forwarder script is located.
    2. Port: The port on which your host accepts the connection over ssh. The default value is 22.
    3. Username: The ssh username for the instance where your FortiSOAR™ forwarder script is installed.
    4. Password: The ssh password for the instance where your FortiSOAR™ forwarder script is installed.
    5. Command String: <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.
      We recommend passing single parameters in the form of a string containing objects. For example:
      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}'
      Note: Here the is_alert value determines whether an alert or an incident will be created in the CyOP™.
  7. 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.

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

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 IP IP Address of McAfee ESM.
Username Username to access McAfee ESM.
Password Password to access McAfee ESM.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True.

Actions supported by the connector

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, GT.
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
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 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

operation: Parse URL

Input parameters

None.

Output

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": ""
}

operation: Create Case

Input parameters

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.
Org 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.

Output

The output contains the following populated JSON schema:
{
     "return": {
         "value": ""
     }
}

operation: Get Cases

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "return": [
         {
             "summary": "",
             "id": {
                 "value": ""
             },
             "openTime": "",
             "statusId": {
                 "value": ""
             },
             "severity": ""
         }
     ]
}

operation: Get Case Details

Input parameters

Parameter Description
Case ID ID of the case whose details you want to retrieve from McAfee ESM.

Output

The output contains the following populated JSON schema:
{
     "return": {
         "closeTime": "",
         "history": [
             {
                 "content": "",
                 "timestamp": "",
                 "action": "",
                 "changes": [],
                 "username": ""
             },
             {
                 "content": "",
                 "timestamp": "",
                 "action": "",
                 "changes": [],
                 "username": ""
             }
         ],
         "deviceList": [
             {
                 "id": ""
             }
         ],
         "noteAdded": "",
         "id": {
             "value": ""
         },
         "assignedTo": "",
         "orgId": "",
         "severity": "",
         "notes": [
             {
                 "content": "",
                 "timestamp": "",
                 "action": "",
                 "changes": [
                     {
                         "changes": [],
                         "changeType": ""
                     }
                 ],
                 "username": ""
             }
         ],
         "openTime": "",
         "eventList": [
             {
                 "id": {
                     "value": ""
                 },
                 "message": "",
                 "lastTime": ""
             }
         ],
         "summary": "",
         "dataSourceList": [
             {
                 "id": ""
             }
         ],
         "statusId": {
             "value": ""
         }
     }
}

operation: Update Case

Input parameters

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.

Output

The JSON output contains the case id of the case updated in McAfee ESM.

The output contains the following populated JSON schema:
{
     "message": ""
}

operation: Add WatchList Values

Input parameters

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.

Output

The output contains the following populated JSON schema:
{

  "addedValuesList": [],
  "ignoredValuesList": []
}

operation: Get WatchLists

Input parameters

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
Show Hidden Select this option, i.e., set it to True if you want to include hidden watchlists in the list of watchlists retrieved from McAfee ESM.
By default, this is set to False.
Show Dynamic Select this option, i.e., set it to True if you want to include dynamic watchlists in the list of watchlists retrieved from McAfee ESM.
By default, this is set to False.
Show Write Only Select this option, i.e., set it to True if you want to include watchlists that can be modified in the list of watchlists retrieved from McAfee ESM.
By default, this is set to False.
Show Indexed Only Select this option, i.e., set it to True if you want to include watchlists that can be indexed in the list of watchlists retrieved from McAfee ESM.
By default, this is set to False.

Output

The output contains the following populated JSON schema:
{
     "return": [
         {
             "type": {
                 "id": "",
                 "name": ""
             },
             "dynamic": "",
             "customType": {
                 "id": "",
                 "name": ""
             },
             "valueCount": "",
             "scored": "",
             "id": "",
             "source": "",
             "name": "",
             "errorMsg": "",
             "hidden": "",
             "active": ""
         }
     ]
}

operation: Get WatchList Values

Input parameters

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

Output

The output contains the following populated JSON schema:
{
  "return": {
    "fileSize": "",
    "bytesRead": "",
    "data": ""
  }
}

operation: Delete WatchList

Input parameters

Parameter Description
Watchlist Name of the watchlist that you want to delete from McAfee ESM.

Output

The output contains the following populated JSON schema:
{
     "message": ""
}

operation: Delete WatchList Values

Input parameters

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.

Output

The output contains the following populated JSON schema:
{
     "removedValuesList": [],

     "ignoredValuesList": [],
}

operation: Get Alarms

Input parameters

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 Count 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.

Output

The output contains the following populated JSON schema:
{
     "return": [
         {
             "acknowledgedUsername": "",
             "id": {
                 "value": ""
             },
             "assignee": "",
             "conditionType": "",
             "alarmName": "",
             "summary": "",
             "acknowledgedDate": "",
             "triggeredDate": "",
             "severity": ""
         }
     ]
}

operation: Acknowledge Alarm

Input parameters

Parameter Description
Alarm ID ID of the triggered alarm id that you want to mark as "Acknowledged" on McAfee ESM.
For example,  [{"value": 0}]

Output

The output contains the following populated JSON schema:
{
     "message": ""
}

operation: Unacknowledge Alarm

Input parameters

Parameter Description
Alarm ID ID of the triggered alarm id that you want to mark as "Unacknowledged" on McAfee ESM.
For example, [{"value": 0}]

Output

The output contains the following populated JSON schema:
{
     "message": ""
}

operation: Get Data Source List

Input parameters

Parameter Description
Device ID ID of the receiver whose data source list you want to retrieve from McAfee ESM.  

Output

The output contains the following populated JSON schema:
{
     "return": []
}

operation: Get Data Source Details

Input parameters

Parameter Description
Data Source ID ID of the data source whose details you want to retrieve from McAfee ESM.

Output

The output contains the following populated JSON schema:
{
     "return": ""
}

operation: Get Device Tree

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "return": [
         {
             "name": "",
             "type": "",
             "id": {
                 "id": ""
             },
             "children": [],
             "addDeleteRight": ""
         }
     ]
}

operation: Add Note to event

Input parameters

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.

Output

The output contains the following populated JSON schema:
{
     "message": ""
}

Included playbooks

The Sample - McAfee ESM - 2.0.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.

  • Add Note to event
  • Alarm : Acknowledge Alarm
  • Alarm : Get Alarms
  • Alarm : Unacknowledge Alarm
  • Case :  Create Case
  • Case : Get Case Details
  • Case : Get Cases
  • Case :  Update Case
  • Get Data Source Details
  • Get Data Source List
  • Get Device Tree
  • WatchList : Add WatchList Values
  • WatchList : Delete WatchList 
  • WatchList : Delete WatchList Values
  • WatchList : Get WatchList Values
  • WatchList : Get WatchLists

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.

Troubleshooting

Connection refusal while requesting to run the wrapper

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.

Playbook fails after the ingestion is triggered

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.

About the connector

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.

Version information

Connector Version: 2.0.0

FortiSOAR™ Version Tested on: 4.11.0-1161

McAfee ESM Versions Tested on: 10.3.0

Authored By: Fortinet

Certified: Yes

Release Notes for version 2.0.0

Following enhancements have been made to the McAfee ESM Connector in version 2.0.0:

Installing the 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.

Prerequisites to configuring the connector

Configuring the FortiSOAR™ forwarder

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

Configuring the FortiSOAR™ forwarder

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:

  1. Install openssl-devel.
  2. Install Python 3.
  3. From the 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.
    Update the cyops_forwarder.py to point to your FortiSOAR™ instance.
    Edit the following lines in the config.py file (considering Basic Auth):
    cyops_host_uri
    cyops_username
    cyops_password
    The full URI of the instance is generated using the above information.
  4. To test the connectivity of the script, in FortiSOAR™ add a playbook with an Action trigger containing the same URL as in specified in the full_uri in step 2.
    Run the script as follows: <path to python> cyops_forwarder.py {“asasa”: “1”, “assa”: “2”}
    The script forwards the data to FortiSOAR™ in a JSON format with the arg name as the key and value as the value. The playbook should get triggered with the payload {“asasa”: “1”, “assa”: “2”}.
    Wrapper script connectivity test

Configuring the FortiSOAR™ forwarder script in McAfee ESM

  1. Log on to McAfee ESM and click Alarms in the navigation pane.
    McAfee ESM - Alarms option
  2. Click the Settings icon and in the System Properties dialog, select Alarms.
    McAfee ESM - System Properties dialog 
    This displays the list of alarms already configured in the system, along with an option to add a new alarm to the system.
    McAfee ESM - List of Alarms dialog
  3. Select an existing alarm or create a new one depending on your requirement.
    We are taking an example of editing an alarm, select an existing alarm and click Edit.
    McAfee ESM - Edit Alarms dialog
    The Alarm Settings dialog is displayed.
    McAfee ESM - Alarm Settings dialog
  4. Configure the parameters for the alarm in the Alarm Settings dialog as per your requirements.
    For example, On the Condition tab, define the condition based on which you want an alarm to be triggered. On the Device tab, configure the device to set up an alarm, by default, this is set to local. On the Actions tab, define an action to be taken once an alarm is triggered.
  5. To call the FortiSOAR™ forwarder script, on the Actions tab, select the Execute remote command option and click Configure.
    McAfee ESM - Alarm Settings dialog - Action Tab
  6. On the Execute Remote Command Configurations dialog, configure the following parameters:

    1. Host: The Host IP where your FortiSOAR™ forwarder script is located.
    2. Port: The port on which your host accepts the connection over ssh. The default value is 22.
    3. Username: The ssh username for the instance where your FortiSOAR™ forwarder script is installed.
    4. Password: The ssh password for the instance where your FortiSOAR™ forwarder script is installed.
    5. Command String: <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.
      We recommend passing single parameters in the form of a string containing objects. For example:
      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}'
      Note: Here the is_alert value determines whether an alert or an incident will be created in the CyOP™.
  7. 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.

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

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 IP IP Address of McAfee ESM.
Username Username to access McAfee ESM.
Password Password to access McAfee ESM.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True.

Actions supported by the connector

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, GT.
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
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 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

operation: Parse URL

Input parameters

None.

Output

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": ""
}

operation: Create Case

Input parameters

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.
Org 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.

Output

The output contains the following populated JSON schema:
{
     "return": {
         "value": ""
     }
}

operation: Get Cases

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "return": [
         {
             "summary": "",
             "id": {
                 "value": ""
             },
             "openTime": "",
             "statusId": {
                 "value": ""
             },
             "severity": ""
         }
     ]
}

operation: Get Case Details

Input parameters

Parameter Description
Case ID ID of the case whose details you want to retrieve from McAfee ESM.

Output

The output contains the following populated JSON schema:
{
     "return": {
         "closeTime": "",
         "history": [
             {
                 "content": "",
                 "timestamp": "",
                 "action": "",
                 "changes": [],
                 "username": ""
             },
             {
                 "content": "",
                 "timestamp": "",
                 "action": "",
                 "changes": [],
                 "username": ""
             }
         ],
         "deviceList": [
             {
                 "id": ""
             }
         ],
         "noteAdded": "",
         "id": {
             "value": ""
         },
         "assignedTo": "",
         "orgId": "",
         "severity": "",
         "notes": [
             {
                 "content": "",
                 "timestamp": "",
                 "action": "",
                 "changes": [
                     {
                         "changes": [],
                         "changeType": ""
                     }
                 ],
                 "username": ""
             }
         ],
         "openTime": "",
         "eventList": [
             {
                 "id": {
                     "value": ""
                 },
                 "message": "",
                 "lastTime": ""
             }
         ],
         "summary": "",
         "dataSourceList": [
             {
                 "id": ""
             }
         ],
         "statusId": {
             "value": ""
         }
     }
}

operation: Update Case

Input parameters

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.

Output

The JSON output contains the case id of the case updated in McAfee ESM.

The output contains the following populated JSON schema:
{
     "message": ""
}

operation: Add WatchList Values

Input parameters

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.

Output

The output contains the following populated JSON schema:
{

  "addedValuesList": [],
  "ignoredValuesList": []
}

operation: Get WatchLists

Input parameters

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
Show Hidden Select this option, i.e., set it to True if you want to include hidden watchlists in the list of watchlists retrieved from McAfee ESM.
By default, this is set to False.
Show Dynamic Select this option, i.e., set it to True if you want to include dynamic watchlists in the list of watchlists retrieved from McAfee ESM.
By default, this is set to False.
Show Write Only Select this option, i.e., set it to True if you want to include watchlists that can be modified in the list of watchlists retrieved from McAfee ESM.
By default, this is set to False.
Show Indexed Only Select this option, i.e., set it to True if you want to include watchlists that can be indexed in the list of watchlists retrieved from McAfee ESM.
By default, this is set to False.

Output

The output contains the following populated JSON schema:
{
     "return": [
         {
             "type": {
                 "id": "",
                 "name": ""
             },
             "dynamic": "",
             "customType": {
                 "id": "",
                 "name": ""
             },
             "valueCount": "",
             "scored": "",
             "id": "",
             "source": "",
             "name": "",
             "errorMsg": "",
             "hidden": "",
             "active": ""
         }
     ]
}

operation: Get WatchList Values

Input parameters

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

Output

The output contains the following populated JSON schema:
{
  "return": {
    "fileSize": "",
    "bytesRead": "",
    "data": ""
  }
}

operation: Delete WatchList

Input parameters

Parameter Description
Watchlist Name of the watchlist that you want to delete from McAfee ESM.

Output

The output contains the following populated JSON schema:
{
     "message": ""
}

operation: Delete WatchList Values

Input parameters

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.

Output

The output contains the following populated JSON schema:
{
     "removedValuesList": [],

     "ignoredValuesList": [],
}

operation: Get Alarms

Input parameters

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 Count 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.

Output

The output contains the following populated JSON schema:
{
     "return": [
         {
             "acknowledgedUsername": "",
             "id": {
                 "value": ""
             },
             "assignee": "",
             "conditionType": "",
             "alarmName": "",
             "summary": "",
             "acknowledgedDate": "",
             "triggeredDate": "",
             "severity": ""
         }
     ]
}

operation: Acknowledge Alarm

Input parameters

Parameter Description
Alarm ID ID of the triggered alarm id that you want to mark as "Acknowledged" on McAfee ESM.
For example,  [{"value": 0}]

Output

The output contains the following populated JSON schema:
{
     "message": ""
}

operation: Unacknowledge Alarm

Input parameters

Parameter Description
Alarm ID ID of the triggered alarm id that you want to mark as "Unacknowledged" on McAfee ESM.
For example, [{"value": 0}]

Output

The output contains the following populated JSON schema:
{
     "message": ""
}

operation: Get Data Source List

Input parameters

Parameter Description
Device ID ID of the receiver whose data source list you want to retrieve from McAfee ESM.  

Output

The output contains the following populated JSON schema:
{
     "return": []
}

operation: Get Data Source Details

Input parameters

Parameter Description
Data Source ID ID of the data source whose details you want to retrieve from McAfee ESM.

Output

The output contains the following populated JSON schema:
{
     "return": ""
}

operation: Get Device Tree

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "return": [
         {
             "name": "",
             "type": "",
             "id": {
                 "id": ""
             },
             "children": [],
             "addDeleteRight": ""
         }
     ]
}

operation: Add Note to event

Input parameters

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.

Output

The output contains the following populated JSON schema:
{
     "message": ""
}

Included playbooks

The Sample - McAfee ESM - 2.0.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.

Troubleshooting

Connection refusal while requesting to run the wrapper

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.

Playbook fails after the ingestion is triggered

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.