Trend Micro Apex Central Custom Response Integration

Trend Micro Apex Central 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 to use that integration instead.
This article shows how to leverage the Lumu Defender API and the Trend Micro Apex Central User-Defined Suspicious Objects (UDSO) REST API to mitigate security risks.
Response integration setup from Lumu Defender to Trend Micro Apex Central
Response integration setup from Lumu Defender to Trend Micro Apex Central

Requirements

  1. A Trend Micro Apex Central license (SaaS or on-premise). Please refer to About Apex Central for more information.
  2. Trend Micro Apex Central application ID and API key.
    1. For further reference, please refer to Using the Apex Central Automation APIs.
  3. A Lumu Defender active subscription and API key.
  4. Scripting host with Python v3.6+.
    1. The host must be able to reach both Trend Micro Apex Central REST API and Lumu Defender REST API endpoints.
  5. Script package.
    1. Contact the Lumu Support Team to request the deployment package.

Set Up Trend Micro Apex Central

First, create an Application, then obtain its ID and API Key. For further reference, please refer to the article Adding an Application.
Trend Micro Application sample
Trend Micro Application sample

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 the Script

First, contact the Lumu Support Team to request the deployment package. 

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

Install requirements

The file requirements.txt contains the list of requirements for this data collector. After deploying the package locally, run the following command from the deployment folder:
[sudo] pip install -r ./requirements.txt

Script details

To use the script, you must locate yourself on the path selected for deployment ( <apex_lumu_root> ). Use the following command to show all options available for the package:
python lumu_apex-ioc.py --help

Usage: lumu-apex-ioc.py [options]

Options
Description
-h, --help
show this help message and exit
--config CONFIG
Load options from config file
--company-key COMPANY_KEY
--company_key COMPANY_KEY
Lumu Company Key (Defender API).

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

--logging {screen,file}
Logging option (default screen).
--verbose, -v
Verbosity level
--host HOST
Trend Micro Apex Central host.
--application-id APPLICATION_ID
--application_id APPLICATION_ID
Trend Micro Apex Central Application ID.

--api-key API_KEY
--api_key API_KEY
Trend Micro Apex Central API Key.

--adversary-types {C2C,Malware,DGA,Mining,Spam,Phishing}
--adversary_types {C2C,Malware,DGA,Mining,Spam,Phishing}
Lumu adversary types to be filtered.

--scan-action {log,block}
--scan_action {log,block}
Scan action to be used to push UDSO (default "block").

--no-expiration-date
Tells to not set the expiration date to each UDSO (default 30 days).
--ioc-types {ip, domain, url, hash}
--ioc_types {ip, domain, url, hash}
IOC types to be collected and processed by the integration.

--preserve-iocs, --preserve_iocs
Preserve the existent UDSO created by Lumu.
--days DAYS
The number of days from now to query Lumu incidents backward (default 30).
--threaded
Set if you want the integration to operate with multi-threading.
--threads THREADS
Number of threads to use for the multi-threaded mode. USE WITH CAUTION (default 20).
--clean
Cleans all rules and objects created by the Lumu integration.

Usage examples

Task: Fetch all IOCs related to Lumu open incidents and add them into the Apex Central User-Defined Suspicious Object (UDSO) list in block mode for the last 30 days.

Use the following command to fetch and push all IOCs related to open incidents in Lumu in the last 30 days to the Apex Central User-Defined Suspicious Object (UDSO) list.

python lumu_apex_ioc.py --host <apex-host> --application-id <apex-application-id> --api-key <apex-api-key> --company-key <lumu_company_key>

The supported Apex Central UDSO types are: ip, domain and url.

The integration creates new User-Defined Suspicious Objects in the Threat Intel > Custom Intelligence module.


Each time the script runs, it will delete all UDSO created by Lumu.

Apex UDSO sample
Apex UDSO sample

Task: Fetch specific types of IOCs related to Lumu open incidents and add them into the Apex Central User-Defined Suspicious Object (UDSO) list in block mode for the last 30 days.

Use the following command to fetch and push specific types of IOCs related to open incidents in Lumu in the last 30 days to the Apex Central User-Defined Suspicious Object (UDSO) list.

python lumu_apex_ioc.py --host <apex-host> --application-id <apex-application-id> --api-key <apex-api-key> --company-key <lumu_company_key> --ioc-types url

In this example, just URL type IOCs will be fetched and added.
For each type, add an --ioc-types IOC-TYPE argument to the script. Keep in mind that the supported types are: ip , domain, and url .
It’s recommended to not mix domain and URL IoC types. If you need a granular blocking model, URLs are recommended over domains.

Task: Fetch IOCs related to Lumu open incidents and add them into the Apex Central User-Defined Suspicious Object (UDSO) list in block mode for the last X days.

If you need to fetch IOCs for the last X days, you can use the flag --days DAYS , where DAYS is the number of days you define.

python lumu_apex_ioc.py --host <apex-host> --application-id <apex-application-id> --api-key <apex-api-key> --company-key <lumu_company_key> --ioc-types url --days 15

In this example, the script will fetch open incidents in the last 15 days.
The maximum number of days you can set is 30 days.

