Skip to main content

An API for the Thinkst Canary Console

Project description

Thinkst Applied Research

Overview

The Python Canary API Wrapper allows access to the Canary Web API.

Installation

The API is supported on python 2.7. 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.

Quickstart

Assuming you have your API key handy as well as the domain of your website:

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

Note: You can find your API key and domain on your console. Head over to the console’s setup page and under Canary Console API you’ll find your API key. Your domain is the tag in-front of ‘canary.tools’ in the console’s url. For example in https://testconsole.canary.tools/settings testconsole is the domain.

Alternatively, you can download a configurations file from the Canary Console API tab. Inside the file you’ll find instructions on where to place it. If you have this on your system the api_key and domain parameters are no longer necessary when instantiating a Console object.

With the console instance you can then interact with a Canary Console:

# Get all devices
console.devices.all()

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

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

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

# 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')

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

Please see the API doc’s documentation for more examples of what you can do with the Canary Console API.

Discussion and Support

Please file bugs and feature requests as issues on GitHub after first searching to ensure a similar issue was not already filed. If such an issue already exists please give it a thumbs up reaction. Comments to issues containing additional information are certainly welcome.

Documentation

The documentation is located at http://canarytools.readthedocs.io.

License

The Python Canary API Wrapper’s source (v1.0.0+) is provided under the Revised BSD License.

  • Copyright (c), 2017, Thinkst Applied Research

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

canarytools-1.0.13.tar.gz (17.5 kB view details)

Uploaded Source

Built Distribution

canarytools-1.0.13-py2.py3-none-any.whl (20.8 kB view details)

Uploaded Python 2Python 3

File details

Details for the file canarytools-1.0.13.tar.gz.

File metadata

  • Download URL: canarytools-1.0.13.tar.gz
  • Upload date:
  • Size: 17.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/42.0.2 requests-toolbelt/0.9.1 tqdm/4.40.2 CPython/3.7.5

File hashes

Hashes for canarytools-1.0.13.tar.gz
Algorithm Hash digest
SHA256 7d3cc4b546e99d09961a906ad5f2bd7a4ed6291d91810cb32a1bfcca2371d2fa
MD5 473586fd7d4a1140cd64874d52fcd72d
BLAKE2b-256 357e34136b1e0520d8c7a1fcfe3a10a217c6aeef228af527603782f24a51c775

See more details on using hashes here.

File details

Details for the file canarytools-1.0.13-py2.py3-none-any.whl.

File metadata

  • Download URL: canarytools-1.0.13-py2.py3-none-any.whl
  • Upload date:
  • Size: 20.8 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/42.0.2 requests-toolbelt/0.9.1 tqdm/4.40.2 CPython/3.7.5

File hashes

Hashes for canarytools-1.0.13-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 deeb37cbef6ad81a7030da1b55254178db67574a8cd35a0d217ab08e5d06d839
MD5 c65ae7b08a34b598a6f05a45f90993e1
BLAKE2b-256 520c49c0781764e78e49cf0d76ad1f3f7e9d42eb6b52ab2023f9c410efeae744

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page