Learn how to leverage the Lumu Defender API and the Zero Network Segmentation API to proactively reduce your organization's exposure to threats and strengthen security.

Response integration between Zero Networks and Lumu

Requirements

• An active Zero Networks subscription
  • A Zero Networks subscription with the Network segmentation module.
  • A Zero Networks administrator user.
• 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 Zero Networks public services. According to the deployment model you select, you will need a host with:
    • Python 3.13+
      or
    • A Docker-enabled host.
• Script package
  • Contact the Lumu support team to request the package we created to deploy the required files.

Contacted hosts

Ensure your script host can communicate with the following hosts. These are required for the operation of this integration.

• portal.zeronetworks.com
• defender.lumu.io
• docker.io
• ghcr.io
• *.ubuntu.com
• *.launchpad.net
• canonical.com
• debian.org
• *.debian.org
• debian-security.org
• pypi.python.org
• pypi.org
• pythonhosted.org
• files.pythonhosted.org

Preliminary setup - Zero Networks

To set up the integration, you must prepare your Zero Networks instance to communicate with the Lumu integration. To do this, you need the following:

• Create an API Token.
• Identify and extract the source name for the outbound rule.

The following sections will guide you through these tasks.

Create an API token

You must create a Full Access API token. This token enables the integration to utilize the Zero Networks API to execute the necessary queries and update the Lumu Indicators into the Outbound Rule. To create it, log in to your Zero Networks portal, and follow these steps:

1. Click on the Settings (1) located in the left navigation menu.

2. Scroll down in the Settings navigation bar. Look for the Integrations section and click on API (1).

3. Click on Add new token (1) to create a new token.

4. Fill in the token details following these guidelines:

1. Enter a descriptive Token name (1).
2. Set Access type to Full Access (2).
3. Set the Expiry period (3). We encourage you to follow your organization's guidelines to set the expiration period. We recommend an expiration period no longer than 12 months.
4. When finished, click on Add (4) to create the token.
   
   
   
   
   Be aware of the expiration period configured for your token. To keep your integration working, you must regenerate it and replace it in your integration before it expires.

5. Copy the token secret and keep it at hand. It will be required to set up the integration during the Complete the integration file step

Identify and extract the source name for the outbound rule

You must collect the Source assets you want to cover with the integration outbound rule. These assets can be specified using predefined groups that cover most of the assets in your Zero Network deployment.

• All segmented assets: This group covers all segmented assets in your deployment.
• All segmented servers: This group covers all segmented servers in your deployment.
• All segmented clients: This group covers all segmented devices, different from servers, in your deployment.

We encourage you to use one of the groups above as the value for the source_assets field during the Complete the integration file step.

If you must narrow down source assets in your integration policy, log in to the Zero Networks console and follow these steps:

1. Click on the Entities (1) at the left navigation menu.

2. Select the required type of assets on the Entities navigation bar.

3. Identify the source asset, copy its name and save it for later. It will be needed during the Complete the integration file step.

Preliminary setup - 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 procedures to collect this data.

Collect the Lumu Defender API key

To collect the Lumu Defender API key, please 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 - Choose your integration environment

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

• Run it as a Python script (Unix-based systems and Windows)
• Run it as a Docker container.
  • By using the Makefile model (Unix-based systems)(Recommended).
  • By using Docker commands (Unix-based systems and Docker Desktop for Windows).

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

Prepare your integration environment

Before starting, ensure your integration environment can communicate with all the hosts listed in the Contacted hosts section.

You can deploy your integration using the following alternatives:

• Run your integration using Python
• Run your integration using Docker

Follow the instructions based on the selected deployment method.

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

Prepare Docker on your environment

If you chose Python as your deployment method, you may skip this step.

If Docker is your chosen deployment method, you must follow the Docker installation documentation that corresponds to your OS. Make sure you follow the Post-installation steps for Linux before deploying the integration.

Windows users can follow the Install Docker Desktop for Windows documentation to install the Docker Engine.

We encourage you to follow the Manage Docker as a non-root user documentation to implement best practices to operate Docker securely.

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 third-party console

You will find the companies_template.yml and integrations_template.yml sample files inside the integrations package. Use them to build your configuration files.

In the following sections, 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.

Complete the companies file

The companies file is in charge of defining how the integration connects to Lumu and extracts the information of the incidents and related indicators of compromise.

lumu:
  uuid: "COMPANY_UUID"
  defender_key: "DEFENDER_API_KEY"
  hash_type: "sha256" # sha256 | sha1 | md5
  ioc_types: # list of ioc types, option one, many or all
    - ip
    - domain
  adversary: # list of adversary types, option one, many or all
    - C2C
    - Malware
    - Mining
    - Spam
    - Phishing
    - Anonymizer
  days: 3 # MIN 1, MAX 30

Replace the highlighted placeholders as follows:

• COMPANY-UUID with the Company UUID collected in the Collect your Lumu company UUID section.
• DEFENDER-KEY with the Defender Key collected in the Collect the Lumu Defender API Key section.

Complete the integrations file

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

lumu:
  uuid: "COMPANY-UUID"
  days: 3
app:
  name: "UNIQUE-NAME"
  source_assets: "SOURCE-ASSETS-NAME"
  api:
    token: "JWT-TOKEN"

Replace the highlighted placeholders as follows:

