Learn how to use the Lumu Defender API and ESET PROTECT Cloud, together with the ESET Connect API, to effectively mitigate security risks.

Response integration between ESET PROTECT Cloud and Lumu

Requirements

• ESET PROTECT Cloud
  • You need an ESET PROTECT Cloud administrator user to perform actions over ESET Connect API required to deploy 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 ESET public services. According to the deployment model you select, you will need a host with:
    • Python 3.13+
      or
    • A Docker-enabled host.
• Script package
  • Contact the Lumu support team to request the package we created to deploy the required files.

Contacted hosts

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

• ESET PROTECT Cloud servers. Refer to the ESET Connect Network Prerequisites based on the location of your Cloud deployment.
• defender.lumu.io
• docker.io
• ghcr.io
• *.ubuntu.com
• *.launchpad.net
• canonical.com
• debian.org
• *.debian.org
• debian-security.org
• pypi.python.org
• pypi.org
• pythonhosted.org
• files.pythonhosted.org

Integration overview

Lumu’s custom response integration with ESET PROTECT Cloud uses the ESET Connect API to manage a URL group within the Web Access Protection rules in Windows Workstation policies. It automatically updates this group with URLs identified by Lumu as confirmed risks, helping to prevent further communication with those endpoints.

URL groups for web control are only available in Windows rules (Desktop devices). Be aware that the ESET Connect API only supports the management of this type of object.

Preliminary Setup - ESET PROTECT Cloud

To set up the integration, you must prepare the ESET PROTECT Cloud console to communicate with the Lumu integration. To do this, you need the following:

• Create a dedicated integration user.
• Create a custom permission set in your PROTECT console.
• Map the integration user and link it to the permission set.
• Identify your ESET Regional Authentication and Regional Web Access Protection domains.
• Collect the Windows policy ID.
• Configure the Web Access protection module inside the Windows policy.

Next, we will guide you through the process to fulfill these requirements.

Create a dedicated integration user

We encourage you to create a dedicated integration user. This will allow you to separate API activities from regular activities. If required, you can use an existing administrator user.

Creating your integration user depends on the portal you use for managing your ESET deployments and licensing. You have the following options:

• ESET Business account or ESET MSP Administrator 2.
• ESET PROTECT Hub.

Follow the steps in the next sections based on your management portal.

ESET Business account or ESET MSP Administrator 2

Log in to your ESET portal with an administrator user and follow these steps:

1. Click on User management (1) in the left navigation menu.

2. Click on New user (1) located at the bottom of the User management window.

3. Fill in the new user information by following these guidelines

1. Type in the First name (1) and Last name (2).
2. Type in the Email Address (3). This is the primary identifier of the user.
3. Set the Company access right to Read (4).
4. Set the ESET PROTECT access rights to Custom (5). These will be mapped later.
5. Activate the Integrations toggle (6).
6. When finished, click on CREATE (7).
   

4. You will receive an account activation email. Activate your new integration user by following the instructions given in the ESET activation email. Keep the credentials at hand, they will be used during the Complete the integration file step.

ESET PROTECT Hub

Follow the steps in the Create API user account for ESET PROTECT Hub. Fill in the Permission section based on the indications given in the step 3 of the ESET Business account or ESET MSP Administrator 2 section.

Create a custom permission set

We encourage you to create a custom permission set to implement the principle of least privilege.

The integration script will need permissions to Read, Use, and Write policies. To create a permission set with these features, log in to your ESET PROTECT Cloud portal and follow these steps:

1. Click on More (1) in the left navigation menu to expand a secondary menu. Then, click on Permission Sets (2) under the ACCESS RIGHTS section.

2. In the Permission Sets window, click on NEW (1) at the bottom of the screen. The New Permission Set window will appear.

3. Fill in the information about your New Permission Set by following these guidelines:

1. Give the role a distinctive Name (1). Then, click on CONTINUE (2).
   
   
   
   
2. Click on Select (1) in the Static Groups tab.
   
   
   
   
3. Mark the device groups to cover with the permission set. If you are not sure, activate the All toggle. Then, click on OK (1).
   
   
   
   
4. Once you have selected the device groups, click on CONTINUE (1) in the Static Groups tab.
   
   
   
   
5. In the Functionality tab, activate the Read, Use, and Write privileges (1) for the Policies functionality. Then, click on Finish (2).
   
   
   
   
6. When finished, you will have created your new integration permission set.
   
   
   
   

