v1.1.1 Carbon Black Cloud Splunk App Installation and Configuration

V1.1.1 and earlier versions have been deprecated.

v2.0.0 was release in January 2024 with support for new APIs. The APIs used in v1.1.1 and earlier for Alerts and Live Response will be deactivated on July 31st 2024. Please upgrade to v2 of the Carbon Black Cloud Splunk App prior to 31st July 2024.

For information on upgrading your application, please see TO DO PUT LINK TO UPGRADE INSTRUCTIONS.

For information on APIs and Access Level types that are deprecated and will be deactivated in the second half of 2024, see the Migration Guides.

The VMware Carbon Black Cloud App for Splunk is a single application to integrate your endpoint and workload security features and telemetry directly into Splunk dashboards, workflows and alert streams.

This application connects with any Carbon Black Cloud offering and replaces the existing product-specific Carbon Black Cloud apps for Splunk. This app provides a unified solution to integrate Carbon Black Cloud Endpoint and Workload offerings with Splunk Enterprise, Splunk Cloud, and Splunk Enterprise Security (ES). Out-of-the-box, this app provides holistic visibility into the state of your endpoints and workloads through customizable dashboards and alert feeds in Splunk.

Requirements

  • Splunk Enterprise 8.1, 8.2, 9.0 or Splunk Cloud
  • Splunk CIM Add-on

Use Cases

This app realizes many key SOC use cases, from conventional SIEM to XDR:

  • Use Splunk as a single pane of glass for your Carbon Black Cloud alerts
    • Triage and investigate from Splunk, or pivot back to the Carbon Black Cloud console
  • Automate workflows with built-in SOAR capabilities
    • Enrich alerts with event or process context
    • Kick off Live Response and Live Query actions to gather information directly from endpoints
    • Remediate critical issues by killing a process or banning hashes from future execution
  • Bring full EDR visibility to Splunk
    • Endpoint Events enable your SOC to perform threat hunting, conduct forensic investigations, and build custom analytics

Deployment Guide

Warning: Installing the VMware Carbon Black Cloud Technology Add-on (TA) or Input Add-on (IA) on the same node as the App is an unsupported configuration that may result in instability or errors.

Depending on your Splunk configuration and version, the VMware Carbon Black Cloud app, Technology Add-on (TA), and Input Add-on (IA) need to be installed on specific Splunk instances. See the following sections as to where each component is installed.

Note: This app has not been reviewed for FedRAMP Compliance for use in the AWS GovCloud (US) environment. Please reach out to Carbon Black Cloud Support for further information.

Distributed App Configuration

In a distributed environment the app and add-ons only support a subset of configuration as each Splunk component provides specific functionality.

The Heavy Forwarder is where Splunk will ingest data from the Carbon Black Cloud, the Indexer will process the incoming data and apply the CIM compliant models, and the Search Head provides the graphical search interface that allows you to interact with the data through dashboards, alert actions and custom commands.

  • Search Head - vmware_app_for_splunk

    • VMware CBC Base Configuration
    • Proxies
    • API Token Configuration
    • Alert Actions
    • Custom Commands

  • Heavy Forwarder - IA-vmware_app_for_splunk

    • Proxies
    • API Token Configuration
    • Built-in Inputs (Alert Inputs, Audit Log Inputs, Live Query Inputs, and Vulnerabilities Inputs)

Note: If you are using the Data Forwarder to ingest Alerts and Events then you will need to install and configure the Splunk AWS Add-on.

  • Indexer - TA-vmware_app_for_splunk
    • No additional configuration needed beyond installation for CIM compliant models

App Setup and Configuration

