This article shows how to leverage the Lumu Defender API and Imperva Cloud WAF API to mitigate security risks.

Requirements

• Imperva Cloud WAF
  • You need an Imperva Cloud WAF admin console to perform the configuration steps required to deploy 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 Imperva Cloud WAF public services. 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

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

• Lumu services:
  • defender.lumu.io (HTTP and WSS traffic)
• Imperva Cloud WAF services:
  • api.imperva.com (HTTP traffic)

Integration’s overview

The integration uses the ACL WAF Policy feature from Imperva Cloud WAF to feed IP addresses related to Lumu-detected adversarial contacts, blocking any inbound connection attempts to the assets covered by the policy.

Preliminary Setup - Imperva Cloud WAF

While several of the steps mentioned are labeled as “Optional”, Lumu very strongly recommends executing them to maximize the integration’s capabilities.

• Create a dedicated integration role with the least privileges (optional, but recommended).
• Create a dedicated integration user and attach it to the previous role (optional, but recommended).
• Enforce the API-Only type to the integration user (optional, but recommended).
• Generate the API ID and API Key for the integration.
• Identify the policy you want to integrate Lumu with.

Create an integration role

We encourage you to create a dedicated integration role to preserve the least privilege principle. You can use a role with the privileges depicted in this section if you don’t want to create a dedicated integration role.

1. Click on the Account(1) button, and open the Account Management(2) section. Then, expand the User Management(3) section in the navigation bar on the left, and click on the Roles(4) menu. Here, click on the blue New Role(5) button.

2. In the next window, fill in the requested information:

a. Give the role a distinctive Name(1).

b. Enter a role Description(2).

c. In the Role(3) section, select View policy, Manage API Keys, and Edit policy permissions

d. Save your new role

Take note of the created role. This will be needed later.

Create an integration user

We encourage you to create a dedicated integration user to track its usage if required and restrict its permissions. You can use an existing administrator user if you don’t want to create an integration user. If you choose to use an already existing user, make sure you have the credentials on hand, since they will be needed for a future step.

1. Click on the Account(1) button, and open the Account Management(2) section. Then, expand the User Management(3) section in the navigation bar on the left, and click on the Users(4) menu. Here, click on the blue Add New User(5) button.

2. In the window that opens, fill in the requested information:

a. Enter a valid E-mail(1).

b. Enter the first and the last name in the First Name and Last Name fields(2).

c. In the Role(3) section, mark the Assign a role option and select the role created in the previous step

d. Once all the necessary information has been correctly entered, the Add User(4) button will activate. Click on it to save your changes.

Generate the API key for the integration user

These steps apply to the user you selected to operate with Lumu integration, regardless of if you just created it, or if it already exists.

1. Look for the integration user you want to generate the API key for. Click on the three-dot icon on the right side of the user row. In this contextual menu, click on the Edit menu.

2. In the Edit user modal, go to the API keys tab. Click on the Add API key button.

3. Fill in the required data:

a. In the Name(1) field, type a distinctive name for the API key.

b. In the Description(2) field, type a description for the key (optional, but recommended).

c. Set the expiration period in the API key will expire in(3) field. Set it according to your organization security policy guidelines. Remember, you must reissue the key after it has expired to maintain the integration working properly. The intervals are fixed.

d. Make sure the Enabled switch is on. Click on the blue Create(4) button to save your new API key.

4. Copy from the Key Generated modal the API id and API key. Save this information for later usage.

This information will not be recoverable after closing the modal. If you close the modal before saving this information, you must generate the key again.

Enforce the API-Only user feature to the integration user

For better security, we recommend enforcing the API-Only user feature to the integration user. This feature will remove Web console access to the integration user.

Integrate with an Imperva WAF policy

To integrate with an Imperva WAF policy, you can create a dedicated ACL policy for Lumu integration or you can select an existing ACL policy. Based on your needs and your deployment characteristics, select and follow the method that fits better.

Create an Imperva WAF Policy

We encourage you to name the policy by selecting a unique distinctive name. The integration operates with case-sensitive names. Remember to save the policy name as it is typed to avoid issues when deploying the integration.

