Experiments in Extending Thinkst Canary – Part 1


The Thinkst Canary is best described as a digital tripwire for physical and virtual environments. It sits there waiting for a threat actor to tip you off they are mooching around your environment. What is less appreciated however is it is extensible with custom user modules. This post is the first in a series detailing our experiments in extending the product.

The dev environment

For development I’m using Windows Subsystem for Linux on Windows 10 with Ubuntu. The core technology in Canary is Python 2.7 (yes yes) and Twisted – the latter of which is important as you’ll need to get familiar with the framework’s concepts.

The development documentation is rather sparse but the steps outlined worked to get the environment live and the packing system functioning. All development can be done on host with only final deployment and testing needing to be done on live hardware.

Opencanary is used for the develop, test, fix cycle, and works as expected under WSL. Within Opencanary there are a number of protocol modules with varying degrees of complexity which help a lot to understand the concepts in place of any detailed documentation.

Dev and test cycle

My dev / test cycle is something like this:

  1. python setup.py develop (first time only)
  2. *do development*
  3. ./build.sh
  4. opencanaryd –usermodule
  5. GOTO 2

You know your module has successfully loaded when you see something like this on stdout:

{"dst_host": "", "dst_port": -1, "local_time": "2020-07-04 13:24:23.842965", "logdata": {"msg": {"logdata": "Added service from class canaryproxy in canaryproxy to fake"}}, "logtype": 1001, "node_id": "opencanary-1", "src_host": "", "src_port": -1}

then later:

2020-07-04T14:24:23+0100 [-] ServerFactory starting on 823
2020-07-04T14:24:23+0100 [twisted.internet.protocol.ServerFactory#info] Starting factory

My first extensions

The best way to show how it is extensible is through code.

The third module I wrote took a couple of hours due to not knowing Twisted very well. However I was easily enough able to implement a TCP proxy (thanks Internet) which allows traffic to route through the Canary to another system. This enables, for example, a highly interactive honeypot to be present behind it.

The example below listens on port 823 and proxies through to Telnet Starwars.

The first module I wrote actually implemented a TLS server and an echo server. It served as another good example to the basic concepts, but also solved something we’re going to need in the latter posts in the series.

As you can see the Canary module system is super simple to use once you understand Twisted concepts, which if I’m honest, I found less intuitive initially.


NCC Group’s Managed Network Intruder Alarm service as part of our Managed Detection and Response offering uses Canaries. We can see the potential for gaining better intelligence on adversaries to shorten the containment and response phases through extending their functionality. These are the experiments that underpin the journey.