Skip to content

Cisco Umbrella Integration Guide๐Ÿ”—

The following instructions are for configuring a Cisco Umbrella integration to facilitate log ingestion into Secureworksยฎ Taegisโ„ข XDR.

XDR supports two integration paths for Umbrella log ingestion:

  • (Preferred) Integrate via Cisco-Managed S3 Bucket โ€” This option is preferred as it does not require any XDR components to be deployed in your environment to enable log ingestion.
  • Integrate via Customer-Managed S3 Bucket โ€” This option provides equivalent data to the Cisco-Managed S3 integration, but requires deployment of the XDR Lambda function in your AWS environment.

Data Provided from Integrations๐Ÿ”—

Normalized Data Out-of-the-Box Detections Vendor-Specific Detections
Cisco Umbrella   DNS, HTTP, Netflow  

Note

XDR detectors are not guaranteed to be triggered, even if a data source's logs are normalized to a schema associated with a given detector. However, you can create Custom Detection Rules to generate detections based on normalized data from a data source.

Start Cisco-Managed S3 Integration๐Ÿ”—

Prerequisites๐Ÿ”—

The following tasks must be completed in the Umbrella console prior to beginning the integration in XDR. Follow the instructions in the vendor documentation to configure Umbrella to log to a Cisco-managed S3 bucket.

  1. Select Use Cisco-managed Amazon S3 storage.
  2. Select a Region that is closest to the XDR environment in which your tenant resides.
Taegis Environment AWS Region
US1 US East (Ohio)
US2 US East (Ohio)
US3 US West (Oregon)
EU Europe (Frankfurt)
  1. Select any Retention Duration value.
  2. Click Save and Continue.

When activation is complete, a summary page displays. Copy the Data Path, Access Key, and Secret Key values to a safe location. These values will be used to complete the Umbrella integration in XDR.

Important

The Data Path must be in the format: cisco-managed-<Region>/<ID>. For example, cisco-managed-us-west-1/2069997_6ff2802af17337def701c2e7816cf14913zf848a.

Add Integration in XDR๐Ÿ”—

  1. From the Taegis Menu, select Integrations โ†’ Cloud APIs.

  2. Select Add an Integration from the top of the page.

    Add an Integration

  3. From the Optimized tab, select Cisco Umbrella.

    Set up Cisco Umbrella Integration

  4. Enter the following fields:

    • Taegis Integration Name โ€” Any unique string
    • Cisco Umbrella Access Key โ€” Generated in the Prerequisites section
    • Cisco Umbrella Secret Key โ€” Generated in the Prerequisites section
    • Cisco Umbrella Data Path โ€” Generated in the Prerequisites section

  5. Select Done. The Cloud API Integrations table displays the successfully added Cisco Umbrella integration.

Start Customer-Managed S3 Integration๐Ÿ”—

Note

If you do not have login access to XDR, have someone who does help you complete any steps that require access. You can also contact your Secureworksยฎ representative for help.

  1. From the Taegis Menu, select Integrations โ†’ Cloud APIs.

  2. Select Add an Integration from the top of the page.

    Add an Integration

  3. From the Optimized tab, choose AWS and then select Setup under Cisco Umbrella.

    Set up Cisco Umbrella Integration

  4. Select Download CloudFormation Shared Resources and save it as taegis-cloudformation-shared-resources.yaml.

  5. Select Download CloudFormation Lambda Template and save it as taegis-cloudformation-lambda-template.yaml.

  6. Select Download Lambda; the file should be named taegis-lambda-amd64.zip.

  7. Select Download Credentials.

  8. Select Create after you have downloaded all files.

Create an S3 Bucket for Cisco Umbrella๐Ÿ”—

  1. Follow the instructions in the Cisco Umbrella documentation, Enable Logging to Your Own S3 Bucket.
  2. The bucket you create will be the NotificationBucket parameter in the CloudFormation template.

