This article shows how to leverage the Lumu Defender API and Malwarebytes Nebula Configuration API to mitigate security risks.
To create a new API client, log in to your Malwarebytes Web console and click on the Integrate button in the left navigation base. Finally, click on the Add button. In the Create Client windows, make sure you mark the Read and Write accesses.
Click on the Save button. The OAuth client window will display the required details from Malwarebytes for setting up the integration.
The Account ID is required to configure the integration. To extract this data, please login into your Malwarebytes Web console. The account ID is part of the URL after you log in to the service.
Before deploying the Lumu integration, you need to select an existing policy or create a new one. To do so, you can follow the directions given by Malwarebytes in Manage policies in Nebula to select or create a new policy to protect your devices.
To allow Lumu to manage blocked DNS in your Malwarebytes Nebula deployment, you need to create a DNS Filtering rule. Follow the directions given by Malwarebytes in Create DNS Filtering rules in Nebula to set up your DNS Filtering rule.
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 <malwarebytes_lumu_root>.
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 (<malwarebytes_lumu_root>). Specific directions are included in the next sections.
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 <malwarebytes_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:
To use the script, you must locate yourself on the path selected for deployment (<malwarebytes_lumu_root>). Use the following command to show all options available for the package:
usage: mbytes_lumu.py [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). |
--logging {screen,file} | Logging option (default screen). |
--verbose, -v | Verbosity level. |
--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). |
--test, -t | Runs a test with one incident only. |
--clean | Cleans all rules and objects created by the Lumu integration. |
--mbytes_account_id MBYTES_ACCOUNT_ID | Account ID of your subscription, can checked at the web browser url box |
--mbytes_client_id MBYTES_CLIENT_ID | client id given when API credential is created |
--mbytes_client_secret MBYTES_CLIENT_SECRET | Client secret given when API credential is created |
--mbytes_host MBYTES_HOST | Malwarebytes Host (domain) (Default api.malwarebytes.com) |
--mbytes_dns_rule MBYTES_DNS_RULE | Malwarebytes Name of the DNS content filtering rule |
--ioc-types {domain}--ioc_types {domain} | IOC types to be collected and processed by the integration. |
To query all the IoCs related to Lumu incidents triggered in the last 30 days, run the following command.
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.
In this example, the integration will query and push to Malwarebytes lists, IOCs related to incidents in the last 5 days
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
In this example, the integration will query and push to the indicated Malwarebytes DNS filtering rule, IOCs from incidents related to adversaries classified as C2C and Malware.
By default, the integration script will collect all the supported IOC types (IPs, domains, URLs, and hashes). If you need to filter the query to collect specific IOC types, you can use the --ioc-types flag as follows
In this example, the integration will query and push to Malwarebytes lists, URLs and hashes from Lumu incidents.
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 <malwarebytes_lumu_root> path, save a file named .config with your configuration. Following, you have a sample of the format of the file.
- ## Configuration file # Lumu company_key=<LUMU_COMPANY_KEY> # App mbytes_account_id=<MALWAREBYTES_ACCOUNT_ID> mbytes_client_id=<MALWAREBYTES_CLIENT_ID> mbytes_client_secret=<MALWAREBYTES_CLIENT_SECRET> mbytes_dns_rule=<MALWAREBYTES_DNS_RULE> # Misc # Optional arguments ioc-types=domain # 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=30 # Output trace destination. For Docker deployments leave this as screen logging=[screen|file]
When the script is run with the –clean flag, it will erase all Lumu records created. Using this flag, you will return the Malwarebytes lists to their original state.
According to your needs, you can combine the examples shown.
To run the script on a timely basis, consider implementing a Scheduled task in Windows or a Cron task in Unix-based systems. If you are pushing hashes, the integration could take longer to run. 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.
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:
If you need to work with another scheduling time, you can use the 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.
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 <malwarebytes_lumu_root> folder, and follow these instructions:
1. To build the container, run the following command. Change all the flags based on the reference in the script section above.
docker build --build-arg APP_PATH='mbytes_lumu.py' --build-arg mbytes_account_id='xxx' --build-arg mbytes_client_id='xxx' --build-arg mbytes_client_secret='xxx' --build-arg mbytes_host='xxx' --build-arg mbytes_dns_rule='xxx' --build-arg company_key='xxx' --tag python-lumu-mbytes-response .Do not forget the dot "." at the end of line2. To run the container, run the following command:
docker run -d --restart unless-stopped --name lumu-mbytes-response python-lumu-mbytes-responseWith this mode, your integration will run every 30 minutes.
For troubleshooting purposes, you can run the following commands:
To log in to your container using an interactive shell:
To collect integration logs:
After running the integration, you can check your DNS Filtering rule block set. Go to Monitor - DNS Filtering, click the selected DNS rule on the Rules tab, and check the blocked domains.
In the agents associated with the Malwarebytes policy, you will see that all domains related to your DNS filtering rule are blocked.
To identify failures in the script execution, use the -v flag. The script execution log will show more detailed information.
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. Search for this process in your system. The following pictures show the process in Windows and Linux.