Network Threat Metadata API

Overview

The Network Threat Metadata Service gathers information to enrich Alerts and Observations of types Intrusion Detection System (IDS) and Network Traffic Analysis (NTA).

Use Cases

  • From an Observation or Alert get information about the network threat.
    • When the type is an IDS or NTA Alert or Observation, the rule_id is the tms_rule_id in this API.

Requirements

  • Enterprise EDR with XDR

Resources


Authentication

Determine whether you use Carbon Black Cloud or VMware Cloud Services Platform to manage identity and authorization, or see the Carbon Black Cloud API Access Guide for complete instructions.


Carbon Black Cloud Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with Role-Based Access Control; All APIs and Services authenticate via API Keys. To access the data in Carbon Black Cloud via API, you must set up a key with the correct permissions for the calls you want to make and pass it in the HTTP Headers.

Environment
Available on majority of environments; Use the Carbon Black Cloud Console URL, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
  • {cbc-hostname}/threatmetadata/v1/orgs/{org_key}/detectors/{tms_rule_id}

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:
  • Alerts > Threat Metadata > org.xdr.metadata, allow permission to READ

API Key
When creating your API Key, use the Access Level Type of "Custom" and select the Access Level you created. Details on constructing and passing the API Key in your requests are available here.


Cloud Services Platform Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with OAuth Access Control; API access is controlled using OAuth apps or User API Tokens. This is currently limited to the UK Point of Presence and AWS GovCloud (US).

Environment
Available on Prod UK and AWS GovCloud (US). Full list of environments is available here; Use the Carbon Black Cloud Console URL from Cloud Services Platform, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
  • {cbc-hostname}/threatmetadata/v1/orgs/{org_key}/detectors/{tms_rule_id}

Access Level
Before you create your OAuth App, you need to create a custom Role with the following permissions under IDENTITY & ACCESS MANAGEMENT > Roles > VMware Carbon Black Cloud:
  • _API.Alerts:org.Xdr.Metadata, allow permission to READ

API Authentication
The Cloud Services Platform supports several authentication options, Access Token, API Token, and for backward compatibility, X-Auth-Token. To learn about the differences or how to use the authentication methods see the Authentication Guide.

Note: This feature is not yet available in AWS GovCloud (US).

API Calls

Get metadata for a detector (rule)

Get the metadata for a given detector (rule).


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.xdr.metadata READ Majority of environments
VMware Cloud Services Platform _API.Alerts:org.Xdr.Metadata.READ N/A - included in permission name Prod UK and AWS GovCloud (US)


Request 

GET {cbc-hostname}/threatmetadata/v1/orgs/{org_key}/detectors/{tms_rule_id}

Query Parameters

Parameter Required Description Values Default
tms_rule_id Yes The unique identifier for the threat rule (detector) to get metadata about N/A


Response Codes

Code Description Content-Type Content
200 Successful Requests application/json View example response below
4xx Requests that failed application/json See Error Response below


Examples

Request 
GET https://defense.conferdeploy.net/threatmetadata/v1/orgs/ABCD1234/detectors/b38fddf2-833d-4c82-8085-c58e9ed34caf
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "detector_abstract": "A remote shell is a bidirectional communication channel that allows an attacker to send commands to a compromised host over the network. A remote shell is defined *direct* (or *bind*) if the attacker's host (client) initiates the connection towards the compromised host (server).\n\nThe detector matches on the string `whoami` sent by the attacker (client) in the first 30 bytes of a TCP packet's payload. To decrease the likelihood of false positives, an alert is generated only if no known application layer protocol is decoded.",
    "detector_goal": "Detect the transfer of a whoami command over a TCP direct shell.",
    "false_negatives": "The detector only matches on plaintext TCP direct shell. Stealthier shells could obfuscate or encrypt the commands.\n\nFurthermore, if `whoami` is sent deeper in the TCP payload than 30 bytes, the detector would not generate an alert.",
    "false_positives": "While a remote shell is a plausible explanation for the string `whoami` sent over a TCP connection, other applications may have legitimate reasons for transferring content matching the detector (e.g., plaintext streaming of audit logs).\n\nThe captured traffic associated to the event should help investigate the context and purpose of the TCP connection.",
    "threat_public_comment": "Once a host has been compromised, a remote shell could be used by the attacker to perform additional tasks (e.g., environment reconnaissance, lateral movements). An alert for this threat is generated by a plain TCP connection that may be used to transmit and execute cleartext commands through a remote shell on a compromised host."
}
To download or review the Carbon Black Cloud Postman collection, click here.

Field Definitions

Threat Metadata Response

Field Definition Data Type Values
detector_abstract Abstract or description of the detector string N/A
detector_goal Description of what the detector is achieving string N/A
false_negatives Highlights why detector could not have been triggered string N/A
false_positives Highlights why detector could have been triggered string N/A
threat_public_comment Public comment of the threat string N/A

Error Response

Field Definition Data Type Values
timestamp Time the request was made in ISO 8601 UTC format String Format: yyyy-MM-dd’T’HH:mm:ss.SSS’Z'
status HTTP Response Code String N/A
error HTTP Response Message String N/A
path URL that was submitted String N/A

Last modified on March 1, 2023