Two decoys are on by default and thirteen are commented out
Modular and decentralised honeypot
At a glance
- What is it?
- opencanary is a low-resource honeypot that emulates network services so you find out after someone is already inside. Its shipped compose file enables exactly two of the fifteen protocols it can imitate, its port-scan detection needs the older firewall backend that modern distributions no longer use, and its configuration file is Python that the daemon evaluates.
- Who is it for?
- OpenCanary fits anyone running internal services who has discovered that perimeter logs only tell you about the intrusion they already saw, and its cost is genuinely low enough to put one on a small machine per subnet. Three things to decide before you deploy it.
- Can I use it commercially?
- Yes. BSD-3-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 3 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- thinkst/opencanary3,108 ★ · +66
| Repository | 2026-09-24 | 2026-11-15 |
|---|---|---|
| thinkst/opencanary | 3k | 3.1k |
66 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The compose file enables two services and documents thirteen more
The clearest inventory of what this honeypot can imitate is a port list in the compose file, and it is worth reading line by line because of which lines are live.
Two are uncommented: file transfer on its standard port, and web traffic on its standard port. Those two are what you get out of the box.
The other thirteen are present and commented, each with a label naming the service. They cover secure shell, a line-oriented remote protocol, trivial file transfer, network time, network management, two database servers, remote desktop, virtual network computing, session initiation, a cache database that attackers routinely probe, a plain TCP banner service, an HTTP proxy, and the Git protocol.
The comment above the block says to uncomment the lines for the services you are using. So the design decision is exposed as configuration: a decoy is either on or off by editing one character, and the shipped default is minimal.
Two of those choices are notable for what they catch. A Git endpoint and an HTTP proxy attract a different class of traffic from a database port, and a proxy decoy in particular is the kind of thing an intruder tries first when they have already got shell access somewhere.
Host networking turns the port list into documentation
There is a subtlety in the compose file that will confuse anyone who has written compose files before.
Every service is set to use the host network engine. The readme explains why: the images are only useful on Linux hosts, because accurate network information requires it.
But a compose file using host networking does not publish ports. So the port list in this file is not doing the job it looks like it is doing: the container is on the host's network stack, the ports are already bound by the host, and those lines are there to document and to be toggled, not to map. Commenting a line out does not stop the honeypot from listening on that port; it just removes the line.
That is a fair design given the requirement, but it means the file cannot be read as if it were a port-mapping manifest, and a reviewer checking exposure should look at what the daemon binds rather than at the ports block.
The file also defines two services, one built from a file tracking the newest code and one from a file tracking the stable line. Both merge the same common block, including host networking and the same live port lines, so they are alternatives rather than a pair. Nothing in the file stops you starting both.
The port scan detector needs the firewall backend modern systems dropped
The optional modules are listed with their prerequisites, and one of them carries a requirement that has quietly stopped being met.
The port-scan module is described as using a packet filtering tool and explicitly not its newer successor, and as being supported only on Linux-based systems. So on a distribution whose firewall is the newer backend by default, that module either will not load or will not see anything.
That matters more than it looks. Port scanning is one of the earliest things an intruder does, so a module that silently detects nothing is worse than a module that is visibly absent. It is worth checking that your detection works on your distribution before you rely on it.
The other two optional modules are simpler. The network management module needs a packet library, and the Windows file share module needs a working file server, and that one is stated as unavailable on macOS. So the module set differs by platform in three places, and the readme is upfront about all three.
The configuration file is Python, and the daemon evaluates it
There is a warning callout near the configuration section that begins by telling you the config file includes complex data and includes Python objects. The sentence is cut off there, but the mechanism is not in doubt: the daemon reads that file as Python.
That is worth pausing on for a security tool. A honeypot's configuration is where you put callback addresses, credentials for outbound alerts, the services to imitate and the paths to watch. Making that file executable means anyone who can write it has code execution as the daemon's user, and it means the file belongs in the same review bucket as the application, with the same care about who commits it.
It also explains why the sample configuration is more than a list of settings. Complex data structures and embedded objects are the only way to express things like per-service options in one file, and the price is that a syntax error is a traceback rather than a parse message.
The practical guidance that follows the warning is to edit the file before starting the daemon, which is the right order, and to launch it with an explicit unprivileged user, which is the next section.
It starts as root and drops to an unprivileged user
The two commands that configure and start this daemon are worth reading as a pair, because the privilege story is in them.
The first must be run as root, and it writes the sample configuration into the system configuration directory. The second starts the daemon with an explicit user and group to drop to afterwards.
$ opencanaryd --copyconfig
[*] A sample config file is ready /etc/opencanaryd/opencanary.conf
[*] Edit your configuration, then launch with "opencanaryd --start --uid=nobody --gid=nogroup"So the process needs root to do one thing, and then is told to become an unprivileged identity for everything that follows. That is the right shape for a daemon that binds privileged ports and watches file paths, and it is stated in the same line that a reader will copy.
There is a separate wrinkle in the packaged route. The note about that route says that because of environment variable protections in modern privilege elevation, the entire command must be run as root or with the flag that preserves the environment. So one of the three installation routes needs elevated privileges for a reason that has nothing to do with binding ports.
Three package managers, and Scapy installed twice by two different routes
The installation section has grown three parallel paths, and the documentation handles that gracefully rather than pretending one of them does not exist.
There is the standard flow with the language's own package installer and a virtual environment. There is an equivalent flow for a newer, faster package manager, introduced with a sentence explaining that if that tool is installed you can use it, and that if it is not, the standard flow continues to work. And there is a packaged route that needs no installation at all, where you prefix the daemon with a third tool.
Each of the main blocks is then repeated for the alternative, so a reader on either toolchain finds a complete set rather than a footnote.
One papercut survives all three paths. The distribution package block installs the packet library through the system package manager, and the optional extras block installs the same packet library through pip, along with another one. So following the documented flow end to end installs two copies of the same library by two different routes, which on a system with a packaged version can produce a version mismatch at runtime.
The requirements file at the repository root is a single line that installs the project from itself in editable mode, which is a clean way to express a project-plus-its-own-dependencies.
Two Python versions are declared that the metadata forbids
The prerequisites say Python 3.10 or newer, and they say it twice, once for each processor architecture. That is consistent.
The packaging metadata is not. It declares the same floor in its requirement field, and its classifier list then runs from Python 3.8 all the way to 3.13.
So two versions are advertised to the classifier and refused by the resolver. In practice the floor wins, and a machine on either of the older versions is refused the install with a message about the requirement rather than with anything about the classifiers. The mismatch is cosmetic, but it is the kind of thing that makes a compatibility table unreliable for anyone planning a deployment across a fleet.
The rest of that classifier list is more informative than the requirement. It names the asynchronous networking framework the daemon is built on, three security and monitoring topics, an intended audience of developers, and Unix plus two specific Unix families rather than a generic operating system line.
Fourteen of eighteen dependencies are pinned to an exact version
The runtime dependency list is unusual, and the unusual part is the pinning.
Eighteen dependencies. Fourteen of them are pinned with an exact version operator, including the asynchronous framework, the templating engine, the HTTP client, the JSON library, and the interface package the framework needs. Only four carry a lower bound.
Some of those pins are the security argument rather than a style choice. The list contains a Windows authentication library, a password hashing library, a bcrypt implementation, a certificate identity library, an ASN.1 library, and two TLS stacks. For a tool whose entire job is parsing hostile network traffic from strangers, pinning the parsers and the credential code is a defensible stance even if it means the package manager will refuse to install until someone updates each pin by hand.
Two entries deserve separate mention. The build system package is pinned as a runtime dependency, which is not a thing most packages do. And one of the four lower-bound entries is a Git library, which is the reason the Git protocol decoy needs almost nothing extra to run.
Editorial conclusion
OpenCanary fits anyone running internal services who has discovered that perimeter logs only tell you about the intrusion they already saw, and its cost is genuinely low enough to put one on a small machine per subnet. Three things to decide before you deploy it. Which decoys to enable, because the default is two of fifteen and the choice is a comment in a compose file rather than a documented recommendation. Whether your firewall backend is compatible, because the port-scan detection module will not work on the newer one. And who writes the configuration, because that file is Python the daemon executes, so it belongs under the same review as code.
Frequently asked questions
how to install opencanary
With Python 3.10 or newer, create and activate a virtual environment and install the package. The documentation gives that flow for Ubuntu and for macOS, an equivalent flow for a newer package manager, a from-source route that builds a source distribution first, and a packaged route that requires no installation at all.
how to setup opencanary
Run the daemon once as root with the flag that copies a sample configuration into the system config directory, edit that file to choose which services and logging to enable, then start the daemon with the user and group it should drop to. The daemon stops looking for configuration at the first of three locations it finds.
What is a canary honeypot?
This repository does not define the term. It describes itself as a multi-protocol network honeypot whose primary use is to catch intruders after they have breached a non-public network, with low resource use and alerts by several mechanisms, and as the open source version of a commercial honeypot from the same company.
opencanary vs cowrie
This repository makes no comparison with other honeypots. What it lists instead is what it can imitate: fifteen network services across both processor architectures it supports, two of which are enabled in the shipped compose file and thirteen of which are present but commented out.
Who owns Thinkst Canary?
The repository is maintained by an applied research group at that company, and the readme states that the project is the open source version of the company's commercial honeypot. It is published under a BSD licence.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/thinkst-opencanary)Star history chart for your README
[](https://hysenlabs.com/projects/thinkst-opencanary)Was this useful?