Welcome to canarytools’ 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
console = 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 or the domain anywhere in your code.
import canarytools
console = 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.
Flocks¶
Flocks are organisation groupings of Canaries.
# List Flocks on your Canary Console
console.flocks.all()
Read more at Flocks Interface.
Settings¶
Ignorelist devices like scanners and other harmless hosts.
# Ignorelist 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.
API Documentation¶
- Canary Console API Python Client v1
- Incidents and event attributes
- Canarytokens incidents
- Port Scans
- Canary Disconnected
- FTP Incident
- Git Repository Clone Attempt
- HTTP Incidents
- HTTP Proxy Request
- Microsoft SQL Server Login Attempt
- Modbus Request
- MySQL Login Attempt
- NTP Monlist Request
- Redis Command
- SIP Request
- Shared File Opened
- SNMP Request
- SSH Login Attempt
- Custom TCP Service Request
- TFTP Request
- Telnet Login Attempt
- VNC Login Attempt
- Console Settings Changed
- Device Settings Changed
- Flock Settings Changed
- Rollback Network Settings