A guide to Birding (aka: Tips for deploying Canaries)

Heres a quick, informal guide to deploying birds. It isn't a Canary user guide and should:
  • be a fun read;
  • be broadly applicable. 
One of Canary's core benefits is that they are quick to deploy (Under 5 minutes from the moment you unbox them) but this guide should seed some ideas for using them to maximum effect.

Grab the Guide Here (No registration, No Tracking Link, No Unnecessary Drama)

If you have thoughts, comments, or ideas, hit us back at info@canary.tools or DM us on twitter @thinkstCanary

Get notifications when someone accesses your Google Documents (aka: having fun with Google Apps Script)

Our MS Word and PDF tokens are a great way to see if anyone is snooping through your documents. One simply places the document in an enticing location and waits. If the document is opened, a notification (containing useful information about the viewer) is sent to you. Both MS Word tokens and PDF tokens work by embedding a link to a resource in the tokened document. When the document is opened an attempt to fetch the resource is made. This is the request which tickles the token-server, which leads to you being notified.

Because so many of us store content on Google Drive we wanted to do something similar with Google Documents and Google Sheets. Using the embedded image approach was possible in Google Sheets, however, due to image caching coupled with weak API support for Google Documents we turned to Google Apps Script.

Google Apps Script is a powerful Javascript platform with which to create add-ons for Google Sheets, Docs, or Forms. Apps Script allows your documents to interface with most Google services - it's pretty sweet. Want to access all your Drive files from a spreadsheet? No problem! Want to access the Google Maps service from a document? No problem! Want to hook the Language API to your Google Forms? Easy. It's also possible to create extensions to share with the community. You can even add custom UI features.

The Apps Script files can be published in three different ways.

  1. The script may be bound to a document (this is the approach we followed);
  2. It may be published as a Chrome extension;
  3. It may be published to be used by the Google Execution API (the Execution API basically allows you to create ones own API endpoints to be used by a client application).  

With the script bound to a document, the Apps Script features most important for our purposes are: Triggers, the UrlFetchApp service, and the Session service. A brief outline of the flow is:

  1. A user opens the document, 
  2. A trigger is fired which grabs the perpetrator's email address;
  3. This is sent via a request notification to the document owner. 

A more detailed outline of each feature is given bellow.


Apps Script triggers come in two flavours: simple and installable. The main difference between the two is the number of services they're allowed to access. Many services require user authorisation before giving the app access to a user's data. Each flavour also has separate types. For example: "on open", "on edit", "on install", even timed triggers.  For our purposes the "on open" installable triggers proved most useful.

UrlFetchApp service

This service simply gives one's script the ability to make HTTP requests. This service was used to send the requests needed to notify the document owner that the token'd document had been opened. Useful information about the document viewer may also be sent as the payload of a POST request.

Session service

The Session service provides access to session information, such as the user's email address and language setting. This was used to see exactly which user opened the document.

Putting it all together

So, what does this all look like? Let's go ahead and open up a new Google sheet and navigate to the Script editor.

Open the Script editor

Once in the Script editor create a new function named whatever you like (in our case it is called "notify"). Here a payload object is constructed which contains the email address of the document owner, the email address of the document viewer and the document viewer's locale. This information is then sent to an endpoint. Here we use hookbin for convenience. 

Write a function which sends user information to an endpoint

Once the file has been saved and our notify function is solid, we can go ahead and add the "on open" trigger. To do this: open the Edit tab dropdown from the script editor and go to "Current project's triggers".

Open the project's triggers

Under the current project's triggers add an "On open" trigger to the notify function. This trigger will cause the "notify" function to run each time the document is opened.

Add an "On open" trigger to the "notify" function

Because the function is accessing user data (the Session service) as well as connecting to an external service (sending requests to Hookbin) the script will require a set of permissions to be accepted before being run.

Set of permissions needed by the installable trigger

Once the permissions have been accepted all that remains is for the document to be shared. You can share the document with specific people or anyone on the internet. The only caveat being that the document needs to be shared with EDIT permissions or else the script will not function correctly.

Every time the document is opened post requests will be sent to the endpoint. Below is an example of the contents of the POST request sent to Hookbin.

The request contents received by the endpoint


We ran into a few limitations while investigating the use of Apps Script for tokens. While copying a document as another Google user would also copy the script bound to the document, it would not copy the triggers if any had been previously installed. Thus, the user with which the document was shared would need to manually add the triggers to the copied document. Another limitation was that anyone viewing the document needed to have EDIT permissions in order for the script to work correctly. This could prove problematic if the person viewing the document decided to delete/edit the script and/or document.

We overcame this, through some creativity and elbow grease..


Thanks for reading. The methods described here were used in our new Google Docs/Sheets Canarytokens for our Canary product, you should totally check them out! We hope you found this useful and that you'll come up with some other cool new ways to use Google Apps Script!

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

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:

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.

Cloud Canary Beta

Is that a cloud next to Tux?

We are sorry that this blog has been so quiet lately. Our Canary product took off like a rocket and we've had our heads down giving it our all. This month we released version-2 with a bunch of new features. You really should check it out.

Since almost day one, customers have been asking for virtual Canaries.  We generally prefer doing one thing really well over doing multiple things "kinda ok", so we held off virtualising Canary for a long time. This changes now.

With Canary software now on version 2.0 and running happily across thousands of birds, a crack at virtual Canaries make sense. Over the past couple of months we’ve been working to get Canaries virtualised, with a specific focus initially, on Amazon’s EC2.

We're inviting customers to participate in a beta for running Canaries in Amazon’s EC2. The benefits are what you’d expect: no hardware, no waiting for shipments and rapid deployments. You can plaster your EC2 environment with Canaries, trivially.

The beta won't affect your current licensing, and you’re free to deploy as many Cloud Canaries as you like during the beta period. They use the same console as your other birds, and integrate seamlessly.

Mail cloudcanarybeta@canary.tools if you’d like to participate and we'll make it happen.