Map the integration user and link it to the permission set

Now, it’s time to map your ESET Business/PROTECT hub user into your ESET PROTECT console. Follow these steps in your ESET PROTECT Console.

1. Click on More (1) in the left navigation menu to expand a secondary menu. Then, click on Users (2) under the ACCESS RIGHTS section.

2. In the Users window, click on ADD NEW (1) at the bottom of the screen. The New Permission Set window will appear.

3. Fill in the information about your New mapped account by following these guidelines:

1. Click on SELECT (1).
   
   
   
   
2. Mark the new user (1) created in the Create a dedicated integration user section. Then, click on OK (2).
   



3. Once you have selected the account, click on Continue (1).



4. Under the Unassigned (Available) Permission Sets section (1), select the permission set created in the Create a Custom permission set section. The policies functionality with Read, Use, Write privileges should be listed under the Functionality access (2).


If you did not create a permission set, select one that has the Policies functionality with the Read, Use, and Write privileges.
5. When finished, click on FINISH to complete the account mapping.

Please refer to the Map ESET Business Account users for further reference.

Identify your ESET Regional Authentication and Regional Web Access Protection domains

ESET Connect API uses dedicated domains for specific services and regions. Thus, it is necessary to identify the region where your ESET PROTECT Console is deployed. Ask your ESET PROTECT administrator about the deployment region selected when the console was deployed. If you don’t have access to this information, you can infer it from your console’s URL. Here is an example. Let’s see the string before the first dot:

For the example above, us02 is the string we are looking for. The first two letters indicate that this ESET PROTECT Console is deployed in the United States. In the following table, you will find the domains for each region. Look for the specific region and collect the Authentication and Web Access Protection domains. These will be needed later to configure the integration.

For updated reference, please refer to the ESET Connect Network Prerequisites document and find the Authentication and Web Access Protection domains related to your deployment region.

Collect the Windows policy ID

Remember that the integration works only with Windows policies for Workstations.

The integration script requires the ID of the policy it will manage. Log in to your ESET PROTECT Cloud console and follow these steps:

1. Click on Configuration (1) in the navigation menu. Then, click on the Advanced Setup tab (2) to access the Policies window.

2. Locate and click on the policy you want the Lumu integration to manage to open the contextual menu. Then, click on Edit (1) to open the Edit Policy window.

3. Go to the browser URL bar to collect the Policy ID in the u query parameter in the URL. Copy from the character next to the equal sign and stop at the character before the semicolon. Keep this value at hand, it will be needed during the Complete the integration file step.

Configure the web access protection module inside the Windows policy

First, you must check if the web access protection module is enabled in the policy. Then, you need to enable the web control feature and add an integration URL group. Continue where you left off on the previous step, in the Edit policy window, and follow these steps:

1. Click on Settings (1). Then, click on Web access protection (2) under the PROTECTIONS section.

2. Expand the WEB CONTROL section. Then, click on the Enable Web control toggle (1) to activate the feature. Then, click on Edit (2) near the URL groups field to open the URL groups window.

3. Click on Add (1). Give the group a distinctive name and click on OK (2) when finished.

4. On the URL groups window, click on the recently created group. The window will expand to show the group IOCs, which will initially be empty. Click on Add (1) and type in canary.lumu.net in the Add pop-up window. Finish by clicking the OK (2) button.

5. When finished, click on Save (1) in the URL groups window.

6. Now, you are ready to save the changes to the policy. Click on FINISH in the Edit Policy window.

Preliminary setup - Lumu portal

The integration set-up process needs you to collect this information from Lumu portal:

• Lumu Defender API key
• Company UUID

Log in to your Lumu portal and run the following procedures to collect these data.

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.

Preliminary Setup - Choose your integration environment

There are 2 environment options to deploy the script. Select the one that best fits your current infrastructure.

