This article shows how to leverage the Lumu Defender API and the Ubiquiti Unifi Cloud Gateway features to mitigate security risks.

Requirements

• Ubiquiti Unifi Cloud Gateway
  
  • You need a Ubiquiti Unifi Cloud Gateway with administrative access to the Network application on 9.0.114 version or above.
    
• 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 your Ubiquiti Unifi device. According to the deployment model you select, you will need a host with:
    • Python 3.12+
      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

• Lumu services
  • defender.lumu.io (HTTPS and WSS traffic)
• Ubiquiti Unifi Cloud Gateway devices
  • The integration must be able to connect to the Unifi device via HTTPS

Integration overview

The integration uses Unifi Traffic rules to block outbound traffic related to Lumu-detected adversarial contacts. It manages a rule per IOC type, IP addresses, and Domains, updating them based on Lumu-reported detections and updates.

Preliminary Setup - Ubiquiti Unifi Cloud Gateway

• Create a dedicated integration role for managing the Unifi Network application (optional, but recommended).
• Create a dedicated integration local user attached to the integration rule (optional, but recommended).
• Ensure network visibility between the integration host and the Ubiquiti Unifi Cloud gateway devices.

• Use the Unifi Site Manager.
• Log in to the Network application directly on the Unifi device.

1. Open your Web browser and access the Unifi Site Manager. Log in if the Site Manager requests it.

2. In the Site Manager window, look for the site where your Unifi devices are attached to, then, click on the site.

3. Now, you are on the Network application.

Create a dedicated integration role

We encourage you to create a dedicated integration role with only the required permissions to ensure the least privilege principle in your Unifi devices.

1. Head to the left navigation bar and look for the Settings button (the Gear icon). Click on it.

2. Head to the Settings navigation bar on the left. Click on the Admin & Users menu.

3. In the Admins window, click the Manage Roles(1) button next to the search bar. The Manage Roles section will appear on the right side of the Window. Click on the Create New Role(2) menu to create your integration role.

4. Create your integration role by following these guidelines:

a. Enter a distinctive Role Name(1).

b. Select the Permissions(2) for each application. Ensure that the Network application has Full Management selected. The rest of the applications must be set to None.

c. When finished, save your integration role by clicking on the Create button.

Create a dedicated integration user

We encourage you to create a dedicated integration user with the integration role created above. This will aid you in preserving the least privilege principle and trace all activities performed by the integration.

1. Click on the Create New Admin button located next to the search bar.

2. Fill in the information in the Create New Admin section on the right side of the window. Follow these guidelines:

a. Type your integration Username(1)

b. Give your integration user a secure Password(2)

c. Ensure the Restrict to Local Access Only(3) toggle is enabled.

d. Enable the Use a Predefined Role(4) toggle and

e. Select the Role(5) you created in the Create a dedicated integration role section.

e. When you are ready, save your integration user by clicking the Create(6) button.

The integration operates with local users instead of Unifi Accounts.

Ensure you store your integration user credentials in a safe place. This information will be needed to configure your integration.

Ensure network visibility between the integration host and the Ubiquiti Unifi Cloud gateway devices

Ensure the device you will use to deploy the integration can reach the Ubiquiti Unifi devices you want to integrate. In case you need changes in your network to allow communications between the integration components, contact your network administrator.

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

• Run it as a Python script executing the install.sh bash file
  • Creates a Python virtual run time and its dependencies for you
  • Installs the crontab line in the host
• Run it as a Docker container.

If you use the install script, use the uninstall.sh bash file to remove the integration from the host

Prepare your integration environment

• Run your integration on Python
• Run your integration on Docker

Prepare Python on your environment

If Docker is your chosen deployment method, you may skip this step.

Prepare Docker on your environment

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

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

Set up the configuration files

• companies.yml: this file contains the information collected from the Lumu portal.
• integrations.yml: this file contains the information collected from your Ubiquiti Unifi device.

