Back to Blogs

CbAPI 1.4.0 Released

Posted on January 10, 2019

We are proud to announce that CbAPI 1.4.0 is now available for installation via Python’s PyPI. This release includes compatibility with Carbon Black Cloud Enterprise EDR and the new APIs available in Carbon Black Cloud’s Enterprise EDR.

Currently, the Process Search API is exposed. As of version 1.4.0, there are three available model objects:

  • Process
  • Event
  • Tree

Install

The Python CbAPI works with Python 2.x and 3.x, however we do recommend using Python 3.x.

You can install cbapi by running:

$    pip install --upgrade cbapi ```

Note: Make sure the version installed is 1.4.0 or newer.

Demo

Let’s take the new CbAPI bindings for a spin and see what we can do with the new updates for Enterprise EDR.

$ python3
python 3.6.1 (default, Apr  4 2017, 09:40:21)
[GCC 4.2.1 Compatible Apple LLVM 8.1.0 (clang-802.0.38)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> from cbapi.psc.threathunter import *
>>> cbthr = CbThreatHunterAPI()
>>> process = cbthr.select(Process).first()
>>> print(process)
Process object, bound to https://defense-eap01.conferdeploy.net.
-------------------------------------------------------------------------------

       backend_timestamp: 2018-12-11T22:22:42.603Z
         childproc_count: 0
         crossproc_count: 0
      device_external_ip:
            device_group: lucasevilempire
         device_group_id: 0
               device_id: 14436
      device_internal_ip: 165.225.35.7
             device_name: red_october_th
               device_os: WINDOWS
        device_timestamp: 2018-12-10T20:19:18.253Z
           document_guid: 8F3gAyeIQpamHrS9LOeOgg
           filemod_count: 0
    kinesis_partition_id: WNEXFKQ7:0
                  legacy: True
           modload_count: 0
           netconn_count: 0
                  org_id: WNEXFKQ7
           org_size_perc: 1
             parent_guid: WNEXFKQ7-00003864-0000030c-00000000-1d490c8d9ad...
             parent_hash: ['be42e4a901d6ac8885882d2cd9372a64023794428e0ac...
             parent_name: c:\windows\system32\services.exe
              parent_pid: 780
            partition_id: 0
         process_cmdline: ['"C:\\Program Files\\VMware\\VMware Tools\\vmt...
    process_effective_reputation: WHITE
            process_guid: WNEXFKQ7-00003864-000008b0-00000000-1d490c8dbce...
            process_hash: ['1e577f6d1f3c530c11dc0a7bd1fe765d', 'ed9fb40c3...
            process_name: c:\program files\vmware\vmware tools\vmtoolsd.exe
             process_pid: [2224]
      process_reputation: TRUSTED_WHITE_LIST
      process_terminated: False
        process_username: ['NT AUTHORITY\\SYSTEM']
            regmod_count: 0

The process model printed out above is a simple in memory object representing the process information returned by Enterprise EDR.

Lets continue to investigate the events associated with the process and the tree of execution this process is in.


>>> print ([e for e in process.events()][0])
Event object, bound to https://defense-eap01.conferdeploy.net.
-------------------------------------------------------------------------------

       backend_timestamp: 2018-12-12T04:27:09.740Z
       childproc_cmdline: C:\Windows\system32\cmd.exe /c ""C:\Program Fil...
          childproc_name: c:\windows\system32\cmd.exe
    childproc_process_guid: WNEXFKQ7-00003864-00000974-00000000-1d490d34128...
        childproc_sha256: 9a7c58bd98d70631aa1473f7b57b426db367d72429a5455...
      childproc_username: NT AUTHORITY\SYSTEM
       created_timestamp: 2019-01-10T17:03:42.953Z
              event_guid: SDu0Tb5QSViO8kzFL8pqqA
         event_timestamp: 2018-12-10T19:57:01.236Z
              event_type: childproc
                  legacy: True
      legacy_description: The application "<share><link hash="ed9fb40c3cb...
            process_guid: WNEXFKQ7-00003864-000008b0-00000000-1d490c8dbce...
                     ttp: ['RUN_CMD_SHELL']
>>> print(process.tree().nodes)
{'children': [{'_s3_location': 'Bz24uL58SJGHSLzlvvVkDQ:167a0a9bfbd:0:ba1', 'backend_timestamp': '2018-12-12T04:25:38.492Z', 'childproc_count': 0, 'children': [{'_s3_location': '4aUbJ69WTkq9JGugPQrowA:1679f5d79ac:2b355:8b4', 'backend_timestamp': '2018-12-11T22:22:42.603Z', 'childproc_count': 0, 'crossproc_count': 0, 'device_external_ip': '', 'device_group': 'lucasevilempire', 'device_group_id': 0, 'device_id': 14436, 'device_internal_ip': '165.225.35.7', 'device_name': 'red_october_th', 'device_os': 'WINDOWS', 'device_timestamp': '2018-12-10T20:19:18.253Z', 'document_guid': 'bRZ9CSYpRVKprF1xJ1dWaw', 'filemod_count': 0, 'kinesis_partition_id': 'WNEXFKQ7:0', 'legacy': True, 'modload_count': 0, 'netconn_count': 0, 'org_id': 'WNEXFKQ7', 'org_size_perc': 1, 'parent_guid': 'WNEXFKQ7-00003864-000008b0-00000000-1d490c8dbcea3ae', 'parent_hash': ['1e577f6d1f3c530c11dc0a7bd1fe765d', 'ed9fb40c3cb5ba0a9ac3ade80b503f5d7128016c75852e612a6c838f04401ea3'], 'parent_name': 'c:\\program files\\vmware\\vmware tools\\vmtoolsd.exe', 'parent_pid': 2224, 'partition_id': 0, 'process_cmdline': ['"C:\\Program Files\\VMware\\VMware Tools\\VMwareResolutionSet.exe" 0 1 , 0 0 1920 1200 0'], '

Of course, the Python bindings support the whole process-search API, and the various query arguments it supports. Here’s an example getting a process by name - cmd.exe. See the REST API documentation for a full list of supported query-syntax - Carbon Black EDR customers will find the syntax quite familiar.

>>> process = cbthr.select(Process).where("process_name:cmd.exe").first()
>>> print(process)
Process object, bound to https://defense-eap01.conferdeploy.net.
-------------------------------------------------------------------------------

       backend_timestamp: 2018-12-11T22:22:42.603Z
         childproc_count: 0
         crossproc_count: 0
      device_external_ip:
            device_group: lucasevilempire
         device_group_id: 0
               device_id: 14436
      device_internal_ip: 165.225.35.7
             device_name: red_october_th
               device_os: WINDOWS
        device_timestamp: 2018-12-10T19:57:04.541Z
           document_guid: 5PAh588fRG2VUv_YltaCgg
           filemod_count: 0
    kinesis_partition_id: WNEXFKQ7:0
                  legacy: True
           modload_count: 0
           netconn_count: 0
                  org_id: WNEXFKQ7
           org_size_perc: 1
             parent_guid: WNEXFKQ7-00003864-000008b0-00000000-1d490c8dbce...
             parent_hash: ['1e577f6d1f3c530c11dc0a7bd1fe765d', 'ed9fb40c3...
             parent_name: c:\program files\vmware\vmware tools\vmtoolsd.exe
              parent_pid: 2224
            partition_id: 0
         process_cmdline: ['C:\\Windows\\system32\\cmd.exe /c ""C:\\Progr...
    process_effective_reputation: WHITE
            process_guid: WNEXFKQ7-00003864-00000974-00000000-1d490d34128...
            process_hash: ['9a7c58bd98d70631aa1473f7b57b426db367d72429a54...
            process_name: c:\windows\system32\cmd.exe
             process_pid: [2420]
      process_reputation: TRUSTED_WHITE_LIST
      process_terminated: False
        process_username: ['NT AUTHORITY\\SYSTEM']
            regmod_count: 0
                     ttp: ['RUN_CMD_SHELL']

These three models allow users to search for process’s of interest, explore the hierarchy of process’s up and down to parents and children as well as expose the pertinent events in the lifetime of a process. Support for additional Enterprise EDR APIs is coming soon.

Additional Resources

Happy threat hunting!