Sophos UTM SG Custom Response Integration

Sophos UTM SG Custom Response Integration

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


Requirements

  • Sophos UTM SG subscription
    • You need a Sophos UTM SG with Firewall and Web filter capabilities.
  • Lumu Defender API key
    • To retrieve an API token, please refer to the Defender API document.
  • Script host.
    • Host with Python 3.10+ with Internet visibility over Lumu Defender endpoints and Sophos UTM SG.
  • Script package
  • Contact the Lumu support team to request the package we created to deploy the required files.

Set up your Sophos UTM SG Firewall

To run the integration, you need an API key linked to a particular Firewall user. We strongly recommend setting up a restricted user to link it to the API key generated in the next step.

Create a dedicated Firewall user for the integration

Create a new user for the integration using the Sophos Web Console. Go to the Users & Groups menu under the Definitions & Users section. Fill in the required data and save the user.

Set up a limited access role

To set up an access role for the user to be linked with the API key, go to the WebAdmin Settings menu under the Management section. Select the Access Control tab and click on the New Role button. Fill in the requested data, and associate the user created in the step above. In the Rights section enable only the following:

  • Network Protection Manager
  • Web Protection Manager

Save the new role.

Create a new API Key

Using the Sophos UTM SG Web Console, go to the WebAdmin Settings under the Management section. In the WebAdmin Settings window, go to the RESTful API tab. Click in the New API Token button to create the token and attach the user created before.


Deploy the integration

There are 2 environment options to deploy the script, select the one that fits better in your current infrastructure. Whatever alternative you select, you need to unpack first the integration package shared by our Support team. 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>.

The integration works with Python 3.10. If your environment has prior versions, we recommend deploying the integration as a Docker Container.

Prepare Python on your environment

As a recommended practice, we encourage you to create a Virtual environment for each integration to avoid conflicts between them and your operating system tools. Make sure you follow the steps in our Preparing Environment for Custom Integrations article.

Deploy as script

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 (<sophos_lumu_root>). Specific steps are included in the next sections.

Install requirements

If you are running different Python scripts in the selected host, it’s recommended to create a virtual environment to preserve the integrity of other tools. To do so, follow these steps:

1. Using a command line tool, locate yourself in the <sophos_lumu_root> folder

2. Run the following command to create the virtual environment

python3 -m venv <venv_folder>

3. Activate the virtual environment running the following

source <venv_folder>/bin/activate

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:

pip install -r sophoslumu/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:

python3 sophos_lumu.py -h

usage: sophos_lumu.py [options]

Options

Description

