This article shows how to leverage Azure Virtual Networks REST API and Lumu Defender API to enhance your Response capabilities.

Response integration between Azure and Lumu

Requirements

• An Azure subscription with Compute services deployed.
  • An Azure Global admin user must be used to configure 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 Azure Cloud. According to the deployment model you select, you will need a host with:
    • Python 3.10
      or
    • A Docker-enabled host.

Contacted hosts

Allow all the traffic to the following hosts. These are required for the operation of this integration:

• Azure Cloud Endpoints
• Microsoft Authentication Endpoints
• defender.lumu.io

Integration’s overview

The integration leverages the following Azure services to block malicious contacts:

• Network Security Groups Outbound Security Rules for IP adversaries.
• Azure Firewall Policies for domain adversaries.

Azure Firewall is an additional subscription. You need a Standard or above tier level to work with domain IOCs. If you already have a Third-party service deployed to protect your traffic, we encourage you to review our list of response integrations. Implement the one that fits your environment.

If you use Azure Firewall, ensure it’s configured as the default gateway for the networks and workloads you want to protect.

For each rule type, Azure defines the following limits:

• Up to 100 IP entries per security rule.

• Up to 1000 domains per Azure Firewall policy

Collect the required data from Lumu portal

• Lumu Defender API key
• Company UUID

Log in to your Lumu portal and run the following data collection procedures.

Collect the Lumu Defender API key

To collect the Lumu Defender API key, 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.

Deploy the integration

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
  • Creates a Python virtual run time and its dependencies for you
  • Installs the crontab line in the host
• Run it as a Docker container.

Whichever alternative you select, you must first unpack the integration package shared by our Support team.

Unpack the deployment package provided by Lumu in your preferred path/folder. Bear 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>.

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

Prepare Python on your environment

You must create a Virtual environment to run the Azure setup script. Follow the steps in our Preparing Environment for Custom Integrations article.

Run the Azure setup script

You need an Azure Global administrator user to run the Azure setup script inside the integration package.

Inside the integration package, you will find the azure_setup.py file. This file will help you to configure your Azure deployment to operate with your Network Security Groups and your Azure Firewall rules, if applicable. Run the setup script by executing the following command.

You will be asked to authenticate with the Global administrator user through your browser and a code.

Open the page shown in the console message. Then, copy and paste the authentication code provided. The code is highlighted in a red square in the previous image for reference.

The authentication process will ask you to grant permissions to Azure CLI. Grant them to continue running the setup script.

After you authenticate, the setup script will continue. Follow the on-screen instructions. The process will ask you to select information based on your Azure environment. From this configuration, you will have a base configuration file (integrations.yml) based on your selections. Review it, and edit the uuid and name fields accordingly.

If you don’t have Azure Firewall, just type N when the Azure setup script asks you to configure this feature.

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

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.

Complete the companies file

The companies file defines how the integration connects to Lumu and extracts the information of the incidents and related indicators of compromise.

-
  lumu:
    uuid: "<COMPANY-UUID>"
    [name: "<COMPANY-NAME>"]
    [contact_name: "<CONTACT_NAME>"]
    [contact_email: "<CONTACT_EMAIL>"]
    defender_key: "<DEFENDER_API_KEY>"
    hash_type: "<HASH_ALG>" # sha256 | sha1 | md5
    ioc_types: # list of ioc types, option one, many or all
      - ip
      - domain
      - url
      - hash
    adversary:  # list of adversary types, option one, many or all
      - C2C
      - Malware
      - Mining
      - Spam
      - Phishing
    days: 30 # MIN 1, MAX 30

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

Complete the integrations file

The Azure setup script generates this file. Review it and modify it accordingly.

The NetworkACL.Name parameter must be a list of a maximum of 15 string elements (the Name or ID of each NACL).

Deploy Integration as script

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

Make sure the install.sh script has the 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 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: azure_lumu [-h] [--config CONFIG] [--ioc-manager-db-path IOC_MANAGER_DB_PATH] [-v] [-c] [-l {screen,file}] [--hours HOURS]

Usage Examples

Task: query IOC related to Lumu incidents with default options

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

Task: query IOC related to specific parameters

By default, the integration script will query incidents related to all adversary types. If you need to filter the query to specific adversary types, you can use the --adversary-types flag as follows

Task: Clean records

To clean the existing records related to the integration in your Azure deployment, just set up the clean flag in the integrations.yml file to true.

Then, run the integration script as follows:

Or you can run the clean command directly to clean all the companies

The records not manipulated by the integration will be preserved

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

Security Rules - IP Indicators

After running the integration, you will see new items under the Outbound Security Rules of each Network Security Rules set in the configuration file.

Firewall Policy Network Rule - Domain Indicators

If you configured the Azure Firewall feature in the integration, you will see a rule collection named Lumu Rule Collection under the Network rules of the selected Azure Firewall policy. Inside there will be a rule with the Lumu adversaries-related domains.

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 the wrong values for those parameters.

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.