DOCSEARCHbyAlgolia
Submit Docs

OpenCanary Documentation

repository·master·Indexed 25 days ago

https://github.com/thinkst/opencanary

OpenCanary is a multi-protocol network honeypot designed to detect attackers who have breached a network by mimicking various network services and sending alerts upon unauthorized interaction. It supports a wide range of services including FTP, SSH, Telnet, HTTP, SNMP, MSSQL, MYSQL, RDP, and more. The project provides a daemon (opencanaryd) for management and supports deployment via Python virtual environments, Docker Compose, and pkgx.

Tokens
12.1K
Snippets
39
Records
71
Agent score
83%

What's inside OpenCanary

  1. Overview of OpenCanary services and alerting

    master
    OpenCanary is a daemon that runs canary services. When these services are interacted with, they trigger alerts. Alerts can be sent to various destinations such as Syslog, email, or via the opencanary-correlator daemon. The Correlator is used to coalesce multiple related events (like individual brute-force login attempts) into a single alert sent via email or SMS.

  2. Run and test OpenCanary

    master

    Once configured, you can start the OpenCanary daemon and verify it is working by triggering a service (e.g., FTP) and checking the logs.

    1. Start the daemon:
    $ opencanaryd --start
    1. Trigger an alert (e.g., via FTP):
    $ ftp localhost
    1. Verify the alert in the log file:
    $ cat /var/tmp/opencanary.log
    $ opencanaryd --start
$ ftp localhost
$ cat /var/tmp/opencanary.log

  3. Upgrade OpenCanary

    master
    To upgrade an existing installation of OpenCanary, activate your Python virtual environment and use pip or uv to upgrade the opencanary package. Upgrading does not wipe your existing configuration file. If you want to generate a new configuration file with updated settings, use the --copyconfig flag.

  4. Install OpenCanary on Ubuntu

    master

    To install OpenCanary on Ubuntu 22.04 LTS or 24.04 LTS, install the required system dependencies, create a virtual environment, and install the opencanary package.

    Prerequisites:

    • Python 3.10+
    • For SNMP module: scapy
    • For Windows File Share (smb) module: samba
    • For Portscan module: iptables (Linux only)
    $ 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

  5. Install OpenCanary from source via Git

    master

    Clone the repository and use setup.py to create a distribution package, then install it via pip or uv.

    $ git clone https://github.com/thinkst/opencanary
$ cd opencanary
$ python setup.py sdist
$ cd dist
$ pip install opencanary-<version>.tar.gz

  8. Configure Samba `smb.conf` for OpenCanary auditing

    master

    To allow OpenCanary to monitor Samba activity, configure your smb.conf to use the full_audit VFS object. Ensure the full_audit:facility is set to local7 so that logs can be redirected via Syslog.

    Important: You should customize the following fields in the example configuration:

    • server string
    • netbios name
    • The share name (e.g., [myshare])
    • The path for the share

    Ensure that the smbd_audit logs to the file specified in your OpenCanary configuration (e.g., /var/log/samba-audit.log).

    [global]
    workgroup = WORKGROUP
    server string = NBDocs
    netbios name = SRV01
    dns proxy = no
    log file = /var/log/samba/log.all
    log level = 0
    max log size = 100
    panic action = /usr/share/samba/panic-action %d
    server role = standalone
    passdb backend = tdbsam
    obey pam restrictions = yes
    unix password sync = no
    map to guest = bad user
    usershare allow guests = yes
    load printers = no
    vfs object = full_audit
    full_audit:prefix = %U|%I|%i|%m|%S|%L|%R|%a|%T|%D
    full_audit:success = flistxattr
    full_audit:failure = none
    full_audit:facility = local7
    full_audit:priority = notice
[myshare]
    comment = All the stuff!
    path = /samba
    guest ok = yes
    read only = yes
    browseable = yes

  9. Initialize OpenCanary configuration

    master

    To create a default configuration file, run the --copyconfig flag as root. This generates a sample configuration at /etc/opencanaryd/opencanary.conf.

    Warning: The configuration file contains Python objects for logging. It is highly recommended to make the file root-owned and only writable by root to prevent privilege escalation.

    $ opencanaryd --copyconfig

  10. Run the OpenCanary Correlator daemon

    master

    Before running the correlator, ensure that a Redis server is running. You can then start the correlator daemon by pointing it to your configuration file using the --config flag.

    # Check if redis-server is running
pgrep redis-server || echo 'Redis is not running!'

# Run the correlator
opencanary-correlator --config=./opencanary-correlator.conf
    $ pgrep redis-server || echo 'Redis is not running!'
$ opencanary-correlator --config=./opencanary-correlator.conf

  11. Install OpenCanary on macOS

    master

    To install OpenCanary on macOS, create a Python virtual environment and manually compile cryptography with the correct OpenSSL flags to avoid version conflicts. Note that the Windows File Share (smb) module is not available on macOS.

    Installation Steps:

    1. Create and activate a virtual environment.
    2. Install cryptography using specific ARCHFLAGS and LDFLAGS based on your architecture (Intel/x86_64 or Apple Silicon/M1).
    3. Install opencanary and optional dependencies like scapy and pcapy-ng.
    # 1. Create virtual environment
$ virtualenv env/
$ . env/bin/activate

# 2. Install cryptography (Choose the command for your architecture)
# For Macports users:
$ sudo port install openssl
$ env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/opt/local/lib" CFLAGS="-I/opt/local/include" pip install cryptography

# For Homebrew x86 users:
$ 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

# For Homebrew M1 users:
$ 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

# 3. Install OpenCanary
$ pip install opencanary
$ pip install scapy pcapy-ng # optional