Introducing our Python API Wrapper

With our shiny new Python API wrapper, managing your deployed Canaries has never been simpler. With just a few simple lines of code you’ll be able to sort and store incident data, reboot all of your devices, create Canarytokens, and much more (Building URLs correctly and parsing JSON strings is for the birds…).

So, how do you get started? Firstly you’ll need to install our package. You can grab it from a number of places:

PyPI
GitHub
Or simply startup your favourite shell and run “pip install canarytools”

Assuming you already have your own Canary Console (see our website for product options) and a flock of devices, getting started is very easy indeed! First, instantiate the Console object:

Your API_KEY can be retrieved from your Console’s Console Setup page. The CLIENT_DOMAIN is the tag in-front of “canary.tools” in your Console’s url. For example in https://testconsole.canary.tools/settings “testconsole” is the domain.

Alternatively a .config file can be downloaded and placed on your system (place this in ~/ for Unix (and Unix-like) environments and C:\Users\{Current Users}\ for Windows environments). This file contains all the goodies needed for the wrapper to communicate with the Console. Grab this from the Canary Console API tab under Console Setup (This is great if you’d rather not keep your api_key and/or domain name in your code base).

To give you a taste of what you can do with this wrapper, let’s have a look at a few of its features:

Device Features

Want to manage all of your devices from the comfort of your bash-shell? No Problem…

Assuming we have instantiated our Console object we can get a handle to all our devices in a single line of code:

From here it is straightforward to do things such as update all your devices, or even reboot them:

Incident Features

Need the ability to quickly access all of the incidents in your console? We’ve got you covered. Getting a list of incidents across all your devices and printing the source IP of the incident is easy:

Acknowledging incidents is also straightforward. Let’s take a look at acknowledging all incidents from a particular device that are 3 weeks or older:

Canarytoken Features

Canarytokens are one of the newest features enabled on our consoles. (You can read about them here). Manage your Canarytokens with ease. To get a list of all your tokens simply call:

You can also create tokens:

Enable/disable your tokens:

Whitelist Features

If you’d like to whitelist IP addresses and destination ports programmatically, we cater for that too:

This is just a tiny taste of what you can do with the API. Head over to our documentation to see more. We’re hoping the API will make your (programatic) interactions with our birds a breeze.

Introducing our Python API Wrapper