Task: Fetch Lumu detected adversaries filtering by type
To filter your query to specific types of adversaries, you can use the option --adversary-types ADVERSARY-TYPE. If you need to set more types of adversaries, you can use the option repeatedly as in the following example:

python lumu_apex_ioc.py --host <apex-host> --application-id <apex-application-id> --api-key <apex-api-key> --company-key <lumu_company_key> --ioc-types url --adversary-types C2C --adversary-types Mining

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

Task: Add Apex UDSO with no expiration date

By default, the script adds each UDSO with an expiration date 30 days after the current date. If you need to add UDSO without an expiration date, you can use the --no-expiration flag.

python lumu_apex_ioc.py --host <apex-host> --application-id <apex-application-id> --api-key <apex-api-key> --company-key <lumu_company_key> --ioc-types url --no-expiration
It’s recommended to add UDSO with the default expiration date for dynamic adversary types like DGA.

Apex UDSO with no expiration date
Apex UDSO with no expiration date

Task: Preserve previously added UDSO

By default, the script deletes the previously added UDSO. If you need to preserve the UDSO previously added by Lumu, you can use the flag --preserve-iocs .

python lumu_apex_ioc.py --host <apex-host> --application-id <apex-application-id> --api-key <apex-api-key> --company-key <lumu_company_key> --ioc-types url --preserve-iocs
The script will only delete any UDSO added by itself. Not any other UDSO, if any, would be affected.

Task: Clean all changes made by Lumu integration

If you need to delete all the User-Defined Suspicious Objects created by the integration, use the --clean flag with the authentication arguments.

python lumu_apex_ioc.py --host <apex-host> --application-id <apex-application-id> --api-key <apex-api-key> --company-key <lumu_company_key> --clean


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 lumu_apex_ioc.py --host <apex-host> --application-id <apex-application-id> --api-key <apex-api-key> --company-key <lumu_company_key> --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: save log output to file

You can run the integration using a configuration file where you can save the required arguments in form of <argument_name>=, 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. 
  
    
   
  1. 
            # Sample config file
            # Lumu
            company_key=<lumu-company-key>
            # Trend Micro Apex Central
            host=<apex-host>
            application_id=<apex-application-id>
            api_key=<apex-api-key>
            # Misc
            # Optional parameters
            days=<days-to-collect>
            ioc-types=url
            ioc-types=hash
            # Threading support
            threads=20
            # Logging
            logging=file           
    2.
The file .config_sample in the repo can be tailored according to your needs. Remember to rename it to .config.

if you need to add flags (arguments without values like -v or --clean, those need to be added on the command line)

Task: run the integration script with multiple threads

Some tasks run by the script support multiple threads. If you want to speed up the integration process, you can use the flag --threaded followed by the parameter --threads X, where X is the number of threads to use.

python lumu_apex_ioc.py --host <apex-host> --application-id <apex-application-id> --api-key <apex-api-key> --company-key <lumu_company_key> --threaded --threads X

By default, if you use the --threaded flag, the number of threads to run the integration will be 20. MODIFY THIS NUMBER WITH CAUTION.

Other tasks

The above samples can be combined according to your needs.

Expected Results

After running the script, all queried IoCs will be added into the Custom Intelligence module inside the Apex Central console as follows:

User-Defined Suspicious Objects list
User-Defined Suspicious Objects list

The block action will reflect in the endpoint as a pop-up modal and in the Apex Central console:

Detected violation
Detected violation


C&C Callback events

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. To avoid race conditions related to the time taken to execute the script if there are several IoCs to be added, the script controls that only one instance is running. Keep this in mind when you are defining the time of the Scheduled job or the cron task. We recommend that this 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>/lumu_apex_ioc.py --host <apex-host> --application-id <apex-application-id> --api-key <apex-api-key> --company-key <lumu_company_key>

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 any arguments. It should look as follows:

*/30 * * * * python3 <repo_root>/lumu_apex_ioc.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, others will be terminated immediately.

Troubleshooting and Known Issues

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


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 present in the integration’s folder. This file stores the id of the process related to the integration, if it’s running. Search for this process in your system. The following images show the process in Windows and Linux.


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

Check integration process - Windows
Check integration process - Windows

Check integration process - Linux
Check integration process - Linux

If the previous validation indicates that another instance is running, check the progress of the execution using the integration’s log lumu.log.
    Still can’t find an answer?
    Send a message to our experts.
    Contact Us

        • Related Articles

        • Trend Micro Web Security 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 ...

        • Trend Vision One Out-of-the-Box Response Integration

          Requirements Trend Vision One: Make sure you read the Suspicious Object Management article on the Trend Vision One documentation thoroughly to ensure a smooth process. Lumu License An active Lumu Defender subscription Configure Trend Vision One Trend ...

        • Guardicore Custom Response Integration

          This article shows how to leverage the Lumu Defender API and Guardicore API to mitigate security risks. Response integration between Guardcore and Lumu Requirements An active Guardicore Centra subscription A Guardicore administrator user. Lumu ...

        • Illumio Custom Response Integration

          Learn how to leverage the Lumu Defender API and Illumio API to mitigate security risks. Response integration between Illumio and Lumu Requirements An active Illumio Segmentation subscription. You need an Illumio administrator user to set up the ...

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