This article shows how to leverage the Lumu Defender API and Cisco Secure Access API to mitigate security risks by leveraging the Cisco Secure Access Destination List feature.

Requirements

• An active Cisco Secure Access subscription.
• A Cisco Secure Access administrator user
• 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 the Lumu Custom Collector API and the Cisco Secure Access 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.

• Cisco Secure Access API services: api.sse.cisco.com
• 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 Cisco Secure Access uses its API to manage a dedicated Destination List. The integration updates the Domains, IP and URL indicators of the list based on Lumu detections to avoid further outbound contacts within your Cisco Secure Access deployment.

Preliminary Setup - Cisco Secure Access

To set up the integration, you must prepare your Cisco Secure Access instance to communicate with the Lumu integration, specifically you need to create a Custom API Key.  The following sections will guide you on how to perform this task.

Create a Custom API Key

Log in to your Cisco Secure Access Web console with a user with administrative privileges and perform the following steps to create a new Custom API Key. 

1. Navigate to Admin > Management > API Keys. Then, Click Add (1), located in the upper right corner of the screen.

2. Give it a distinct name. Then, locate and select Destination List and Destinations within Key Scope / Policies, and subsequently assign Read/Write permissions to both. Set an Expiry Date following your organization’s security guidelines. 

You must reissue the integration API key near the expiration date and update the integration configuration to keep your integration working.

3. Locate the API Key and the API Key Secret at the bottom of the screen. Copy and save these credentials, they will be used during the Set up the configuration parameters step.

Preliminary setup - Lumu portal

The integration set-up process needs you to collect this information from Lumu portal:

• Lumu Defender API key
• Company UUID

Log in to your Lumu Portal and run the following procedures to collect this data.

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 - Choose 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 by using the Makefile model (Unix-based systems). Adhere to the subsequent guidance to prepare the hosting environment.

First, you must 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. From now on, we will refer to this folder as <app_lumu_root>.

Prepare Docker on 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.

Set up the configuration parameters

Execute the following command and input all parameters gathered during the Preliminary Setup - Lumu Portal and Preliminary Setup - Cisco Secure Access steps.

Each input is subject to format validation. Ensure that the inputs adhere to the required format. Incorrect formatting will prevent the wizard from advancing to the subsequent prompt.

Once you correctly enter the configuration parameters, a .config.toml file will be generated.

The integration should not be deployed until this setup process is complete to prevent underlying errors.

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

Deploy as a Docker container via Makefile

The deployment involves two components, the IoC Manager, which is responsible for managing the Lumu indicators for your organization, and the Application component, which ingests the active indicators into the third-party solution.

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.

Expected results

Once you have successfully integrated Cisco Secure Access, any Indicators of Compromise (IoC) present in your instance will be visible within the Destination List created specifically for this integration.

Proceed to Resources > Destinations > Internet and SaaS Resources, then select the Destination List Tab. Then, locate and expand the relevant destination list to view the ingested indicators.

Adding the Destination List to an Access Policy

Once the Destination List is populated and synchronized by the integration, it can be applied to specific access policies. Navigate to Secure > Access Policy. Then, select the desired rule and edit it to associate the Destination list populated by the integration.

This is how it looks like a blocking web page listed in the Destination List.

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-ioc
  make logs-component
• Checking integration errors
  
  Run the following command to check errors in your integration.
  make errors-ioc
  make errors-component
• Check the status of the integration
  
  Run the following command to check the status of the integration.
  make stats-ioc
  make stats-component
• Stopping the integration
  
  Run the following command if you need to stop the integration.
  make stop-ioc
  make stop-component
• Starting the integration
  
  Run the following command to start the integration.
  make start-ioc
  make start-component
• 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-ioc-force
  make reset-component-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

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 a proper Docker Network connection or temporarily unavailable repositories, just make sure your Docker has an active DNS resolution and a good internet outgoing. 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

You will get the following log, when the component is operational, an error such as 401 Unauthorized may be observed.

Network Connection Problems

You may encounter issues associated with general network connection failures. Make sure you have a stable Internet connection and try again.

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