DNSFilter Custom Response Integration

DNSFilter Custom Response Integration

This article shows how to leverage the Lumu Response API and DNSFilter API to mitigate security risks.


Requirements

  • An active DNSFilter subscription.
    • A DNSFilter Pro subscription or up is required.
  • Script host.
    • A scripting host is required to deploy the integration. This host must have Internet visibility over the Lumu Defender API and the DNSFilter API endpoints. According to the deployment model you select, you will need a host with:
      • Python 3.10+, or
      • A Docker-enabled host
  • Lumu Defender API key
    •  To retrieve an API token, please refer to the Defender API document.
  • Script package
    • Contact the Lumu support team to request the package we created to deploy the required files.

Set up DNSFilter

Request a persistent token for the integration

For running the integration, it’s recommended to generate a persistent token. To do so, contact the DNSFilter support team and issue the corresponding request. You have two options to contact them:

  1. Write a request ticket to DNSFilter support .
  2. Using your DNSFilter Web console, click on the Support icon in the top right part of your screen, then click on the Open a ticket option.

(Optional) Create a Filtering policy dedicated to the integration

It’s recommended to create a Filtering policy to be fed by the integration. To do so, follow these directions within your DNSFilter Web console.

  1. Using the left navigation panel, click on the Filtering menu under the Policies section.
  2. In the Filtering window, click on the Add button. Give a name to your new policy.

You can select an existing policy to work with the integration. The integration will only modify the IOCs pushed by itself, letting others intact.


Deploy the integration

There are 2 environment options to deploy the script, select the one that fits better in your current infrastructure. Whatever alternative you select, you need to unpack first 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 <dnsfilter_lumu_root> .

The integration works with Python 3.10. If your environment has prior versions, we recommend deploying the integration as a Docker Container.

Prepare Python on your environment

As a recommended practice, we encourage you 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.

Deploy as script

In the package, you will find the script required to run the integration. To use the script, you must locate yourself on the path selected for deployment ( <dnsfilter_lumu_root> ). Specific directions are included in the next sections.

Install requirements

If you are running different Python scripts in the selected host, it’s recommended to create a virtual environment to preserve the integrity of other tools. To do so, follow these steps:

1. Using a command line tool, locate yourself in the <dnsfilter_lumu_root> folder

2. Run the following command to create the virtual environment

python3 -m venv <venv_folder>

3. Activate the virtual environment running the following

source <venv_folder>/bin/activate

The file requirements.txt contains the list of requirements for this integration. After deploying the package locally, run the following command from the deployment folder:

pip install -r ./requirements.txt

Script details

To use the script, you must locate yourself on the path selected for deployment ( <dnsfilter> ). Use the following command to show all options available for the package:

python3 dnsfilter_lumu.py -h

usage: dnsfilter_lumu [OPTIONS]

Options

Description

-h, --help show this help message and exit
--config CONFIG  Load options from config file
--proxy-host PROXY_HOST--proxy_host PROXY_HOST Proxy host (if required)
--proxy-port PROXY_PORT--proxy_port PROXY_PORT Proxy port (if required)
--proxy-user PROXY_USER--proxy_user PROXY_USER Proxy user (if required)
--proxy-password PROXY_PASSWORD--proxy_password PROXY_PASSWORD Proxy password (if required)
--company-key COMPANY_KEY--company_key COMPANY_KEY Lumu Company Key (Defender API).
--adversary-types {C2C,Malware,Mining,Spam,Phishing}--adversary_types {C2C,Malware,Mining,Spam,Phishing} Lumu adversary types to be filtered.
--days DAYS    The number of days backward from now to query Lumu incidents (default 30).
--clean   Cleans all rules and objects created by the Lumu integration.
--dns_filter_token DNS_FILTER_TOKEN DNSFilter API JWToken
--dns_filter_policy_name DNS_FILTER_POLICY_NAME
--logging {screen,file} Logging option (default screen).
--verbose, -v Verbosity level.

Usage Examples

Task: query IoCs (Domain) related to Lumu incidents for the last 30 days

To query all the IoCs related to Lumu incidents triggered in the last 30 days, run the following command.

python dnsfilter_lumu.py --company-key LUMU_KEY --dns_filter_token DNS_FILTER_TOKEN --dns_filter_policy_name DNS_FILTER_POLICY_NAME

Task: query IoCs (Domain) related to Lumu incidents for the last X days

By default, the integration script will query incidents for the last 30 days. If you need to change this value, you can use the --days flag as follows.

python dnsfilter_lumu.py --company-key LUMU_KEY ---dns_filter_token DNS_FILTER_TOKEN --dns_filter_policy_name DNS_FILTER_POLICY_NAME --days 5

In this example, the integration will query and push to DNSFilter lists, IOCs related to incidents in the last 5 days

Task: query IoCs (Domain) related to specific adversary types

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

