Learn how to leverage the Lumu Defender API and Illumio API to mitigate security risks.

Response integration between Illumio and Lumu

Requirements

• An active Illumio Segmentation subscription.
  • You need an Illumio administrator user to set up the integration.
• 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 Illumio 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. They are required for the operation of this integration.

• console.illum.io
• 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

Integration overview

Lumu Custom response integration with Illumio uses its API to manage an IP list. The integration manages IPs reported by Lumu as confirmed risks to avoid further contacts. The integration’s IP list must be set as a Destination in an Override Deny rule.

Preliminary Setup - Illumio

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

• Create a dedicated integration user
• Create an API Key

The following sections will guide you on how to perform these tasks.

Create a dedicated integration user

We encourage you to create a dedicated Illumio integration user. It allows you to segregate and trace activities beyond the regular administration tasks. To create your new integration user, log in to your Illumio console and follow these steps:

1. Go to Access (1) in the left navigation menu, and click on Users (2).

<

2. In the Users window, click on Add (1).

3. Fill in the New User information following these guidelines:

1. Type in the First and Last Name.
2. Type in a valid Email.
3. Assign the Admin role to the user (1).
4. When finished, click on Add (2).
   
   

4. You will receive an account activation email. Activate your new integration user by following the instructions given in the Illumio activation email. Keep the credentials at hand, they will be used during the Set up the configuration files step.

Create an API Token

You must create an API key. This credential allows the integration to use the Illumio API to manage the Illumio IP list by updating it with Lumu IPs. To create it, log in to your Illumio portal with your integration user and follow these steps:

1. Open the profile menu (1) in the top-right corner of the screen. Then click on My API Keys (2) from the list.

2. In the API Keys window, copy the listed API Endpoint (1) and Organization ID (2) values and keep them at hand, they will be used during the Set up the configuration files step. Finally, click on Add (3).

3. Fill in the Create API Key form. Give the key a distinctive Name. Optionally, give it a Description. When finished, click on Create (1).

4. Copy the API key information. Alternatively, click on Download Credentials (1) to download the API credentials into a text file (.txt). Save them for later, they will be used during the Set up the configuration files 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 these 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 executing the install.sh bash file (Unix-based systems and Windows)
  • Creates a Python virtual environment and its dependencies for you
  • Installs the crontab line in the host
• 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 need to first 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 the all 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. 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 companies.yml and the integrations.yml configuration files in the <app_lumu_root> folder and edit them as instructed to set up the integration.

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

Complete the companies file

The companies.yml file contains the information required by the integration to collect the Lumu-related IOCs and make them available for their injection in the Illumio IP List.

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

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.

Complete the integrations file

The integrations.yml file contains the information required by the integration to manage Lumu-related IOCs into the Illumio IP List.

lumu:
  uuid: "COMPANY-UUID"
  days: 3

app:
  name: "UNIQUE-NAME"
  api:
    api_endpoint: "API-ENDPOINT" # https://us-scp41.illum.io/api/v2/
    username: "USERNAME"
    secret: "SECRET"
    organization_id: "ORGANIZATION-ID"

Replace the highlighted placeholders as follows:

• COMPANY-UUID with the Company UUID collected in the Collect your Lumu company UUID section.
• UNIQUE-NAME with a distinctive name for the integration. We recommend using the customer's or Illumio tenant’s name.
• API-ENDPOINT with the API Endpoint collected in the Create an API Token section. Delete the <resource> part at the end of the string if present. The value should look as follows:

api_endpoint: "https://us-scp41.illum.io/api/v2/"

• USERNAME with the username of the user created in the API token collected in the Create an API Token section.
• SECRET with the secret of the user created in the API token collected in the Create an API Token section.
• ORGANIZATION-ID with the organization ID 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 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 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. 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. If issues arise, refer to the Troubleshooting section or attempt to address them accordingly.

Deploy as a Python script

To streamline the deployment process of the integration as a Python script, you can run the install.sh script. To deploy the integration, locate yourself in the <app_lumu_root> folder, and run the following command:

Make sure the install.sh script has the execution permission before running it.

The installation script will set up the Python environment and two different cron jobs.

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, respectively.

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

1. Build the container by running the following command.

Do not forget the dot "."

2. Run the container by using the following command.

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

Add the integration IP list to an Override Deny rule

You must use the integration IP list inside a policy rule. Create or update an existing Override deny rule, adding the integration list to the destination section. When you are done, your Override Deny rule must look as follows.

Please refer to the Illumio How to Create Policy document for further reference.

Expected results

After running the integration, you will see the new Integration IP List under the IP Lists menu in the Policies > Policy Objects section.

You can see the contents of the IP list by clicking on it. All Lumu-related IP IOCs will be contained in this list.

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

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

The following are the troubleshooting commands for this deployment option:

• Checking integration logs
  Run the following command to check your integration 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.

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

• Uninstalling the integration
  Run the following command to uninstall the integration.

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

• Logging in to the container using an interactive shell

• Collecting integration logs

Known issues

Input Validation

If you receive errors like this:

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

Authentication Failed

You will get the following error when the authentication fails.

Network Connection Problems

You will get the following error when there are connectivity issues.

Conflict error

There might be previous integration still running. If this is the newest instance, you should remove the others that are causing the conflict.

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.