Carbon Black Python API - Summer 2016

This deck introduces the new Carbon Black Python API. Learn how to use the Python API to interact with both Carbon Black Enterprise Response and Enterprise Protection.

See https://developer.carbonblack.com for more information on Carbon Black's APIs and https://cbapi.readthedocs.io for the latest documentation on the Python API layer.

Transcript

1. The new Carbon Black Python API Jason Garman & Jason McFarland Carbon Black Developer Network
2. 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
3. Current API - Example Walk parents up the execution chain
4. New API - Example Let’s get rid of all the boilerplate:
5. 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
6. 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
7. 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
8. 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”)
9. 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…:”)
10. 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’))
11. 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]
12. 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
13. “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!
14. 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()
15. 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()
16. 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()
17. How to Contact Developer Relations • Email • dev-support@carbonblack.com • 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
18. Developer Network: APIs & Documentation
19. Happy (Automated) Hunting!