-h, --helpshow this help message and exit
--config CONFIGLoad options from config file
--proxy-host PROXY_HOST--proxy_host PROXY_HOSTProxy host (if required)
--proxy-port PROXY_PORT--proxy_port PROXY_PORTProxy port (if required)
--proxy-user PROXY_USER--proxy_user PROXY_USERProxy user (if required)
--proxy-password PROXY_PASSWORD--proxy_password PROXY_PASSWORDProxy password (if required)
--company-key COMPANY_KEY--company_key COMPANY_KEYLumu Company Key (Defender API).
--logging {screen,file}Logging option (default screen).
--verbose, -vVerbosity level.
--adversary-types {C2C,Malware,Mining,Spam,Phishing--adversary_types {C2C,Malware,Mining,Spam,Phishing}Lumu adversary types to be filtered.
--days DAYSThe number of days backward from now to query Lumu incidents (default 30).
--test, -tRuns a test with one incident only.
--cleanCleans all rules and objects created by the Lumu integration.
--sophos_hostname SOPHOS_HOSTNAMESophos SG UTM Name
--sophos_api_token SOPHOS_API_TOKENSophos SG UTM API Token
--ioc_types {ip,url,host}--ioc-types {ip,url,host}IOC types to be collected and processed by the integration

The integration script manages a local database named sophos_ioc. We strongly encourage not editing or deleting this file to avoid errors in the integration.

Usage Examples

To query all IPs, domains, URLs related to Lumu incidents triggered in the last 30 days, run the following command.

python3 sophos_lumu.py --company-key LUMU_KEY --sophos_api_token SOPHOS_API_TOKEN --sophos_hostname SOPHOS_HOSTNAME

By default, the integration script will query incidents for the last 30 days. If you need to change this value, you can use the --days flag as follows.

python3 sophos_lumu.py --company-key LUMU_KEY --sophos_api_token SOPHOS_API_TOKEN --sophos_hostname SOPHOS_HOSTNAME --days 5

In this example, the integration will query and push to the Sophos Firewall IPs, URLs, and domains related to incidents in the last 5 days

By default, the integration script will query incidents related to all adversary types. If you need to filter the query to specific adversary types, you can use the --adversary-types flag as follows

python3 sophos_lumu.py --company-key LUMU_KEY --sophos_api_token SOPHOS_API_TOKEN --sophos_hostname SOPHOS_HOSTNAME --adversary-types C2C --adversary-types Malware

In this example, the integration will query and push to the Sophos Firewall IPs, URLs, and domainsfrom incidents related to adversaries classified as C&C and Malware.

Task: run with .config file

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

  1. # Configuration file example
company_key=abcd
sophos_api_token=xyz
sophos_hostname=a.b.c.d:1234
ioc-types=ip
ioc-types=url
ioc-types=host
adversary-types=C2C
adversary-types=Malware
adversary-types=Mining
adversary-types=Spam
adversary-types=Phishing
days=15

If you need to add flags (arguments without values like -v or --clean, those need to be added on the command line). In the repo files, you will find a sample file named .config_sample. You can tailor its content according to your needs. Remember to rename it to .config before running the integration script.

Task: Clean records

When the script is run with the –clean flag, it will erase all Lumu records created. Using this flag, you will return the sophos lists to their original state.

python3 sophos_lumu.py --clean --company-key LUMU_KEY --sophos_api_token SOPHOS_API_TOKEN --sophos_hostname SOPHOS_HOSTNAME
The records not manipulated by the integration will be preserved 
Other tasks
According to your needs, you can combine the examples shown.
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. 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 * * * * python3 sophos_lumu.py --company-key LUMU_KEY --sophos_api_token SOPHOS_API_TOKEN --sophos_hostname SOPHOS_HOSTNAME
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 * * * * python3 sophos_lumu.py
If you need to work with another scheduling time, you can use the [crontab guru](https://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.
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 <sophos_lumu_root> folder, and follow these instructions:
1. To build the container, run the following command. Change all the flags based on the reference given in the script section above.
docker build --build-arg company_key='xxx' --build-arg sophos_api_token='xxx' --build-arg sophos_hostname='xx-xx-xx-xx-xx' --tag python-lumu-sophos .
Do not forget the dot "." at the end of the line
2. To run the container, run the following command:
docker run -d --name lumu-sophos python-lumu-sophos
With this mode, your integration will run every 30 minutes.
Troubleshooting
For troubleshooting purposes, you can run the following commands:
To log in to your container using an interactive shell:
docker exec -it lumu-sophos bash
To collect integration logs:
docker logs -f lumu-sophos
Expected results
After running the integration, you will see changes in your Firewall configuration. Check the following sections to learn more about them.
Network Definitions
All the IPs and domains related to Lumu can be found in this list. This item can be found in the Network Definitions menu under the Definitions & Users section in the Sophos Web Console.

Finally, the integration creates a new Firewall rule above all existing rules. This rule can be found in the Firewall menu under the Network Protection section in the Sophos Web Console.

Web Protection
The URLs related to Lumu incidents can be checked in the Websites tab. You can find it in the Filtering Options menu under the Web Protection section. All the URLs created by the integration will be associated with the Lumu tag.

Use the Lumu tag to finish your configuration. You need to associate this tag to a Filter Action, then the Filter Action to a Filter Policy. Finally, associate the Filter policy to a Filter Profile.

When creating the Filter Policy, select the Operation mode that best fits your environment. Check the Sophos SG official documentation for further reference.
  • Standard mode: Explicit proxy using TCP port 8080. This mode enables the filtering of non-regular ports.
  • Transparent mode: Transparent proxy. This mode enables the filtering of HTTP:80 and HTTPS:443 port only.

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.


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






    

    Still can’t find an answer?  
    Send a message to our experts.  
    Contact Us   
    

    

      

      

      

      

        

        • Related Articles
          • 

        • Sophos Antivirus Custom Response Integration
          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 ...
          • 

        • DNSFilter Custom Response Integration
          This article shows how to leverage the Lumu Response API and DNSFilter API to mitigate security risks. Requirements An active DNSFilter subscription. A DNSFilter Pro subscription or up is required. Script host. A scripting host is required to deploy ...
          • 

        • Azure Custom Response Integration
          This article shows how to leverage Azure Virtual Networks REST API and Lumu Defender API to enhance your Response capabilities. Response integration between Azure and Lumu Requirements An Azure subscription with Compute services deployed. An Azure ...
          • 

        • Infoblox Custom Response Integration
          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 ...
          • 

        • Bitdefender Custom Response Integration
          Bitdefender Custom Response Integration This article shows how to leverage the Lumu Defender API and Bitdefender API to mitigate security risks. Requirements GravityZone Business Security Enterprise, cloud version, ...
          •