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.
- Prerequisites
- Features
- Installation
- Configuring OpenCanary
- Running OpenCanary
- Documentation
- Project Participation
- AMD64: Python 3.7 (Recommended Python 3.7+)
- ARM64: Python 3.9+
- Optional SNMP requires the Python library Scapy
- Optional Samba module needs a working installation of Samba
- Optional Portscan uses iptables (not nftables) and is only supported on Linux-based operating systems
- Mimic an array of network-accessible services for attackers to interact with.
- Receive various alerts as soon as potential threats are detected, highlighting the threat source IP address and where the breach may have occurred.
The OpenCanary installation essentially involves ensuring the Python environment is ready, then installing the OpenCanary Python package (plus optional extras).
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 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
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/openssl@1.1/lib" CFLAGS="-I/opt/homebrew/opt/openssl@1.1/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
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
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:
./opencanary.conf(i.e. the directory where OpenCanary is installed)~/.opencanary.conf(i.e. the home directory of the user, usually this will berootso/root/.opencanary.conf)/etc/opencanaryd/opencanary.conf
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.
Configuration is performed via the JSON config file. Edit the file, and when happy save and exit.
The snmp module is only available when Scapy is present. See the installation steps for SNMP above.
The portscan module is only available on Linux hosts, as it modifies iptables rules.
Please note that for the Portscan service, we have added a portscan.ignore_localhost setting, which means the OpenCanary portscan service will ignore (not alert on) port scans originating for the localhost IP (127.0.0.1). This setting is false by default.
The Windows File Share module (smb) requires a Samba installation. See a step-by-step guide on the Wiki.
OpenCanary is either run directly on a Linux or macOS host, or via a Docker container.
Start OpenCanary by running:
$ . env/bin/activate
$ opencanaryd --start --uid=nobody --gid=nogroup
With the uid and gid flags, OpenCanary drops root privileges after binding to its ports. This can be changed to other low-privileged user/group or omitted to keep running with root privileges.
Start OpenCanary by running:
$ sudo -E pkgx opencanaryd --start --uid=nobody --gid=nogroup
With the uid and gid flags, OpenCanary drops root privileges after binding to its ports. This can be changed to other low-privileged user/group or omitted to keep running with root privileges.
The route requires Docker and Docker Compose to be installed.
Note The portscan module is automatically disabled for Dockerised OpenCanary.
- Edit the
data/.opencanary.conffile to enable, disable or customize the services that will run. - Edit the
portssection of thedocker-compose.ymlfile to enable/disable the desired ports based on the services you have enabled in the config file. - Run the container.
docker-compose up latest
To view the logs run docker-compose logs latest.
To stop the container run docker-compose down.
To build your own Docker OpenCanary using docker compose, head over to our wiki
Please head over our dedicated Docker wiki for everything Dockerised OpenCanary.
Please head over to our forked repository for an Ansible OpenCanary role over here.
We welcome PRs to this project. Please read our Code of Conduct and Contributing documents before submitting a pull request.
At a minimum you should run pre-commit before submitting the PR. Install and run it in the same Python environment that OpenCanary is installed into:
$ pip install pre-commit
# Do work
$ git add file
$ pre-commit
$ git add file # only run this if pre-commit auto-fixed the file
$ git commit
See our Security Policy for details on how to report security vulnerabilities.
Please file bug reports on Github using the template we provide.
Feature requests are tracked here.
This project and everyone participating in it is governed by the Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to github@thinkst.com.