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 capabilities of your organization.

Requirements

• An active DNSFilter subscription.
• A DNSFilter Pro subscription or up is required.
• Lumu Custom Collector API configuration for DNS queries.
• A Lumu custom collector ID and client key are required to set up the collection process. Information on how to create a custom collector in your Lumu portal can be found in Manage Custom Collectors.
• Script host.
• A scripting host is required to deploy the integration. This host must have Internet visibility over the Lumu Custom Collector 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
• 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.

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.

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:

Script details

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

usage: dnsfilter_lumu [-h] -token DNS_FILTER_TOKEN -key LUMU_CLIENT_KEY -cid LUMU_COLLECTOR_ID [-v] [-l {screen,file}]

Usage Examples

Task: poll and inject DNSfilter logs into Lumu

Run the following command to poll all the DNSFilter logs and push them into the Lumu custom data collector. The poll process will trigger every 1 minute.

The script starts polling from now minus a delay set in the script. By default, this offset is 3 minutes.

Task: store execution records in a file

To redirect all the output from the execution process to a file, use the --logging file argument. The integration output will be stored in a file called lumu.log.

It’s recommended to set this flag. The script runs as a daemon process. The information stored in the file lumu.log is useful for tracing progress or troubleshooting.

Further considerations

The script is intended to be used as a daemon process. It is recommended to use it using complementary tools like nohup. Use the following line as an example:

If you are using a Python virtual environment

If you are NOT using a Python virtual environment

Troubleshooting

To identify failures in the script, please use the -v flag. This will allow you to identify failures in the script execution.

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 lumu_client_key='xxx' --build-arg lumu_collector_id='xxx' --tag python-lumu-dnsfilter .

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 python-lumu-dnsfilter

Troubleshooting

For troubleshooting purposes, you can run the following commands:

To log in to your container using an interactive shell:

To collect integration logs: