This article shows how to leverage the Lumu Defender API and Check Point Harmony Email & Collaboration API to mitigate security risks.

Requirements

• A Harmony Email & Collaboration subscription with Office 365 Mail or Gmail SaaS applications configured
  • A Check Point Infinity admin user must be used to configure the integration
• Lumu Defender API key
  • To retrieve an API token, please refer to the Defender API document.
• Script host.
  • A scripting host is required to deploy the integration. This host must have Internet visibility over Lumu Defender API endpoints and Azure Cloud. According to the deployment model you select, you will need a host with:
    • Python 3.12
      or
    • A Docker-enabled host.

Before you start

If you are using the previous version of the integration, you must stop it and remove any old IOCs from your Harmony Email & Collaboration console.

The integration package includes a clean-up script you can use for cleaning up IOCs from the previous integration version. Use it as follows

Replace the values in red for the ones collected in the Create an account API key section of this document.

Contacted hosts

The integration script communicates with the following domains. Please ensure traffic is allowed before deploying the integration:

• Lumu services
  • defender.lumu.io (HTTP and WSS traffic)
• Harmony services
  Depending on the deployment region you need to allow HTTPS to one of these domains
  • cloudinfra-gw-us.portal.checkpoint.com
  • cloudinfra-gw.portal.checkpoint.com
  • cloudinfra-gw.ca.portal.checkpoint.com
  • cloudinfra-gw.ap.portal.checkpoint.com
  • cloudinfra-gw.uk.portal.checkpoint.com
  • cloudinfra-gw.me.portal.checkpoint.com
  • cloudinfra-gw.in.portal.checkpoint.com

If you are not sure about the Harmony domain, you can identify it when you generate the API key

Integration overview

The integration leverages the Harmony Anti-phishing exceptions to allow Harmony to prevent or detect and remediate emails with Lumu-related hashes, and URLs. Any mail matching these exceptions will be treated according to the protection mode defined in the policy rules.

Preliminary Setup - Harmony Email & Collaboration

Create an account API key

1. Open your Web browser and access the Check Point Infinity Portal. Log in into the portal if you are not already logged in.

2. On the top navigation bar, click on the Gear icon. Then, click on the API Keys button

3. On the API Keys window, click the New button at the top of the page. Then click on the New account API key option.

4. Fill the required information within the CREATE A NEW ACCOUNT API KEY modal as follows:

a. Under Service(1), search for and select the Email & Collaboration option. You can type in the field to narrow down the options shown.

b. Select an Expiration(2) date by clicking on the calendar button. Choose an expiration date based on your internal security policy guidelines.

c. Under Description(3), type a distinctive description to identify the API key

d. When done, click on the blue CREATE(4) button.

e. A new window will appear, containing the Client ID(5), Secret Key(6), and Authentication URL(7). Make sure you store this information safely. Once you do, click on the blue CLOSE(8)
button.

This will be the only time you will be able to record it. If you lose this info, you will need to do the entire process from the beginning.

da

Preliminary setup - Lumu portal

• Lumu Defender API key
• Company UUID

Collect the Lumu Defender API key

To collect the Lumu Defender API key, please refer to the Defender API document.

Collect your Lumu company UUID

To collect your Lumu company UUID, log in to your Lumu portal. Once you are in the main window, copy the string below your company name.

Deploy the integration

• Run it as a Python script executing the install.sh bash file
  • Creates a Python virtual run time and its dependencies for you
  • Installs the crontab line in the host
• Run it as a Docker container.

If you use the install script, use the uninstall.sh bash file to remove the integration from the host

Prepare Python on your environment

If Docker is your chosen deployment method, you may skip this step.

Set up the configuration files

• companies.yml: this file contains the information collected from the Lumu portal
• integrations.yml: this file contains the information collected from your Harmony Infinity portal

Inside the integration package, you will find sample files you can use to build your configuration files. These files are companies_template.yml and integration_template.yml.

Complete the companies file

