Learn how to enhance the detection & response capabilities of your organization by integrating Zero Networks with Lumu’s data collection capabilities to pull, transform and inject the activity network logs recorded by Zero Networks into Lumu.

Requirements

• An active Zero Networks subscription
  • A Zero Networks subscription with the Network segmentation module.
  • A Zero Networks administrator user.
• Lumu Custom Collector API configuration for firewall logs.
  • A Lumu custom collector ID and client key are required to set up the collection process. Create a custom firewall collector by following the directions given in Manage Custom Collectors.
• Script host.
  • A scripting host is required to deploy the integration. This host must have Internet visibility over the Lumu Custom Collector API and the Zero Networks API endpoints. Depending on your deployment model, the host must have:
    • 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, as they are required for the operation of this integration.

• portal.zeronetworks.com
• api.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 Lumu by generating an API token.

Create a Read-only API Token

This token allows the integration to use the Zero Networks API to run the required queries to collect the activity records and process them as firewall metadata.

To create it, log in to your Zero Networks portal and follow these steps:

1. Click on 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 the Access type to Read only (2).
3. Set the Expiry period (3). We encourage you to follow your organization's guidelines to set the expiration period. We recommend that you set a 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.

Preliminary setup - Lumu Portal

The integration set-up process needs you to collect this information from Lumu Portal:

• Lumu Collector Key
• Lumu Collector ID
• Company UUID

Log in to your Lumu Portal and run the following procedures to collect this data.

Collect your Lumu Collector Key

To collect the Lumu Collector key, please refer to the Collector key document.

Collect your Lumu Collector ID

To collect the Lumu Custom Collector key, please refer to the Collector ID 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 of this article.

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. Make sure 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. 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.

Set up the configuration files

Add the integrations.yml configuration file in the <app_lumu_root> folder and edit it as instructed to set up the integration.

You will find the integrations_template.yml sample file inside the integrations package. Use it to build your configuration file.

The integrations.yml file contains the information required by the integration to collect the network activity data from Zero Networks, transform it, and send it to the Lumu Cloud.

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"
  collector_key: "COLLECTOR-KEY"
  collector_id: "COLLECTOR-ID"
app:
  name: "UNIQUE-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.
  
• COLLECTOR-KEY with the Collector Key collected in the Collect your Lumu Collector Key section.
• COLLECTOR-ID with the Collector ID collected in the Collect your Lumu Collector ID section.
• UNIQUE-NAME with a distinctive name for the integration. We recommend using the customer's or Zero Networks tenant's name here.
• JWT-TOKEN with the API token collected in the Preliminary Setup - Zero Networks section.

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

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:

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.

Deploy Integration as a Python script

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 to python3.

We encourage you to create a Python environment to deploy the integration as a Python script. You will find specific instructions in the Create a Virtual Environment document. Install the required dependencies by running the following commands:

• For Windows environments:

First run

Then, run

• For Unix-based environments:

First run

Then, run

Replace the ENV_FOLDER placeholder with the name of your virtual environment.

Script details

To use the script, you must locate yourself in the <app_lumu_root> folder. Use the following command to show all options available for the package: 

Usage: run.py [OPTIONS]

╭─ Options ─────────────────────────────────────────────────────────────────────────────────╮

│ --verbose -v Enable verbose mode. │

│ --logging-type -l [screen|file] Logging output type: 'screen' or 'file' [default: screen]│

│ --config TEXT Path to the configuration file. [default: integrations.yml] │

│ --help Show this message and exit. │

╰───────────────────────────────────────────────────────────────────────────────────────────╯

Usage Examples

Task: poll and inject Zero Networks logs into Lumu

Run the following command to poll all the Zero Networks logs and push them into Lumu’s custom data collector.

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 <package-path> 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.

docker build --tag img-zero-networks-collection --file Dockerfile .

Do not forget the dot "." at the end of the line

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

docker run -v ./integrations.yml:/app/integrations.yml -v ./dead_letters:/app/dead_letters -d --restart unless-stopped --log-driver json-file --log-opt max-size=30m --log-opt max-file=3 --name lumu-zero-networks-collection img-zero-networks-collection

Expected results

After you configure the integration, you will see the processed events in the custom collector created in Lumu Portal. Lumu will process events from 10 minutes previous to the integration activation time.

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:

make docker-logs

You will obtain the following results.

• Checking integration errors

Run the following command to check errors in your integration.

make docker-errors

• Check the status of the integration

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

make docker-ps

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.

make docker-stop

• Starting the integration

Run the following command to start the integration.

make docker-start

• Fixing issues with sudo for Docker

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

make docker-fix-sudo

• Reinstalling integration from scratch

Run the following command to reinstall the integration from scratch:

docker-reset-force

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

make docker-support

Deployment as a Python script

To identify failures in the script, please use the -v flag. This will allow you to identify failures in the script execution.

Deployment as a Docker container

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

• Logging in to the container using an interactive shell

docker exec -it lumu-zero-networks-collection

• Collecting integration logs

docker logs -f lumu-zero-networks-collection