python dnsfilter_lumu.py --company-key LUMU_KEY ---dns_filter_token DNS_FILTER_TOKEN --dns_filter_policy_name DNS_FILTER_POLICY_NAME --adversary-types C2C --adversary-types Malware

In this example, the integration will query and push to DNS Filter lists, IoCs from incidents related to adversaries classified as C&C and Malware.

Task: run with .config file

You can run the integration using a configuration file where you can save the required arguments in the form of < argument_name >=< value >, one argument per line. In the dnsfilter_lumu path, save a file named .config with your configuration. Following, you have a sample of the format of the file.

  1.  ## Configuration file            
            
    # Lumu
company_key=<COMPANY_KEY>
#  DNS Filter
dns_filter_token=<DNSFILTER_TOKEN>
# Misc
# Optional arguments (default all adversary types)
adversary-types=C2C
adversary-types=Malware
adversary-types=Mining
adversary-types=Spam
adversary-types=Phishing
# Optional (default days: 30)
days=<DAYS>
# Output trace to file. Relevant for cron job or scheduled task
logging=[screen|file]

If you need to add flags (arguments without values like -v or --clean, those need to be added on the command line). In the repo files, you will find a sample file named .config_sample. You can tailor its content according to your needs. Remember to rename it to .config before running the integration script.

Task: clear records

When the script is run with the –clean flag, it will erase all the Lumu records created by the integration. Using this flag, you will return the DNSFilter lists to their original state.

python dnsfilter_lumu.py --clean --company-key LUMU_KEY ---dns_filter_token DNS_FILTER_TOKEN --dns_filter_policy_name DNS_FILTER_POLICY_NAME

The records not manipulated by the integration will be preserved

Other tasks

According to your needs, you can combine the examples shown.

Further considerations

To run the script on a timely basis, consider implementing a Scheduled task in Windows or a Cron task in Unix-based systems. We recommend that the scheduled job runs every 30 minutes.

Following, you have an example of how this Cron job should look using the recommended time.

*/30 * * * * python dnsfilter_lumu.py --company-key LUMU_KEY --dns_filter_token DNS_FILTER_TOKEN --dns_filter_policy_name DNS_FILTER_POLICY_NAME

It’s recommended to add the --logging file argument to any scheduled task. It will record all the output in the log file for further reference. If you have created a configuration file, your crontab entry doesn’t need arguments. It should look as follows:

*/30 * * * * python dnsfilter_lumu.py

If you need to work with another scheduling time, you can use the [ crontab guru ]( https://crontab.guru) service.

To avoid race conditions, you can run only one instance. If you have one running, the second one will be canceled immediately.

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 in the <dnsfilter_lumu_root> folder, and follow these instructions:

1. To build the container, run the following command. Change all the flags based on the reference given in the script section above.

docker build --build-arg dns_filter_token='xxx' --build-arg dns_filter_policy_name='xxx' --build-arg company_key='xxx' --tag python-lumu-dnsfilter-response .
Do not forget the dot "." at the end of the line
2. To run the container, run the following command:
docker run -d --name lumu-dnsfilter-response python-lumu-dnsfilter-response

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

Troubleshooting

For troubleshooting purposes, you can run the following commands:

To log in to your container using an interactive shell:

docker exec -it lumu-dnsfilter-response bash

To collect integration logs:

docker logs -f lumu-dnsfilter-response

Expected results

After running the integration, you will see new domains in the Block List tab inside the selected policy.


Remember to assign the policy to your deployment members.


Troubleshooting and known issues

To identify failures in the script execution, use the -v flag. The script execution log will show more detailed information.

Another instance is running

If you receive the following error.

Error: Another instance is running. Quitting.

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. Search for this process in your system. The following pictures show the process in Windows and Linux.


Integration process - Windows

 

Check integration process - Linux

If the previous validation indicates that another instance is running, please, check its progress using the integration’s log lumu.log .



    Still can’t find an answer?
    Send a message to our experts.
    Contact Us

        • Related Articles

        • DNSFilter Custom Data Collection Integration

          In this article, you will find out how to configure your DNSFilter subscription and its Lumu Custom Data Collection integration to pull, transform, and inject the query logs recorded by DNSFilter into Lumu to enhance the detection & response ...

        • Azure Custom Response Integration

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

        • Infoblox Custom Response Integration

          Before going through this article, check our Out-of-the-box App Integrations category. This is the recommended way to integrate the components of your cybersecurity stack with Lumu. If the product you are looking to integrate is there, it is advised ...

        • Bitdefender Custom Response Integration

          Bitdefender Custom Response Integration This article shows how to leverage the Lumu Defender API and Bitdefender API to mitigate security risks. Requirements GravityZone Business Security Enterprise, cloud version, ...

        • Akamai SIA Custom Response Integration

          This article shows how to leverage the Lumu Defender API and Akamai SIA (ETP) Configuration API to mitigate security risks. Requirements An Akamai SIA subscription. An Akamai Control Center access is required for setting up and collecting Akamai ...