OpenCanary Cheatsheet

OpenCanary is a daemon that runs canary services, which trigger on (ab)use. It's designed to be triggered by unknown users on your network, providing early warning of potential intrusions. OpenCanary creates honeypots that appear as legitimate services but alert administrators when accessed by unauthorized users.

Installation and Setup

Ubuntu/Debian Installation

Package Installation:

# Update package list
sudo apt update

# Install dependencies
sudo apt install python3-dev python3-pip python3-virtualenv python3-venv python3-scapy libssl-dev libpcap-dev

# Create virtual environment
python3 -m venv opencanary-env
source opencanary-env/bin/activate

# Install OpenCanary
pip install opencanary

# Install additional dependencies for specific services
pip install scapy pcapy-ng

# Verify installation
opencanaryd --help

From Source:

# Clone repository
git clone https://github.com/thinkst/opencanary.git
cd opencanary

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install OpenCanary
python setup.py install

# Verify installation
opencanaryd --version

Configuration

Generate Default Configuration:

# Create configuration directory
sudo mkdir -p /etc/opencanary

# Generate default configuration
opencanaryd --copyconfig

# Copy to system location
sudo cp ~/.opencanary.conf /etc/opencanary/opencanary.conf

# Set proper permissions
sudo chown root:root /etc/opencanary/opencanary.conf
sudo chmod 644 /etc/opencanary/opencanary.conf

Basic Configuration:

{
    "device.node_id": "opencanary-1",
    "device.name": "Production Server",
    "device.description": "Honeypot canary",
    "git.enabled": false,
    "git.port": 9418,
    "ftp.enabled": true,
    "ftp.port": 21,
    "ftp.banner": "FTP server ready",
    "http.enabled": true,
    "http.port": 80,
    "http.banner": "Apache/2.2.22",
    "http.skin": "nasLogin",
    "httpproxy.enabled": false,
    "httpproxy.port": 8080,
    "httpproxy.skin": "squid",
    "httpsProxy.enabled": false,
    "httpsProxy.port": 8443,
    "logger": {
        "class": "PyLogger",
        "kwargs": {
            "formatters": {
                "plain": {
                    "format": "%(asctime)s %(name)s: %(message)s"
                }
            },
            "handlers": {
                "console": {
                    "class": "logging.StreamHandler",
                    "stream": "ext://sys.stdout"
                },
                "file": {
                    "class": "logging.FileHandler",
                    "filename": "/var/log/opencanary.log"
                }
            }
        }
    },
    "portscan.enabled": true,
    "portscan.ignore_localhost": false,
    "smb.enabled": true,
    "smb.auditfile": "/var/log/opencanary-audit.log",
    "smb.domain": "corp.company.com",
    "mysql.enabled": true,
    "mysql.port": 3306,
    "mysql.banner": "5.5.43-0ubuntu0.14.04.1",
    "ssh.enabled": true,
    "ssh.port": 22,
    "ssh.version": "SSH-2.0-OpenSSH_5.1p1 Debian-4",
    "redis.enabled": false,
    "redis.port": 6379,
    "rdp.enabled": false,
    "rdp.port": 3389,
    "sip.enabled": false,
    "sip.port": 5060,
    "snmp.enabled": false,
    "snmp.port": 161,
    "ntp.enabled": true,
    "ntp.port": 123,
    "tftp.enabled": false,
    "tftp.port": 69,
    "tcpbanner.maxnum": 10,
    "tcpbanner.enabled": false,
    "tcpbanner_1.enabled": false,
    "tcpbanner_1.port": 8001,
    "tcpbanner_1.datareceivedbanner": "",
    "tcpbanner_1.initbanner": "",
    "tcpbanner_1.alertstring.enabled": false,
    "tcpbanner_1.alertstring": "",
    "tcpbanner_1.keep_alive.enabled": false,
    "tcpbanner_1.keep_alive_secret": "",
    "tcpbanner_1.keep_alive_probes": 11,
    "tcpbanner_1.keep_alive_idle": 300,
    "tcpbanner_1.keep_alive_interval": 300,
    "telnet.enabled": true,
    "telnet.port": 23,
    "telnet.banner": "",
    "telnet.honeycreds": [
        {
            "username": "admin",
            "password": "$pbkdf2-sha512$19000$bG1NaY3xvlRMwcplEs8u9w$dqK6J8UfzSXK6lZaFXJVUd.nVHLOdlVwIWaLxKqurLx6XRgRHMKe4lhDtdY8DwlnWqBJSEJyXP8RQOmvKjgdPw"
        }
    ],
    "mssql.enabled": false,
    "mssql.version": "2012",
    "mssql.port": 1433,
    "vnc.enabled": false,
    "vnc.port": 5900
}