• Run it as a Python script (Unix-based systems and Windows)
• Run it as a Docker container.
  • By using the Makefile model (Unix-based systems)(Recommended).
  • By using Docker commands (Unix-based systems and Docker Desktop for Windows).

Whichever alternative you select, you must unpack 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 <app_lumu_root>.

Prepare your integration environment

Before starting, ensure your integration environment can communicate with all the hosts listed in the Contacted hosts section

You can deploy your integration using the following alternatives:

• Run your integration using Python
• Run your integration using Docker

Follow the instructions based on the selected deployment method.

Prepare Python on your environment

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

If Python is your chosen deployment method, you will need to create a virtual environment for each integration to avoid conflicts between them and your operating system tools. Ensure you follow the steps in our Preparing Environment for Custom Integrations article.

Prepare Docker on your environment

If you chose Python as your deployment method, you may skip this step.

If Docker is your chosen deployment method, you must follow the Docker installation documentation that corresponds to your OS. Ensure you follow the Post-installation steps for Linux before deploying the integration.

For Windows users, follow the Install Docker Desktop for Windows documentation to install the Docker Engine.

Set up the configuration files

Add the companies.yml and the integrations.yml configuration files in the <app_lumu_root> folder and edit them as instructed to set up the integration.

You will find the companies_template.yml and integrations_template.yml sample files inside the integrations package. Use them to build your configuration file.

Complete the companies file

The companies.yml file contains the information required by the integration to collect the Lumu-related IOCs and make them available for their injection in the ESET PROTECT Cloud policy.

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: "sha256" # sha256 | sha1 | md5
  ioc_types: # list of ioc types, option one, many or all
    - ip
    - domain
  adversary: # list of adversary types, option one, many or all
    - C2C
    - Malware
    - Mining
    - Spam
    - Phishing
    - Anonymizer
  days: 3 # MIN 1, MAX 30

Replace the highlighted placeholders as follows:

• COMPANY-UUID with the Company UUID collected in the Collect your Lumu company UUID section.
• DEFENDER-KEY with the Defender Key collected in the Collect the Lumu Defender Key section.

You must fill in the configuration data carefully. If there are any mistakes or missing data, you’ll receive errors during the deployment of the integration.

Complete the integrations file

The integrations.yml file contains the information required by the integration to manage Lumu-related IOCs into the URL group inside the Web control feature of the ESET PROTECT Cloud policy.

lumu:
  uuid: "COMPANY-UUID"
  days: 3
app:
  name: UNIQUE-NAME
  policy_uuid: POLICY-UUID
  api:
    auth_base_domain: REGIONAL-AUTHENTICATION-DOMAIN
    web_access_protection_base_domain: REGIONAL-WEB-ACCESS-PROTECTION-DOMAIN
    username: USERNAME
    password: PASSWORD

Replace the highlighted placeholders as follows:

• COMPANY-UUID with the Company UUID collected in the Collect your Lumu company UUID section.
• UNIQUE-NAME with a distinctive name for the integration. We recommend using the customer's or ESET PROTECT Cloud tenant’s name.
• POLICY-UUID with the policy ID collected in the Collect the Windows policy ID section.
• REGIONAL-AUTHENTICATION-DOMAIN with the authentication domain collected in the Identify your ESET Regional Authentication and Regional Web Access Protection domains section.
• REGIONAL-WEB-ACCESS-PROTECTION-DOMAIN with the Web Access protection domain collected in the Identify your ESET Regional Authentication and Regional Web Access Protection domains section.
• USERNAME with the username of the user created in the API token collected in the Create a dedicated integration user section.
• PASSWORD with the password of the user created in the API token collected in the Create a dedicated integration user section.

You must fill in the configuration data carefully. If there are any mistakes or missing data, you’ll receive errors during the deployment of the integration.

Deploy as a Docker container via Makefile (Recommended)

To streamline the deployment process, Lumu introduced the Makefile model integration that allows you to easily deploy integrations as a Docker container. To deploy the integration, locate yourself in the <app_lumu_root> folder, and run the following command:

Monitor the console output for any unexpected errors. If there are any errors present, fix them and run the command again. Check the Troubleshooting section for further reference.

Deploy Integration as a Python script via Makefile