The companies file is in charge of defining how the integration connects to Lumu and extracts the information of the incidents and related indicators of compromise.

All the parameters in red should be replaced with the real data necessary for your integration deployment. For example, the parameter “COMPANY-UUID” should end up as something similar to “aa11bb22bb33-123a-456b-789c-11aa22bb33cc”. Follow these indications for all similar parameters.

-
  lumu:
    uuid: "COMPANY_UUID"
    defender_key: "DEFENDER_API_KEY"
    hash_type: "md5" # sha256 | sha1 | md5
    ioc_types: # list of ioc types, option one, many or all
      - url
      - domain
      - hash
    adversary:  # list of adversary types, option one, many or all
      - C2C
      - Malware
      - Mining
      - Spam
      - Phishing
      - Anonymizer
    days: 3 # MIN 1, MAX 3

Within this file, COMPANY_UUID and DEFENDER_API_KEY fields are mandatory. Please use the values captured in the previous steps. The ioc_types values must match with the IOC types required by the integration, in this case, url, ip and domain.

Complete the integrations file

The integrations file contains the information required for the integration to connect and interact with your Harmony Email and Collaboration deployment:

-
  lumu:
    uuid: "COMPANY_UUID"
    adversaryTypes: [ "C2C", "Malware", "Mining", "Spam", "Phishing", "Anonymizer"]
    days: 3
  app:
    name: "UNIQUE-NAME" # Unique Account Name of the Cloud company subscription
    clean: false # false | true
    ioc:
      - url
      - domain
      - hash
    api:
      clientId: "HARMONY-CLIENT-ID"
      secretKey: "HARMONY-SECRET-KEY"
      authenticationURL: "HARMONY-AUTHENTICATION-URL"

You must fill in the configuration data carefully. If there are any mistakes or missing data, you’ll receive errors. Please refer to the Troubleshooting and known issues section at the end of this article for further reference.

Deploy Integration as script

Make sure the install.sh script has the execution permission before running it.

If you want to modify the default running interval set up by the installation script, you can modify the latest crob job entries based on your environment requirements.

If you want to restart or uninstall the integration run the ./restart all and ./uninstall all respectively.

Script details

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

Usage: run [-h] [--config CONFIG] [--ioc-manager-db-path IOC_MANAGER_DB_PATH] [-v] [-l {screen,file}] [--hours HOURS]

Usage Examples

Task: query IOCs related to Lumu incidents with default options

To query all the hashes related to Lumu incidents triggered in the days defined in your configuration files, run the following command.

Task: Clean records

To clean the existing records in Harmony Email & Collaboration, just set up the clean flag in the integrations.yml file to true.

Then, run the integration script as follows:

The records not manipulated by the integration will be preserved

Other tasks

According to your needs, you can combine the examples shown. If you need more details on the steps executed by the integration script, you can add the –logging {file, screen} and –verbose arguments. These arguments can be used for troubleshooting.

Deploy as a Docker container (Optional)

If you have a Docker environment, you can select this option to run the integration as a Docker process. To deploy and run your integration as a docker container, locate yourself at the <app_lumu_root> folder, and follow these instructions:

1. Build the container by running the following command.

Do not forget the dot "."

2. Run the container by using the following command.

With this mode, your integration will run every 5 minutes.

Troubleshooting

For troubleshooting purposes, you can run the following commands:

To log in to your container using an interactive shell:

To collect integration logs:

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. You can get here by clicking on Security Settings on the left hand menu and clicking on the Exceptions header. The list is under Anti-Phishing.

After the IOCs are uploaded to your Harmony Email & Collaboration subscription, further events will be detected and marked as Phishing attempts in the Check Point portal, under the Events header in the left hand menu.

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

The application logs will be redirected to the lumu.log file. The file errors.log stores only the errors to make them easier to find and aid the troubleshooting process.

Input Validation

If you receive errors like this:

It means you are using the wrong key parameters or values. Review your configuration files and run the integration again.

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 folder. This file stores the process ID if it’s running.