Inside the integration package, you will find sample files you can use to build your configuration files. These files are companies_template.yml and integration_template.yml.

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: "sha1" # Supported hash types: sha256, sha1, md5
    ioc_types: # Supported IOC types: ip, domain, url, hash. Select one, multiple, or all of them
      - ip
      - domain
      - url
      - hash
    adversary: # Supported adversary types: C2C, Malware, Mining, Spam, Phishing, Anonymizer. Select one, multiple, or all of them
      - C2C
      - Malware
      - Mining
      - Spam
      - Phishing
      - Anonymizer
    days: 3 # Min 1, max 3
-
  COMPANY 2
-
  COMPANY 3
-
  ...

Within this file, COMPANY_UUID and DEFENDER_API_KEY fields are mandatory. Please use the values captured in the previous steps. The ioc_types values must match the IOC types required by the integration, in this case, ip and domain.

Complete the integrations file

The integrations file contains the information required for the integration to connect and interact with your Ubiquiti Unifi Cloud Gateway devices:

- lumu:
    uuid: "COMPANY_UUID"
    adversary: # Supported adversary types: C2C, Malware, Mining, Spam, Phishing, Anonymizer. Select one, multiple, or all
      - C2C
      - Malware
      - Mining
      - Spam
      - Phishing
      - Anonymizer
    days: 3 # Number of days to collect adversary data from the IOC Manager
  app:
    name: "INTEGRATION_NAME"
    clean: false # Flag used if you want to revert all changes made by the integration component. Supported values are true or false
    ioc_types: # Supported IOC types: ip, domain. Select one, multiple, or all of them
      - ip
      - domain
    api:
      username: UNIFI_USERNAME
      password: UNIFI_PASSWORD
      host: UNIFI_IP_OR_HOSTNAME
      site: UNIFI_SITE_NAME # Site name. If not defined, the integration will use "default"

• COMPANY_UUID with the Company UUID given in the Complete the companies file section.
  
• INTEGRATION_NAME with a distinctive name for the integration. We recommend using the customer name here. If you have multiple Unifi devices, use a unique name related to the device, for example, Customer S.A. - Main datacenter.
• UNIFI_USERNAME with the username created in the Create a dedicated integration user section.
• UNIFI_PASSWORD with the password given to the user created in the Create a dedicated integration user section.
• UNIFI_IP_OR_HOSTNAME with the IP address or the hostname of your Unifi device. If you use a hostname, ensure your integration device can resolve this value to its IP address.
• UNIFI_SITE_NAME with your Unifi deployment assigned site. If you are not sure, use default as its value.

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

Deploy Integration as Python script

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

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 on the path selected for deployment (<app_lumu_root>). Use the following command to show all options available for the package:

Usage: run [-h] [--config CONFIG] [--ioc-manager-db-path IOC_MANAGER_DB_PATH] [-v] [-l {screen,file}] [--hours HOURS]

Usage Examples

• Task: query IOCs related to Lumu incidents with default options

To query all ip addresses and domains 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 from your Ubiquiti Unifi Cloud Gateway device, just set up the clean flag in the integrations.yml file to true.

Then, run the integration script as follows:

The Traffic rules created and managed by the integration will be permanently deleted.

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

Troubleshooting

For troubleshooting purposes, you can run the following commands:

To log in to your container using an interactive shell:

To collect integration logs:

Expected results

• Lumu IOCs (IPs)
• Lumu IOCs (Domains)

1. Head to the left navigation bar. Click on the Settings menu (the Gear icon).

2. Head to the Settings navigation bar. Click on the Security menu.

3. The Lumu rules are listed under the Traffic & Firewall Rules window. Ensure the Simple option and the All toggle are enabled.

The integration will set the rules to block outbound traffic from all sources behind the Firewall to the added destinations.

Troubleshooting and known issues

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.

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.

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.