Before going through this article, check our Out-of-the-box App Integrations category . This is the recommended way to integrate the components of your cybersecurity stack with Lumu. If the product you are looking to integrate is there, it is advised to use that integration instead.

This article shows how to leverage the Lumu Defender API and the Sophos Central REST API to mitigate security risks.

Requirements

1. Sophos Endpoint Protection subscription.
   
1. A Sophos Intercept X Advanced or later is required.
   
2. Lumu Defender API key.
   
1. For retrieving an API token, please refer to the Defender API document.
   
3. Scripting host with Python v3.6+.
   
1. Host with Python 3.6+ and network visibility over Lumu Defender endpoints and Sophos Central API
   
4. Script package.
   
1. Contact the Lumu Support Team to request the package we created to deploy the required files.
   

Before you start

Command line considerations

If you are deploying the integration package in your Lumu Virtual Appliance, change the commands as follows:

• Change python for python3.
• Change pip for pip3.

Migrating from the previous version of the script

If you are working with the previous version of the script lumu-sophos.py , you need to clean up your Sophos Central console before proceeding. Run the following command to clean up your environment.

python lumu-sophos.py --clientID <sophos_client_id> --clientSecret <sophos_client_secret> --company-key <lumu-company-key> --sha_unlocked True --web_unlocked True  

Contacted hosts

Please, allow all the traffic to the following hosts. These are required for the operation of this integration:

• id.sophos.com
• api.central.sophos.com
• api-*.central.sophos.com
• defender.lumu.io

Set up the Sophos Central console

Create a Sophos Central credential

Using a global administrator user in your Sophos Central console, follow these steps:

1. Click on the Global Settings menu in the left navigation pane. Under the Global Settings window, click on the API Credential Management link.
   
   
2. Create a new credential using the Add Credential button. Fill in the required data. For the role, select Service Principal Management.
   
   
3. Copy from the API Credential Summary window the Client ID and the Client Secret. Click on the Show Client Secret link to show it. Copy and save it for further usage, this will be the only time it will be visible.

Check the tenant name to operate with (for partner and organization account types)

For Partner and Organization accounts, you need to identify the tenant you want to use for the integration. Check your Sophos Central console for the exact name of the tenant. Save it for later usage.

Prepare Python on your environment

Deploy the script

First, contact the Lumu Support Team to request the package we created to deploy the required files.

Script 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 <sophos_lumu_root>.

In the package, you will find the script required to run the integration. To use it, you must locate yourself on the path selected for deployment (<sophos_lumu_root>). In the following directions, you can find specific instructions to set up and use it.

Install requirements

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

[sudo] pip install -r ./requirements.txt 

Script details

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

python sophos_lumu.py --help 

Usage: sophos_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 your Sophos Central Web console URLs and hashes related to incidents found in your organization by Lumu in the last 30 days:

python sophos_lumu.py --client-id <sophos_client_id> --client-secret <sophos_client_secret> --company-key <lumu_company_key> [--tenant-name <sophos_tenant_name>]   

If you are working with a Sophos Central Partner or Organization account, you need to indicate the tenant you want to integrate. Use the --tenant-name flag followed by the selected tenant name.

After running the integration, you can find the uploaded IOCs in the Global Settings window. The URLs are stored under the Website Management section.

The hashes in SHA256 are stored under the Blocked Items section.

Task: query and add specific indicators related to Lumu incidents

To push a defined type of IOCs (URLs or hashes) to your Sophos Central Web console, use the argument --ioc-types IOC_TYPE . IOC_TYPE can have the value url  or hash:

python sophos_lumu.py --client-id <sophos_client_id> --client-secret <sophos_client_secret> --company-key <lumu_company_key> [--tenant-name <sophos_tenant_name>] --ioc-types hash 

This example will only create new hashes under the Blocked Items section.

Task: query and add indicators related to Lumu incidents of specific types

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.

python sophos_lumu.py --client-id <sophos_client_id> --client-secret <sophos_client_secret> --company-key <lumu_company_key> [--tenant-name <sophos_tenant_name>] --adversary-types Phishing --adversary-types Malware

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

Task: clean all changes made by Lumu integration

If you need to delete all Anti-Phishing block lists created by the integration, use the --clean  flag with the authentication arguments.

python sophos_lumu.py --client-id <sophos_client_id> --client-secret <sophos_client_secret> --company-key <lumu_company_key> [--tenant-name <sophos_tenant_name>]  --clean 

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.

python sophos_lumu.py --client-id <sophos_client_id> --client-secret <sophos_client_secret> --company-key <lumu_company_key> [--tenant-name <sophos_tenant_name>] --logging file 

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

## Lumu Sophos configuration file
# Lumu
company-key=COMPANY_KEY
# Sophos
client-id=CLIENT_ID
client-secret=CLIENT_SECRET    

The file .config_sample  in this repo can be tailored according to your needs. Remember to rename it to .config

 if you need to add flags (arguments without values 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.

Next steps

If you are working with URLs, configure your Sophos policies to block navigation to the tag Lumu . To do so, follow these steps in your Sophos Central  Web console.

1. Click on the Endpoint Protection link in the left navigation bar.
2. Under the CONFIGURE section in the Endpoint Protection navigation bar, click on Policies.
3. Select and modify your Web Control policies to block traffic to the Lumu  tag. Click on the policy, and go to the Settings tab.
4. Under the Settings window, enable the Control sites tagged in Website Management. Add a new tag, select the Lumu tag, and set the action to Block. Save the policy.
   

Remember to enable the SSL/TLS decryption of HTTPS websites feature under the Threat Protection Policy

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.

*/30 * * * * python <repo_root>/sophos_lumu.py --client-id <sophos_client_id> --client-secret <sophos_client_secret> --company-key <lumu_company_key> [--tenant-name <sophos_tenant_name>] 

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 arguments. It should look as follows:

*/30 * * * * python <repo_root>/sophos_lumu.py     

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, others will be terminated 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.

Error: Another instance is running. Quitting. 

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. Search for this process in your system. The following pictures show the process in Windows and Linux.