Requirements

• A Wazuh deployment (Cloud or On-premise)For Cloud deployments, you need a forwarding agent reporting to the Wazuh Cloud manager
• 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 Wazuh REST API. According to the deployment model you select, you will need a host with:
    
    • Python 3.10+
      OR
    • A Docker-enabled host.

Contacted hosts

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

• Wazuh Manager host (Cloud or On-premise)
• defender.lumu.io
  

On-premise deployment preparation

These steps apply for Wazuh On-premise deployments.

Create an integration user (recommended)

Make sure you use a Wazuh REST API user with the following permissions if you choose not to follow this step:

• Decoders: read and update
• Rules: read and update
• Manager: read and restart
• Cluster: read and restart for all nodes

Cloud deployment preparation

These steps apply for Wazuh Cloud deployments.

Create an integration user for Cloud deployment (recommended)

Make sure you use a Wazuh user with the following permissions if you choose not to follow this step:

• Decoders: read and update
• Rules: read and update
• Manager: read and restart
• Cluster: read and restart for all nodes

If you are working with a Cloud deployment, you need to create an internal user and map it to the created role. First, let’s create the internal user. To do it, follow these steps:

Now, it’s time to map it to the created role.

Configure Syslog forwarding on a Wazuh agent

Wazuh Cloud deployments rely on Syslog forwarding from its agents to process data. Follow the Forward syslog events document to configure it.

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. Bear 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 .bash file to remove the integration from the host

Set up the configuration file

To set up the integration, add and edit the companies.yml configuration file. This file contains the collected information from your Wazuh and Lumu deployments

Inside the integration package, you will find the sample file companies_template.yml, which you can use to build your configuration file.

The companies file defines how the integration:

• Connects to your Wazuh deployment for setting up the decoders and rules
  
• Connects to Lumu and extracts the information of the incidents.
• Sends Lumu collected information to your Wazuh collector

  lumu:
    uuid: "<COMPANY-UUID>"
    defender_key: "<DEFENDER-KEY>"
    include_muted_updates: false # Boolean: true | false
    throttle: 0 # INT<[0-5]> minutes
    incident_types: ["C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"] # ["C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"] | [] | null
    app:
      rule_level:
        # Define rule severity. This will be used for creating the Lumu rules in Wazuh
        # For further reference, check https://documentation.wazuh.com/current/user-manual/ruleset/rules/rules-classification.html
        new_incident: 14 # 0-16 (14 | High importance security event | It is triggered with correlation most of the time, and it indicates an attack.)
        updated_incident: 14 # 0-16 (14 | High importance security event | It is triggered with correlation most of the time, and it indicates an attack.)
      # Defines the wazuh receiver information
      wazuh_receiver: "<WAZUH_RECEIVER_DATA>" # (udp|tcp):hostname_ip:port
      api:
        # Connection parameters to manage Wazuh
        host: "<WAZUH_HOST_IP>" # Wazuh Manager host or IP address. For Cloud deployments, this has the format HOSTNAME.cloud.wazuh.com
        port: <WAZUH_API_PORT> # Wazuh Manager API port. By default is 55000
        username: "<WAZUH_API_USERNAME>" # Wazuh API username 
        password: "<WAZUH_API_PASSWORD>" # Wazuh API password
        verify: false # Verify Wazuh SSL certificate

Mandatory fields

Within the configuration file, fill in these fields:

From Lumu

• COMPANY-UUID: The company ID collected from Lumu portal
• DEFENDER-KEY: The Lumu Defender API key
  

From Wazuh

• WAZUH_RECEIVER_DATA: The Wazuh receiver data, protocol, server, and port where the incident data will be sent. Use the format
  

  (tcp|udp):HOSTNAME_IP:PORT

• WAZUH_HOST_IP: The Wazuh Manager host or IP address. This will be used for setting up the decoders and rules
  
• WAZUH_API_PORT: The Wazuh Manager API port
  
• WAZUH_API_USERNAME: The Wazuh API username created in previous steps
  
• WAZUH_API_PASSWORD: The corresponding Wazuh API user password
  

WAZUH_RECEIVER_DATA for On-premise deployments usually is the same Wazuh manager server. Make sure your manager server can receiver Syslog traffic.

Other fields

To tailor in detail your integration, you can use the following parameters within the configuration file:

• include_muted_updates. Indicates if the updates to muted incidents must be processed. We recommend you leave the default value of false.
• incident_types: A list of the incident types the integration will process and send to your Wazuh server. If you want to remove a particular type of incident, this is the parameter you need.
• new_incident: Define the level of the associated rule with Lumu’s new incident events.
• updated_incident: Define the level of the associated rule with Lumu’s new incident events.
• verify: Set it to false if your Wazuh Manager uses a self-signed certificate and you don’t have it installed in your system.
  

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. Make sure you follow the steps in our  Preparing Environment for Custom Integrations article.

Deploy Integration as a script

To deploy the integration as a script, 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 a cron job. This job will try to keep running your integration script even if your deployment host restarts.

If you want to modify the running interval set up by the installation script, change the latest crob job entry 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: wazuh_lumu [-h] [--config CONFIG] [--ioc-manager-db-path IOC_MANAGER_DB_PATH] [-v] [-c] [-l {screen,file}] [--hours HOURS]

Usage Examples

Task: configure your Wazuh Manager and send Lumu detection events to your Wazuh receiver with the default values

To configure your Wazuh Manager and send Lumu detection events to your Wazuh deployment with the default values, run the following command.

You must use the default companies.yml file filling in the required values to use the default/suggested configuration.

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 choose to deploy your integrations in a Docker-based model, you must install the Docker engine in your device. Please refer to the Install Docker Engine documentation, and follow the specific instructions for your operating system.

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 decoders
  

  

• New rules
  

  

These will allow Wazuh to process Lumu alerts. You will see them in your Wazuh dashboard for new incidents or new contacts to identified adversaries.

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.