OpenCanary: a multi-protocol honeypot for internal networks

What OpenCanary is for, and who should run it

OpenCanary is a multi-protocol network honeypot that runs as a daemon. The README states its primary use case plainly: catching attackers after they have breached non-public networks. That framing matters, because it puts the tool behind the perimeter rather than at it. You deploy it on an internal segment where ordinary users and services have no reason to connect, and any interaction with it is by definition suspicious.

The intended operator is a defender with a Linux host and a modest budget for noise. The README notes extremely low resource requirements and gives a Raspberry Pi or a minimal VM as examples, so the hardware bar is low. What is not low is the operational discipline: a honeypot that nobody monitors is just an unused port. If you cannot route its alerts somewhere a human reads, the deployment is decorative.

How the daemon, modules and alerting fit together

OpenCanary is written in Python and built on Twisted, which the package metadata lists as a runtime dependency. The daemon implements several common network protocols as modules. The docker-compose file in the repository enumerates the services the project ships: FTP, SSH, Telnet, TFTP, HTTP, NTP, SNMP, MSSQL, MYSQL, RDP, VNC, SIP, Redis, a TCP banner, an HTTP proxy and Git. Each is a listener on its well-known port, and each is enabled or disabled through configuration rather than code changes.

When a client interacts with one of those listeners, the daemon records the event and sends an alert. The README describes the alert as highlighting the threat source IP address and where the breach may have occurred. Alerting is pluggable: the configuration file controls which handlers fire, and the dependency list includes requests, hpfeeds, redis and Jinja2, which correspond to webhook-style, hpfeeds, Redis and email-style delivery paths. There is no central controller. Each instance is independent, which is what the project means by decentralised: you can scatter nodes across segments without a management server tying them together.

The trade-off in that design is that correlation is your problem. Ten OpenCanary nodes produce ten streams unless you aggregate them yourself.

Installing OpenCanary and getting a first alert

The README documents installation on Ubuntu 22.04 LTS or 24.04 LTS, on macOS, from Git, and via Docker. The Ubuntu path needs system packages first, then a virtual environment, then the package from PyPI. Python 3.10 or newer is required on both AMD64 and ARM64.

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

The README also gives a uv equivalent, replacing the virtualenv and pip steps with `uv venv env` and `uv pip install opencanary`. Optional extras are separate: the Windows File Share module needs a working Samba installation, and the SNMP module needs Scapy and pcapy-ng.

Configuration comes next. The daemon searches three locations in order and stops at the first file it finds: `/etc/opencanaryd/opencanary.conf`, then `~/.opencanary.conf`, then `./opencanary.conf` in the install directory. To generate a starting file, run as root:

opencanaryd --copyconfig

That places a config with every module and handler stubbed out. You edit it to enable the protocols you want and to set an alert destination. Then start the daemon. The repository ships an `opencanary.service` unit file for systemd deployments, and the README's running section covers starting it directly on Linux or macOS.

For Docker, the project publishes images on Docker Hub and the compose file defines two services, `latest` and `stable`, both using `network_mode: "host"`. The README is explicit that the images are only useful on Linux Docker hosts, because the host network engine is required for accurate network information. The compose file mounts the config from `./data/.opencanary.conf` into `/root/.opencanary.conf` and lists every service port as a commented line you uncomment to enable.

docker-compose up --build -d stable

After starting, the thing to verify is not that the process is alive but that a connection to an enabled port produces an alert at your configured destination. Connect to the FTP or HTTP port from another host and watch for the event.

Where OpenCanary is the wrong tool

The portscan module is the clearest constraint. The README says it uses iptables rather than nftables and is supported only on Linux-based operating systems. On a host where nftables has replaced iptables, or on macOS, that module is not an option. This is not a minor footnote; portscan detection is one of the behaviours people most want from a honeypot, and here it is tied to a specific firewall backend.

The Samba module has a similar shape. It depends on a working Samba installation, and the macOS section states outright that the Windows File Share module is not available there. If your environment is Mac-heavy, you are running a reduced OpenCanary.

There is also a conceptual limit. OpenCanary detects interaction, not exploitation. A listener that answers on port 21 will log a connection attempt whether the client is a curious admin with a mistyped hostname or an attacker enumerating the subnet. The README does not document any mechanism for distinguishing the two, and it does not document rollback or an undo path for configuration changes. Treat every alert as a lead to investigate, not a verdict.

Finally, the README does not document a built-in log retention policy, rotation scheme or query interface. What you do with the events after they are emitted is outside the daemon's scope.

OpenCanary compared with Cowrie

Cowrie is the alternative most often raised, and the difference is architectural rather than cosmetic. Cowrie is an SSH and Telnet honeypot with an emphasis on interactive emulation: it presents a shell, records sessions, and captures attacker commands. OpenCanary spreads across many protocols instead of going deep on one, and it does not present an interactive shell to the attacker in the same way.

That changes what you learn. A Cowrie deployment tells you what an attacker typed once they believed they had a shell. An OpenCanary deployment tells you that something touched port 1433 or port 3389 on a segment where nothing should. The first is a research instrument; the second is a tripwire. They are not substitutes, and running both on the same host requires care, since they compete for the same well-known ports.

If your goal is to study credential-guessing behaviour against SSH, Cowrie is the closer fit. If your goal is broad, cheap coverage of a flat internal network with a single daemon and a config file, OpenCanary is the closer fit.

Maintenance, releases and the BSD licence

The repository is not archived, and the last push was on 2026-09-21, which is the same date as the v0.9.10 release. Releases arrive at a steady cadence: v0.9.8 on 2026-05-18, v0.9.9 on 2026-07-22, v0.9.10 on 2026-09-21. That is roughly a two-month rhythm across the visible window, and the version numbers still sit below 1.0 despite the package metadata classifying the project as Production/Stable.

Upgrade cost is mostly dependency churn. The pyproject file pins Twisted at 26.4.0, cryptography at 50.0.0 or newer, requests at 2.33.0, Redis at 7.4.0 and several others to exact versions. Exact pins make upgrades predictable but also mean a security fix in one of those libraries requires a new OpenCanary release or a local override. Plan for periodic reinstallation rather than in-place patching, and test the config against the new version before swapping it into a monitored segment.

On licensing, the project is BSD-3-Clause, and the package metadata declares the license as BSD. That is permissive: it allows commercial use and modification with attribution and without a copyleft obligation on your own code. It is not legal advice, and if you are embedding OpenCanary in a product you should read the LICENSE file in the repository root yourself. Note also that OpenCanary is the open source version of Thinkst's commercial Canary product, so the two share a lineage but not a licence.

Editorial conclusion

Adopt OpenCanary if you have a non-public network segment where nothing legitimate should ever connect, and you can run a Linux host with iptables and a working alert path. Do not adopt it as a perimeter IDS, as a replacement for Samba auditing, or on macOS if you need the Windows File Share module, which the README says is unavailable there. Before rollout, verify that the protocol modules you enable are actually reachable on the ports you expect, that the config file is being read from the location you think it is, and that alerts arrive at your chosen destination rather than only in the local log.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. Project website
3. README
4. Releases
5. thinkst/opencanary on GitHub