1. Head to the top navigation bar and click on the Application(1) tab. Then, in the left navigation bar, expand the WAF(2) section and click on the WAF Policies(3) menu. In the Policies window, click on the Create Policy(4) button located at the right side of the window. The Create Policy window will appear.

2. Fill in the General information:

a. Give the policy a distinctive name in the Policy Name(1) field.

b. Optionally, type a Description(2).

c. Make sure the Enable Policy(3) toggle is enabled.

d. Select ACL - Access control list as the Policy Type(4).

e. Do not click on the Create button. When finished, move to the Applied on(5) tab by clicking on it.

3. In the Applied on window, you can configure how this new policy applies to the existing Imperva environment. The sections here are:

a. Available For: Here you can select which types of accounts this policy will be applied to.

• Lumu strongly recommends the policy made available for All Sub-Accounts. This will streamline the deployment of the Lumu integration across your Imperva environment.

b. Apply to: Here you can select the domains where this policy will take effect.

c. Enable as default policy: Whether this policy will be set as the default policy for the accounts listed.

• Lumu strongly recommends enabling this policy as default policy. This will speed up the deployment of the Lumu integration in the accounts protected by Imperva.

Make sure you take note of your new policy name. This will be required later for setting up the integration.

d. When finished, click on the Create button.

Collect the Imperva WAF Policy Name to integrate with

The integration operates with case-sensitive names. Remember to save the policy name as it is typed to avoid issues when deploying the integration.

1. Head to the top navigation bar and click on the Application(1) tab. Then, in the left navigation bar, expand the WAF(2) section and click on the WAF Policies(3) menu. In the Policies window. Look for the policy you want to integrate Lumu with and copy its name exactly as it appears, you will need it for a future step.

Make sure your selected policy is of type ACL.

Preliminary setup - Lumu Portal

• Lumu Defender API key
• Company UUID

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 Python on your environment

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

• companies.yml: this file contains the information collected from the Lumu portal
• integrations.yml: this file contains the information collected from your third party console

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 is in charge of defining how the integration connects to Lumu and extracts the information of the incidents and related indicators of compromise.

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
    adversary:  # list of adversary types, option one, many or all
      - C2C
      - Malware
      - Mining
      - Spam
      - Phishing
      - Anonymizer
    days: 3 # MIN 1, MAX 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 with the IOC types required by the integration, in this case, ip.

Complete the integrations file

The integrations file contains the information required for the integration to connect and interact with your Imperva Cloud WAF deployment:

- lumu:
    uuid: "COMPANY-UUID"
    adversaryTypes: [ "C2C", "Malware", "Mining", "Spam", "Phishing", "Anonymizer"] # ["C2C", "Malware", "Mining", "Spam", "Phishing", "Anonymizer"]
    days: 30 # INTEGER=(get incidents from X days of the ioc manager local db)
  app:
    name: UNIQUE-NAME
    clean: false # true | false
    PolicyName: POLICY-NAME # Case Sensitive
    ioc: [ ip ]
    api:
      apiId: IMPERVA-API-ID
      apiKey: IMPERVA-API-KEY
      baseurl: https://api.imperva.com  # https://api.imperva.com

Keep in mind that:

COMPANY_UUID is the ID found in the Collect your Lumu company UUID section.

DEFENDER_API_KEY is the key found in the Collect the Lumu Defender API key section

IMPERVA-API-ID is the ID found in Step 4 of the Generate the API key for the integration user section, under API id.

IMPERVA-API-KEY is the key found in Step 4 of the Generate the API key for the integration user section, under API KEY.

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 the hashes 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 Imperva Cloud WAF console, just set up the clean flag in the integrations.yml file to true.

clean: true

Then, run the integration script as follows:

python3 run.py [--config CONFIG] [--ioc-manager-db-path IOC_MANAGER_DB_PATH]

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

After running the integration, your ACL-type WAF Policy will be updated with IP-related adversary information, if you have detections with IP addresses among its IOCs.

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 the following error:

Some parameters in your configuration files have been entered incorrectly. Refer to the error message to learn which parameters need to be corrected and run the integration again..

Another instance is running

If you receive the following error:

There may be another instance running concurrently. To validate whether this is true, open the pid.pid
file in the integration folder. If another instance is running, the process ID will be stored in the file.