This article shows how to leverage the Lumu Defender API and Akamai Web App & API protector API to mitigate security risks by using its Client List feature.

Requirements

• An active Akamai App & API Protector subscription.
  • An Akamai App & API Protector administrator user is required to perform the configuration of the integration.
• Lumu Defender API key.
  • To retrieve an API token, please refer to the Defender API document.
• Script host.
  • A Docker-enabled host is required to deploy the integration. This host must have Internet visibility over Lumu Defender API endpoints and Web app & API protection services.
• Script package
  • Contact the Lumu support team to request the package we created to deploy the required files.

Contacted hosts

Ensure your script host can communicate with the following hosts. These are required for the operation of this integration.

• Akamai App & API Protector instance
• defender.lumu.io
• docker.io
• ghcr.io
• *.ubuntu.com
• *.launchpad.net
• canonical.com
• debian.org
• *.debian.org
• debian-security.org
• pypi.python.org
• pypi.org
• pythonhosted.org
• files.pythonhosted.org

Integration’s overview

Lumu Custom Response integration with Akamai App & API Protector uses its API to manage a dedicated Client List. The integration updates the IP Indicators of the list based on Lumu detections to avoid inbound contacts within your Akamai deployment.

Preliminary Setup - Akamai App & API Protector

To set up the integration, you must prepare your Akamai App & API Protector console to communicate with the Lumu integration. To do this, you need the following:

• Create a Custom Role.
• Create an Integration Service Account.
• Identify Contract and Group ID.

The following sections will guide you on how to perform these tasks.

Create a Custom Role

We strongly recommend the creation of a custom Role. This practice facilitates the implementation of the Principle of Least Privilege for your integration user. To establish this custom integration role, please log in to your Web app & API protection console and proceed as follows:

1. In the left-hand navigation bar, go to ACCOUNT ADMIN > Identity & Access.

2. Select the Role tab and initiate the creation of a new role.

3. Provide a suitable name and description in the respective fields.

4. In the Permissions section, search for Web Security > Client List/Network List edit and activate.

5. Once you have configured the new role to look as follows, click on Save.

Create an Integration Service Account

Having created the new Custom Role, you can proceed with the creation of the Integration Service Account as follows:

1. Within the same Identity & Access Management section, navigate to the Users and API Clients tab, then click Create API client.

2. Under Select API client type, select Service Account, and then click Set API Client Options.

3. Fill the Create API client for a service account form as follows:

• Enter a recognizable Name.
• Enter a Description.
• Leave IP Allowlist unchecked.
• Enter the users for the Notification list. By default, it will be autopopulated with the user creating the service account. It is recommended to add users interested in the status of the integration, such as the Akamai administration and the integration administrator.
• Enter the Authorized User for this service account. By default, it will be auto populated with the user creating the service account.
  

• Click on Select API and filter by Client List. Then, set the READ-WRITE access level for the Client List APIs. Click Submit.
  

• Click on Select Groups, select the group, and associate the role created in the previous step. Click Submit.
  

4. Once you finish with the configuration, the API client should look as follows to keep the Principle of Least Privilege. Enable the I reviewed and acknowledge any escalation to the authorized users' permissions option and click Create API client.

5. Once the Client API is created, you will need to create the credentials to be used during the integration. Click on Create Credential.

6. Copy the following credential fields and the Akamai Host; keep them at hand as they will be used during the Identify Contract and Group ID and Set up the configuration files sections.

• Access Token
• Client Secret
• Client Token
• Akamai Host
  

Identify Contract and Group ID

The Contract and Group ID are specific to the Akamai App & API Protector service. If there are multiple IDs, contact the service administrator to know the exact ID.

Prior to deployment, you must verify the credentials and the contracts and groups association for the integration. To extract the Contract ID and the Group ID, you need to first unpack 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 in the Set up the configuration files step. From now on, we will refer to this folder as <app_lumu_root>.

Or

Provide the requested data collected in step 6 from the Create an Integration Service Account section. You will obtain a result like the following if everything works.

Upon execution of the command, a summary of your credentials will be displayed, along with a potential list of contract and group IDs available for selection in the integration. Select and copy the Contract and Group to which the integration will apply. Keep them at hand. They will be used during the Set up the configuration files step.

Please note that administrative privileges may be required for the installation of dependencies such as CURL and UV, if they are not already present on the system.

