This article shows how to leverage ESET Endpoint Security through its ESET Protect Web Console and Lumu Defender API to enhance your Response capabilities.

Response integration between ESET Endpoint and Lumu

Requirements

• ESET PROTECT deployment
  
  • An ESET PROTECT Advanced or above subscription is required with an On-premise Web console on version ~11.0 (11.0.193.0)
• Lumu Defender API key
  
  • To retrieve an API token, please refer to the Defender API document.
  • Integration package. Contact Lumu Support to request the specific package for this integration.
• Script host.
  
  • A scripting host is required to deploy the integration. This host must have Internet visibility over Lumu Defender API endpoints and ESET Protect Web console. According to the deployment model you select, you will need a host with:
    
    • A Linux-based distro: Ubuntu 20.04 or 22.04 is recommended
    • + 4GB RAM
    • APT package manager (some packages might require SUDO access)
    • Python 3.10+
    • Docker Engine for container-like deployment

Contacted hosts

• ESET Protect Server
• defender.lumu.io

Integration overview

• For instance, if the parent IOC domain.com has already been added, it will not be possible to add the child domain child.domain.com.
• In the same manner, if the parent IOC example.com/path has already been added, it will not be possible to add the child IOC example.com/path/subpath.

The maximum number of items supported per Web address list are 10.000 each, but reaching this amount would require having much better hardware resources, mainly RAM.

Prepare ESET Protect for Lumu integration

Before deploying and implementing the Lumu Integration, you must prepare your ESET Protect On-premise server to ensure the integration functions properly. You will find the required preliminary steps in this section.

It is important to keep in mind the language chosen at the login screen. It will be necessary to properly configure the integration in a further step.

Identify endpoint policies

• ESET Endpoint Security for Windows (V11+)
• ESET Endpoint for Linux (V7+)

If you need the integration to work with more than one policy, you will need to deploy multiple instances of the integration, one for each policy.

Select or create an address list

1. Click on the policy of interest and right-click to open the contextual menu. Then, click on the Edit button.

2. Under the policy you selected, go to Settings > Protections > Web Access Protections > URL list management and click on the Edit label next to the Address list label.

3. In the Address list window, identify or create a list. The list must be tagged as Blocked under the Address types field.

If you choose to create a list, make sure the name is unique for this integration. Due to the nature of permissions in ESET some Address List names might be hidden, which can cause the integration to feed IOCs to the wrong Address List.

Take note of the exact name of the address list, as it will be used as an input for the integration.

Create an Integration role

1. Use the left navigation bar to expand the More menu (the one with an ellipsis icon - it will fold back once you select it). Then click on the Permissions Sets menu under the ACCESS RIGHTS section. Click on the NEW button

2. Fill in the information following these guidelines:

a. Fill in the Basic information. Use a descriptive name to facilitate the assignment process.

b. In the Static Groups section, click on the Select button, and select the All and the Companies options in the dialog that appears. Click Continue when you’re done.

c. Next, In the Functionality section, mark the following options

Functionality	Permissions
Groups & Computers	Read, Use
Policies	Read, Use, Write

d. Save the role by clicking on the FINISH button

Create an Integration user

Ensure you can create an Integration user without MFA enforcement. The integration will not work with a user with MFA enabled.

1. Use the left navigation bar to expand the More menu (the one with an ellipsis icon - it will fold back once you select it). Then click on the Users menu under the ACCESS RIGHTS section. Click on the ADD NEW… button and select Add New Native User.

2. Fill in the information following these guidelines

a. Fill in the Basic information. Username, password and other required fields

When you’re done filling out this section, click on the Continue button.

b. In the Permission Sets section, assign the role created during the Create an Integration Role section earlier on this document. Save the user by clicking on the FINISH button

3. The user you created should appear in the Users list.

Collect the required data from Lumu portal

• Lumu Defender API key
• Company UUID

Collect the Lumu Defender API key

Collect your Lumu company UUID

Preliminary Setup - Choose your integration environment

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

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 ESET Protect instance.

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

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"
    [name: "COMPANY-NAME"]
    [contact_name: "CONTACT_NAME"]
    [contact_email: "CONTACT_EMAIL"]
    defender_key: "DEFENDER_API_KEY"
    hash_type: "sha256" # sha256 | sha1 | md5
    ioc_types: # list of ioc types, option one, many or all
      - ip
      - domain
      - url
      - hash
    adversary:  # list of adversary types, option one, many or all
      - C2C
      - Malware
      - Mining
      - Spam
      - Phishing
      - Anonymizer

    days: 30 # MIN 1, MAX 30
