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

Requirements

• Sophos XG Firewall
  
• A Sophos XG Firewall with SFOS 19.0.0 GA-Build317 with the Xstream Protection bundle (Network Protection and Web Protection) is required.
  
• Lumu Defender API key
  
• To retrieve an API token, please refer to the Defender API document.
  
• Script host
  
• Host with Python 3.10+ with network visibility over Lumu Defender endpoints and Sophos XG Firewall.
  
• Script package
  
• Contact the Lumu support team to request the package we created to deploy the required files.
  

Set up the Sophos XG API

Add an administrator role for Lumu integration

1. Using the Sophos XG Web console, go to the Profiles menu under the SYSTEM section. 

2. Click on the Device access tab, and then on the Add button. 

3. Give a name to the profile and enable the Read-write permissions for the Objects , Rules, and policies , and Web & content filter configurations .

Add a new administrator user

1. Go to the Authentication menu under the CONFIGURE section.

2. On the Users tab, click the Add button. Fill in the required information. 

3. In the User type select Administrator , and in the Profile field list, select the profile created in the previous step.

Enable the API

1. To enable the API in your Sophos XG Firewall, go to the Backup & Firmware menu under the SYSTEM section. 

2. Go to the API tab, then, under the API configuration section, toggle the API configuration button, and fill in the Allowed IP addresses . 

3. Finally, click the Apply button to save your changes.

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 <sophosxg_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 ( <sophosxg_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 ( <sophosxg_lumu_root> ). Use the following command to show all options available for the package:

Usage: sophosxg_lumu.py [options]

If you are updating from a previous integration version, it’s encouraged to remove previous objects within your Sophos XG Firewall. Use the flag --old-clean to run a first clean. Check in your Firewall objects that no Lumu-related objects remain before running the integration again.

Usage Examples

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

Use the following command to fetch and push to Sophos XG firewall IPs and URLs IOCs related to incidents found in your organization by Lumu in the last 30 days:

The integration creates a new IP host group Lumu IPs and related IP hosts with the prefix Lumu_ . For web filtering, it creates new Web filtering categories named with the Lumu Web prefix. Each Web category contains the URLs. Also, the integration adds a new rule at the beginning of the Web policy in block mode.

Multiple Web categories can be created to prevent some Sophos API limitations.

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

This example will push domains under the FQDN host group in Sophos named Lumu Hosts .

You cannot combine domain and URL IOC types. If you try so, the integration chooses to process URLs instead of domains. URLs allow more granularity to block potential adversarial contacts.

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 Sophos XG Firewall IOCs related to incidents found in your organization by Lumu with contacts in the last X days.

All previously pushed IOC to your Sophos XG Firewall will be replaced, even if they correspond to incidents with contacts before X days.

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, 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: clean all changes made by Lumu integration

If you need to delete all objects created by this integration in your Sophos XG Firewall, use the --clean flag with the authentication arguments.

The integration will try to delete all created objects. If they are being used by Firewall rules, you need to modify them first by withdrawing the objects.

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

## Sample .config file
# Sophos XG
host=<sophos_ip_or_host>
username=<sophos_username>
password=<sophos_password>
web_policy=<sophos_web_policy>

# Lumu
company_key=<lumu_company_key>

# Misc
# Optional arguments
ioc-types=ip
ioc-types=domain
ioc-types=url
# Optional arguments (default all adversary types)
#adversary-types=C2C
#adversary-types=Mining
# Optional (default days: 30)
days=30
# Output trace to file. Relevant for cron job or scheduled task
logging=[screen|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

You will see new objects in your Sophos XG Firewall: Lumu IPs in host groups, IP objects with the prefix Lumu_ in IP hosts, and a Web category named Lumu Web .

Lumu IPs host group

Set up Sophos XG policies

After the custom objects have been created and maintained by the integration, you need to use it inside Firewall policies. Here, some examples of how to use these inside your Firewall 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 looks as follows:

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

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.

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.

Check integration process - Linux

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