Service Configuration

SSH Honeypot

SSH Configuration:

{
    "ssh.enabled": true,
    "ssh.port": 22,
    "ssh.version": "SSH-2.0-OpenSSH_5.1p1 Debian-4",
    "ssh.listen_addr": "0.0.0.0"
}

Custom SSH Banner:

# Create custom SSH banner
sudo tee /etc/opencanary/ssh_banner.txt << EOF
Welcome to Production Database Server
Unauthorized access is prohibited
All connections are logged and monitored
EOF

# Update configuration
{
    "ssh.enabled": true,
    "ssh.port": 22,
    "ssh.version": "SSH-2.0-OpenSSH_5.1p1 Debian-4",
    "ssh.banner": "/etc/opencanary/ssh_banner.txt"
}

HTTP/HTTPS Honeypot

HTTP Configuration:

{
    "http.enabled": true,
    "http.port": 80,
    "http.banner": "Apache/2.2.22 (Ubuntu)",
    "http.skin": "nasLogin",
    "http.listen_addr": "0.0.0.0"
}

Available HTTP Skins:

# Login page skins
"http.skin": "basicLogin"     # Basic login form
"http.skin": "nasLogin"       # NAS device login
"http.skin": "sindLogin"      # Synology login
"http.skin": "meraki"         # Cisco Meraki login
"http.skin": "ubnt"           # Ubiquiti login

# Custom skin directory
"http.skin": "custom",
"http.skindir": "/etc/opencanary/skins/"

HTTPS Configuration:

{
    "https.enabled": true,
    "https.port": 443,
    "https.banner": "Apache/2.2.22 (Ubuntu)",
    "https.skin": "nasLogin",
    "https.cert": "/etc/opencanary/cert.pem",
    "https.key": "/etc/opencanary/key.pem"
}

SMB Honeypot

SMB Configuration:

{
    "smb.enabled": true,
    "smb.auditfile": "/var/log/opencanary-audit.log",
    "smb.domain": "WORKGROUP",
    "smb.serverName": "FILESERVER",
    "smb.netbiosName": "FILESERVER",
    "smb.workgroup": "WORKGROUP"
}

SMB Shares Configuration:

{
    "smb.enabled": true,
    "smb.shares": [
        {
            "name": "Documents",
            "comment": "Shared Documents",
            "path": "/tmp/documents",
            "readonly": true
        },
        {
            "name": "Backup",
            "comment": "Backup Files",
            "path": "/tmp/backup",
            "readonly": false
        }
    ]
}

Database Honeypots

MySQL Configuration:

{
    "mysql.enabled": true,
    "mysql.port": 3306,
    "mysql.banner": "5.5.43-0ubuntu0.14.04.1",
    "mysql.listen_addr": "0.0.0.0"
}

MSSQL Configuration:

{
    "mssql.enabled": true,
    "mssql.version": "2012",
    "mssql.port": 1433,
    "mssql.listen_addr": "0.0.0.0"
}

Redis Configuration:

{
    "redis.enabled": true,
    "redis.port": 6379,
    "redis.listen_addr": "0.0.0.0"
}

Network Service Honeypots

Telnet Configuration:

