This article shows how to leverage the Lumu Defender API and Guardicore API to mitigate security risks.

Response integration between Guardcore and Lumu

Requirements

• An active Guardicore Centra subscription
  • A Guardicore 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 Guardicore 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.

• Guardicore Instance Server
• 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’s custom response integration uses Guardicore’s API to manage a policy rule linked to a ruleset. The integration updates the destination IPs of the rule based on Lumu’s detections to block further outbound connections within your Guardicore deployment.

Preliminary setup - Guardicore

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

• Create a Custom Permission Scheme
• Create an Integration user
• Create a Policy rule and link it to a unique ruleset.

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

Create a Custom Permission Scheme

We recommend creating a custom permission scheme that grants the integration user only the minimal access required to perform its tasks. This allows you to follow the principle of least privilege for your integration user. To create the integration custom permission scheme, log in to your Guardicore console and follow these steps:

1. Enter a distinctive Title.
2. Optionally, enter a Description.
3. Define the associated Role, and configure its specific Permissions/Scope.
   • Select the Application Owner role for the Edit rule scope.
   • Select the Application Administrator role for the Edit and publish scope.
     
   • When finished, click Save.
     

Create an integration user

We encourage you to create an integration user and assign the custom Permission Scheme created in the previous step. This will preserve the least privilege principle and allows you to track the integration activities. To create your integration user, log in to your Guardicore console and follow these steps:

1. Head to the left navigation bar. Expand System (1) and click Users (2) under the USER MANAGEMENT section.

1. Enter a distinctive Username.
2. Enter the user’s Email Address.
3. Optionally, enter the user Description.
4. Select the Permission Scheme created in the previous step.
5. When finished, click Save.
   

4. You will receive an activation email. Follow the instructions given to activate your user and set its password. Keep the username and password at hand. These will be required to configure the integration.

Create a Policy Rule and link it to a unique ruleset

You must create a policy rule linked to a unique ruleset for the integration. To do so, log in to your Guardicore console and follow these steps:

1. Set the Source to the set of devices you want to protect.
2. Set the Destination to the Lumu Canary IP 3.89.191.115/32.
3. Set the Ports/Protocols to cover all communication ports.
4. Set the Action to Block.
5. Enter a unique Ruleset name. Keep it at hand, it will be required to configure the integration.
6. When finished, save your integration policy rule.

We recommend using a unique ruleset on each deployment. Contact Lumu support team if you have more than one rule linked to a Ruleset

4. Publish your rule changes by selecting your new rule and clicking on Publish (1).

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 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. 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 Guardicore policy.

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 file contains the information required for the integration to connect and interact with your Guardicore deployment:

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

app:
  name: "UNIQUE-NAME"
  rule_set: "RULE-SET-NAME" # Case Sensitive, e.g. "LumuClientARuleSet"

api:
  url_management_server: "URL-MANAGEMENT-SERVER" # "https://Hostname|FQDN|IPAddress[:Port]/"
  username: "USERNAME"
  password: "PASSWORD"

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 Guardicore tenant’s name.
• RULE-SET-NAME with the Rule set name collected in the Create a Policy Rule and link it to a unique ruleset section.
• URL-MANAGEMENT-SERVER with the URL of your Guardicore Management Server.
• USERNAME with the username of the user created in the API token collected in the Create an integration user section.
• PASSWORD with the password of the user created in the API token collected in the Create an integration user 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 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:

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

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:

./install.sh all

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 crob 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:

python run.py --help

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.                                │
╰─────────────────────────────────────────────────────────────────────────────────────────────────╯

Options	Description
-h, --help	Show this help message and exit
--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]
--logging-type -l [screen|file]	Logging output type: 'screen' or 'file' [default: screen]
--verbose -v	Enable verbose mode.
--clean	Clean all integrations and override the yml clean field.

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.

python3 run.py

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.

python3 run.py –clean

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

CONSOLE:docker build \
--tag img-lumu-guardicore-response \
--file DockerfileAllInOne .

Do not forget the dot "."

2. Run the container by using the following command.

docker run -d \
-v ./companies.yml:/app/companies.yml \
-v ./integrations.yml:/app/integrations.yml \
--restart unless-stopped \
--log-driver json-file \
--log-opt max-size=30m \
--log-opt max-file=3 \
--name lumu-guardicore-response \
img-lumu-guardicore-response

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

Expected results

After running the integration, you will see your new integration rule under the Policy Rules window. You will see new IP addresses reported in the Destination column of the rule if Lumu has reported any IP-related detections.

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.

make docker-logs

• 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

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

The following are the troubleshooting commands for this deployment option:

• Checking integration logs
  Run the following command to check your integration logs.

make sh-logs

• Checking integration errors
  Run the following command to check errors in your integration.

make sh-errors

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

make sh-ps

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

make sh-restart-all

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

make sh-uninstall-all

• 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 sh-support

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

docker exec -it lumu-guardicore-response bash

• Collecting integration logs

docker logs -f lumu-guardicore-response

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

If you get an error like this

You may have more than one integration running with the same ruleset. Modify the ruleset in your integration rule and in your integration configuration to fix this. Ask Lumu support if you need to preserve this behavior.

Another instance is running

If you receive the following error.

Stopping the integration 39, it might have another older instance running, check if is feasible or not

older pid: 25 - cwd: /app - since: 2024-10-04 14:50:01.560000

cmdline: /usr/local/bin/python3 /app/run.py

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.