_images/logo_canary@2x.png

Welcome to canarytools’s documentation!

This Python library wraps the Canarytools API, for deploying and managing Thinkst Canary honeypots.

NOTE: This API is still in Beta.

Requirements

Python 2.7+, Python 3.3+

Installation

The recommended way to install the API Wrapper is via pip.

pip install canarytools

For instructions on installing python and pip see “The Hitchhiker’s Guide to Python” Installation Guides

Using the Library

All uses of the Canary Console API start by importing the library module and instantiating the Console class.

import canarytools
client = canarytools.Console('YOUR_DOMAIN', 'YOUR_API_KEY')

Alternatively, you can download a configuration file from your console’s Canary Console API settings tab. Place this file in your home directory (~/ for Unix environments and C:\Users\{Current User}\ for Windows Environments). With this file in place you can instantiate the Console class without needing the API token nor the domain anywhere in your code.

import canarytools
client = canarytools.Console()

You may also specify the timezone to be used to format time specific data.

import canarytools
from pytz import timezone
console = canarytools.Console(timezone=timezone('US/Eastern'))

After instantiating the Console class, you’re ready to start making calls. See Main Interface for more details on the Console class.

Quick Start

With the Console instance it’s easy to do all the cool things you can do on the Canary Console webpage. Let’s take a look at some key features.

Devices

The API makes managing your devices simple. Managing more than one device at a time can become difficult. Why not manage them programmatically?

# Get all devices
console.devices.all()

Updating and rebooting all your devices can be done in just a few lines of code.

# Iterate all devices and start the update process
for device in console.devices.all():
    device.update(update_tag='4ae023bdf75f14c8f08548bf5130e861')

If you’d like to see more cool things you can do with your devices, see Devices Interface.

Incidents

Keep a handle on incidents. Want to quickly acknowledge a large batch? No problem!

# Acknowledge all incidents for a device older than 3 days
console.incidents.acknowledge(node_id='329921d242c30b5e', older_than='3d')

Perhaps you’d just like to do a large clean up of a specific incident type? Don’t forget to acknowledge before deleting!

# Acknowledge and delete all host port scan Incidents
for incident in console.incidents.unacknowledged():
    if isinstance(incident, canarytools.IncidentHostPortScan):
        incident.acknowledge()
        incident.delete()

Get important incident information quickly. Perhaps to be piped to your SIEM system.

# Print out the name of all incidents and the source IP address
for incident in console.incidents.all():
    print incident.description, incident.src_host

To see more head to Incidents Interface.

Canarytokens

Canarytokens are our form of agentless detection. More information is on the tokens site and this blog post.

You can manage your cool Canarytokens with the canarytools library!

# Create a web image Canarytoken
console.tokens.create(
    kind=canarytools.CanaryTokenKinds.KIND_WEB_IMAGE,
    memo='Drop this token on DC box',
    web_image='/path/to/test.png',
    mimetype='image/png')

Read more at Canarytokens Interface.

Settings

Whitelist devices like scanners and other harmless hosts.

# Whitelist IP and destionation port
console.settings.whitelist_ip_port('10.0.0.2', '5000')

For a complete list of options see Settings Interface.

Updates

Keep an eye out for new device updates.

# List all available updates
for update in console.updates.list_updates():
    print update.tag()

See Updates Interface for more.