The Wazuh XDR Custom SecOps Integration allows you to poll and push adversary-related events to your Wazuh deployment. After configuring the integration, your Wazuh deployment will be able to receive and process Lumu events. By using it, you will be able to see adversarial activity detected by Lumu, giving your Security Operations team more visibility.

SecOps integration between Wazuh XDR and Lumu

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.
• A Docker-enabled host.
  
• This host will be used to deploy the integration component. It must have Internet visibility over the Lumu Defender API endpoints and the Wazuh manager, or the Wazuh selected forwarding agent, depending on your deployment type
  
• Component and Script package
  
• Contact the Lumu support team to request for indication or visit the documentation component in our DockerHub site.
  

Contacted hosts

Ensure your integration host can communicate with the following hosts. These are required for this integration to operate.

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

Integration’s overview

The integration configures your Wazuh XDR deployment to process and trigger alerts for Lumu detections based on the level defined in the Wazuh detection rules. For detailed information about Wazuh Data analysis and rules capabilities, please refer to Wazuh Data Analysis and Wazuh rule classification.

Preliminary Setup - Prepare Wazuh for Lumu integration

To set up the integration, you must prepare your Wazuh deployment to communicate with the Lumu integration. To do this, you need to: 

1. Create a policy for the integration role
2. Create a role for the integration user
   
3. Create an integration user
4. Configure a Syslog listener or Syslog forwarding on a Wazuh agent
   

The following sections will guide you through the steps to perform each task. Follow them based on your Wazuh deployment: On-premises or Cloud. There are specific steps applicable for both types of deployments. Ensure you follow them entirely.

 The integration user is required to automatically load the decoders and rule definitions your Wazuh deployment needs to ingest Lumu events.

General preparation

The following steps apply to prepare Cloud and On-premise environments

Create a policy for the integration role (recommended)

It’s encouraged to create a dedicated policy for the integration user to avoid potential security risks

The integration needs a policy that allows the integration user to run some tasks on the Wazuh manager after setting up the decoders and rules. To do so, login to your Wazuh server and follow these steps:

1. Click on the hamburger icon in the top left corner of the screen. Then, expand the Server management section and click on the Security menu

2. Under the Policies tab in the Security screen, click on the Create policy button.

3. Fill in the required data for your new policy as follows:

Action	Resources
cluster:read	node:id:*
cluster:restart	node:id:*
manager:read	*:*:*
manager:restart	*:*:*

You can use the following image for guidance.

4. Create your policy by clicking on the Create policy button

Create a role for the integration user (recommended)

It’s encouraged to create a dedicated rule for the integration user to avoid potential security risks

Now it’s time to create a tailored role for the integration and link the created policy to it. To create the integration role, go to the Security screen by following the steps in the previous section. There, follow these steps:

1. Under the Roles tab in the Security screen, click on the Create role button.

2. Fill in the required data for your new role following the next example:

Role name	lumu_integration
Policies:	decoders_read_decoders decoders_all_resourceless rules_read_rules rules_all_resourceless manager_integration

You can use the following image for guidance.

3. Create your role by clicking the Create role button

On-premise deployment preparation

These steps apply to 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

A Wazuh API user is required for the integration to set up your on-premise environment to process Lumu detections. To create it, go to the Security screen by following the steps in the previous section. Then follow these steps:

1. Under the Users tab in the Security screen, click on the Create user button

2. Fill in the data for your new user. Make sure you assign the lumu_integration role created before.

3. Create your user by clicking on the Apply button

Collect the integration username and password. These will be used later to configure the integration.

Configure Syslog listener on the Wazuh server

Follow the Configuring syslog on the Wazuh server document to configure it.

Please ensure that the configuration is specifically set to use the TCP syslog protocol.

Cloud deployment preparation

These steps apply for Wazuh Cloud deployments.

Create an integration user for Cloud deployment (recommended)

Ensure 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 must create an internal user and map it to the created role. First, let’s create the internal user. To do it, follow these steps:

1. Click on the Security menu under the Indexer Management section.

2. In the Security window, click on the Internal users option in the left menu. Then click on the Create internal user button.

3. Fill in the Username and Password fields. Other fields are optional. Click on the Create button.

Collect the username and password. These will be used to set up the integration later.

1. Click on the hamburger icon in the top left corner of the screen. Then, expand the Server management section and click on the Security menu

2. In the Security window, click on the Roles mapping tab. Then click on the Create Role mapping button

3. Fill in the information in the Create new role mapping window. Make sure you select the lumu_integration role under the Roles field. Under the Internal users field, select the internal user created before.

4. Click on the Save role mapping buton to create your new mapping.

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.

Preliminary setup - Lumu portal

You must  collect the following information from the 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.

Preliminary Setup - Docker-enabled host

Follow the steps below if your integration host does not have Docker installed. 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.

During the configuration process, you will be prompted to define values for the following parameters:

1. rule_level_new_incident: The specific severity level designated for alerts originating from newly detected Lumu incidents.
2. rule_level_updated_incident: The specific severity level designated for alerts triggered by modifications or updates to existing incidents.
3. rule_level_operational_event: The specific severity level designated for alerts produced by system-level or operational Lumu events.
   

Adjusting these configurations will allow you to set the relevance given by Wazuh to each Lumu event.

Deploy the integration

Set up the Management Script

Lumu provides a short script to manage your integration. On your integration host, create a file named manage.sh and paste the following code: 

Code Snippet

#!/usr/bin/env bash

RED='\033[0;31m'

GREEN='\033[0;32m'