Upload the Lambda Executable and CloudFormation Templates to S3๐Ÿ”—

  1. Log in to the AWS Console for the region (e.g., https://us-east-1.console.aws.amazon.com/cloudformation) with an account that has permissions to create roles, lambdas, secrets, and policies, or using a role that can assume another role with these permissions.
  2. In the Storage section, select S3.
  3. Create a new bucket or locate an existing bucket in which to store the Lambda executable and, optionally, the CloudFormation templates. The bucket does not need to be public, versioned, or encrypted.
  4. Upload the Lambda taegis-lambda-amd64.zip to the root of the bucket and take note of the bucket name.

  5. Optionally upload taegis-cloudformation-shared-resources.yaml and taegis-cloudformation-lambda-template.yaml to the same bucket.

    Tip

    Take note of the bucket name and the key, including any prefix. These identifiers are needed when you create a stack.

Create a Shared Resources Stack in Each AWS Region That Will Contain a Lambda Deployment๐Ÿ”—

Important

The Shared Resources Stack (Steps 1-11) only needs to be deployed once per AWS region.

  1. Log in to the AWS Console for the region (e.g., https://us-east-1.console.aws.amazon.com/cloudformation) with an account that has permissions to create roles, lambdas, secrets, and policies, or using a role that can assume another role with these permissions.
  2. In the Management and Governance section, select CloudFormation.

  3. Select Create Stack to create a new stack using the taegis-cloudformation-shared-resources.yaml template provided.

    Note

    You might see a list of CloudFormation stacks when you select CloudFormation like the following image. If that is the case, select the Create Stack drop-down and choose With new resources (standard).

    Create New Stack

  4. From the Prepare Template section, choose Template is ready.

  5. From the Specify Template section, choose Amazon S3 URL OR choose Upload a template file.

  6. If you choose Amazon S3 URL, input the CloudFormation object URL gathered previously into the Amazon S3 URL field. For example, https://cwl-poc.s3.amazonaws.com/taegis-cloudformation-shared-resources.yaml.

    To find the URL, navigate to the S3 service and open the S3 bucket to which the taegis-cloudformation-shared-resources.yaml file was uploaded. Select the CloudFormation template then click Copy URL.

    Copy CloudFormation URL

  7. Select Next.

  8. Enter an appropriate stack name.

    Note

    Spaces are not allowed in stack names.

  9. Enter the contents of the credentials.txt file into the SecretValue field.

  10. Select the correct TaegisRegion based off of your XDR login URL; for example, select ctpx if you use https://ctpx.secureworks.com/login or foxtrot if you use https://foxtrot.taegis.secureworks.com/.
  11. Select Next.
  12. On the Configure stack options page, the default selections and values can be accepted. Select Next.
  13. On the Review and create page, select Submit.

Create the Lambda Stack๐Ÿ”—

Note

The AWS Lambda function uses the following two secret tokens to communicate with the Taegisโ„ข XDR API:

  • A short-lived token that expires every 10 hours and is rotated by XDR
  • Long-lived credentials that do not expire
  1. Log in to the AWS Console for the region (e.g., https://us-east-1.console.aws.amazon.com/cloudformation) with an account that has permissions to create roles, lambdas, secrets, and policies, or using a role that can assume another role with these permissions.
  2. In the Management and Governance section, select CloudFormation.

  3. Select Create Stack.

    Note

    You might see a list of CloudFormation stacks when you select CloudFormation like the following image. If that is the case, select the Create Stack drop-down and choose With new resources (standard).

    Create New Stack

  4. From the Prepare Template section, choose Template is ready.

  5. From the Specify Template section, choose Amazon S3 URL OR choose Upload a template file.

  6. If you choose Amazon S3 URL, input the CloudFormation object URL gathered previously into the Amazon S3 URL field. For example: https://cwl-poc.s3.amazonaws.com/taegis-cloudformation-lambda-template.yaml.

    To find the URL, navigate to the S3 service and open the S3 bucket to which the taegis-cloudformation-lambda-template.yaml file was uploaded. Select the CloudFormation template, then click the Copy URL button.

    Copy CloudFormation URL

  7. Select Next.

  8. Enter an appropriate stack name.

    Note

    Spaces are not allowed in stack names.

  9. Select IntegrationType from the dropdown. This describes what sort of log objects are in the NotificationBucket. If more than one type, or you are not sure, select generic.

    Update Lambda Stack Integration Type

  10. In the field NotificationBucket, enter the bucket name, not a URL or URI, that houses the logs.

  11. (Optional) Enter the appropriate value into the SNSNotificationarn field if you wish to use SNS notifications going forward instead of S3 notifications.
  12. (Optional) Enter the appropriate value into the NotificationBucketCustomerManagedKMSarn if you wish to add the KMS key ARN that may be encrypting the objects in the NotificationBucket. The KMS key policy must have Enable IAM User Permissions. If not, the Lambda ARN can be added to your KMS key.
  13. The field TaegisLambdaS3BucketName should be the name of the S3 bucket that contains the Lambda that was previously uploaded.
  14. The field LambdaEnvKMSarn can be left empty. If populated, the KMS key must have Enable IAM User Permissions.
  15. The field EnableObjectTagging will enable tagging of processed objects if set to true. For more information, see AWS Lambda Lifecycle Policy Management.
  16. The remaining fields can be left at their defaults.
  17. Select Next.

Complete Remaining Stack Options๐Ÿ”—

  1. The configure stack options page is optional.
  2. Select Next.

  3. Review all parameters. Make sure that all fields you have specified from Step 9 through Step 15 have a valid value.

    Review Lambda Parameters

  4. Select the I acknowledge that AWS CloudFormation might create IAM resources checkbox and choose Submit.

  5. Wait at least 30 seconds and then select the refresh button. The process may take a minute or more to finish. A status of CREATE_COMPLETE for the stack indicates the process has finished. Discard the credential.txt file containing the client_id and client_secret downloaded in the Set Up section. These values are now stored in the AWS SecretsManager.

Add the Lambda Trigger๐Ÿ”—

  1. In the AWS console, switch to the Lambda service.
  2. Locate the new Lambda by name. The default name is {STACKNAME}-scwx-tdr-lambda-{INTEGRATIONTYPE}. For example: ct-demo-scwx-tdr-lambda-awscloudtrail.
  3. Select the Lambda name. The edit page for that Lambda displays.
  4. Expand the Function overview section and choose Add Trigger.
  5. In the Trigger Configuration editor, select the drop-down menu and choose S3. Optionally, use an SNS trigger configured with a previously created topic.
  6. From the Bucket options, find the bucket containing the logs and select it.
  7. From the Event Type options, choose All Object Create Events.
  8. In the prefix field, enter the bucket prefix where the logs are located. Leave this blank if no prefix is used.
  9. Leave the suffix field blank.
  10. Check the following box to acknowledge the cost impact of a lambda function.
  11. Choose Add. The configuration page for that lambda displays again. A message displays at the top indicating adding a trigger was successful; for example, The trigger wmikeking was successfully added to function Logs-TDR-Upload.

  12. The function is now receiving events from the trigger.

    Important

    AWS Lambda Concurrency Guidance๐Ÿ”—

    The Reserved Concurrency value set by the Taegis XDR CloudFormation template (taegis-cloudformation-lambda-template.yaml) is 5. For more information regarding Lambda concurrency and the calculation of a value appropriate for your environment, please reference Lambda function scaling in AWS Docs.

    Please reference the following AWS documentation to the identify the values to be used in the concurrency calulation:

    AWS Concurrent Execution Limit๐Ÿ”—

    If you see the following Rate Exceeded error when running your Lambda, you need to request a quota increase from AWS to raise your concurrent execution limit. For more information, see Lambda quotas in AWS Docs.

    AWS Lambda Concurrent Execution Limit Error

Verification Steps๐Ÿ”—

  1. Verify Lambda Runtime settings. The Runtime value should be Custom runtime on Amazon Linux 2.

    Verify Lambda Runtime Settings

  2. See Test AWS Lambda Logs to verify that the AWS Lambda function for your integration is working by configuring a test for it in the AWS Console.

  3. In the AWS console, go to the Lambda function that was installed. If there is an error, select Fix errors.

    Fix Lambda Errors

  4. See View AWS Lambda Logs to view logs generated by your AWS Lambda functions and verify successful uploads. This verifies the trigger is working, on the assumption there is new S3 data being published to the bucket.

    {"level":"debug","time":"2023-11-15T19:27:19Z","message":"Uploading data to s3"}

Download Existing Integration Setup Files๐Ÿ”—

If you need to add your integration to many regions or completely redo the integration, you can download the existing set of integration files including the templates, Lambda, and credentials files at any time.

  1. From the Taegis XDR menu, navigate to Integrations โ†’ Cloud APIs.
  2. From the Cloud API Integrations table, click the download icon from the Actions column in the row of the integration you want to redo/modify.

  3. Select the Download Integration icon. The Download panel appears.

    Download Existing Integration Files

  4. Download any needed files.

Centralized Umbrella Log Management๐Ÿ”—

Read more about Ciscoโ€™s approach to Centralized Umbrella Log Management with Amazon's S3 service for MSP, MSSP, and Multi-org customers.