• COMPANY-UUID with the Company UUID collected in the Collect your Lumu company UUID section.
• DEFENDER-KEY with the Defender Key collected in the Collect the Lumu Defender API Key section.
• UNIQUE-NAME with a distinctive name for the integration. We recommend using the customer's or Zero Networks tenant's name here.
• SOURCE-ASSETS-NAME with the asset name collected in the Identify and extract the source name for the outbound rule section. If you are using one of our recommended groups, this can be one of the following values:
  • source_assets: "All segmented assets"
  • source_assets: "All segmented servers"
  • source_assets: "All segmented clients"
• JWT-TOKEN with the API token collected in the Create an API Token section.

You must fill in the configuration data carefully. If there are any mistakes or missing data, you’ll receive errors. Please refer to the Known issues section at the end of this article for further reference.

Deploy as a Docker container via Makefile (Recommended)

To streamline the deployment process, Lumu introduced the Makefile model integration that allows you to easily deploy integrations as a Docker container. To deploy the integration, locate yourself in the <app_lumu_root> folder, and run the following command:

Please monitor the console output for any unexpected errors. Refer to the Troubleshooting section for further information.

Deploy as a Python script

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

Make sure the install.sh script has 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 configured 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

In some Python installations, the executable name could vary from python to python3. If any Python command shows an error, change the python string in the presented command by python3.

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: run.py [OPTIONS]

╭─ Options ───────────────────────────────────────────────────────────────────────────────────╮
│ --verbose              -v        Enable verbose mode.                                       │
│ --clean                          Clean all integrations and override the yml clean field.   │
│ --logging-type -l [screen|file]  Logging output type: 'screen' or 'file' [default: screen]  │
│ --config             TEXT        Path to the configuration file. [default: integrations.yml]│
│ --ioc-manager-db-path    TEXT    Path to the IOC manager database file. [default: ./ioc.db] │
│ --help                           Show this message and exit.                                │
╰─────────────────────────────────────────────────────────────────────────────────────────────╯

Usage examples

Task: query IOCs related to Lumu incidents with default options

To query all the indicators related to Lumu incidents triggered in the days defined in your configuration files, run the following command.

Task: Clean records

To clean the existing records in the third-party solution, just set up the clean flag in the integrations.yml file to true.

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 Python script via Makefile

To streamline the deployment process, Lumu introduced the Makefile model integration that allows you to easily deploy integrations as a Python script via Makefile. To deploy the integration, locate yourself in the <app_lumu_root> folder, and run the following command:

Please monitor the console output for any unexpected errors. Refer to the Troubleshooting section for further information.

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

1. To build the container, run the following command. Change all the flags based on the reference given in the script section above.

Do not forget the dot "."

2. To run the container, run the following command:

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

Expected results

After running the integration, you will see new IP addresses in the outbound network rule if there was any detection related to IP addresses.

You will also see the blocked connections in the Activities section of the Networks navigation menu of the Zero Networks console.

Troubleshooting

The commands defined in this section will allow you to troubleshoot the operation of your integration. Keep in mind that you must locate yourself in the <app_lumu_root> folder before running any of them.

Deployment as a Docker container via Makefile

The following are the troubleshooting commands for this deployment option:

• Checking integration logs

Run the following command to check your integrations logs:

You will obtain the following results.

• Checking integration errors

Run the following command to check errors in your integration.

• Check the status of the integration

Run the following command to check the status of the integration.

The command output will show the Docker container operational stats and running processes.

• Stopping the integration

Run the following command if you need to stop the integration.

• Starting the integration

Run the following command to start the integration.

• Fixing issues with sudo for Docker

If you cannot run Docker commands with your current user, run the following command.

• Reinstalling integration from scratch

Run the following command to reinstall the integration from scratch:

• Collecting and packaging logs for Lumu support

Run the following command to collect and package the integration logs to share them with the Lumu support team. This command will create the support.tar package file that contains relevant information for the Lumu support team.

Deployment as a Python Script

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 the lumu.log file. The file errors.log stores only the errors to make them easier to find and aid the troubleshooting process.

Deployment as a Python Script via Makefile

The following are the troubleshooting commands for this deployment option:

• Checking your integration logs

Run the following command to check your integrations logs:

• Checking integration errors

Run the following command to check errors in your integration.

• Check the status of the integration

Run the following command to check the status of the integration, showing the running processes.

• Restart the integration

Run the following command if you need to restart the integration.

• Uninstall the integration

Run the following command to stop the integration and undo the installation.

• Collect and package logs for Lumu support

Run the following command to collect and package the integration logs to share them with the Lumu support team. This command will create the support.tar package file. This package contains relevant information for the Lumu support team.

Deployment as a Docker container

For troubleshooting purposes, you can run the following commands to:

• Logging in to the container using an interactive shell

• Collect integration logs

Known issues

In this section, we collect all the potential issues you will find after you run the troubleshooting commands from the above section.

Input Validation

If you receive the following error:

It means you are using the wrong key parameters or values. Review your configuration files and run the integration again.

Authentication Failed

Check your API key if you get a log message like this.

Network Connection Problems

Check the network connectivity of your scripting host if you get a log message like this.

Conflict error

If you get a log message like this, check if you have another integration running. Make sure you delete the Lumu outbound rule in Zero Networks before creating a new integration instance.

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.