This article shows how to leverage the Lumu Defender API and Akamai SIA (ETP) Configuration API to mitigate security risks.

Requirements

• An Akamai SIA subscription.
• An Akamai Control Center access is required for setting up and collecting Akamai configuration for the integration.
  
• Lumu Defender API key
  
• To retrieve an API token, please refer to the Defender API document.
• 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 Akamai ETP Reporting API endpoints. According to the deployment model you select, you will need a host with:
  
• Python 3.11+, or
  
• A Docker-enabled hostHost with Python 3.11+ with internet visibility over Lumu Defender endpoints and Akamai SIA (ETP) Config Cloud.
  
• Script package
• Contact the Lumu support team to request the package we created to deploy the required files.
  

Setup Akamai Secure Internet Access Enterprise (SIA)

Create an API client

An Akamai API client is required to push IOCs using its ETP Config API. To create an API client, follow these steps in the Akamai Control Center:

1. Open the hamburger menu at the top left side of the screen. Click on the Identity & access menu under the ACCOUNT ADMIN section.

2. In the Identity and Access Management screen, click on the Users and API Clients tab. Then, click on the Create API client button.

3. In the Create API client window, do the following:

a. Click on the Service Account tab. Then, click on the Set API client options button.

b. Fill in the required data.

c. Click on the Select APIs button. In the API selection window, look for the ETP Configuration API. Set the Access level to READ-WRITE. Click on the Submit button.

d. Click on the Select groups button. In the Group selection window, assign the Editor role. Click on the Submit button.

e. Click on the I reviewed and acknowledge any escalation to the authorized users' permissions checkbox. Dinally, click on the Create API client button.

4. Now, you will see the details for the created API client. You need to create a new credential. To do so, click on the Create credential button under the Credentials section. 

Copy the details shown: client_secret, host, access_token, and client_token. These will be required later to configure the integration.

Extract SIA configuration ID

The configuration ID is required to configure the integration. To extract this data, please follow these steps in the Akamai Control Center.

1. Open the hamburger menu at the top left side of the screen. Click on the Enterprise Center menu under the ENTERPRISE SECURITY section.

2. In the Enterprise Center window, click on the Policies menu under the Threat Protection > Policies section.

3. Review your browser bar. Look for the number after the /etp/ string.

Take note of this number. This will be required for setting up the integration script.

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

The integration works with Python 3.11. If your environment has prior versions, we recommend deploying the integration as a Docker Container.

Prepare Python on your environment

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 (<akamai_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 <akamai_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 (<akamai_lumu_root>). Use the following command to show all options available for the package:

usage: akamai_etp_lumu.py [options]

Usage Examples

Task: query IoCs related to Lumu incidents for the last 30 days

To query all the IoCs related to Lumu incidents triggered in the last 30 days, run the following command.

Task: query IoCs related to Lumu incidents for the last X days

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 Akamai ETP lists, IOCs related to incidents in the last 5 days

Task: query IoCs related to specific adversary types

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 Akamai SIA  lists, IOCs from incidents related to adversaries classified as C2C and Malware.

Task: query specific IoCs types

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 Akamai SIA lists, URLs and hashes from Lumu incidents.

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

# Configuration file example
company_key=ABC
#  Akamai ETP
aka_host=x.x.x
aka_client_secret=asdfg
aka_access_token=asdfg
aka_client_token=asdfg
aka_etp_config_id=asdfg
ioc-types=ip
ioc-types=url
ioc-types=domain
ioc-types=hash
adversary-types=C2C
adversary-types=Malware
adversary-types=Mining
adversary-types=Spam
adversary-types=Phishing
days=15

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. Using this flag, you will return the Akamai SIA lists to their original state.

The records not manipulated by the integration will be preserved

Other tasks

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

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.

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.

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 at the <akamai_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 aka_client_secret='xxx' --build-arg aka_access_token='xxx' --build-arg aka_client_token='xxx' --build-arg aka_etp_config_id='xxx' --build-arg aka_host='xxx' --build-arg company_key='xxx' --tag python-lumu-akamai-etp-response .

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-akamai-etp-response python-lumu-akamai-etp-response

With this mode, your integration will run every 30 minutes.

Troubleshooting

For troubleshooting purposes, you can run the following commands:

To log in to your container using an interactive shell:

To collect integration logs:

Expected results

After running the integration, you will see a new custom list named Lumu_IoC under the Threat Protection > Policies > Lists module.

Do not add or delete any object to that lists manually, they are updated by the integration

You need to associate this list with the required policies.

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.

Windows

Linux