Python Canary API Wrapper
===================================
Thinkst Applied Research
Overview
------------
The Python Canary API Wrapper allows access to the Canary Web API.
.. _installation:
Installation
------------
The API is supported on python 2.7. The recommended way to
install the API Wrapper is via `pip <https://pypi.python.org/pypi/pip>`_.
.. code-block:: bash
pip install canarytools
For instructions on installing python and pip see "The Hitchhiker's Guide to
Python" `Installation Guides
<http://docs.python-guide.org/en/latest/starting/installation/>`_.
Quickstart
----------
Assuming you have your API key handy as well as the domain of your website:
.. code-block:: python
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:
.. code-block:: python
# 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 <http://canarytools.readthedocs.io/>`_ 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
<https://github.com/thinkst/canarytools-python/issues>`_ 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
<https://github.com/thinkst/canarytools-python/blob/master/LICENSE.txt>`_.
* Copyright (c), 2017, Thinkst Applied Research
Raw data
{
"_id": null,
"home_page": "https://canary.tools/",
"name": "canarytools",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "canary thinkst canarytools api wrapper",
"author": "Thinkst Applied Research",
"author_email": "canary@thinkst.com",
"download_url": "https://files.pythonhosted.org/packages/0a/cd/8f4e3fdafdd94501a9936e0508225fc386ec56ca07d7c3ee7dcfef96a0eb/canarytools-1.1.1.tar.gz",
"platform": null,
"description": "Python Canary API Wrapper\n===================================\n\nThinkst Applied Research\n\nOverview\n------------\nThe Python Canary API Wrapper allows access to the Canary Web API.\n\n.. _installation:\n\nInstallation\n------------\n\nThe API is supported on python 2.7. The recommended way to\ninstall the API Wrapper is via `pip <https://pypi.python.org/pypi/pip>`_.\n\n.. code-block:: bash\n\n pip install canarytools\n\nFor instructions on installing python and pip see \"The Hitchhiker's Guide to\nPython\" `Installation Guides\n<http://docs.python-guide.org/en/latest/starting/installation/>`_.\n\nQuickstart\n----------\n\nAssuming you have your API key handy as well as the domain of your website:\n\n.. code-block:: python\n\n import canarytools\n console = canarytools.Console(api_key='API_KEY', domain='CLIENT_DOMAIN')\n\n**Note:** You can find your API key and domain on your console. Head over to the console's setup page and under\n*Canary Console API* you'll find your API key. Your domain is the tag in-front of 'canary.tools' in the console's\nurl. For example in https://testconsole.canary.tools/settings **testconsole** is the domain.\n\nAlternatively,\nyou can download a configurations file from the *Canary Console API* tab. Inside the file you'll find instructions\non where to place it. If you have this on your system the *api_key* and *domain* parameters are no longer\nnecessary when instantiating a *Console* object.\n\nWith the ``console`` instance you can then interact with a Canary Console:\n\n.. code-block:: python\n\n # Get all devices\n console.devices.all()\n\n # Acknowledge all incidents for a device older than 3 days\n console.incidents.acknowledge(node_id='329921d242c30b5e', older_than='3d')\n\n # Iterate all devices and start the update process\n for device in console.devices.all():\n device.update(update_tag='4ae023bdf75f14c8f08548bf5130e861')\n\n # Acknowledge and delete all host port scan Incidents\n for incident in console.incidents.unacknowledged():\n if isinstance(incident, canarytools.IncidentHostPortScan):\n incident.acknowledge()\n incident.delete()\n\n # Create a web image Canarytoken\n console.tokens.create(\n kind=canarytools.CanaryTokenKinds.KIND_WEB_IMAGE,\n memo='Drop this token on DC box',\n web_image='/path/to/test.png',\n mimetype='image/png')\n\n # Print out the name of all incidents and the source IP address\n for incident in console.incidents.all():\n print incident.description, incident.src_host\n\nPlease see the API doc's `documentation <http://canarytools.readthedocs.io/>`_ for\nmore examples of what you can do with the Canary Console API.\n\nDiscussion and Support\n---------------------------\n\nPlease file bugs and feature requests as issues on `GitHub\n<https://github.com/thinkst/canarytools-python/issues>`_ after first searching to ensure a\nsimilar issue was not already filed. If such an issue already exists please\ngive it a thumbs up reaction. Comments to issues containing additional\ninformation are certainly welcome.\n\nDocumentation\n-------------\n\nThe documentation is located at http://canarytools.readthedocs.io.\n\nLicense\n-------\n\nThe Python Canary API Wrapper's source (v1.0.0+) is provided under the `Revised BSD License\n<https://github.com/thinkst/canarytools-python/blob/master/LICENSE.txt>`_.\n\n* Copyright (c), 2017, Thinkst Applied Research\n\n\n",
"bugtrack_url": null,
"license": "Revised BSD License",
"summary": "An API for the Thinkst Canary Console",
"version": "1.1.1",
"project_urls": {
"Homepage": "https://canary.tools/"
},
"split_keywords": [
"canary",
"thinkst",
"canarytools",
"api",
"wrapper"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "913171451052f977a0ec3a23f267f9d8246567f1482ed04ebe6efdc65a414fc8",
"md5": "29ee0df6eef9da0dea72e67be7938465",
"sha256": "96c0a006679c6e6e204b5fdeef118e0202c62439f15f496e98a99a1cdf7da51a"
},
"downloads": -1,
"filename": "canarytools-1.1.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "29ee0df6eef9da0dea72e67be7938465",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 23195,
"upload_time": "2023-07-10T16:13:14",
"upload_time_iso_8601": "2023-07-10T16:13:14.132032Z",
"url": "https://files.pythonhosted.org/packages/91/31/71451052f977a0ec3a23f267f9d8246567f1482ed04ebe6efdc65a414fc8/canarytools-1.1.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0acd8f4e3fdafdd94501a9936e0508225fc386ec56ca07d7c3ee7dcfef96a0eb",
"md5": "f742a2e3056f9f99b24bb76c2586aed8",
"sha256": "a0390959dbbec0efbf6b930377bb9729dfc3d544a5adc7e8a6dfcb3ee6bd86d8"
},
"downloads": -1,
"filename": "canarytools-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "f742a2e3056f9f99b24bb76c2586aed8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 18745,
"upload_time": "2023-07-10T16:13:16",
"upload_time_iso_8601": "2023-07-10T16:13:16.446295Z",
"url": "https://files.pythonhosted.org/packages/0a/cd/8f4e3fdafdd94501a9936e0508225fc386ec56ca07d7c3ee7dcfef96a0eb/canarytools-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-10 16:13:16",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "canarytools"
}
JSON