thinkst/opencanaryLow-resource honeypot that emulates common network services to detect post-breach attacker activity, with extensible protocol modules and configurable alerting.
OpenCanary is a multi-protocol network honeypot. It's primary use-case is to catch hackers after they've breached non-public networks. It has extremely low resource requirements and can be tweaked, modified, and extended.
OpenCanary runs as a daemon and implements multiple common network protocols. When attackers breach networks and interact with the honeypot, OpenCanary will send you alerts via a variety of mechanisms.
OpenCanary is implemented in Python, so the core honeypot is cross-platform; however, certain features require specific OSes. Running on Linux will give you the most options. It has extremely low resource requirements; for example, it can be deployed happily on a Raspberry Pi or a VM with minimal resources.
This README describes how to install and configure OpenCanary on Ubuntu Linux and MacOS.
OpenCanary is the Open Source version of our commercial Thinkst Canary honeypot.
The OpenCanary installation essentially involves ensuring the Python environment is ready, then installing the OpenCanary Python package (plus optional extras).
If uv is installed, you can use it for virtual environment creation and package installation. If it is not installed, the standard python/pip flow below continues to work.
Installation on Ubuntu 22.04 LTS or 24.04 LTS:
$ sudo apt-get install python3-dev python3-pip python3-virtualenv python3-venv python3-scapy libssl-dev libpcap-dev
$ virtualenv env/
$ . env/bin/activate
$ pip install opencanary
Optional uv equivalent:
$ uv venv env
$ . env/bin/activate
$ uv pip install opencanary
Optional extras (if you wish to use the Windows File Share module, and the SNMP module):
$ sudo apt install samba # if you plan to use the Windows File Share module
$ pip install scapy pcapy-ng # if you plan to use the SNMP module
First, create and activate a new Python virtual environment:
$ virtualenv env/
$ . env/bin/activate
Optional uv equivalent:
$ uv venv env
$ . env/bin/activate
Macports users should then run:
$ sudo port install openssl
$ env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/opt/local/lib" CFLAGS="-I/opt/local/include" pip install cryptography
Alternatively, Homebrew x86 users run:
$ brew install openssl
$ env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/usr/local/opt/openssl/lib" CFLAGS="-I/usr/local/opt/openssl/include" pip install cryptography
Homebrew M1 users run:
$ brew install openssl
$ env ARCHFLAGS="-arch arm64" LDFLAGS="-L/opt/homebrew/opt/[email protected]/lib" CFLAGS="-I/opt/homebrew/opt/[email protected]/include" pip install cryptography
(The compilation step above is necessary as multiple OpenSSL versions may exist, which can confound the Python libraries.)
Now the installation can run as usual:
$ pip install opencanary
$ pip install scapy pcapy-ng # optional
With uv installed, the equivalent commands are:
$ uv pip install opencanary
$ uv pip install scapy pcapy-ng # optional
The Windows File Share (smb) module is not available on macOS.
To install from source, instead of running pip do the following:
$ git clone https://github.com/thinkst/opencanary
$ cd opencanary
$ python setup.py sdist
$ cd dist
$ pip install opencanary-<version>.tar.gz
With uv installed, you can replace the final install step with:
$ uv pip install opencanary-<version>.tar.gz
OpenCanary is packaged via pkgx, so no installation is needed if pkgx is installed, simply preface the opencanaryd command with
pkgx. Due to environment variable protections in modern sudo implementations, the entire command must be run as root, or via sudo -E.
$ pkgx opencanaryd --version
OpenCanary Docker images are hosted on Docker Hub. These are only useful on Linux Docker hosts, as the host network engine is required for accurate network information.
When OpenCanary starts it looks for config files in the following locations and will stop when the first configuration is found:
/etc/opencanaryd/opencanary.conf~/.opencanary.conf (i.e. the home directory of the user, usually this will be root so /root/.opencanary.conf)./opencanary.conf (i.e. the directory where OpenCanary is installed)To create an initial configuration, run as root (you may be prompted for a sudo password):
$ opencanaryd --copyconfig
[*] A sample config file is ready /etc/opencanaryd/opencanary.conf
[*] Edit your configuration, then launch with "opencanaryd --start --uid=nobody --gid=nogroup"
This creates the path and file /etc/opencanaryd/opencanary.conf. You must now edit the config file to determine which services and logging options you want to enable.
[!WARNING] The config file includes complex data, include Python objects for the logging configuration. The configuration is read while the process is running with root privileges. We recommend making the file root-owned and only writable by root. If regular users can write the file, it is possible to escalate privileges to root.
Configuration is performed via the JSON config file. Edit the file, and when happy save and exit.