The new Carbon Black Python API Jason Garman & Jason McFarland Carbon Black Developer Network 

Why a New Python API? • Enforce Security Best Practices • API Tokens now read from Credential Store, not from scripts or command lines • Merge bindings for both Products • Cb Response • Cb Protection • Move complexity from the developer to the API bindings • Modernized design concepts and toolchains • More “Python like” • Python 3 support • Better performance • Caching • Documented 

Current API - Example Walk parents up the execution chain 

New API - Example Let’s get rid of all the boilerplate: 

What about all my “old” scripts!? • They’ll still work fine • No changes required • Same old restrictions apply (Python 2 only, etc.) • Some URLs have changed: • The Python API bindings now live in their own repository: https://github.com/carbonblack/cbapi-python • The old example scripts are now in a new ”cbcommunity” organization: https://github.com/cbcommunity/cbapi-examples 

Basics The new API exposes Carbon Black data in terms of “Model objects” • If you have used an “ORM” database layer before, you’ll be familiar with it • If not, no worries! It will become very clear... At its core, there are four actions you can take: • Query for one or a set of objects (searching Processes or Computers) • Modify an existing object • Create a new blank object (eg., Feed in Cb Response, Notification in Cb Protection) • Delete an existing object 

Getting Started Install the new bindings via pip: $ pip install cbapi Grab your Cb API token and create a credential file in one of these directories: • /etc/carbonblack • ~/.carbonblack • (current dir)/.carbonblack Credential filenames depend on the product: • credentials.response • credentials.protection Sample Credential File $ cat ~/.carbonblack/credentials.response [default] url=https://company.cbserver.com token=abcd01234 ssl_verify=True rabbitmq_host=cbserver.com rabbitmq_port=5004 rabbitmq_user=cb rabbitmq_pass=xxifn342zoep032 [dev] url=https://dev-server.cbserver.com token=01234abcd ssl_verify=False 

Connecting to your Cb Response Server from cbapi.response import CbEnterpriseResponseAPI c = CbEnterpriseResponseAPI() API credentials are retrieved from your Credential Storage You can specify a different credential Profile by passing the profile= parameter to the CbEnterpriseResponseAPI or CbEnterpriseProtectionAPI constructor: c = CbEnterpriseResponseAPI(profile=“dev”) 

Querying objects from cbapi.response import Process c.select(Process).where(“process_name:notepad.exe”) .sort(“last_update desc”) This will create a Query object that is ready to process this search whenever you attempt to access the results... It will *not* send the query to the Carbon Black server until you either create a list (through the array [] operator) or you iterate over the query (using “for…in…:”) 

Examples from cbapi.response import Process c.select(Process).where(“process_name:notepad.exe”)[:10] for proc in c.select(Process).where(“process_name:notepad.exe”): print proc.hostname, proc.username, proc.path print proc.binary.signed print proc.sensor.group.name list(c.select(Feed).where(‘name:yara’)) 

More Query Examples If you know there should only be one result, .one() will throw an exception if there is not exactly one result for a query: c.select(Process).where(“process_name:notepad.exe”).one() If you just want the first result, .first() will return it (or None if zero results): c.select(Process).where(“process_name:notepad.exe”).first() You can also use standard Python slice notation. What about the last ten results? c.select(Process).where(“process_name:notepad.exe”)[:-10] 

Object Attributes Each object is populated with attributes corresponding to the JSON structure returned by the server. For example: proc["username"] proc["start"] sensor["computer_name"] proc.username proc.start sensor.computer_name If you want to see the original JSON returned by the server: proc.original_document 

“Joining” Objects When applicable, objects are “joined” with each other. Notice: print proc.sensor.group.name This will auto-magically retrieve the Sensor associated with this Process, then the Sensor Group associated with the Sensor. Prior, you would have to explicitly send a separate query for both Sensor and Group PLUS- results are cached so that repeated requests for the same Sensor or Group do not end up issuing REST API calls to the Carbon Black server! 

Creating Objects Some objects can be created. Call .create() on the API object to retrieve an empty Model, then .save() after you’ve filled it in: from cbapi.response import Feed f = c.create(Feed) f.feed_url = “http://localhost:7000/feed.json” f.save() 

Updating/Deleting Objects The same concept applies to modifying objects: just set the appropriate fields to the new values and call .save() on the object. from cbapi.response import Feed f = c.select(Feed).where(“name:yara”).one() f.provider_rating = 5.0 f.save() Similarly, to delete an object, just call .delete() on the object: f.delete() 

Carbon Black Enterprise Protection The two APIs are now merged, so the same concepts apply: from cbapi.protection import CbEnterpriseProtectionAPI, Computer, Policy p = CbEnterpriseProtectionAPI() new_policy = p.select(Policy).where(“name:restricted”).one() for computer in p.select(Computer).where(“ipAddress:192.168.*”): computer.policy = new_policy computer.save() 

How to Contact Developer Relations • Email • [email protected] • User Exchange • https://community.carbonblack.com/community/developer-relations • Developer Network website • https://developer.carbonblack.com/ • Carbon Black API resources • Python API source code: https://github.com/carbonblack/cbapi-python (includes examples using the new API) • Examples (old API): https://github.com/cbcommunity/cbapi-examples 

Developer Network: APIs & Documentation 

Happy (Automated) Hunting!