Preliminary setup - Lumu portal

You must collect the following information from your Lumu portal:

• Lumu Defender API key
• Company UUID

Log in to your Lumu portal and proceed with the following sections.

Collect the Lumu Defender API key

To collect the Lumu Defender API key, please refer to the Defender API document.

Collect your Lumu company UUID

To collect your Lumu company UUID, log in to your Lumu portal. Once you are in the main window, copy the string below your company name.

Preliminary Setup - Prepare your integration environment

Before starting, ensure your integration environment can communicate with the hosts listed in the Contacted Hosts section.

The integration is deployed in a Docker environment; therefore, adhere to the subsequent guidance to prepare the hosting environment.

• Run it as a Docker container.
  • By using the Makefile model (Unix-based systems).
  • By using Docker commands (Unix-based systems and Docker Desktop for Windows).

At this point, you should have already unpacked the integration package shared by our Support team in the <app_lumu_root> folder during the Identify Contact and Group ID step.

Prepare Docker in your environment

You must follow the Docker installation documentation that corresponds to your OS. Ensure you follow the Post-installation steps for Linux before deploying the integration.

For Windows users, follow the Install Docker Desktop for Windows documentation to install the Docker Engine.

Set up the configuration files

Add the companies.yml and the integrations.yml configuration files in the <app_lumu_root> folder and edit them as instructed to set up the integration.

You will find the companies_template.yml and integrations_template.yml sample files inside the integrations package. Use it to build your configuration file.

Complete the companies file

The companies.yml file contains the information required by the integration to collect the Lumu-related IOCs and make them available for their injection in the Web app & API protection policy.

All the parameters in red should be replaced with the real data necessary for your integration deployment. For example, the parameter “COMPANY-UUID” should end up as something similar to “aa11bb22bb33-123a-456b-789c-11aa22bb33cc”. Follow these indications for all similar parameters.

-
  lumu:
    uuid: "COMPANY_UUID"
    defender_key: "DEFENDER_API_KEY"
    ioc_types: # list of ioc types, option one, many or all
      - ip
    adversary: # list of adversary types, option one, many or all
      - C2C
      - Malware
      - Mining
      - Spam
      - Phishing
      - Anonymizer
    days: 3 # MIN 1, MAX 30

Replace the highlighted placeholders as follows:

• COMPANY-UUID with the Company UUID collected in the Collect your Lumu company UUID section.
• DEFENDER-KEY with the Defender Key collected in the Collect the Lumu Defender Key section.

You must fill in the configuration data carefully. If there are any mistakes or missing data, you’ll receive errors during the deployment of the integration.

Complete the integrations file

The integrations file contains the information required for the integration to connect and interact with your Web app & API protection deployment:

- lumu:
    uuid: "COMPANY-UUID"
    days: 30
  app:
    name: "UNIQUE-NAME"
    contract_id: "AKAMAI-CONTRACT-ID"
    group_id: "AKAMAI-GROUP-ID"
    list_type: ['IP']
    api:
      host: "AKAMAI-API-HOST"
      client_token: "AKAMAI-CLIENT-TOKEN"
      client_secret: "AKAMAI-CLIENT-SECRET"
      access_token: "AKAMAI-ACCESS-TOKEN"

Replace the highlighted placeholders as follows:

• COMPANY-UUID with the Company UUID collected in the Collect your Lumu company UUID section.
• UNIQUE-NAME with a distinctive name for the integration. We recommend using the customer's or Web app & API protection tenant’s name; special characters are not supported.
• AKAMAI-CONTRACT-ID with the contract ID collected in the Identify Contract and Group ID section.
• AKAMAI-GROUP-ID with the group ID collected in the Identify Contract and Group ID section.
• AKAMAI-API-HOST with the API Host shown in the Create an Integration Service Account section.
  
• AKAMAI-CLIENT-TOKEN with the client token generated in the Create an Integration Service Account section.
  
• AKAMAI-CLIENT-SECRET with the client secret generated in the Create an Integration Service Account section.
  
• AKAMAI-ACCESS-TOKEN with the access token generated in the Create an Integration Service Account section.

You must fill in the configuration data carefully. If there are any mistakes or missing data, you’ll receive errors during the deployment of the integration.

Deploy as a Docker container via Makefile (Recommended)