To streamline the deployment process, Lumu introduced the Makefile model integration that allows you to easily deploy integrations as a Python script. To deploy the integration, locate yourself in the <app_lumu_root> folder, and run the following command:

Please monitor the console output for any unexpected errors. If issues arise, refer to troubleshooting guidelines or attempt to address them accordingly.

Deploy Integration as a Python script

To streamline the deployment process of the integration as a Python script, you can run the install.sh script. To deploy the integration, locate yourself in the <app_lumu_root> folder, and run the following command:

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

The installation script will set up the Python environment and two different cron jobs.

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

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

Script details

To use the script, you must locate yourself in the <app_lumu_root> folder. Use the following command to show all options available for the package:

Usage: run.py [OPTIONS]

╭─ Options ──────────────────────────────────────────────────────────────────────────────────────╮

│ --verbose -v                       Enable verbose mode.                                        │
│ --clean                            Clean all integrations and override the yml clean field.    │
│ --logging-type -l [screen|file]    Logging output type: 'screen' or 'file' [default: screen]   │
│ --config TEXT                      Path to the configuration file. [default: integrations.yml] │
│ --ioc-manager-db-path TEXT         Path to the IOC manager database file. [default: ./ioc.db]  │
│ --help                             Show this message and exit.                                 │
╰────────────────────────────────────────────────────────────────────────────────────────────────╯

Usage Examples

Task: query IOCs related to Lumu incidents with default options

To query all the indicators 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 the third party, just set up the clean flag in the integrations.yml file to true.

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 in the <app_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

Do not forget the dot "."

2. To run the container, run the following command:

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

Expected results

After you configure the integration, you will see new network indicators in the URL group linked to the Windows policy.

You will see the following block screen after you link this policy to Windows devices for each connection attempt to Lumu-related network IOCs.

Troubleshooting

The commands defined in this section will allow you to troubleshoot the operation of your integration. Keep in mind that you must locate yourself in the <app_lumu_root> folder before running any of them.

Deployment as a Docker container via Makefile

The following are the troubleshooting commands for this deployment option:

• Checking integration logs
  Run the following command to check your integration logs.

• Checking integration errors
  Run the following command to check errors in your integration.

• Check the status of the integration
  
  Run the following command to check the status of the integration.

• Stopping the integration
  Run the following command if you need to stop the integration.
  

• Starting the integration
  Run the following command to start the integration.
  

• Fixing issues with sudo for Docker
  If you cannot run Docker commands with your current user, run the following command

• Reinstalling integration from scratch
  Run the following command to reinstall the integration from scratch:

• Collecting and packaging logs for Lumu support
  Run the following command to collect and package the integration logs to share them with the Lumu support team. This command will create the support.tar package file that contains relevant information for the Lumu support team.

Deployment as a Python script via Makefile

The following are the troubleshooting commands for this deployment option:

• Checking integration logs
  Run the following command to check your integration logs.

• Checking integration errors
  Run the following command to check errors in your integration.

• Check the status of the integration
  Run the following command to check the status of the integration.

• Restarting the integration
  Run the following command if you need to restart the integration.

• Uninstalling the integration
  Run the following command to uninstall the integration.

• Collecting and packaging logs for Lumu support
  Run the following command to collect and package the integration logs to share them with the Lumu support team. This command will create the support.tar package file that contains relevant information for the Lumu support team.

Deployment via Python script

To identify failures in the script, please use the -v flag. This will allow you to identify failures in the script execution.

Deployment as a Docker container

For troubleshooting purposes, you can run the following commands to:

• Logging in to the container using an interactive shell

• Collecting integration logs

Known issues

In this section, we collect all the potential issues you will find after you run the troubleshooting commands from the above section.

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.

Authentication Failed

Check your integration user username and password if you get a log message like this.

Forbidden or Not Found error

Check your integration user permissions and if it has the integration capability enabled in the users settings if you get one of the following log messages.

Policy UUID not match

Check if you have the right policy ID if you get a log message like this.

Cannot find URL group for Web control

Check if you created the URL group with the Lumu canary indicator (canary.lumu.net) in the Web Control feature of your windows policy if you get a log message like this.

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.