v1.1.1 Carbon Black Cloud Splunk App - User Guide

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.

Initial Application Configuration

VMware Carbon Black Cloud is configured from the Application Configuration menu option under the Administration menu.

  • VMware Base Configuration

    The options configured on this tab will update settings in local/eventtypes.conf.

    • VMware Base Index: specifies where the Carbon Black Cloud data will be indexed and searched. Required on the searching tier.
    • VMware Action Index: specifies where outputs generated from alert actions will be stored and/or searched. Required on the searching tier.
    • Data model acceleration: enables acceleration for the VMWare_CBC data model for quicker pivot searches
    • Use data model summaries only: enables the dashboards to use summary information from the VMWare_CBC data model accelerations for quicker load times

  • API Configurations

    Use this tab to configure access to Carbon Black Cloud. The application supports multiple API Configurations to enable data from multiple Carbon Black Cloud organizations to be ingested.


  • Alert Inputs

    Use this tab to configure inputs that will pull alerts using the Carbon Black Cloud APIs. If you configure the alert input on this tab do not also configure alerts using the Data Forwarder/AWS Add-on. Doing so will result in duplicate alert entries. The alert input uses the Carbon Black Cloud Alerts API

    • Name: The generic name the input should be named.
    • Active: A checkbox to enable or disable the input.
    • Minimum Severity: The minimum severity level that will be pulled from the API
    • Type: The types of alerts to pull from the API. Note: Don't select 'All' if you don't have both Endpoint Standard and Enterprise EDR.
    • API Token: The API Key from the API Token Configuration tab to use for the API authorization. See Table 1 for required permissions.
    • Proxy: The proxy configuration, if needed.
    • Lookback (days): The number of historical days to pull from the API on initial configuration.
    • Index: The Splunk Index in which to store the data. Note: This should match value of the 'VMware Base Index' on the 'VMware Base Configuration' tab.
    • Interval: The frequency (in seconds) that the API should poll for data. Range: 60-86400 Default: 300
    • Query: The Carbon Black Cloud compatible query to limit the Alert results. The same syntax as used by the search bar at the top of the Carbon Black Cloud console Alerts tab. Example: ttp:MITRE*

  • Audit Log Inputs

    Use this tab to configure inputs that will pull audit logs using the Carbon Black Cloud APIs. The alert input uses the CBC Audit Log Events

    • Name: The generic name the input should be named.
    • Active: A checkbox to enable or disable the input.
    • API Token: The API Key from the API Token Configuration tab to use for the API authorization. See Table 1 for required permissions.
    • Proxy: The proxy configuration, if needed.
    • Index: The Splunk Index in which to store the data. Note: This should match value of the 'VMware Base Index' on the 'VMware Base Configuration' tab.
    • Interval: The frequency (in seconds) that the API should poll for data. Range: 60-86400 Default: 300

  • Live Query Inputs

    Use this tab to configure inputs that will pull Live Query results using the Carbon Black Cloud APIs. The alert input uses the [CBC Live Query API

    Note: Limited to the first 10,000 results of a Live Query
    • Name: The generic name the input should be named.
    • Active: A checkbox to enable or disable the input.
    • API Token: The API Key from the API Token Configuration tab to use for the API authorization. See Table 1 for required permissions.
    • Proxy: The proxy configuration, if needed.
    • Lookback (days): The number of historical days to pull from the API on initial configuration.
    • Index: The Splunk Index in which to store the data. Note: This should match value of the 'VMware Base Index' on the 'VMware Base Configuration' tab.
    • Interval: The frequency (in seconds) that the API should poll for data. Range: 60-86400 Default: 300
    • Result Query: The Carbon Black Cloud compatible query to limit the LiveQuery results. The same syntax as used by the search bar at the top of the Carbon Black Cloud console “Live Query” -> “Query Results” tab. Example: NOT "Test" AND NOT "Chrome"

  • Vulnerabilities Inputs

    Use this tab to configure inputs that will pull alerts using the Carbon Black Cloud APIs. The alert input uses the CBC Vulnerability Data

    • Name: The generic name the input should be named.
    • Active: A checkbox to enable or disable the input.
    • Minimum Risk: The minimum risk level that will be pulled from the API
    • Query: The Carbon Black Cloud compatible query to limit the vulnerability results. The same syntax as used by the search bar at the top of the Carbon Black Cloud console Vulnerabilities tab. Example: CVE-2021
    • API Token: The API Key from the API Token Configuration tab to use for the API authorization. See Table 1 for required permissions.
    • Proxy: The proxy configuration, if needed.
    • Index: The Splunk Index in which to store the data. Note: This should match value of the 'VMware Base Index' on the 'VMware Base Configuration' tab.
    • Interval: The frequency (in seconds) that the API should poll for data. Range: 60-86400 Default: 300

  • Auth Events Inputs

    Use this tab to configure inputs that will pull Auth Events using the Carbon Black Cloud APIs. The auth event input uses the Carbon Black Cloud Auth Events API

    Requires Enterprise EDR for access to this data.

    • Name: The generic name the input should be named.
    • Active: A checkbox to enable or disable the input.
    • API Token: The API Key from the API Token Configuration tab to use for the API authorization. See Table 1 for required permissions.
    • Proxy: The proxy configuration, if needed.
    • Lookback (days): The number of historical days to pull from the API on initial configuration.
    • Index: The Splunk Index in which to store the data. Note: This should match value of the 'VMware Base Index' on the 'VMware Base Configuration' tab.
    • Interval: The frequency (in seconds) that the API should poll for data. Range: 60-86400 Default: 300

  • Alert Actions

    • See the Alert Actions section below for configuration details and considerations.

  • Custom Commands

    • See the Custom Commands section below for configuration details and usage examples.
Note: Do not modify any configurations in '/default'. Doing so will cause your changes to be overwritten when the app is upgraded. If required or directed to by support, create the appropriate configuration files in '/local' and include the stanza attributes that are being changed.

Optional: Create a Data Forwarder

Set up a Data Forwarder to get alerts, watchlist hits, and endpoint events from VMware Carbon Black Cloud to Splunk via AWS S3 & SQS.

Included Data Model

VMware Carbon Black Cloud includes a datamodel: VMWare_CBC. The VMWare_CBC data model is a clone of the Alert and Endpoint data models from the Splunk CIM. This data model is not accelerated by default, however accelerating this data model will improve dashboard performance.

The data model acceleration setting can be changed in the app under Administration -> Application Configuration. Check the setting Acceleration Enabled on the main tab. Make sure that the event types and macros for the app are configured prior to acceleration.

Macros

VMware Carbon Black Cloud includes the following macros that control dashboard searches.

  • vmware_tstats

    • This macro is the default macro used in all searches on this applications dashboards.

      By default it is configured as:

      tstats prestats=false local=false summariesonly='VMWare_CBC_summariesonly'`.

  • vmware_tstats_pre

    • This macro is the same as ‘vmware_tstats’ with the exception that prestats=true. To use this macro in dashboards replace vmware_tstats in all applicable dashboards.

  • VMWare_CBC_summariesonly

    • This macro controls if summariesonly should be set to true in the vmware_tstats and vmware_tstats_pre macros. By default summariesonly=false. Enabling summariesonly will improve the performance of searches on the dashboards in this app.

To enable summaries only create $SPLUNK_HOME$/etc/apps/vmware_app_for_splunk/local/macros.conf and add this stanza

[VMWare_CBC_summaries_only]
definition = "true"

Dashboards

The VMware Carbon Black Cloud app includes the following dashboards.

  • CBC Alerts Overview

    This dashboard is an overview of all alerts from the Carbon Black Cloud.

    • Requires the Alerts data source from either the Data Forwarder or built-in Alerts Input

  • CBC Endpoint Event Overview

    This dashboard is an overview of all endpoint events from the CBC appliance.

    • Requires the Endpoint Events data source via the Data Forwarder

  • CBC Alert Details

    This dashboard contains detailed information about the alerts received from the CBC appliance. By clicking on a row in the alert details you can get an expansion panel that displays endpoint event details. You must have endpoint events in the console for any endpoint events to display. From the endpoint event details panel you can click on the following fields to open a new window with the actual raw endpoint events:

    • device_id
    • device_name
    • device_external_ip
    • process
    • parent_cmdline
    • process_hash
    • parent_hash
    • process_guid

  • CBC Devices Overview

    This dashboard is an overview of the active devices reporting event data to the Carbon Black Cloud.

    • Requires the Endpoint Events data source via the Data Forwarder

  • CBC Processes Overview

    This dashboard is an overview of the processes based on the endpoint event data sent to the Carbon Black Cloud for your org(s).

    • Requires the Endpoint Events data source via the Data Forwarder

  • CBC Vulnerabilities Overview

    This dashboard is an overview of vulnerability information from the Carbon Black Cloud console.

    • Requires the built-in Vulnerabilities Input

  • Application Health Overview (under the Administration menu option)

    Use this tab to get health and status information about any alerts, events, or API errors in the Carbon Black Cloud. View total_failures, messages, and severity level for each instance.

Alert Actions

The global configurations referenced below are configured under Administration -> Application Configuration under the Alert Actions tab. You only need one API Token per Action per Org. The Credential Type corresponds to the Access Level required by the configured API Token; see Table 2 for details about the credential type and permission required for each Alert Action.

If you use multi-tenancy, include the org_key field with the corresponding value in the Splunk search query.

By default when a new alert is created in Splunk the parameter action.vmware-list-process.param.tenant = <api_config guid> will be added to the savedsearches.conf file in the VMware Carbon Black Cloud app’s local directory. If you need to change credentials for an alert action in the Application Configuration dashboard then all previously created alerts that were using the old credential need to be changed. After updating the credentials, delete the above parameter from the savedsearches.conf file for the appropriate saved search and restart Splunk.

The VMware Carbon Black Cloud app includes the following alert actions:

  • Add IOC to watchlist

    Add specified IOC(s) to a specified report in a watchlist.

    • Requires VMware Carbon Black Cloud Enterprise EDR
    • API Documentation
    • Credential Type: Custom
    • Configuration:
      • Watchlist: The name of the watchlist.
        • Will match exactly.
        • If the watchlist doesn’t exist, it will be created.
        • Can be overridden with a field value in the results. Fieldname: watchlist.
      • Report Name: The name of the report on the watchlist.
        • Will match exactly.
        • If the report doesn' t exist, it will be created.
        • Can be overridden with a field value in the results. Fieldname: report_name.
      • IOC Match Type: The type of indicator of compromise to add to the watchlist report. Either Equality or Query
      • IOC Field: The field name in the search results that contains the IOC to add to the watchlist report.
        • Supported Fields: src, src_ip, src_port, dest, dest_ip, dest_port, domain, os, process, process_name, process_hash, hash, user
      • Severity: The severity to assign to the alert action report IOC.
        • Can be overridden with a field value in the results. Fieldname: severity.

  • Remove IOC from watchlist

    Remove an IOC from a report in a watchlist.

    • Requires VMware Carbon Black Cloud Enterprise EDR
    • API Documentation
    • Credential Type: Custom
    • Configuration:
      • Watchlist: The name of the watchlist.
        • Will match exactly.
        • If the watchlist doesn’t exist, it will be created.
        • Can be overridden with a field value in the results. Fieldname: watchlist.
      • Report Name: The name of the report on the watchlist.
        • Will match exactly.
        • Can be overridden with a field value in the results. Fieldname: report_name.
      • IOC Value Field: The field name in the search results that contains the IOC to remove from the watchlist report.
        • This will be “string match”. If the report value is a query, and contains the IOC string, it will be removed.
        • If the IOC removed was a single IOC on the report, the report also gets removed.

  • Dismiss Alerts

    Dismiss the specified alert in Carbon Black Cloud

    • API Documentation
    • Credential Type: Custom
    • Configuration:
      • Alert ID Field: the field name in the search results that contains the alert id that should be dismissed.

  • Enrich CB Alert Observations

    Search and ingest the Observations that are associated with the alert.

    Note: This Alert Action will write events to the VMware Base Index (value specified for 'VMware CBC Base Index' in the Application Configuration).

    • API Documentation
    • Credential Type: Custom
    • Supports single instance and multi-tenancy
    • Required Search Result Fields: sourcetype, host, org_key, alert_id, source
      • alert_id MUST be a ;:;: separated string, with de-dupped Alert IDs for query to the endpoint via alert action.
      • org_key field MUST be included in the results in order for the alert action to determine which API Token to use.

  • Enrich CB Analytics Events

    Search and ingest the Enriched Events that are associated with the CB Analytics alert.

    Note: This Alert Action will write events to the VMware Base Index (value specified for 'VMware CBC Base Index' in the Application Configuration).

    • Requires VMware Carbon Black Cloud Endpoint Standard
    • API Documentation
    • Credential Type: Custom
    • Example: CB Analytics - Ingest Enriched Events
    • Supports single instance and multi-tenancy
    • Required Search Result Fields: sourcetype, host, org_key, alert_id, source
      • alert_id MUST be a ;:;: separated string, with de-dupped Alert IDs for query to the endpoint via alert action.
      • org_key field MUST be included in the results in order for the alert action to determine which API Token to use.

  • Process GUID Details

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

    • API Documentation
    • Credential Type: Custom
    • Configuration
      • Process GUID Field: the field name in the search results that contains the process GUID that you desire to fetch more details.

  • Get File Metadata

    Get file metadata, such as the number of devices the hash was observed on from the specified sha256 file hash.

    • API Documentation
    • Credential Type: Custom
    • Configuration:
      • File Hash Field: the field name in the search results that contains the SHA256 hash (only SHA256) of the object in question.

  • Ban Hash

    Prevent a sha256 hash from being executed in Carbon Black Cloud.

    • Currently requires Endpoint Standard; Enterprise EDR support expected CY21Q2.
    • API Documentation
    • Credential Type: Custom
    • Configuration:
      • File Hash Field: the field name in the search results that contains the SHA256 hash (only SHA256) of the object in question.
    • Search Result Fields:
      • description: (Optional) If field present in the search results then use value for the description in the Reputation Override. Default: Banned via Splunk Alert Action
      • threat_cause_actor_name: (Optional) If field present in the search results then use value for the filename of the Reputation Override. Default: Actor Name not defined

  • Quarantine Device

    Quarantining the specified device(s) prevents suspicious activity and malware from affecting the rest of your network. The device(s) will only be able to communicate with Carbon Black Cloud until un-quarantined.

    • API Documentation
    • Credential Type: Custom
    • Configuration:
      • Device ID Field: the field name in the search results that contains the device id to quarantine.

  • Un-quarantine device

    Remove the specified device from the quarantined state, allowing it to communicate normally on the network.

    • API Documentation
    • Credential Type: Custom
    • Configuration:
      • Device ID Field: the field name in the search results that contains the device id to un-quarantine.

  • Update Device Policy

    Update the policy associated with the specified device. Example: move a device to a more restrictive policy during incident investigation

    • API Documentation
    • Credential Type: Custom
    • Configuration:
      • Device ID Field: the field name in the search results that contains the Device ID that should be updated.
      • Policy ID Field: the field name in the search results that contains the new policy ID that should be applied

  • Kill Process

    Remotely kill a process on the devices specified in the search

    • API Documentation
    • Credential Type: Live Response
    • Configuration:
      • Device ID Field: the field name in the search results that contains the device id to kill process.
      • Process Field: the field name in the search results that contains the process name to kill.

  • List Processes

    Remotely list processes on the specified device(s). Example: If an Analytics alert did not terminate the process, identify if the suspicious process is still running on the device.

    • API Documentation
    • Credential Type: Live Response
    • Configuration:
      • Device ID Field: the field name in the search results in the search results that contains the device id to list processes.

  • Run Livequery

    Create 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 and Remediation
    • API Documentation
    • Credential Type: Custom
    • Example: Using Live Query to Enrich LSASS Scraping Investigations
    • Configuration:
      • LiveQuery Name: the name that should be used for the Live Query Run.
      • SQL Query: the field name in the search results that contains the SQL query that will be submitted.
      • Device IDs: (Optional) the field name in the search results that contains a comma separated list of device IDs that the query will be run against.
      • Device OS: (Optional) the field name that contains a comma separated list of device OSs or ALL that the query will be run against.
      • Policy Name: (Optional) the field name that contains a comma separated list of policy IDs that the query will be run against.

Custom Commands

The VMware Carbon Black Cloud app includes the following custom commands (default/commands.conf).

  • cbcdvcinfo

    This command enhances data with additional data pulled from the CBC. The arguments are listed below.

    • device_id: The field name that contains the device id for the command to enrich, as found in the CBC interface.

    • org_key: The field name that contains the org key that is associated with the credential.

    • fields: This is a quoted and comma-separated list of fields to return from the query.

      Example: The following will only add the columns last_location and last_name fields="last_location,last_name"

    Best Practices:

    • This command will query the Carbon Black Cloud API once per device_id
    • Limit your Splunk search to 100 devices to avoid potential API throttling

    Sample Usage:

    • Get real-time device information including sensor version and last contact time for the top 10 most frequent devices in high severity alerts

      index="carbonblackcloud" sourcetype="vmware:cbc:s3:alerts" severity >= 8  | stats dc(id) as alert_count by device_id, org_key | sort -alert_count | head 10 | cbcdvcinfo | table org_key, device_id, name, alert_count, sensor_version, last_contact_time, os_version, sensor_states

  • bchashinfo

    This command enhances data with additional data pulled from the CBC. The arguments are listed below.

    • hash: The field name that contains the sha256 hash for the command to enrich, as found in the CBC interface.

    • org_key: The field name that contains the org key that is associated with the credential.

    • fields: This is a quoted and comma-separated list of fields to return from the query.

      Example: The following will only add the columns last_location and last_name fields="last_location,last_name"

    Note: This command requires VMware Carbon Black Cloud Enterprise EDR.

    Best Practices:

    • This command will query the Carbon Black Cloud API once per hash
    • Limit your Splunk search to 100 hashes to avoid potential API throttling

    Sample Usage:

    • Get the device count and first-seen timestamp for the top 10 most frequent hashes found in high severity alerts 
      index="carbonblackcloud" sourcetype="vmware:cbc:s3:alerts" severity >= 8 | stats count(id) as alert_count by sha256_process_hash, org_key | sort -alert_count | head 10 | cbchashinfo hash=sha256_process_hash fields="first_seen_device_timestamp,num_devices"

Saved Searches

The VMware Carbon Black Cloud app includes the following saved searches (default/savedsearches.conf).

  • vmware_example_for_alerting

    Designed to show users how to create alerts using the app. The saved search is disabled by default in the app and can be enabled from the saved searches settings tab. This saved search will create a report whenever there is a new alert. The user can then use any of the alert actions stated above, or custom ones within their environment.

  • CB Analytics - Ingest Enriched Events

    This saved search provides Enriched Event Details based on CB_ANALYTICS alerts. The default time range is earliest=-30m AND latest=-20m and runs every 10 minutes, once enabled. The delay is built-in to allow the Carbon Black Cloud the time to aggregate and deliver additonal events associated with the alert. The following search is required to output these fields alert_id, org_key, sourcetype, source, host

    • The alert ids should be de-duplicated via stats
    • The alert_id field should be a ;:;: delimited string for efficiency and accuracy in the alert action
'stats values(aid) as alert_id by org_key sourcetype source host | eval alert_id = mvjoin(alert_id, ";:;:" )'

Monitoring Console Health Checks

The VMware Carbon Black Cloud app includes the following health checks in the Monitoring Console health check list (default/checklist.conf).

  • VMware CBC API Errors

    • Check to see if there are any CBC errors

  • VMware CBC Alerts Present

    • Check to see if there are any CBC Alerts present in the indexes

  • VMware CBC Events Present

    • Check to see if there are any CBC Events present in the indexes

  • VMware CBC Vulnerabilities Present

    • Check to see if there are any CBC Vulnerabilities present in the indexes

Lookups

The VMware Carbon Black Cloud app does not contain lookup files.

Event Generator

The VMware Carbon Black Cloud app includes a limited event generator. This allows the product to display data, when there are no inputs configured. The event generator requires the SA-Eventgen app to be installed.

The eventgen.conf contains two stanzas that reference the necessary log files:

[vmware_cbc_s3_alerts.log]

[vmware_cbc_s3_events.log]

To enable the event generator feature:

  1. Create a test index where the data can be loaded.

  2. Copy $SPLUNK_HOME$/etc/apps/vmware_app_for_splunk/default/eventgen.conf to the local folder in $SPLUNK_HOME$/etc/apps/vmware_app_for_splunk. There are 2 sources, one for alerts and one for events. You will need to change disabled = 1 to disabled = 0. By default the data will be written to the test index. This can be changed in the eventgen.conf file.

  3. You will also need to enable the SA-Eventgen input. To do this:

    1. Navigate to Settings -> Data Inputs
    2. Locate the SA-Eventgen app in the Local Inputs list.
    3. Select enable on the default input.

  1. Restart Splunk
Note: 'SA-Eventgen' will look through all apps in '$SPLUNK_HOME$/etc/apps' looking for 'eventgen.conf'. 'SA-Eventgen' will then run 'eventgen' logic for enabled inputs for any app 'eventgens' it locates.

Acceleration Supported

  1. Summary Indexing: No
  2. Data Model Acceleration: Yes, if Enabled
  3. Report Acceleration: No

Last modified on August 17, 2023