To streamline the deployment process, Lumu introduced the Makefile model integration that allows you to easily deploy integrations as a Docker container. To deploy the integration, locate yourself in the <app_lumu_root> folder, and run the following command:

Monitor the console output for any unexpected errors. If there are any errors present, fix them and run the command again. Check the Troubleshooting section for further reference.

Deploy as a Docker container

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 <app_lumu_root> folder, and follow these instructions.

1. Build the container by running the following command.

Do not forget the dot "."

2. Run the container by using the following command.

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

Expected results

After the integration has been executed, any Indicators of Compromise (IoC) present in your instance will be visible within the Client List created specifically for this integration.

Navigate to Web & Data Center Security > Security configuration and then view the Client List.

The source will be blocked if the feed is present on the list and a connection block has occurred.

Adding the Client List to a Web Security Configuration Policy

Once the Client List is populated and synchronized by the integration, it can then be applied to specific web configuration policies.

Proceed to Web & Data Center Security > Security Configurations and click on Web Security to access the security configuration policies for the web applications and APIs and do the following:

1. Select a configuration policy.

2. Navigate to the Action menu (represented by the "three dots icon") and create a new version based on the most recent one.

3. A new version can be created based on the last one, allowing for the addition of the Client list in specific sections of the policy, such as:

• IP/Geo Firewall -> IP Controls -> Blocked IP Client/Network Lists
  

• Custom Rules -> Rule Structure -> Match Criteria -> Client list matches
  

• Bot Management -> Custom Bot Categories -> Bot conditions -> Client/Network Lists
  

The preceding three examples merely illustrate the association of the client list; for further details, please refer to the Akamai Official Documentation and consult the Client List Compatibility section regarding list usability.

4. If you try to connect to a blocked website, you will see the following

Troubleshooting

The commands defined in this section will allow you to troubleshoot the operation of your integration. Keep in mind that you must locate yourself in the <app_lumu_root> folder before running any of them.

Deployment via Makefile as a Docker container

The following are the troubleshooting commands for this deployment option:

• Checking integration logs
  
  Run the following command to check your integration logs.
  
  make logs
  
  
• Checking integration errors
  Run the following command to check errors in your integration.
  
  make errors
  
  
• Check the status of the integration
  
  Run the following command to check the status of the integration.
  
  make stats
  
  
• Stopping the integration
  Run the following command if you need to stop the integration.
  
  make stop
  
  
• Starting the integration
  
  Run the following command to start the integration.
  
  make start
  
  
• Fixing issues with sudo for Docker
  If you cannot run Docker commands with your current user, run the following command, then reboot the server.
  
  make docker-fix-sudo
  
  
• Reinstalling integration from scratch
  
  Run the following command to reinstall the integration from scratch:
  
  make reset-force

• Collecting and packaging logs for Lumu support
  
  Run the following command to collect and package the integration logs to share them with the Lumu support team. This command will create the support.tar package file that contains relevant information for the Lumu support team.
  
  make support

Deployment as a Docker container

For troubleshooting purposes, you can run the following commands:

• Logging in to the container using an interactive shell
  
  docker exec -it lumu-akamai-web-data-center-sec-response bash

• Collecting integration logs
  
  docker logs -f lumu-akamai-web-data-center-sec-response

Known issues

In this section we collect all the potential issues you will find after you run the troubleshooting commands from the above section.

Building errors

Most of the issues building the component are due to network issues like not having a proper Docker Network connection or temporarily unavailable repositories, just make sure your Docker has an active DNS resolution and a good internet connection.

You might receive errors like failed download, reset connection

Docker permission execution

If you got some error building the integration related to docker: permission denied while trying to connect to the Docker daemon socket, run the make docker-fix-sudo command.

Input Validation

If you receive errors like this:

It means you are using the wrong key parameters or values. Review your configuration files and run the integration again.

Authentication Failed

When the authentication fails, you will get the following error. This may occur during the configuration preparation phase executed by the config command to retrieve the contracts and groups.

When the component is operational, an error 401 may be observed.

Network Connection Problems

When you have connectivity problems, you will get the following error. Make sure you have a stable network connection.

Permission Errors

An error of this nature often indicates that while the credentials may be valid, the associated permissions are likely misconfigured and getting forbidden 403 error. Please verify the assigned role and permissions.

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.