Skip to content

OpenCanary Wiki

Jump to bottom
thinkst-daniel edited this page May 7, 2025 · 3 revisions

Welcome to the OpenCanary wiki!

Thanks for taking an interest in OpenCanary. We are excited to share this work with everyone and hope that you will be encouraged to contribute.

FAQ

How do I get OpenCanary and Samba to work?

Please head over to our dedicated page on this topic over here.

How do I use Dockerised OpenCanary?

Please head over to our dedicated page on this topic over here.

How do I start OpenCanary on startup?

We have had discussions about this in the issue thread over here. It may be useful to read through it as there are a few interesting solutions that folks suggested.

I have included a default opencanary.service file in the OpenCanary repo. If you would like to go this route simply follow these steps (please ensure you have run opencanaryd --start once to get the config setup to how you want it):

  1. copy the service file into /etc/systemd/system/opencanary.service.
  2. edit /etc/systemd/system/opencanary.service and add the full path of your virtual environment; replacing the <VIRTUAL_ENV_PATH> in the service file.
  3. reboot your system and check that opencanaryd is starting on start-up. You can check using systemctl status opencanary.

I'm receiving alerts on port 631 from 127.0.0.1

Port 631 is the default port for the CUPS (standards-based, open source printing system). We found a few workarounds:

  1. installing the CUPS service stopped the port 631 scans coming from 127.0.0.1.
  2. try systemctl stop cups && systemctl disable cups.
  3. add the line load printers = no to your Samba configuration file (/etc/samba/smb.conf). You can read about it over here

Opencanaryd not found

We have seen that in some cases the environment that you install your OpenCanary into via pip does not place opencanaryd into the $PATH. You will need to find where your installed OpenCanary. We highly recommend creating a virtual environment for it (using virtualenv env) and installing your OpenCanary into that environment (using pip install opencanary once you have activated the virtual environment using . env/bin/activate).

If you avoiding a virtual environment, please check your $PATH variable and ensure that opencanaryd is in one of the $PATH directories; otherwise add it.

Portscan Difficulties

The portscan feature of OpenCanary relies on the use of iptables.

  • Docker does not support the use of iptables so the portscan feature of OpenCanary is currently not supported in the dockerised version of OpenCanary
  • Newer versions of Linux based OSes use nftables by default and not iptables. nftables syntax is very different to iptables and so the necessary portscan iptables rules don't work. In order to fix this, we would recommend removing nftables and installing iptables.

Portscan not working on Debian 12

Debian 12 has removed system logging to files such as /var/log/kern.log to instead use systemd-journald (journalctl). This means that the logfile that our portscan module monitors for iptables events doesn't exist. To fix that we need to install rsyslog as a middle-man to make the systemd-journald logs available in the /var/log/kern.log file (this is monitored by OpenCanary)

Rsyslog Configuration

  1. Install rsyslog 
sudo apt-get update && sudo apt-get install rsyslog
  1. Edit the configuration file:
sudo nano /etc/rsyslog.conf
  1. Add the following line in the "global directives" section, to ensure the systemd-journald rsyslog listener is loaded
module(load="imjournal")
  1. Ensure that the following rule is present in the "rules" section
kern.* -/var/log/kern.log
  1. Check that /var/log/kern.log exists and is getting messages.
less /var/log/kern.log
  1. Restart rsyslog and check for any errors
sudo systemctl restart rsyslog && sudo systemctl status rsyslog
  1. Make sure that your Opencanary is using the default portscan.logfile which is /var/log/kern.log.

Iptables configuration

The newer nf_tables versions are unsupported by OpenCanary, so after configuring rsyslog we also need to make the following changes to use iptables instead:

  1. Switch from nf_tables to legacy iptables (persists)
sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
  1. Specify the iptables path in the opencanary.conf file (if you run into issue try /usr/sbin/iptables-legacy instead)
 "portscan.iptables_path":"/usr/sbin/iptables",
  1. Start OpenCanary
opencanaryd --start --uid=nobody --gid=nogroup

Dockerised OpenCanary is not reporting the correct IP

For Dockerised OpenCanary to report the correct IP of the attacker, it must be running on a linux based OS (not Windows or MacOS). The reason for this is that to get the correct IP of the attacker, we need to specify the host parameter for Docker's network_mode. This allows us to see the traffic straight from the host's interface instead of the traffic being NAT through the Docker network stack.

Clone this wiki locally