This article shows how to leverage Kaspersky Endpoint Security, also known as KES through its Kaspersky Security Center (KSC) Web Console and Lumu Defender API to enhance your Response capabilities.

Response integration between Kaspersky Endpoint and Lumu

Requirements

• Kaspersky Security Center deployment
  

• 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 KSC Win Server. 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 packet manager (some packages might require SUDO access)
    • Python 3.10+
    • Docker Engine for container-like deployment

Contacted hosts

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

• KSC IP-Domain Server
• defender.lumu.io

Integration’s overview

Kaspersky Security Center integration works by managing the content of these policy objects:

• A Web control policy belonging to a Device policy
• An application category

The integration feeds IOCs (IPs, domains, and URLs) into the Web control policy. To avoid redundancy, if a parent IOC already exists inside the Web control policy, children IOCs (IOCs with the same base) are not accepted. For instance, domain.com is considered a parent IOC of child.domain.com, and example.com/path is the parent IOC of example.com/path/subpath. Hashes are managed inside the application category. Then, you can reference the application category inside a Device policy

The maximum number of items supported per Web control policy and App Control category is 10.000 each

Prepare Kaspersky Security Center (KSC) for Lumu integration

Before deploying and implementing the Lumu Integration, you must prepare your Kaspersky Security Center (KSC) deployment to ensure the integration works as expected.

Create a Web control rule inside your Device policy

To manage Network IOCs (IPs, domains, or URLs) with the integration, you must create a Web control rule inside the Device policy you want to integrate. To do so, follow these steps:

Create an Application Category

To manage malicious hashes, you must create or select an Application Category. To do so, follow these steps:

Create an integration role (recommended)

To grant the minimum privileges to the user that will be used to run the integration, it’s encouraged to create an integration role with just the required permissions. To create it follow these steps:

Create an integration user (recommended)

To separate duties from other users, it’s encouraged to create a dedicated user to run the integration. This user must be associated with the role created in the previous step. To create this user, follow these steps:

Collect the required data from 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 data collection procedures.

Collect the Lumu Defender API key

To collect the Lumu Defender API key, 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.

Deploy the integration

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

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

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

If you use the install script, use the uninstall.sh bash file to remove the integration from the host

Set up the configuration files

To set up the integration, you need to add and edit two configuration files:

• companies.yml: this file contains the information collected from the Lumu portal
• integrations.yml: this file contains the information collected from your KSC 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

The companies file defines how the integration connects to Lumu and extracts the information of the incidents and related indicators of compromise.

-
  lumu:
    uuid: "<COMPANY-UUID>"
    [name: "<COMPANY-NAME>"]
    [contact_name: "<CONTACT_NAME>"]
    [contact_email: "<CONTACT_EMAIL>"]
    defender_key: "<DEFENDER_API_KEY>"
    hash_type: "<HASH_ALG>" # 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
    days: 30 # MIN 1, MAX 30

Within this file the COMPANY_UUID and DEFENDER_API_KEY fields are mandatory. Please use the values captured in the previous steps. The ioc_types values must match with the IOC types required by the integration.

Complete the integrations file

The integration file contains the information required for the integration to connect and interact with your KSC deployment:

-
  lumu:
    uuid: "<COMPANY_UUID>"
    adversaryTypes: [ "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"] # ["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
    WebPlugIn: # Optional | null
      WebControlRule:  # ONLY APPLY for OS Windows | null
        policy: "<POLICY-NAME>" # "<POLICY-NAME>"
        Name: "<Web-Control-Rule-Name>" # Name | null
        ioc: [ ip, domain, url ] # [ ip, domain, url ] | [] | null
        chunk: <INT=500> # [20 - 1000]
	  max: <INT=1000> # [20 - 10000]
      AppControlCategory: # Optional | null
        Name: "<App-Control-Category-Name>" # Name | null
        ioc: [ hash ] # [hash ] | [] | null
        chunk: <INT=70> # [20 - 200]
	  max: <INT=1000> # [20 - 10000]
    api:
      hostname: "<IP-HOSTNAME:PORT>"
      username: "<AUTH-USERNAME>"
      password: "<AUTH-PASSWORD>"

The integration can manage Web control rules or Application control categories separately. Set them according to your needs.

The chunk and max parameters allow control of the integration’s performance. It’s recommended to work with the default values. If you need to modify them, do so with caution.

Prepare Python on your environment

Deploy Integration as script

To deploy the integration as a script, you need to run the install.sh script inside the integration package.

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

To run the installation script, locate yourself in the app_lumu_root folder, then execute this line through CLI.

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 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: kaspersky_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

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

You must remove the integrations.yml file to run the integration with the default options. If the file exists, the integration script will use the parameters depicted in it.

Task: query IOC related to specific parameters

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

Task: Clean records

To clean the existing records in KSC, just set up the clean flag in the integrations.yml file to true.

Then, run the integration script as follows:

Or you can run the clean command directly to clean all the companies

The records not manipulated by the integration will be preserved

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 at the <app_lumu_root> folder, and follow these instructions:

Troubleshooting

For troubleshooting purposes, you can run the following commands:

To log in to your container using an interactive shell:

To collect integration logs:

Expected results

After running the integration, you will see new items under the Web Rule selected for the integration.

The Application Category selected for the integration will be populated with hashes.

The endpoints covered by the managed policy won’t be able to connect or execute IOCs populated into the rules and lists.

Troubleshooting and known issues

To identify failures in the script execution, use the -v flag. The script execution log will show more detailed information.

The application logs will be redirected to lumu.log file. The file errors.log stores only the errors to make them easier to find and aid the troubleshooting process.

Input Validation

If you receive errors like this:

It means you are using the wrong key parameters or the wrong values for those parameters.

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.