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, https://cloud.gravityzone.bitdefender.com/.

1. The Bitdefender cloud-hosted console is the easiest and fastest way to install, control, and monitor security..

• Lumu Defender API key

1. For retrieving an API token, please refer to the Defender API document.

• Script host.

1. Contact the Lumu support team to request the package we created to deploy the required files.

1. Host with Python 3.6+ with internet visibility over Lumu Defender endpoints and Bitdefender Cloud.

Set up the Bitdefender Gravity Zone API

Create a new API Key

Using the Bitdefender Web console, go to the top right. In the User section, click on My Account > API Keys > Add. In the API Key window, enable the permissions Companies, Licensing, Incidents, and Policies.

Operating with your BitDefender Policies

Select the method to operate with BitDefender Policies

Following, you will find the different options you can use to operate with BitDefender policies:

1. Work on an existing policy. This option is not recommended.
2. Work on a new policy and use it to protect enrolled devices.  More information of how to operate with this option can be found in the Init Script section, option 2.A.
3. Work on a new policy and use it as a parent policy for others. This option is recommended for BitDefender deployments where the administrators use exclusion lists for the Anti-malware settings. More information of how to operate with this option can be found in the Init Script section, option 2.B.
   
   

Create your policy

Regardless of the option chosen, before you use the new policy or create childs from the new policy, you need to have these considerations in mind:

• You have to create the policy beforehand. The integration needs the policy name to update it with the IOCs identified by Lumu.
• The policy must be created with the Incident Sensor option enabled.
  
• The Scan SSL setting must be enabled under the Network Protection section to allow BitDefender to inspect and act on SSL traffic.
  
• The Web Access Control feature must be enabled under the Content Control section.
  

Deploy the script

Scripts location

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 <bitdefender_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 (<bitdefender_lumu_root>). Specific directions are included in the next sections.

Install requirements

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:

[sudo] pip install -r ./requirements.txt 

Init Script

The integration comes with an initialization script. This script will validate the existing policies in your BitDefender deployment against the option you want to use: use the policy as the main policy or use it as a parent for other policies.

Use the following command to set up the initial configuration:

python bitdefender_init_setup.py -key <bitdefender_apikey> 

usage: init_script_lumu [-h] -key APIKEY  [options]

 Follow the on-screen instructions. According to your selection, the script will run some validation over the selected policy. Run the adjustments indicated by the script before proceeding to the next steps

Script details

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

python bitdefender_lumu.py --help

usage : bitdefender_lumu.py [ options ]

Usage Examples

Task: query and add indicators (IPs, hosts, URLs, and hashes) related  to Lumu incidents

Use the following command to fetch and push to Bitdefender HASHs, IPs and URLs IOCs related to incidents found in your organization by Lumu in the last 30 days:

python bitdefender_lumu.py --apikey <bitdefender_apikey> --company-key <lumu_company_key> --policy-name <bitdefender_policy_name> 

The integration creates or deletes recent Hash, FW rules and Web URLs regarding what is found in Lumu.

The number of URLs added to the Web category may vary from the processed ones due to some Bitdefender limitations.

The number of FW Rules added to the Firewall may vary from the processed ones due to some Bitdefender limitations (10000).

The number of HASH added to the block list may vary from the processed ones due to some Bitdefender limitations.

If your current licensing does not includes support for hashes, you will see the following error

08-01-2023 07:59:54 - bitdefender_client - [140451823085376]:[WARNING] - Omitting known errors:['add_to_block_list', 'remove_from_block_list'], {"code": -32602, "message": "Invalid params", "data": {"details": "Not enough rights for this companyId to add a hash to blocklist."}} .Check the Bitdefender API and ApiKey, not receiving what is expected. Parent functions ['_process_response', '_perform_request', 'wrapper', 'wrapper', 'post_method', 'submit_http_request', 'add_to_block_list', 'add_hash_many', 'submit_hash_block_list', 'postprocessing', 'run', 'main', '<module>']

08-01-2023 07:59:54 - bitdefender_actions - [140451823085376]:[ERROR] - Something went wrong adding the hash blocklist, verify connectivity or licensing 