# - COMPANY 2
# - COMPANY 3 
# -  ...

The COMPANY string at the end of the Companies file is used when deploying integrations for multiple companies. If this is your case, replace the COMPANY string with the information of each of your other integration deployments, using the same format as with the first one. This can be particularly useful for LUMU MSP customers.

If your integration is not a multiple deployment, removing the “#” symbol from the COMPANY string will result in an error. Only enable the COMPANY string when you need to deploy multiple integrations.

Complete the integrations file

The integration supports the following Web console languages. You can specify which by filling in the appropriate string under the Language parameter in the Integration file. Select them according to the language you chose in the Prepare ESET Protect for Lumu integration step:

1. English: Use the string English
2. Español (América Latina): Use the string SpanishLatam
3. Español (España): Use the string SpanishSpain

The integration file contains the information required for the integration to connect and interact with your ESET Protect deployment. Here are some guidelines to properly fill it out:

1. The POLICY NAME parameter is filled with the name of the Policy you created in the Identify Endpoint Policies section at the beginning of this document.
   
2. The List of blocked addresses parameter is filled with the name of the Address List used in the Select or Create an Address List section earlier in this document.
   

-
  lumu:
    uuid: "COMPANY_UUID"
    adversaryTypes: [ "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing", "Anonymizer"] # ["C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"]
    days: 10 # INTEGER=(get incidents from X days of the ioc manager local db)
  app:
    name: "<CLIENT-NAME>" # Unique Account Name of the Cloud company subscription
    clean: false # false | true
    Language: English # English, SpanishLatam, SpanishSpain
    Policy: # ONLY APPLIES for OS Windows, Linux workstations
      Name: "POLICY-NAME"      
AddressListName: "List of blocked addresses" # Name | null, default "List of blocked addresses"
      ioc: [ ip, domain, url ] # [ ip, domain, url ] | [] | null
      
    api:
      hostname: "IP-HOSTNAMEPORT"
      username: "AUTH-USERNAME"
      password: "AUTH-PASSWORD"
# - INTEGRATION 2
# - INTEGRATION 3 
# -  ...

The INTEGRATION string at the end of the integrations file is used when deploying multiple integrations. If this is your case, replace the INTEGRATION string with the information of each of your other integration deployments, using the same format as with the first one. This can be particularly useful for LUMU MSP customers.

If your integration is not a multiple deployment, removing the “#” symbol from the INTEGRATION string will result in an error. Only enable the INTEGRATION string when you need to deploy multiple integrations.

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: eset_lumu [-h] [--config CONFIG] [--ioc-manager-db-path IOC_MANAGER_DB_PATH] [-v] [-c] [-l {screen,file}] [--hours HOURS]

Usage Examples

• Task: query IOC related to Lumu incidents with default options
  

• Task: query IOC related to specific parameters
  

• Task: Clean records
  

The records not manipulated by the integration will be preserved.

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)

1. Build the container by running the following command.

docker build \

       [--build-arg IOC_MAN_CONFIG='companies.yml'] \

       [--build-arg APP_CONFIG='integrations.yml'] \

       --tag img-lumu-eset-endpoint-response \

       --file DockerfileAllInOne .

Do not forget the dot "."

2. Run the container by using the following command.

docker run -d \

       -v ./companies.yml:/app/companies.yml \

       -v ./integrations.yml:/app/integrations.yml \

       -v ./debug:/app/debug \

       --restart unless-stopped \

       --log-driver json-file \

       --log-opt max-size=30m \

       --log-opt max-file=3 \

      --name lumu-eset-endpoint-response \

       img-lumu-eset-endpoint-response

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

Docker container deployment Troubleshooting

• To log in to your container using an interactive shell:

• To collect integration logs:

Expected Results and Validation

After running the integration, you will see new items under the selected Address list inside the Web Access Protection configuration for the ESET Policy. Double click on the list you chose at the beginning of the setup process to see IOCs fed by the integration.

If you try to navigate to one of these IOCs by using an endpoint protected with the selected policy, you will get a blocking page like the following:

Troubleshooting and known issues

Authentication Failed

Network Connection Failed

Input Parameters Validation Failed

Policy Failed

Blocklist Within Policy Failed

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.