{
    "telnet.enabled": true,
    "telnet.port": 23,
    "telnet.banner": "Welcome to Cisco Router",
    "telnet.honeycreds": [
        {
            "username": "admin",
            "password": "admin123"
        },
        {
            "username": "cisco",
            "password": "cisco"
        }
    ]
}

FTP Configuration:

{
    "ftp.enabled": true,
    "ftp.port": 21,
    "ftp.banner": "FTP server ready",
    "ftp.listen_addr": "0.0.0.0"
}

SNMP Configuration:

{
    "snmp.enabled": true,
    "snmp.port": 161,
    "snmp.listen_addr": "0.0.0.0"
}

Advanced Configuration

Port Scan Detection

Port Scan Configuration:

{
    "portscan.enabled": true,
    "portscan.ignore_localhost": false,
    "portscan.ports": [22, 23, 80, 443, 3389, 5900],
    "portscan.logfile": "/var/log/opencanary-portscan.log"
}

Custom TCP Banner

TCP Banner Configuration:

{
    "tcpbanner.maxnum": 10,
    "tcpbanner.enabled": true,
    "tcpbanner_1.enabled": true,
    "tcpbanner_1.port": 8001,
    "tcpbanner_1.datareceivedbanner": "Welcome to Custom Service",
    "tcpbanner_1.initbanner": "Custom Service v1.0",
    "tcpbanner_1.alertstring.enabled": true,
    "tcpbanner_1.alertstring": "ADMIN",
    "tcpbanner_1.keep_alive.enabled": true,
    "tcpbanner_1.keep_alive_secret": "keepalive123",
    "tcpbanner_1.keep_alive_probes": 11,
    "tcpbanner_1.keep_alive_idle": 300,
    "tcpbanner_1.keep_alive_interval": 300
}

Logging Configuration

Advanced Logging:

{
    "logger": {
        "class": "PyLogger",
        "kwargs": {
            "formatters": {
                "plain": {
                    "format": "%(asctime)s %(name)s[%(process)d]: %(levelname)s %(message)s"
                },
                "syslog": {
                    "format": "opencanary[%(process)d]: %(name)s %(levelname)s %(message)s"
                }
            },
            "handlers": {
                "console": {
                    "class": "logging.StreamHandler",
                    "stream": "ext://sys.stdout",
                    "formatter": "plain"
                },
                "file": {
                    "class": "logging.handlers.RotatingFileHandler",
                    "filename": "/var/log/opencanary.log",
                    "maxBytes": 10485760,
                    "backupCount": 5,
                    "formatter": "plain"
                },
                "syslog": {
                    "class": "logging.handlers.SysLogHandler",
                    "address": ["localhost", 514],
                    "facility": "local0",
                    "formatter": "syslog"
                }
            },
            "loggers": {
                "opencanary": {
                    "level": "INFO",
                    "handlers": ["console", "file", "syslog"]
                },
                "twisted": {
                    "level": "ERROR",
                    "handlers": ["file"]
                }
            }
        }
    }
}

Running OpenCanary

Manual Execution

Start OpenCanary:

# Start with default configuration
opencanaryd --start

# Start with custom configuration
opencanaryd --start --config=/etc/opencanary/opencanary.conf

# Start in foreground (for debugging)
opencanaryd --dev

# Start with specific log level
opencanaryd --start --logLevel=DEBUG

Stop OpenCanary:

# Stop OpenCanary daemon
opencanaryd --stop

# Force stop
sudo pkill -f opencanaryd

Service Management

Systemd Service:

# Create systemd service file
sudo tee /etc/systemd/system/opencanary.service << EOF
[Unit]
Description=OpenCanary Honeypot
After=network.target

[Service]
Type=forking
User=nobody
Group=nogroup
ExecStart=/usr/local/bin/opencanaryd --start --config=/etc/opencanary/opencanary.conf
ExecStop=/usr/local/bin/opencanaryd --stop
PIDFile=/var/run/opencanary.pid
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# Enable and start service
sudo systemctl enable opencanary
sudo systemctl start opencanary

