Cisco Secure Endpoint Custom Response Integration
This article shows how to leverage the Lumu Defender API and Cisco Secure Endpoint API to mitigate security risks.
Requirements
- Cisco Secure Endpoint subscription
- You need a Cisco Secure Endpoint Essentials or above.
- Lumu Defender API key.
- To retrieve an API token, please refer to the Defender API document.
- Script host
- Host with Python 3.9+ with internet visibility over Lumu Defender endpoints and Cisco Secure Endpoint Cloud.
- Script package
- Contact the Lumu support team to request the package we created to deploy the required files.
Set up the Cisco Secure Endpoint
Create a new API Key
Using the Cisco Secure Endpoint Web console, in the top right part of the screen, look for the Accounts section. In the Accounts section, click on API Credentials > New API Credential. In the New API Credential window, give the credential a distinctive name, select the Read & Write Scope, toggle on the Enable Command Line and Allow API access checkboxes. Click on the Create button.
(Optional) Create Cisco Simple Custom Detection (SCD) and Blocked Applications lists
To deliver hashes to Cisco Secure Endpoint, you need a Simple Custom Detection (SCD) list and an Application Blocking list. Even if you can operate with your already defined lists, it’s recommended to create specific lists to be used by the Lumu integration.
Simple Custom Detection (SCD) List
Using the Cisco Secure Endpoint Web console, look for the Outbreak Control menu in the top navigation bar. In the Outbreak Control section, click on Custom Detection - Simple > Create. Give the list a distinctive name, and click on the Save button.
Application Control - Blocked Applications List
Using the Cisco Secure Endpoint Web console, look for the Outbreak Control menu in the top navigation bar. In the Outbreak Control section, click on Application Control - Blocked Application > Create. Give the list a distinctive name, and click on the Save button.
Attach your Simple Custom Detection (SCD) and Blocked Applications list to your policies
Using the Cisco Secure Endpoint Web console, look for the Management menu in the top navigation bar. In the Management section, click on Policies. There, select and edit the required policies. Click on the > Edit button, and finally, in the Outbreak Control section, attach the integrated SCD and Blocked Applications lists.
Deploy the integration
There are 3 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 <cisco_lumu_root>.
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 (<cisco_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 <cisco_lumu_root> folder
2. Run the following command to create the virtual environment
python -m venv <venv_folder>
3. Activate the virtual environment running the following
source <venvsource <venv_folder>/bin/activate
Script details
To use the script, you must locate yourself on the path selected for deployment (<cisco_lumu_root>). Use the following command to show all options available for the package:
usage: cisco_lumu.py [options]
|
Options |
Description |
|---|---|
| -h, --help | show this help message and exit |
| --config CONFIG | Load options from config file |
| --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) |
| --company-key COMPANY_KEY--company_key COMPANY_KEY | Lumu Company Key (Defender API). |
| --logging {screen,file} | Logging option (default screen). |
| --verbose, -v | Verbosity level. |
| --adversary-types {C2C,Malware,Mining,Spam,Phishing--adversary_types {C2C,Malware,Mining,Spam,Phishing} | Lumu adversary types to be filtered. |
| --days DAYS | The number of days backward from now to query Lumu incidents (default 30). |
| --test, -t | Runs a test with one incident only. |
| --clean | Cleans all rules and objects created by the Lumu integration. |
| --amp_client_id AMP_CLIENT_ID | Cisco Secure Endpoint Client ID. |
| --amp_api_key AMP_API_KEY | Cisco Secure Endpoint APIKEY. |
| --list-scd-name LIST_SCD_NAME--list_scd_name LIST_SCD_NAME | Cisco SCD List name |
| --list-app-blocking-name LIST_APP_BLOCKING_NAME--list_app_blocking_name LIST_APP_BLOCKING_NAME | Cisco Application Blocking List name |
Usage Examples
Task: query hashes related to Lumu incidents for the last 30 days
To query all the hashes related to Lumu incidents triggered in the last 30 days, run the following command.
Task: query hashes 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 Cisco lists, hashes related to incidents in the last 5 days
Task: query hashes 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 Cisco lists, hashes from incidents related to advesaries classified as C&C and Malware.
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 ciscolumu 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=abcde
amp_client_id=abcd
amp_api_key=abc
list_scd_name=LumuSCD
list_app_blocking_name=LumuAppBlock
ioc-types=hash
adversary-types=C2C
adversary-types=Malware
adversary-types=DGA
adversary-types=Mining
adversary-types=Spam
adversary-types=Phishing
days=15
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 Cisco lists to their original state.
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 <cisco_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.
2. To run the container, run the following command:
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:
Deploy in AWS - Serverless Application Model (SAM) (Optional)
This integration is designed to run in a Serverless Application Model in AWS. If you have services with AWS, you can leverage this integration model at your convenience.
Deployment
To deploy the integration code in AWS, follow these steps:
1. AWS CLI installation
- Install AWSCLI
- You will find how to get started here
- Debian/Ubuntu Linux:
- sudo apt install awscli
2. SAM installation
- Install SAM. Please refer to Installing the AWS SAM CLI
3. Grant the following User-Role permissions to the deployment user:
- Cloudformation management: create, delete, rollback, and so on.
- AWS::IAM::Role
- AWS::Events::Rule
- AWS::Lambda::Function
Build
To build the integration package to make it ready for AWS, run the following command using your host CLI.
Deploy
To deploy your code to AWS, run this command. Refer to the script parameter section for further reference related to the flags and arguments required:
Delete
If you need to delete your integration package from AWS, you can run this command:
Expected results
After running the integration, you will see new objects in your lists inside your Cisco Secure Endpoint Web Console.
Populated Simple Custom Detections (SCD) list
Populated Blocking Applications list
With this information, and setting your policies to use these lists, your endpoints will be protected against the execution of confirmed threats. When a quarantine action arises, this will be displayed in the Cisco Secure Endpoint console 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.
Related Articles
Cisco Meraki MX Custom Response Integration
Cisco Meraki MX Custom Response Integration This article shows how to leverage the Lumu Defender API and Meraki Dashboard API to mitigate security risks. Figure 1 - Response setup leveraging Lumu detections with Meraki Dashboard Requirements Cisco ...CylanceENDPOINT Custom Response Integration
This article shows how to leverage the Lumu Defender API and CylanceENDPOINT API to mitigate security risks. Requirements CylanceENDPOINT subscription A CylanceENDPOINT Standard subscription or above is required (formerly CylancePROTECT) Lumu ...Harmony Endpoint Custom Response Integration
This article shows how to leverage the Lumu Defender API and Harmony Endpoint Configuration API to mitigate security risks. Requirements A Harmony Endpoint subscription. Administrative access is required to run the required configurations for ...Bitdefender Custom Response Integration
Bitdefender Custom Response Integration This article shows how to leverage the Lumu Defender API and Bitdefender API to mitigate security risks. Requirements GravityZone Business Security Enterprise, cloud version, ...Akamai SIA Custom Response Integration
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 ...