An updated Setup Video](https://carbonblack.vmware.com/resource/data-forwarder-splunk-configuration) for an in depth walk through of the following sections.

The VMware Carbon Black Cloud App offers two methods to ingest data. Each method supports a subset of the Carbon Black Cloud data which is outlined below.

Built-In Input

  • Use the VMware Carbon Black Cloud App (or Input Add-on via a Heavy Forwarder), which leverages VMware Carbon Black Cloud REST APIs to pull data into Splunk
  • Supported Data
    • Alerts
    • Audit Logs
    • Live Query Results
    • Vulnerabilities

Data Forwarder

  • Streams data into an AWS S3 bucket at scale
  • Uses the AWS Add-on for Splunk to pull the data from AWS S3 into Splunk
  • Supported Data
    • Alerts Recommended for orgs with high volumes
    • Endpoint.Events

Authentication & Authorization

For built-in data inputs, alert actions, and commands, create API Key(s) with the correct permissions in the Carbon Black Cloud and then configure Splunk to use those keys.

  1. Identify the built-in data inputs, alert actions, and commands you intend to use.

  2. Reference Tables 1, 2, and 3 below to identify the required API Key Access Levels and RBAC Permissions.

  3. If Identity is managed in Carbon Black Could: Generate API Keys in the Carbon Black Cloud console under Settings –> API Access. Refer to the VMware Carbon Black Cloud Authentication Guide for additional guidance.

    1. Access Level

      If you are using any functions that require an Access Level Type “Custom”, create a Custom Access Level with the permissions required for the Inputs and Actions you want to use. The tables below list the necessary permissions that must be included in your Custom Access Level for each Action.

    2. API Keys

      You may need multiple API Keys depending on the Inputs and Actions you want to use because a different API key is required for each Access Level Type used (Custom, API, Live Response).

      1. For Custom Access Levels create one API key with Access Level set to Custom, then select the Access Level you created in step 1
      2. If needed, create one API key with the Access Level set to Live Response
      3. If needed, create one API key with the Access Level set to API

    3. ORG KEY

      Remember your organization’s Org Key from the top of the API Keys table for later steps.

  4. If Identity is managed in VMware Cloud Services Platform: Create OAuth Apps in the VMware Cloud Services Platform. Refer to the VMware Carbon Black Cloud Authentication Guide for additional guidance.

    Use the App Id in the API Id field, and App Secret in the API Key.

    1. Custom Role

    If you are using any functions that require an Access Level Type “Custom”, create a Custom Role with the permissions required for the Inputs and Actions you want to use. The tables below list the necessary permissions that must be included in your Custom Role for each Action.

    1. OAuth App - replace API Keys

      You may need multiple OAuth Apps depending on the Inputs and Actions you want to use because a different API key is required for each Access Level Type used (Custom, API, Live Response).

      1. For Custom Access Levels create one OAuth App with the custom role created in step 1
      2. If needed, create one OAuth App with the service role “Connector Live Response”
      3. If needed, create one OAuth App with the service role “Connector API”

    2. ORG KEY

      Get your organization’s Org Key from Carbon Black Cloud on the Settings –> General page for later steps.

  5. In Splunk, navigate to the Administration –> Application Configuration menu in the VMware Carbon Black Cloud App.

    1. On the API Token Configuration tab, create a new API configuration by clicking the + in the top right corner.

    2. Give the configuration meaningful API Name and Organization Name. You’ll use this to configure Alert Inputs and Actions.

    3. Enter the Org Key, API ID (or OAuth App Id), and API Secret Key (or OAuth App Secret) from step 3 (or 4).

    4. The CBC Environment is the hostname of the Carbon Black Cloud console your organization is provisioned e.g. defense.conferdeploy.net.

    Repeat steps 2-4 for each API Key you created from step 3 or 4.


Access Levels & Permissions

The following tables indicate which type of API Key access level is required. If the type is Custom then the permission that is required will also be included.

Table 1: API Data Inputs

Inputs Description Access Level and Permissions Data Schema
Alerts API Alerts indicate suspicious behavior and known threats in your environment. Use the Data Forwarder option instead when you have a high volume or significant bursts as the Data Forwarder provides higher scalability. Custom org.search.events (Read, Create) Alert Schema
Auth Eventss API Auth Events API provides visibility into authentication events that occur on Windows endpoints. Custom orgs.alerts (Read) Alert Schema
Audit Logs Carbon Black Cloud Audit Logs, such as when a user signs-in or updates a policy API or Live Response Audit Log Schema
Live Query Results LiveQuery Run and Result data. Requires VMware Carbon Black Cloud Audit & Remediation Custom livequery.manage (Read) LiveQuery Result Schema
Vulnerabilities Vulnerability assessment data including identified CVEs, metadata, and impacted assets. Requires VMware Carbon Black Cloud Workload Protection Custom vulnerabilityAssessment.data (Read) Vulnerabilty Schema

Table 2: Alert Actions/Adaptive Responses

Alert Action Description Access Level and Permission
Add IOCs to a Watchlist Adds specified IOC(s) to a specified report in a watchlist. Requires VMware Carbon Black Cloud Enterprise EDR Custom orgs.watchlist (Create, Read, Update)
Remove IOCs from a Watchlist Removes IOCs from a report in a watchlist. Requires VMware Carbon Black Cloud Enterprise EDR Custom orgs.watchlist (Read, Update, Delete)
Get File Metadata Retrieves file metadata, such as the number of devices the hash was observed on, from the specified sha256 file hash. Requires VMware Carbon Black Cloud Enterprise EDR Custom ubs.org.sha256 (Read)
Ban Hash Prevents a sha256 hash from being executed in Carbon Black Cloud. Currently requires Endpoint Standard; Enterprise EDR support expected CY21Q2. Custom org.reputations (Create)
Kill Process Remotely kills a process on the devices specified in the search Live Response
List Processes Remotely lists processes on the specified device. Example: If an Analytics alert did not terminate the process, identify if the suspicious process is still running on the device. Live Response
Quarantine Device Quarantines the specified device and prevents suspicious activity and malware from affecting the rest of your network. The device can only communicate with Carbon Black Cloud until unquarantined Custom device (Read), Custom device.quarantine (Execute)
Un-quarantine Device(s) Removes the specified device(s) from the quarantined state, allowing them to communicate normally on the network. Custom device (Read), Custom device.quarantine (Execute)
Update Device Policy Updates the policy associated with the specified device. Example: move a device to a more restrictive policy during incident investigation Custom device (Read), Custom device.policy (Update)
Dismiss Alert Dismisses the specified alert in Carbon Black Cloud Custom org.alerts (Read), Custom org.alerts.dismiss (Execute)
Enrich Alert with Observation Searches and ingests the Observations that are associated with the alert. Intended for use with the “Enrich CB Alert Observations” Splunk Alert. Custom org.search.events (Create, Read)
Enrich CB Analytics Event Searches and ingests the Enriched Events that are associated with the CB Analytics alert. Intended for use with the “CB Analytics - Ingest Enriched Events” Splunk Alert. Requires VMware Carbon Black Cloud Endpoint Standard Custom org.search.events (Create, Read)
Process GUID Details Fetches the most up to date, detailed metadata associated with the specified process GUID. Example: learn more about the process that triggered a Watchlist alert, such as parent and process cmdline Example: learn more about the process that triggered a Watchlist alert. Custom org.search.events (Read, Execute)
Run Livequery Creates a new LiveQuery Run. Example: Automatically get the logged in users on an endpoint after a credential scraping alert. Requires VMware Carbon Black Cloud Audit & Remediation Custom livequery.manage (Create, Read)

Table 3: Commands

Command Description Access Level and Permission
VMware CBC Device Info (cbcdvcinfo) Gets real-time information about a CBC device. See Custom Commands section below for usage and best practices Custom device (Read)
VMware CBC Hash Info (cbchashinfo) Gets real-time information about a sha256 hash, such as the number of devices that observed the file. Requires Enterprise EDR. Custom ubs.org.sha256 (Read)

Built-in Input Configuration

Ensure that you have correctly deployed the Apps and/or Add-ons per the Deployment Guide before attempting any configuration.

  1. Create two Event index(s) for your data.

    • One index for the Carbon Black Cloud data e.g. carbonblackcloud
    • One index for the results of the Alert Actions e.g. vmware_actions

    For instructions on creating an Index see the Splunk documentation

  2. Navigate to the Administration –> Application Configuration menu in the VMware Carbon Black Cloud App

  3. On the VMware CBC Base Configuration tab set the VMware CBC Base Index and VMware CBC Action Index to the index names from step 1 including index= e.g. index=carbonblackcloud

  4. [Optional] Configure a proxy if needed on the Proxies tab

  5. If you have not already configured any API Configurations in Splunk see the Authentication & Authorization section

  6. Depending on what inputs you want to configure see the corresponding section:

    • Alerts

      • Data Forwarder

        See Data Forwarder Input Configuration

      • API

        1. Navigate to the Alerts Inputs tab in the Application Configuration menu

        2. Create a new configuration by clicking the + in the top right corner

        3. Enter a name for this configuration

        4. Set the Minimum Severity to the desired level Default: 4

        5. Select the desired Alert types Default: All

          Note: Don't select 'All' if you don't have both Endpoint Standard and Enterprise EDR

        6. Select the Custom API Token configured in the Authentication & Authorization section

          Note: Ensure your Splunk access level has the permissions specified in Table 1 above for 'Alerts API'

        7. [Optional] Select the proxy configured in step 4

        8. Set Lookback to 0 unless you need to retrieve data from the previous day(s) Default: 7 days

        9. Set the index equal to the Base Index name from VMware CBC Base Configuration e.g. carbonblackcloud

          Note: Do not include 'index='

        10. Set the Interval to the desired poll cycle Default: 300 seconds

          Note: If your organization generates a significant amount of alerts, consider using the Data Forwarder option

        11. [Optional] Add a query to refine the alerts that will be ingested

          Note: The query uses the same syntax as the 'Alerts' page in the Carbon Black Cloud console

    • Audit Logs

      1. Navigate to the Audit Log Inputs tab in the Application Configuration menu

      2. Create a new configuration by clicking the + in the top right corner

      3. Enter a name for this configuration

      4. Select the API or Live Response API Token configured in the Authentication & Authorization section

      5. [Optional] Select the proxy configured in step 4

      6. Set the index equal to the Base Index name from VMware CBC Base Configuration e.g. carbonblackcloud

        Note: Do not include 'index='

      7. Set the Interval to the desired poll cycle Default: 300 seconds

    • Auth Events

      • API

        1. Navigate to the Auth Events Inputs tab in the Application Configuration menu

        2. Create a new configuration by clicking the + in the top right corner

        3. Enter a name for this configuration

        4. Select the Custom API Token configured in the Authentication & Authorization section

          Note: Ensure your Splunk access level has the permissions specified in Table 1 above for 'Auth Events API' Note: This requires Enterprise EDR to be enabled

        5. [Optional] Select the proxy configured in step 4

        6. Set Lookback to 0 unless you need to retrieve data from the previous day(s) Default: 7 days

        7. Set the index equal to the Base Index name from VMware CBC Base Configuration e.g. carbonblackcloud

          Note: Do not include 'index='

        8. Set the Interval to the desired poll cycle Default: 300 seconds

          Note: If your organization generates a significant amount of alerts, consider using the Data Forwarder option

    • Events

      • Data Forwarder

        See Data Forwarder Input Configuration

      • Alert Action

        See the Enrich CB Analytics Event Alert Action for ingesting Enriched Events associated with CB Analytic Alerts

    • Live Query Results

      1. Navigate to the Live Query Inputs tab in the Application Configuration menu

      2. Create a new configuration by clicking the + in the top right corner

      3. Enter a name for this configuration

      4. Select the Custom API Token configured in the Authentication & Authorization section

        Note: Ensure your Splunk access level has the permissions specified in Table 1 above for 'Live Query Results'

      5. [Optional] Select the proxy configured in step 4

      6. Set Lookback to 0 unless you need to retrieve data from the previous day(s) Default: 7 days

      7. Set the index equal to the Base Index name from VMware CBC Base Configuration e.g. carbonblackcloud

        Note: Do not include 'index='

      8. Set the Interval to the desired poll cycle Default: 300 seconds

      9. Add a Result query to refine the results that will be ingested e.g. * for all results

        Note: The query uses the same syntax as the 'Live Query' -> 'Query Results' page in the Carbon Black Cloud console

    • Vulnerabilities

      1. Navigate to the Vulnerabilities Inputs tab in the Application Configuration menu

      2. Create a new configuration by clicking the + in the top right corner

      3. Enter a name for this configuration

      4. Set the Minimum Risk to the desired level Default: 7

      5. Select the Custom API Token configured in the Authentication & Authorization section

        Note: Ensure your Splunk access level has the permissions specified in Table 1 above for 'Vulnerabilities'

      6. [Optional] Select the proxy configured in step 4

      7. Set the index equal to the Base Index name from VMware CBC Base Configuration e.g. carbonblackcloud

        Note: Do not include 'index='

      8. Set the Interval to the desired poll cycle Default: 300 seconds

      9. [Optional] Add a query to refine the vulnerabilities that will be ingested

        Note: The query uses the same syntax as the 'Vulnerabilities' page in the Carbon Black Cloud console

Data Forwarder Input Configuration

A Data forwarder must be created in order for the Carbon Black Cloud to stream data externally. The forwarder will be responsible for routing data to an S3 bucket where it can then be taken as input by Splunk using the AWS input add-on.

Requirements

  • The AWS add-on for Splunk is required for configuring inputs from an AWS source
  • For each data type (Alerts and Events) you want to bring into Splunk you will need the following
    • An AWS S3 bucket
    • An AWS SQS queue
    • A Carbon Black Cloud Data Forwarder
Note: You can configure more than one forwarder for each type if you have complex filtering needs.

Create a Data Forwarder

Configure your forwarder with filters to limit the amount of event data forwarded to Splunk in order to reduce costs. The forwarder can be created via Carbon Black Cloud Console under Settings –> Data Forwarders or the Carbon Black Cloud Data Forwarder API.

For more detailed instructions on setting up a Data Forwarder using the APIs see the following:

Note: The same forwarder cannot be used for both Alerts and Events. Create a separate forwarder for each type of data you want to forward.

Configure AWS Add-On

Before configuring the AWS inputs, make sure that the AWS add-on is installed in your Splunk environment. For instructions on installing the AWS add-on see the Splunk documentation.

The recommended approach to ingest Carbon Black Cloud Data Forwarder data into Splunk is the SQS-based S3 data input.

Configuring an input in the AWS add-on to pull Carbon Black Cloud data using SQS-based S3

  1. Configure your AWS account on the Configuration page in the AWS Add-on
  2. In the AWS Add-on, create a new input on the Inputs page by selecting Create New input -> Custom Data Type -> SQS-based S3

    1. Specify a name that should be used for this input

    2. Select the AWS account you configured with the AWS Add-on

    3. [Optional] If you configured IAM roles when configuring your AWS account select the created role

    4. Select the AWS Region where you configured the SQS queue and S3 bucket

    5. Select the SQS queue from the dropdown

      Note: If you don't see your SQS queue ensure you have selected the correct AWS region and the SQS queue was created in the region

    6. Set the batch size for Splunk to pull from your SQS queue Default: 10 messages

    7. Ensure the S3 File Decoder is set to Custom Logs

    8. Use one of the following Source Types depending on the data you configured for the forwarder

      • Set to vmware:cbc:s3:alerts for Alerts
      • Set to vmware:cbc:s3:events for Events


      Note: You will need to create separate inputs for Alerts and Events

    9. Ensure the index you select matches the base index configured in the VMware Carbon Black Cloud app

      Note: Alerts and Event should both be configured to the base index

    10. In Advanced Settings, you can increase the polling cycle for fetching messages from the SQS Default: 300 seconds

Note: If you need to reload older events and are using SQS to pull buckets, the events will not be available in the queue once they are retrieved. To view historical events or reload data, use the generic S3 option or copy the events to another prefix to copy it to the queue.

Support and Resources

Diagnostics Generation

Please include a support diagnostic file when creating a support ticket. Use the following command to generate the file based on which Splunk app or add-on is installed. Send the resulting file to support.

$SPLUNK_HOME/bin/splunk diag --collect=app:vmware_app_for_splunk
$SPLUNK_HOME/bin/splunk diag --collect=app:IA-vmware_app_for_splunk
$SPLUNK_HOME/bin/splunk diag --collect=app:TA-vmware_app_for_splunk

Last modified on August 17, 2023