Introducing our Python API Wrapper

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: 

	import canarytools
	console = canarytools.Console(api_key='API_KEY', domain='CLIENT_DOMAIN')

view raw canarytools.py hosted with ❤ by GitHub

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).

Click 'Download Token File' to download the API configuration file.

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:

console.devices.all()

view raw devices_all.py hosted with ❤ by GitHub

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

	for device in console.devices.all():
	device.reboot()

view raw devices_reboot.py hosted with ❤ by GitHub

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:

	for incident in console.incidents.all():
	print incident.description, incident.src_host

view raw incidents_print.py hosted with ❤ by GitHub

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

console.incidents.acknowledge(node_id='000000044c2232z', older_than='3w')

view raw incidents_ack.py hosted with ❤ by GitHub

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:

	for token console.tokens.all():
	print token

view raw canarytoken_all.py hosted with ❤ by GitHub

You can also create tokens:

	console.token.create(
	kind=canarytools.CanaryTokenKinds.WEB_IMAGE,
	mimetype='image/jpg',
	web_image='/home/image.jpg')

view raw canarytoken_create.py hosted with ❤ by GitHub

Enable/disable your tokens:

	for token in console.tokens.all():
	token.enable()

view raw canarytoken_enable.py hosted with ❤ by GitHub

Whitelist Features

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

client.settings.is_ip_whitelisted(src_ip='10.0.0.2', dst_port='5000')

view raw settings_is_whitelisted.py hosted with ❤ by GitHub

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.