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 connector, which facilitates automated interactions, with a McAfee ESM server using FortiSOAR™ playbooks. Add the McAfee connector as a step in FortiSOAR™ playbooks and perform automated operations, such as creating or editing a case in McAfee based on an alarm.

Version information

Connector Version: 1.0.0

FortiSOAR™ Version Tested on: 4.9.0.0-708

McAfee Version Tested on: 10.1.0

Authored By: Fortinet

Certified: Yes

 

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:

For the detailed procedure to install a connector, click here.

yum install cyops-connector-mcafee

Prerequisites to configuring the connector

  • You must have the URL and credentials of the McAfee 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 the McAfee.  

  • For forwarding event details from the McAfee ESM to FortiSOAR™, you must configure the forwarding script to run with Python 3 as a standalone script. See the Configuring the FortiSOAR™ forwarder topic.

  • You must have port 22 open for the instance where stand alone script is installed, the port must be whitelisted to enable traffic from the McAfee instance.

FortiSOAR™ forwarder script

The FortiSOAR™ forwarder script is built to forward alarm events from McAfee into FortiSOAR™ for remediation, escalation, and case management. You can then track correlated events according to the information from McAfee 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_1.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.

We recommend 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_1_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 please ensure that python package requests is installed.If you are using an independent linux server then install the requests package by default using following command:sudo  yum install python-pipsudo pip install requests

Configuring the FortiSOAR™ forwarder<a name="Configuring-the-CyOps-forwarder"></a>

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-1_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 config.py (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”}.  

Configuring the FortiSOAR™ forwarder script in McAfee ESM

  1. Log on to McAfee ESM and click Alarms in the navigation pane.  

  2. Click the Settings icon and in the System Properties dialog, select Alarms.  

    This displays the list of alarms already configured in the system, along with an option to add a new alarm to the system.  

  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.  
    The Alarm Settings dialog is displayed.  

  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.  

  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 to instance where CyOPs forwarder script is installed.

    4. Password: The ssh password to instance where CyOPs 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™.

  1. 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_1.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, select the McAfee connector and click Configure to configure the following parameters:

Parameter Description
McAfee ESM IP/FQDN IP Address or FQDN McAfee ESM.
Username Username to access the McAfee.
Password Password to access the McAfee.
Verify SSL Verify SSL connection to the McAfee. <br />Defaults to True.

 

Actions supported by the connector

The following automated operations can be included in playbooks:

  • Parse URI: Parses the McAfee 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.

  • Create Case: Creates a case in McAfee using the input we get from a McAfee alert.

  • Update Case: Updates an existing case in McAfee using the input we get from a McAfee alert.

operation: Parse URI

Input parameters

None.

Output

A customized JSON output that is formatted for easy reference is the output for all the operations. 

The JSON output returns a Success message if all the parameters are in the correct JSON format and the details are parsed successfully. If the URI is not parsed sucessfully, then the JSON output returns an Error message that contains the reason for the failure.

Following image displays a sample output:

operation: Create Case

Input parameters

None.

Output

The JSON output contains the case id of the case created in McAfee.

operation: Update Case

None.

Output

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

Following image displays a sample output: 

Included playbooks

The Sample - McAfee  - 1.0.1 playbook collection comes bundled with the McAfee 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  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.

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 connector, which facilitates automated interactions, with a McAfee ESM server using FortiSOAR™ playbooks. Add the McAfee connector as a step in FortiSOAR™ playbooks and perform automated operations, such as creating or editing a case in McAfee based on an alarm.

Version information

Connector Version: 1.0.0

FortiSOAR™ Version Tested on: 4.9.0.0-708

McAfee Version Tested on: 10.1.0

Authored By: Fortinet

Certified: Yes

 

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:

For the detailed procedure to install a connector, click here.

yum install cyops-connector-mcafee

Prerequisites to configuring the connector

FortiSOAR™ forwarder script

The FortiSOAR™ forwarder script is built to forward alarm events from McAfee into FortiSOAR™ for remediation, escalation, and case management. You can then track correlated events according to the information from McAfee 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_1.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.

We recommend 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_1_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 please ensure that python package requests is installed.If you are using an independent linux server then install the requests package by default using following command:sudo  yum install python-pipsudo pip install requests

Configuring the FortiSOAR™ forwarder<a name="Configuring-the-CyOps-forwarder"></a>

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-1_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 config.py (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”}.  

Configuring the FortiSOAR™ forwarder script in McAfee ESM

  1. Log on to McAfee ESM and click Alarms in the navigation pane.  

  2. Click the Settings icon and in the System Properties dialog, select Alarms.  

    This displays the list of alarms already configured in the system, along with an option to add a new alarm to the system.  

  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.  
    The Alarm Settings dialog is displayed.  

  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.  

  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 to instance where CyOPs forwarder script is installed.

    4. Password: The ssh password to instance where CyOPs 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™.

  1. 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_1.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, select the McAfee connector and click Configure to configure the following parameters:

Parameter Description
McAfee ESM IP/FQDN IP Address or FQDN McAfee ESM.
Username Username to access the McAfee.
Password Password to access the McAfee.
Verify SSL Verify SSL connection to the McAfee. <br />Defaults to True.

 

Actions supported by the connector

The following automated operations can be included in playbooks:

operation: Parse URI

Input parameters

None.

Output

A customized JSON output that is formatted for easy reference is the output for all the operations. 

The JSON output returns a Success message if all the parameters are in the correct JSON format and the details are parsed successfully. If the URI is not parsed sucessfully, then the JSON output returns an Error message that contains the reason for the failure.

Following image displays a sample output:

operation: Create Case

Input parameters

None.

Output

The JSON output contains the case id of the case created in McAfee.

operation: Update Case

None.

Output

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

Following image displays a sample output: 

Included playbooks

The Sample - McAfee  - 1.0.1 playbook collection comes bundled with the McAfee 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  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.