Cisco Umbrella Response Integration with Lumu Defender API

Cisco Umbrella Response Integration with Lumu Defender API

The Lumu Defender API offers a framework to help you leverage Lumu’s integrations with your existing cybersecurity stack, including Security Information and Event Management (SIEM), Security Orchestration, Automation, and Response (SOAR), Endpoint Detection and Response (EDR); incident response systems; and more.

To get started with the Lumu Defender API, consult our get started documentation.

This article shows how to leverage adversarial information from Lumu and feed destination lists to Cisco Umbrella.

Typical setup of Cisco Umbrella with Lumu Defender APIFigure 1 - Typical setup of Cisco Umbrella with Lumu Defender API.
This article is just an example of how this integration can be carried out and is delivered as is, so please use it at your own discretion. 

Requirements

  1. Cisco Umbrella management API access Cisco Umbrella Management and Provisioning API, for destinations lists (refer to Cisco Umbrella Management API).
  2. A host to deploy the scripting code. This host must be able to reach both Cisco Umbrella endpoints and Lumu Defender API host ( https://defender.lumu.io).
  3. Python 3.6+.
  4. Requests module for Python from PyPI.
You can use an existent Destination list to add adversaries identified by Lumu using this script (refer to Cisco Umbrella Destination Lists). Please note that this Destination List must be added in a policy, and this policy must be applied to the required entities existent in your Cisco Umbrella's subscription.

Install Requests module

The Requests' module must be installed in the script host you selected.  This module allows you to send HTTP requests using Python. The following commands can be used to install the requests package for Python libraries. Use the one that best suits you.

Option 1: pip :

[sudo] pip install requests

Option 2: easy_install :

[sudo] easy_install requests

Deploy the script

First, contact the Lumu support team to request the package we created to deploy the required files.

Script location

Once you receive the Python package provided by Lumu, unpack the file in your preferred path / folder. Keep in mind, this location will be required for further configurations. This folder will be referred from now on as <umbrella_lumu_root> .

Script details

For using the script, you must locate yourself on the path selected for deployment ( <umbrella_lumu_root> ). Use the following command to show all options available for the package:

<umbrella_lumu_root>$python lumu-adversaries-to-umbrella.py --help

This is a reference of the options you have access to through this script:

lumu-adversaries-to-umbrella.py destination-list [option]

Option

Description

-h, --help

show the help message and exit

--config=CONFIG

Load options from config file

--org-id=ORG-ID

Cisco Umbrella Organization ID

--key=KEY 

Cisco Umbrella API key

--secret=SECRET 

Cisco Umbrella secret to be used with the API key

--company-key=COMPANY_KEY,
--company_key=COMPANY_KEY

Lumu Defender API key

--logging=LOGGING

Logging option (default screen)

-v, --verbose

Verbosity of the log (default None)

-t, --use-saved-timestamp

To use the saved timestamp from the latest adversary contact, if any

--hours=HOURS

To specify a number of past hours

--from=FROM

To specify a specific “from” date

--adversary-types=ADVERSARY-TYPES

To specify the adversary type to filter (case-sensitive). Possible values are: C2C, Malware, DGA, Mining, Spam, Phishing

 

Usage examples

We provide here some examples of how to use the script:

Task: query and add all adversarial data for the last 30 days

Use the following command for querying and posting to Umbrella all adversarial data found in your organization by Lumu in the last 30 days:

<umbrella_lumu_root>/python lumu-adversaries-to-umbrella.py "destination-list" --org-id XXXXXX --key YYYYYYYY --secret XXxxxXXXxxxxXXX --company-key ZZZZZZZZZ 

Task: query and add all adversarial data since the last runtime

For control purposes, the script stores the latest runtime in a file called timestamp.stmp . If it is the first time you run the script, you will automatically get all the data of the last 30 days. The next time you run this query, it will get the latest runtime timestamp from the timestamp.stmp file.

<umbrella_lumu_root>/python lumu-adversaries-to-umbrella.py "destination-list" --org-id XXXXXX --key YYYYYYYY --secret XXxxxXXXxxxxXXX --company-key ZZZZZZZZZ --use-saved-timestamp

To ignore the saved timestamp, remove the --use-saved-timestamp flag.

Task: Query and add all adversarial data of the last X hours

Use the following command to query all adversarial data from your Lumu subscription for the specified numbers of hours:

<umbrella_lumu_root>/python lumu-adversaries-to-umbrella.py "destination-list" --org-id XXXXXX --key YYYYYYYY --secret XXxxxXXXxxxxXXX --company-key ZZZZZZZZZ --hours X

Task: query and add all adversarial data since a specific date

For filtering data from a specific date, use the flag --from followed by a date string in the standard format published in RFC 3339 and ISO 8601: YYYY-MM-DDTHH:mm:ss:sssZ.

<umbrella_lumu_root>/python lumu-adversaries-to-umbrella.py "destination-list" --org-id XXXXXX --key YYYYYYYY --secret XXxxxXXXxxxxXXX --company-key ZZZZZZZZZ --from 2021-05-01T00:00:00.000Z

Task: filter adversarial types

To query filtered adversarial types before adding them to your Cisco Umbrella's destination list, use the parameter --adversary-types followed by a list of the adversarial types separated by commas.

For this particular example, the adversary types to filter are C2C , Phishing , and DGA :

<umbrella_lumu_root>/python lumu-adversaries-to-umbrella.py "destination-list" --org-id XXXXXX --key YYYYYYYY --secret XXxxxXXXxxxxXXX --company-key ZZZZZZZZZ --hours 24 --adversary-types C2C,Phishing,DGA

Task: save output to file

Use the parameter --logging file to store a record of all tasks run. With this parameter, all the script output will be redirected to a file named lumu.log in the root of the selected path for the deployment of the script ( <umbrella_lumu_root> ).

<umbrella_lumu_root>/python lumu-adversaries-to-umbrella.py "destination-list" --org-id XXXXXX --key YYYYYYYY --secret XXxxxXXXxxxxXXX --company-key ZZZZZZZZZ --hours 24 --logging file

Expected results

For each script run, it is expected that the defined Destination List will be populated with more indicators, as in the following example:


Cisco Umbrella Destination ListFigure 2 - Cisco Umbrella Destination List.

Further considerations

To run this script on a timely-basis, consider implementing a Scheduled job in Windows or a cron task in Unix-based systems. We recommend using the --use-saved-timestamp flag to query and add different adversarial data for each runtime.

Troubleshooting

Use the -v flag to investigate errors on the script. This will provide you with details for identifying failures in the script execution.


        • Related Articles

        • Cisco Umbrella Out-of-the-box Response Integration

          The Lumu Defender API offers a framework to help you leverage Lumu’s integrations with your existing cybersecurity stack, including Security Information and Event Management (SIEM); Security Orchestration, Automation, and Response (SOAR); Endpoint ...
        • Defender API

          Some enterprises may already be using diverse defense solutions such as Security Information and Event Management (SIEM), Security Orchestration, Automation, and Response (SOAR) technologies, etc. Lumu provides an easy-to-use and comprehensive API ...
        • Crowdstrike Response Integration with Lumu Defender API

          The Lumu Defender API offers a framework to help you leverage Lumu’s integrations with your existing cybersecurity stack, including Security Information and Event Management (SIEM), Security Orchestration, Automation, and Response (SOAR), Endpoint ...
        • VMWare Carbon Black EDR Response Integration with Lumu Defender API

          This article shows how to leverage adversarial information from Lumu and feed Carbon Black Reports to VMWare Carbon Black EDR. Figure 1 - Data collection setup from VMWare Carbon Black EDR to Lumu The Lumu Defender API offers a framework to help you ...
        • Palo Alto Next-Gen Firewall Integration with Lumu Defender API

          The Lumu Defender API offers a framework to help you leverage Lumu’s integrations with your existing cybersecurity stack, including Security Information and Event Management (SIEM), Security Orchestration, Automation, and Response (SOAR), Endpoint ...