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 Security and Lumu

Requirements

• Kaspersky Security Center deployment
  
• A Kaspersky Security Center server with versions 14.X up to 15.1.X. This deployment must have the following:
  
• Web Console enabled
  
• Kaspersky Endpoint Security for Windows plug-in and Web plug-in on version 12.3.0 or above
  
• A Kaspersky endpoint policy for Windows and its child Web control rule
  
• An Application Category Entry to feed SHA256 hashes.

Currently, the integration is not tested with other Web console versions besides the ones indicated before.. We cannot guarantee correct integration operation with this console version.

This integration works with Windows devices exclusively.

• 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
  
• More than 4GB RAM 
  
• APT packet manager (some packages might require SUDO access)
  
• Python 3.10 or Python 3.12
  
• Docker Engine for container-like deployment (If either Python 3.10 or Python 3.12 is not your default version)
  

Contacted hosts

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

Integration overview

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

• 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 control policy and App Control category is 10.000 each.

Preliminary Integration Steps - Kaspersky Security Center (KSC)

Create a Web control rule inside your Device policy

1. Click on the Policies & profiles menu under the Devices section in the main navigation bar. Then, click on the policy you want to manage.

Keep note of the selected Device policy name. It will be used to set up the integration.

2. Under the Policy window, click on the Application settings tab. Then, click on the Security Controls link. Finally, click on the Web control menu.

3. Enable the Web control toggle. Then, either select an existing Web control policy or create a new one. Set up its Action to Block. You can use canary.lumu.net as the base address for your rule.

4. Click on the Ok button. Finish the process by clicking on the Save button

Keep note of the name of the Web control rule that was selected as it will be used to set up the integration.

It is recommended to create at most 1000 rules of access to Web resources, as this can cause the system to become unstable.

Create an Application Category

1. On the KSC’s Web console navigation bar, click on the Operations > Third-party applications > Application Category menu. Then, click on the Add button.

2. Fill in a descriptive Name for the category. Under the Creation method select ”Category with content added manually. Data of executable files is manually added to the category.”. Click on the Next button.

3. Add a condition by clicking on the Add button. Then:

a. Select the Hash… option.

b. From the dropdown list, select Specify manually.

c. Click on Next

d. Add the following SHA-256 hash:
      9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

e. Click on Next

f. Under the Conditions window, click on Next

g. On the Exclusions window, click on OK to create the new Application category

It is not recommended to create more than 1000~2000 conditions for KSC application resources, as this can cause the system to become unstable.

Create an integration role

1. Click on the Roles menu under the User & roles section in the left navigation pane. Then, click on the Add button

You can use either the Kaspersky Endpoint Security Operator or the Main Operator roles as a reference to create your new role.

2. Fill in the requested information for your new role.

• Give it a distinctive name.
• Under the Access rights, select the rights as follows:

Access right	Action
Kaspersky Security Center Administration Server > General Features > Basic functionality	Allow
Kaspersky Security Center Administration Server > System management > Software inventory	Allow
Kaspersky Endpoint Security for Windows (12.3.0) > Application Control	Allow
Kaspersky Endpoint Security for Windows (12.3.0) > Web Control	Allow

3. Save your new role by clicking on the Save button.

Create an integration user

1. Click on the Users menu under the User & roles section. Then, click on the Add button

2. Fill in the user’s basic information. After filling this. Go to the Roles tab and assign the created role as follows. First, add the role to the Administrator Server scope. Then, add the role to the Managed devices scope.

Collect the required data from Lumu portal

• Lumu Defender API key
• Company UUID

Collect the Lumu Defender API key

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

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

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"
    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

Complete the Integrations file

1. The POLICY-NAME parameter is filled in with the name of the policy you selected in Step 1 of the Create a Web control rule inside your Device policy section of this document.
   
2. The WEB-CONTROL-RULE parameter is filled in with the name of the web control rule you selected in Step 3 of the Create a Web control rule inside your Device policy section of this document.
   
