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 to use that integration instead.

Due to the lack of API support from the Trend Micro Web Security solution, this example emulates the access and configuration steps a regular admin user would carry out to feed URLs into a Custom URL Category. This integration script is offered as-is. No further support will be provided. Any change in the authentication flow within Trend Micro Web Security will affect the operation of this script.

Requirements

• Trend Micro Web Security Admin user.
• Two-factor authentication must be disabled.
• An administration user with email authentication is required
• Lumu Defender API key. 
• To retrieve an API token, please refer to the Defender API document.
• Script host
• Host with Python 3.10+ with Internet visibility over Lumu Defender endpoints and Trend Micro Web Security URLs.

• Script package.
• Contact the Lumu support team to request the script deployment package.

Set up Trend Micro Web Security

Define the Customized URL category name

Define the name you want to use for the Lumu Customized URL category. Make sure this name is unique and it is not used in another category.

If you use an existing category, the integration will overwrite its contents. By default, the integration script will create a category named Lumu.

Deploy the script

Script location

Unpack the deployed 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 <tmws_lumu_root> .

Install requirements

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

Script details

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

Usage: lumu-tmws.py [options]

Usage examples

Task: query IOCs (URLs) related to Lumu incidents for the last 30 days

Use the following command to fetch and push all adversaries detected by Lumu in the last 30 days to Trend Micro Web Security Custom URL Category.

By default, the integration script uses the Lumu custom category.

Task: query IOCs (URLs) related to Lumu incidents for the last 30 days and push them into a Custom category

Use the following command to fetch and push all adversaries detected by Lumu in the last 30 days to a user-defined Trend Micro Web Security Custom URL Category.

Task: fetch Lumu detected adversaries filtering by type

To specify the types of adversaries you want to filter in your queries, use the option --adversary-types ADVERSARY-TYPE . If you need to set more types of adversaries, you can repeat the option as follows:

For this example, the script will fetch Lumu detected adversaries of types C2C and Mining .

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

## TMWS Lumu configuration file
# TMWS
username=<TMWS_USERNAME>
password=<TMWS_PASSWORD>
# If the category does not exist, the integration attempts to create it
custom_category=<TMWS_CATEGORY> 

# Lumu
company-key=<DEFENDER_KEY>

# Misc
days=30
adversary-types=C2C
adversary-types=Malware
adversary-types=Mining
adversary-types=Spam
adversary-types=Phishing

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: Clean records

When the script is run with the –clean flag, it will erase all Lumu records created.

The integration script deletes the Custom category used for pushing the URLs. If you have Cloud Access Rules using it, you need to review manually the rules and modify them accordingly.

Task: save log output to file

Use the argument --logging file to store a record of all tasks run. Using this, the entire script output will be redirected to a file named lumu.log in the script root path ( <twms_lumu_root> ).

Other tasks

The above samples can be combined according to your needs.

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.

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.

Expected results

After running the script, all queried adversaries will be pushed into the selected Custom URL Category as follows:

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.

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 .