# Check service status
sudo systemctl status opencanary

Init Script (SysV):

# Create init script
sudo tee /etc/init.d/opencanary << 'EOF'
#!/bin/bash
### BEGIN INIT INFO
# Provides:          opencanary
# Required-Start:    $network $local_fs $remote_fs
# Required-Stop:     $network $local_fs $remote_fs
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: OpenCanary Honeypot
# Description:       OpenCanary Honeypot Service
### END INIT INFO

DAEMON="opencanaryd"
CONFIG="/etc/opencanary/opencanary.conf"
USER="nobody"

case "$1" in
    start)
        echo "Starting OpenCanary..."
        su - $USER -c "$DAEMON --start --config=$CONFIG"
        ;;
    stop)
        echo "Stopping OpenCanary..."
        su - $USER -c "$DAEMON --stop"
        ;;
    restart)
        $0 stop
        sleep 2
        $0 start
        ;;
    status)
        if pgrep -f $DAEMON > /dev/null; then
            echo "OpenCanary is running"
        else
            echo "OpenCanary is not running"
        fi
        ;;
    *)
        echo "Usage: $0 {start|stop|restart|status}"
        exit 1
        ;;
esac

exit 0
EOF

# Make executable and enable
sudo chmod +x /etc/init.d/opencanary
sudo update-rc.d opencanary defaults

Monitoring and Alerting

Log Analysis

Parse OpenCanary Logs:

# View recent alerts
tail -f /var/log/opencanary.log

# Filter by service
grep "ssh" /var/log/opencanary.log
grep "http" /var/log/opencanary.log
grep "smb" /var/log/opencanary.log

# Extract source IPs
grep -oP 'src_host=\K[^,]*' /var/log/opencanary.log | sort | uniq -c | sort -nr

# Count alerts by service
grep -oP 'logtype=\K[^,]*' /var/log/opencanary.log | sort | uniq -c | sort -nr

# Extract failed login attempts
grep "login" /var/log/opencanary.log | grep -oP 'username=\K[^,]*' | sort | uniq -c

Log Format Examples:

# SSH connection attempt
2023-01-15 10:30:45,123 opencanary[1234]: INFO Received SSH connection from 192.168.1.100:54321

# HTTP access
2023-01-15 10:31:12,456 opencanary[1234]: INFO HTTP request from 192.168.1.100 for /admin

# SMB connection
2023-01-15 10:32:05,789 opencanary[1234]: INFO SMB connection from 192.168.1.100

# Port scan detection
2023-01-15 10:33:30,012 opencanary[1234]: INFO Port scan detected from 192.168.1.100

SIEM Integration

Syslog Integration:

# Configure rsyslog to forward OpenCanary logs
sudo tee /etc/rsyslog.d/50-opencanary.conf << EOF
# OpenCanary logs
local0.*    @@siem.company.com:514
local0.*    /var/log/opencanary-syslog.log
EOF

# Restart rsyslog
sudo systemctl restart rsyslog

Splunk Integration:

# Splunk Universal Forwarder configuration
# /opt/splunkforwarder/etc/apps/opencanary/local/inputs.conf
[monitor:///var/log/opencanary.log]
disabled = false
index = security
sourcetype = opencanary
host = honeypot-01

# Splunk search examples
index=security sourcetype=opencanary
| stats count by src_host, logtype
| sort -count

index=security sourcetype=opencanary logtype=ssh
| eval hour=strftime(_time, "%H")
| stats count by hour
| sort hour

ELK Stack Integration:

# Filebeat configuration
filebeat.inputs:
- type: log
  enabled: true
  paths:
    - /var/log/opencanary.log
  fields:
    logtype: opencanary
  fields_under_root: true

output.elasticsearch:
  hosts: ["elasticsearch:9200"]
  index: "opencanary-%{+yyyy.MM.dd}"

# Logstash filter
filter {
  if [logtype] == "opencanary" {
    grok {
      match => { 
        "message" => "%{TIMESTAMP_ISO8601:timestamp} %{WORD:service}\[%{NUMBER:pid}\]: %{LOGLEVEL:level} %{GREEDYDATA:event_data}"
      }
    }
    
    if "src_host=" in [event_data] {
      grok {
        match => {
          "event_data" => "src_host=%{IP:src_ip}"
        }
      }
    }
    
    date {
      match => [ "timestamp", "yyyy-MM-dd HH:mm:ss,SSS" ]
    }
  }
}

Alerting Scripts

Email Alerts:

#!/usr/bin/env python3
import re
import smtplib
import subprocess
from email.mime.text import MIMEText
from email.mime.multipart import MIMEMultipart

def send_alert(subject, body, to_email):
    """Send email alert"""
    smtp_server = "smtp.company.com"
    smtp_port = 587
    from_email = "alerts@company.com"
    password = "your_password"
    
    msg = MIMEMultipart()
    msg['From'] = from_email
    msg['To'] = to_email
    msg['Subject'] = subject
    
    msg.attach(MIMEText(body, 'plain'))
    
    server = smtplib.SMTP(smtp_server, smtp_port)
    server.starttls()
    server.login(from_email, password)
    text = msg.as_string()
    server.sendmail(from_email, to_email, text)
    server.quit()

def monitor_opencanary_log():
    """Monitor OpenCanary log for new alerts"""
    log_file = "/var/log/opencanary.log"
    
    # Use tail to follow log file
    process = subprocess.Popen(['tail', '-F', log_file], 
                             stdout=subprocess.PIPE, 
                             stderr=subprocess.PIPE)
    
    while True:
        line = process.stdout.readline().decode('utf-8').strip()
        if line:
            # Parse log entry
            if "ssh" in line.lower() or "http" in line.lower():
                # Extract source IP
                ip_match = re.search(r'(\d+\.\d+\.\d+\.\d+)', line)
                if ip_match:
                    src_ip = ip_match.group(1)
                    
                    # Send alert
                    subject = f"OpenCanary Alert: Activity from {src_ip}"
                    body = f"OpenCanary detected activity:\n\n{line}"
                    send_alert(subject, body, "security@company.com")

if __name__ == "__main__":
    monitor_opencanary_log()

Slack Integration:

#!/usr/bin/env python3
import json
import requests
import subprocess
import re

def send_slack_alert(webhook_url, message):
    """Send alert to Slack"""
    payload = {
        "text": message,
        "username": "OpenCanary",
        "icon_emoji": ":warning:"
    }
    
    response = requests.post(webhook_url, json=payload)
    return response.status_code == 200

def monitor_and_alert():
    """Monitor OpenCanary and send Slack alerts"""
    webhook_url = "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
    log_file = "/var/log/opencanary.log"
    
    process = subprocess.Popen(['tail', '-F', log_file], 
                             stdout=subprocess.PIPE)
    
    while True:
        line = process.stdout.readline().decode('utf-8').strip()
        if line and ("ssh" in line.lower() or "http" in line.lower()):
            # Extract details
            ip_match = re.search(r'(\d+\.\d+\.\d+\.\d+)', line)
            service_match = re.search(r'(ssh|http|smb|ftp)', line.lower())
            
            if ip_match and service_match:
                src_ip = ip_match.group(1)
                service = service_match.group(1).upper()
                
                message = f":warning: *OpenCanary Alert*\n" \
                         f"Service: {service}\n" \
                         f"Source IP: {src_ip}\n" \
                         f"Time: {line.split()[0]} {line.split()[1]}"
                
                send_slack_alert(webhook_url, message)

if __name__ == "__main__":
    monitor_and_alert()

Security Considerations

Network Placement

DMZ Deployment:

# Place OpenCanary in DMZ
# Configure firewall rules to allow specific traffic

# Allow SSH from management network
iptables -A INPUT -s 10.0.0.0/8 -p tcp --dport 22 -j ACCEPT

# Allow HTTP/HTTPS from internet
iptables -A INPUT -p tcp --dport 80 -j ACCEPT
iptables -A INPUT -p tcp --dport 443 -j ACCEPT

# Log and drop everything else
iptables -A INPUT -j LOG --log-prefix "CANARY-DROP: "
iptables -A INPUT -j DROP

Internal Network Deployment:

# Deploy multiple canaries in different network segments
# Segment 1: 192.168.1.0/24 (User network)
# Segment 2: 192.168.10.0/24 (Server network)
# Segment 3: 192.168.100.0/24 (Management network)

# Configure different services per segment
# User network: HTTP, SMB, SSH
# Server network: MySQL, MSSQL, Redis
# Management network: SNMP, Telnet, SSH

Hardening

System Hardening:

# Create dedicated user
sudo useradd -r -s /bin/false opencanary

# Set file permissions
sudo chown -R opencanary:opencanary /etc/opencanary/
sudo chmod 600 /etc/opencanary/opencanary.conf

# Disable unnecessary services
sudo systemctl disable apache2
sudo systemctl disable mysql
sudo systemctl disable ssh

# Configure firewall
sudo ufw enable
sudo ufw default deny incoming
sudo ufw allow from 10.0.0.0/8 to any port 22

SSL/TLS Configuration:

# Generate SSL certificate for HTTPS honeypot
openssl req -x509 -newkey rsa:4096 -keyout /etc/opencanary/key.pem \
            -out /etc/opencanary/cert.pem -days 365 -nodes \
            -subj "/C=US/ST=State/L=City/O=Organization/CN=honeypot.local"

# Set proper permissions
sudo chown opencanary:opencanary /etc/opencanary/*.pem
sudo chmod 600 /etc/opencanary/*.pem

Troubleshooting

Common Issues

Port Binding Problems:

# Check if ports are already in use
sudo netstat -tlnp | grep :22
sudo netstat -tlnp | grep :80

# Kill conflicting processes
sudo systemctl stop ssh
sudo systemctl stop apache2

# Use alternative ports
{
    "ssh.port": 2222,
    "http.port": 8080
}

Permission Issues:

# Fix log file permissions
sudo touch /var/log/opencanary.log
sudo chown opencanary:opencanary /var/log/opencanary.log
sudo chmod 644 /var/log/opencanary.log

# Fix configuration permissions
sudo chown opencanary:opencanary /etc/opencanary/opencanary.conf
sudo chmod 600 /etc/opencanary/opencanary.conf

Service Startup Issues:

# Check service status
sudo systemctl status opencanary

# View service logs
sudo journalctl -u opencanary -f

# Debug configuration
opencanaryd --dev --config=/etc/opencanary/opencanary.conf

# Validate configuration
python3 -c "import json; json.load(open('/etc/opencanary/opencanary.conf'))"

Debugging

Enable Debug Logging:

{
    "logger": {
        "class": "PyLogger",
        "kwargs": {
            "loggers": {
                "opencanary": {
                    "level": "DEBUG",
                    "handlers": ["console", "file"]
                }
            }
        }
    }
}

Test Individual Services:

# Test SSH honeypot
ssh -p 22 localhost

# Test HTTP honeypot
curl -v http://localhost/

# Test SMB honeypot
smbclient -L localhost

# Test MySQL honeypot
mysql -h localhost -u root -p

Network Testing:

# Test from external host
nmap -sS -O target_honeypot_ip

# Test specific services
nc -v target_honeypot_ip 22
nc -v target_honeypot_ip 80
nc -v target_honeypot_ip 3306

# Monitor network traffic
sudo tcpdump -i any -n host target_honeypot_ip

This comprehensive OpenCanary cheatsheet covers installation, configuration, service setup, monitoring, alerting, and security considerations for effective honeypot deployment and threat detection.