3. The APP-CONTROL-CATEGORY-NAME parameter is filled in with the name of the Application Category you created in the Create an Application Category section of this document.
   

-
  lumu:
    uuid: "COMPANY_UUID"
    adversaryTypes: [ "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing" , "Anonymizer"] # ["C2C", "Malware", "DGA", "Mining", "Spam", "Phishing", "Anonymizer"] delete IOC types you do not want to send
    days: 3 
  app:
    name: "CLIENT-NAME" # Unique Account Name of the Cloud company subscription
    clean: false # false | true to delete the integration
    WebPlugIn: # Optional | null
      WebControlRule:  # ONLY APPLY for OS Windows | null
        policy: "POLICY-NAME" # Name of the policy as is in KSC
        Name: "WEB-CONTROL-RULE" # Name | null
        ioc: [ ip, domain, url ] # [ ip, domain, url ] | [] | null        
      AppControlCategory: # Optional | null
        Name: "APP-CONTROL-CATEGORY-NAME" # Name | null
        ioc: [ hash ] # [hash ] | [] | null
    api:
      hostname: "IP-HOSTNAME:PORT"
      username: "AUTH-USERNAME"
      password: "AUTH-PASSWORD"

The integration can manage Web control rules and Application control categories separately. Set them according to the needs of your organization.

Potential errors in KSC consoles

Please follow the steps indicated in this section before contacting us for integration errors. If you are operating with a KSC console on a different version than the ones indicated under Requirements​, these steps could solve any issues.

You can find errors when operating the integration in versions not tested before. You could circumvent these conditions by collecting the Policy ID and the Application category ID from the KSC console to add them to the integrations.yml configuration file.

To collect the IDs follow these steps:

Collecting the Policy ID

To collect the Policy ID, open your KSC Web console and:

1. Head to the left navigation bar, and expand the Devices section. Click on the Policies & profiles menu.

2. In the Devices / Policies & profiles window, look for the policy you want to integrate. Click on the selected policy. For this example, we will use KSC_LumuTestPol.

3. Look at the address bar in your Web browser. The number at the end of the URL is the Policy ID. Extract it.

4. Add the Policy ID to your configuration file. Use the following configuration step as an example. The highlighted text shows how the ID must be added.

      WebControlRule:
        policy: "POLICY-NAME"
        policy_id: 12
        Name: "WEB-CONTROL-RULE"
        ioc: [ ip, domain, url ]

Collecting the Application category ID

To collect the Application category ID, open your KSC Web console and:

1. Head to the left navigation bar, and expand the Operations section. Click on the Application categories menu under the Third-party applications section.

2. In the Operations / Third-party applications / Application categories window, look for the application category you want to integrate. Click on the selected category. For this example, we will use the Lumu category.

3. Look at the address bar in your Web browser. The number at the end of the URL is the Application category ID. Extract it.

4. Add the Policy ID to your configuration file. Use the following configuration step as an example. The highlighted text shows how the ID must be added.

      AppControlCategory:
        Name: "APP-CONTROL-CATEGORY-NAME"
        app_category_id: 3
        ioc: [ hash ]

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

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.

python3 run.py

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

python3 run.py --config integrations.yml --ioc-manager-db-path /<ioc-manager-path>/ioc.db

• Task: Clean Records

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

clean: true

Then, run the integration script as follows:

python3 run.py [--config CONFIG] [--ioc-manager-db-path IOC_MANAGER_DB_PATH]

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

python3 run.py –clean [--config CONFIG] [--ioc-manager-db-path IOC_MANAGER_DB_PATH]

The records not manipulated by the integration will be preserved.

1. 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)

Do not forget the dot "."

Docker Container Deployment Troubleshooting

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

• To collect integration logs:

Expected Results and Validation

Troubleshooting and known issues

Authentication Failed

Network Connection Failed

Input Parameters Validation Failed

Policy Search Failed

• The policy section within the Kaspersky Endpoint Security Console is not loading
• The selected policy was not found in the policy section of the Kaspersky Endpoint Security console

Web Rule Within Policy Search Failed

Another instance is running