Requirements

• Harmony Email & Collaboration subscription.
  A Harmony subscription with Office 365 mail  or Gmail  SaaS applications configured.
• Lumu Defender API key
  For retrieving an API token, please refer to the Defender API document.
• Script host.
  Host with Python 3.6+ with network visibility over Lumu Defender and Harmony Email & Collaboration API endpoints.
• Script package.
  Contact the Lumu support team   to request the package we created to deploy the required files.

Set up the Harmony Email & Collaboration

Request your application ID and secret key

To use the Harmony Email & Collaboration API, you need an Application ID  and a Secret key . If you were not provided with them when you sign-up to the service, please contact  Check Point support . You must include in your request the portal name. This can be collected after logging in to your Check Point portal, hovering over a link, and checking the status bar of your browser.

Deploy the script

First, contact the Lumu support team to request the deployment package.

Scripts location

Unpack the deployment package provided by Lumu in your preferred path/folder. Keep in mind this location, as it will be required for further configurations. From now on, we will refer to this folder as <harmony_lumu_root> .

In the package, you will find the script required to run the integration. To use the script, you must locate yourself on the path selected for deployment ( <harmony_lumu_root> ). Specific directions are included in the next sections.

Install requirements

The file requirements.txt  contains the list of requirements for this integration. After deploying the package locally, run the following command from the deployment folder:

Script details

To use the script, you must locate yourself on the path selected for deployment ( <harmony_lumu_root> ). Use the following command to show all options available for the package:

Usage: harmony_lumu.py [options]

Usage Examples

Task: query and add indicators (URLs and hashes) related to Lumu incidents

Use the following command to fetch and push to Harmony Email & Collaboration URLs and hashes IOCs related to incidents found in your organization by Lumu in the last 30 days:

The integration creates new blocklist entries in the Anti-Phishing Block-list module. All the blocklists uploaded will have the comment Lumu IOC  for easier identification.

Task: query and add indicators (URLs, hashes) related to Lumu incidents

To push a specific type of IOCs (URLs or hashes) to your Harmony Email & Collaboration subscription, use the argument --ioc-types IOC_TYPE . IOC_TYPE can have the value url , or hash :

This example will push URLs IOCs in the blocklist items added to Harmony .

Task: query and add indicators related to Lumu incidents with contacts in the last X days

Use the following command to fetch and push to your Harmony Email & Collaboration subscription IOCs related to incidents found in your organization by Lumu with contacts in the last X days.

All previously pushed IOCs will be replaced, even if they correspond to incidents with contacts before X days.

By default, the script queries open and closed incidents of all adversary types (Phishing, Malware, DAG, Spam, others). If you need to collect specific types of incidents, you can use the argument --adversary-types ADVERSARY_TYPE . If you need to get two or more adversary types, you only need to append a new instance of the argument.

In this example, the adversary types queried are Phishing and Malware .

Task: run the Lumu integration in multi-threaded mode

To accelerate the integration process, the script supports a multi-threaded mode. This is useful if you have to operate with multiple IOCs at a time. To run the integration in this mode, append the flag --threaded to the command line.

Using this mode, the integration will use 20 threads. If you want to modify the number of threads to use, combine the flag --threaded with the argument --threads N . USE IT WITH CAUTION .

Task: clean all changes made by Lumu integration

If you need to delete all objects created by this integration in your Harmony Email & Collaboration subscription, use the --clean  flag with the authentication arguments.

The integration will try to delete all created objects. If there are blocklists that cannot be deleted, they will be reported in the integration output.

Task: save log output to file

By default, you will see the execution log on the screen console. Use the argument --logging file to store a record of all tasks run in the lumu.log file in the script root path.

This file is useful for scheduled tasks or processes running in the background. When you open this file, you will see the following. The information displayed aids in checking the execution progress.

Task: use a configuration file to run the integration

You can run the integration using a configuration file where you can save the required arguments in form of <argument_name>=<value> , one argument per line. In the integration root path, save a file named .config with your configuration. Following, you have a sample of the format of the file.

## Configuration file
# Lumu 
company_key=<lumu-company-key>

# Harmony 
application_id=<harmony-application-id>
secret_key=<secret-key>

# Misc
# Optional parameters
ioc-types=<ioc_type1>
# Logging
logging=file         

 if you need to add flags (arguments without value like -v or --clean, those need to be added on the command line)

Other tasks

According to your needs, you can combine the examples shown.

Expected results

All the uploaded IOCs in form of blocklists will appear in the Anti-Phishing Block-List module under the Harmony Email & Collaboration configuration.

After the IOCs are uploaded in your Harmony Email & Security subscription, further events will be detected and marked as Phishing attempts in the Check Point portal.

The uploaded IOCs will enhance the current visibility of your Harmony Email & Collaboration subscription. All detections must be addressed according to your policies.

Further considerations

To run the script on a timely basis, consider implementing a Scheduled task in Windows or a Cron task in Unix-based systems. If you are pushing hashes, the integration could take longer to run. We recommend that the scheduled job runs every 30 minutes.

Following, you have an example of how this Cron job should look using the recommended time.

It’s recommended to add the --logging file argument to any scheduled task. It will record all the output in the log file for further reference. If you have created a configuration file, your crontab entry doesn’t need any arguments. It should look as follows:

If you need to work with another scheduling time, you can use the crontab guru service.

To avoid race conditions, you can run only one instance. If you have one running, the second one will be canceled immediately.

Troubleshooting and known issues

To identify failures in the script execution, use the -v flag. The script execution log will show more detailed information.

Another instance is running

If you receive the following error.

There could be another instance running. To check this, open the pid.pid file in the integration’s folder. This file stores the process id if it’s running. Search for this process in your system. The following pictures show the process in Windows and Linux.

If the previous validation indicates that another instance is running, please, check its progress using the integration’s log lumu.log.