If this is your case, you can still use the integration to feed URLs, IPs, and hosts to your BitDefender policy. Follow the indications in the next example to fix this.

Task: query and add specific indicators related to Lumu incidents

To push a specific type of IOCs (IPs, hosts, hashes, or URLs) to your Bitdefender, use the argument --ioc-types IOC_TYPE. IOC_TYPE can have the value ip, domain, hash, or url. If you want to add multiple types, just append a new instance of --ioc-types:

python bitdefender_lumu.py --apikey <bitdefender_apikey> --company-key <lumu_company_key> --policy-name <bitdefender_policy_name> --ioc-types hash 

This example will push hashes under the BitDefender list Lumu xxx.

You cannot combine domain and url IOC types. If you try so, the integration chooses to process URLs instead of domains. URLs allow more granularity to block potential adversarial contacts.

Task: query and add indicators related to Lumu incidents with contacts in the last X days

Use the following command to fetch and push to your Bitdefender IOCs related to incidents found in your organization by Lumu with contacts in the last X days.

python bitdefender_lumu.py --apikey <bitdefender_apikey> --company-key <lumu_company_key> --policy-name <bitdefender_policy_name> --days X 

All previously pushed IOC to your Bitdefender web console will be replaced, even if they correspond to incidents with contacts before X days.

Task: query and add indicators related to Lumu incidents of specific types

By default, the script queries open and closed incidents of all adversary types (Phishing, Malware, DAG, Spam, others). If you need to collect specific types of incidents, you can use the argument --adversary-types ADVERSARY_TYPE . If you need to get two or more adversary types, you only need to append a new instance of the argument.

python bitdefender_lumu.py --apikey <bitdefender_apikey> --company-key <lumu_company_key> --policy-name <bitdefender_policy_name> --adversary-types Phishing --adversary-types Malware 

In this example, the adversary types queried are Phishing and Malware.

Task: clean all changes made by Lumu integration

If you need to delete all objects created by this integration in your Bitdefender, use the --clean  flag with the authentication arguments.

python bitdefender_lumu.py --apikey <bitdefender_apikey> --company-key <lumu_company_key> --policy-name <bitdefender_policy_name> --clean      

The integration will try to delete all created objects. If they are being used by Firewall rules, you need to modify them first by withdrawing the objects.

Task: save log output to file

By default, you will see the execution log on the screen console. Use the argument --logging file to store a record of all tasks run in the lumu.log file in the script root path .

python bitdefender_lumu.py --apikey <bitdefender_apikey> --company-key <lumu_company_key> --policy-name <bitdefender_policy_name> --logging file 

This file is useful for scheduled tasks or processes running in the background. When you open this file, you will see the following. The information displayed aids in checking the execution progress.

Task: use a configuration file to run the integration

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 integration root path, save a file named .config with your configuration. Following, you have a sample of the format of the file.

## Sample .config file
# Bitdefender
## Configuration file
# Lumu
company_key=<lumu_company_key>
                  
# bitdefender
apikey=<bitdefender_apikey>
policy_name=<bitdefender_policy_name> 
                     
# Misc
# Optional arguments
ioc-types=<ioc_type_1>
ioc-types=<ioc_type_1>
ioc-types=<ioc_type_1>
ioc-types=<ioc_type_1>

# Optional arguments (default all adversary types)
...
<other key value arguments>

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.

Other tasks

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

Expected results

You will see new objects in your Bitdefender Web Console: Lumu Hash list in blocklist incident, Lumu IPs in policy: FW rule, and Web URLs in policy: web rule.

Set up Bitdefender policies

After the custom objects have been created and maintained by the integration, you need to use them inside the platform to enable and assign them to the endpoint scope.

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

*/30 * * * * python3 <repo_root>/bitdefender_lumu.py -- apikey  <bitdefender_apikey> --company-key <lumu_company_key> --policy-name <bitdefender_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 * * * * python3 <repo_root>/bitdefender_lumu.py

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.

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.

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

Policy not updated

[ERROR] - the policy (Firewall & WebUrl rules) was NOT updated into BitDefender Gravity Zone (Cloud) correctly, check manual importing and the setup policy steps