OpenCanary attack detection

Canary in a Coal Mine

Article from ADMIN 75/2023
The canary in a coal mine has made its way metaphorically into IT security with the OpenCanary honeypot for detecting attacks.

The idea of using honeypots to let attackers penetrate specially prepared systems in an effort to learn more about the attackers themselves and the methods they use is long established. The aim is to uncloak the perpetrators' actions and, in particular, how they move around the network (lateral movement) or what information they access.

Honeypots are also deployed to capture email spam. Email accounts created especially for this purpose are published in non-visible areas of websites. The assumption is that bots collect these addresses and use them to spread spam. The incoming email is bound to be spam and can therefore help improve the filter.

OpenCanary [1] lets you set up network services quickly, and it notifies you when they are accessed. You have many options. On the one hand, you can run OpenCanary on public addresses that are not used for other purposes. Neighboring IP addresses of publicly available services, but also neighboring or unused ports on these machines, are often a good choice. If you are running a web server, it usually responds to requests on ports 80 and 443. Nowadays these requests are often forwarded to internal services with the web server as a proxy. Attackers try to access poorly secured or vulnerable servers or internal information over ports 8001, 8080, 8443, or 9000, for example.

If you run a honeypot with a public IP address, you will quickly notice that an incredible number of requests are addressed there. Most are probably just scans, often triggered by (mostly) legitimate systems, such as vulnerability scanners like Shodan [2] or security researchers around the world. If you generate an alert for each event, you will miss the actual attacks in the mess of data.

OpenCanary offers genuine added value if you run it on your internal network. Once an attacker has penetrated a corporate network, they will pursue different goals, starting with persistent login options on the computer to which they already have access. Maybe they will install a reverse shell, a customized remote administration toolkit (RAT), or simply TeamViewer to access the hijacked computer time and time again.

Installation in Docker

You have different options for deploying OpenCanary on your network. If you use pip in your Python environment, you can easily start the installation with

pip install opencanary

For individual modules, such as Samba, you will then need additional dependencies. A Docker installation on your server is easier. The OpenCanary Git repository is already prepared for use. To create your Docker container, first clone OpenCanary with the command:

git clone

In the opencanary/data folder you will find the .opencanary.conf file, where you can configure your notifications and active services. To receive an email notification when access occurs, look for the PyLogger configuration under logger. You will see two preconfigured handlers: one for logging to the console and one for the opencanary.log logfile. Listing 1 shows how to add another handler.

Listing 1

Adding a Handler

"SMTP": {
   "class": "logging.handlers.SMTPHandler",
   "mailhost": ["", 587],
   "fromaddr": "",
   "toaddrs" : [""],
   "subject" : "Alert from OpenCanary",
   "credentials" : ["canary@it-administrator", "password"],
   "secure" : []

You need to adjust the port in mailhost to match your own mail server. In my tests, name resolution of the mail host in the container did not always work reliably. To avoid seeing errors during your tests, just type your mail server's IP address instead of the domain.

Trial Run

If you want to add more services to those you already fired up, ftp and http, find the .enabled parameter in each case and change the value from false to true. In Windows environments, terminal servers (Remote Desktop Protocol, RDP) are a good choice, whereas attackers in Linux environments would try accessing SSH servers to move around the network. Once you have enabled all the services you want, close the configuration file. Before proceeding, you need to forward all the required ports in the docker-compose.yml file to match your choice of services; then you can create and start the container:

docker compose up -d --build latest

Now you can use netstat to check that Docker is using the selected ports. In the meantime, you should have a message about OpenCanary starting up in your email inbox – you configured logging for this. To only receive alerts to the defined email address, you need to set up appropriate filters with PyLogger. If you enabled the HTTP service, you can call it for a test by pointing your browser at https://localhost . OpenCanary emulates a Synology disk station at this address (Figure 1).

Figure 1: A Synology DiskStation login generated by OpenCanary.

After that, you should find mail in your inbox with a matching alert. The message only contains a JSON-formatted alert. Because it is created by PyLogger, it can also be evaluated automatically from the logfile created by OpenCanary, which is easier to integrate with your existing monitoring setup.

The logged information changes from service to service. If you use the MySQL honeypot, you will also see the user names and any passwords entered in the logdata field of the alert, which could already give you a first hint as to the path and possibly the account the attacker is using. The most important information in an alert, however, is likely to be the src_host. Although that is simply the Docker host in this example, in a real attack on your systems, you will see an IP address in your infrastructure. The system with this IP address is probably already controlled by some attacker.

The response to detecting an attacker can even be automated to some extent if you use dynamic network configurations. You can isolate the affected computer from the network and let it continue to run in a protected environment – a walled garden – for the time being and examine it more closely without the attacker directly noticing that they have already been discovered. Otherwise, you will want to remove the affected system completely from the network for further investigation.


OpenCanary helps you track down attackers as they roam your network. The services available out of the box cover the type of servers that usually exist in a corporate environment and are unlikely to attract excessive scrutiny from attackers. As shown in this article, it is easy to deploy an initial version of the honeypot framework on your network and receive alerts by email. From there, you can continue to strengthen your company's line of defense.

The Author

Dr. Matthias Wübbeling is an IT security enthusiast, scientist, author, consultant, and speaker. As a lecturer at the University of Bonn in Germany and researcher at Fraunhofer FKIE, he works on projects in network security, IT security awareness, and protection against account takeover and identity theft. He is the CEO of the university spin-off Identeco, which keeps a leaked-identity database to protect employee and customer accounts against identity fraud. As a practitioner, he supports the German Informatics Society (GI), administrating computer systems and service back ends. He has published more than 100 articles on IT security and administration.

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy ADMIN Magazine

Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

comments powered by Disqus
Subscribe to our ADMIN Newsletters
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs

Support Our Work

ADMIN content is made possible with support from readers like you. Please consider contributing when you've found an article to be beneficial.

Learn More”>


		<div class=