CYAN='\033[0;36m'

YELLOW='\033[1;33m'

BOLD='\033[1m'

RESET='\033[0m'

info()    { echo -e "${CYAN}[INFO]${RESET}  $*"; }

success() { echo -e "${GREEN}[OK]${RESET}    $*"; }

warn()    { echo -e "${YELLOW}[WARN]${RESET}  $*"; }

error()   { echo -e "${RED}[ERROR]${RESET} $*" >&2; }

prompt()  { echo -e "${BOLD}${YELLOW}$*${RESET}"; }

IMG=lumutools/wazuh-xdr:latest

INTEGRATION_NAME=lumu-wazuh-xdr

INTEGRATION_DIR=${HOME}/WazuhXDR

VOLUME_DATA=${INTEGRATION_DIR}/data:/app/data

VOLUME_CONFIG=${INTEGRATION_DIR}/data/.config.toml:/app/.config.toml:ro

mkdir -p "${INTEGRATION_DIR}/data"

chmod -R o+w "${INTEGRATION_DIR}/data" > /dev/null 2>&1

run_config() {

    info "Running configuration script ..."

    if docker run --rm -it -v "${INTEGRATION_DIR}/data:/app/data" "${IMG}" bash run_config; then

        success "Configuration completed."

    else

        error "Configuration script failed."; return 1

    fi

}

start_integration() {

    if [[ ! -f "${INTEGRATION_DIR}/data/.config.toml" ]]; then

        error "Please configure the integration first."; return 1

    fi

    info "Setting up integration '${INTEGRATION_NAME}' ..."

    if ! docker container inspect "${INTEGRATION_NAME}" &>/dev/null; then

        info "Integration '${INTEGRATION_NAME}' does not exist. Creating ..."

        if ! docker create \

            -v "${VOLUME_DATA}" \

            -v "${VOLUME_CONFIG}" \

            --restart unless-stopped \

            --log-driver json-file \

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

            --log-opt max-file=3 \

            --name "${INTEGRATION_NAME}" \

            "${IMG}" bash run_component; then

            error "Failed to create integration."; return 1

        fi

    else

        warn "Integration '${INTEGRATION_NAME}' already exists. Skipping create."

    fi

    if docker start "${INTEGRATION_NAME}"; then

        success "Integration started."

    else

        error "Failed to start integration."; return 1

    fi

}

check_status() {

    info "Checking status of integrations ..."

    if [[ ! -f "${INTEGRATION_DIR}/data/.status.ndjson" ]]; then

        error "Status check failed. Verify if your integration has been deployed."; return 1

    fi

    if docker run --rm -it -v "${VOLUME_DATA}":ro "${IMG}" bash run_status; then

        success "Status check completed."

    else

        error "Status check failed."; return 1

    fi

}

show_logs() {

    info "Showing logs for '${INTEGRATION_NAME}' ..."

    docker logs --tail 100 -f "${INTEGRATION_NAME}"

}

usage() {

    echo ""

    prompt "  WAZUH INTEGRATION MANAGEMENT"

    echo -e "  ${BOLD}Usage:${RESET} $0 <command>"

    echo ""

    echo -e "  ${CYAN}config${RESET}   Run configuration"

    echo -e "  ${CYAN}start${RESET}    Start integration"

    echo -e "  ${CYAN}status${RESET}   Check integration status"

    echo -e "  ${CYAN}logs${RESET}     Show integration logs"

    echo ""

}

case "${1}" in

    config) run_config ;;

    start)  start_integration ;;

    status) check_status ;;

    logs)   show_logs ;;

    *)      usage

            [[ -n "${1}" ]] && error "Unknown command '${1}'."

            exit 1 ;;

esac

Using the Management Script

With the management script, you can:

1. Configure the integration.

2. Start the integration.

3. Check the status of the integration.

4. Check the audit logs of the integration.

You can check these options by running the following command:

bash manage.sh

When running the configuration options, a wizard will guide you through a series of prompts. If the provided credentials are correct, the wizard will confirm this. If the credentials fail, you will receive an error message and have the option to re-enter the credentials or proceed despite the error.

Set up the configuration parameters

Execute the following command and type in all parameters gathered during the Preliminary Setup of the third-party solution. Fix any errors in your inputs if prompted.

bash manage.sh config

We strongly recommend correcting any credential errors before attempting to start the integration using the start command.

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

Run the Integration

Run the integration by running this command:

bash manage.sh start

If you have run this process previously, you may see warnings indicating that components already exist. To ensure you are running the latest version, we recommend removing any existing integration containers before selecting the start options.

Check the integration status

The integration is now active. Run the following command to check its current status 

bash manage.sh status

For additional debugging or information, you can execute the relevant Docker commands detailed in the troubleshooting section of this document.

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.

Show Logs

This command allows you to view the integration's logs.

bash manage.sh 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

Here, you will find additional commands to run additional diagnostics if they are needed.

1. Stopping the integration
   
   Run the following command if you need to stop the integration.
   
   docker stop lumu-wazuh-xdr

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

docker start lumu-wazuh-xdr

Known Issues

This section outlines common issues you may encounter after running the troubleshooting commands above.

Docker Permission Execution

If you encounter a docker: permission denied while trying to connect to the Docker daemon socket error while building the integration, refer to the official Docker post-installation steps to resolve it: Docker Post-Installation Guide.

Network Connection Issues

Logs indicating a connection problem often contain keywords such as timeout or connection error. These terms point to an underlying network issue and should prompt an immediate check of your network and internet connectivity.