opencanary documentationsmb - a log watcher for samba logging ﬁles which allows opencanary to...

OpenCanary DocumentationRelease 0.6

Thinkst Applied Research

Jun 04, 2021

Contents

1 Getting Started 3

2 Services 11

3 Alerting 15

4 Upgrading 19

5 Indices and tables 21

i

OpenCanary Documentation, Release 0.6

Welcome to the OpenCanary guide.

OpenCanary is a daemon that runs canary services, which trigger alerts when (ab)used. The alerts can be sent to avariety of sources, including syslog, emails and a companion daemon opencanary-correlator.

The Correlator coalesces multiple related events (eg. individual brute-force login attempts) into a single alert sent viaemail or SMS.

Contents 1


2 Contents

CHAPTER 1

Getting Started

The first section will get you quickly up and running with canary services sending alerts.

1.1 OpenCanary

1.1.1 Getting Started

To get started create a virtual environment to play in:

$ virtualenv env$ . env/bin/activate

Inside the virtualenv, install OpenCanary following the instructions in the README.

OpenCanary ships with a default config, which we’ll copy and edit to get started. The config is a single JSONdictionary.

$ opencanaryd --copyconfig$ $EDITOR ~/.opencanary.conf

In the config file we’ll change device.node_id which must be unique for each instance of opencanaryd, and we’llconfigure logger to log alerts to a file.

{"device.node_id": "Your-very-own-unique-name",[...]"logger": {

"class" : "PyLogger","kwargs" : {

"handlers": {"file": {

"class": "logging.FileHandler","filename": "/var/tmp/opencanary.log"

(continues on next page)

3

https://github.com/thinkst/opencanaryhttps://en.wikipedia.org/wiki/JSON


(continued from previous page)

}}

}}

[...]}

With that in place, we can run the daemon, and test that it logs a failed FTP login attempt to the log file.

$ opencanaryd --start[...]$ ftp localhost[...]$ cat /var/tmp/opencanary.log[...]{"dst_host": "127.0.0.1", "dst_port": 21, "local_time": "2015-07-20 13:38:21.281259",→˓"logdata": {"PASSWORD": "default", "USERNAME": "admin"}, "logtype": 2000, "node_id→˓": "opencanary-0", "src_host": "127.0.0.1", "src_port": 49635}

1.1.2 Troubleshooting

The tool JQ can be used to check that the config file is well-formed JSON.

$ jq . ~/.opencanary.conf

Run opencanaryd in the foreground to see more error messages.

$ opencanaryd --dev

You may also easily restart the service using,

$ opencanaryd --restart

1.2 Configuration

Since we have many services, and each service has a few options, we have listed them all for you.

1.2.1 Services Configuration

We have gone ahead and listed all the services by their configuration key with a quick description of the service andwhen it alerts.

Currently OpenCanary supports faking the following services natively:

• ssh : a Secure Shell server which alerts on login attempts

• ftp - a File Transfer Protocol server which on login attempts

• git - a Git protocol which alerts on repo cloning

• http - an HTTP web server that alerts on login attempts

• httpproxy - an HTTP web proxy that alerts when there is an attempt to proxy to another page

4 Chapter 1. Getting Started


• mssql - an MS SQL server that alerts on login attempts

• mysql - a MYSQL server that alerts on login attempts

• telnet - a Telnet server that alerts on login attempts

• snmp - an SNMP server which alerts on oid requests

• sip - a SIP server which alerts on sip requests

• vnc - a VNC server which alerts on login attempts

• redis - a Redis server which alerts on actions

• tftp - a tftp server which alerts on requests

• ntp - an NTP server which alerts on ntp requests.

• tcpbanner - a TCPbanner service which alerts on connection and subsequent data recieved events.

• ignorelist - comma separated ips or CIDRs that will ignore alerting on.

Please note that each service may have other configurations such as port. For example, the tcpbanner service has abunch of extra settings that drastically change the way the service would interact with an attacker.

The default generated config will include all options, with all services set to false (except for ftp).

You may also want to fiddle with some of our other services which require a bit more setup;

smb - a log watcher for Samba logging files which allows Opencanary to alert on files being opened in a Windows FileShare.

For this configuration, you will need to setup your own Windows File Share, and point Opencanary at it using thefollowing configuration,

"smb.auditfile": "/var/log/samba-audit.log",

which is where your Windows File Share will be logging any activity happening on that share.

portscan - a log watcher that works with iptables to monitor when your Opencanary is being scanned. At this stagethe portscan module supports detection of nmap OS, nmap FIN, nmap OS, nmap NULL and normal port scans.

1.2.2 Logger Configuration

Opencanary allows us to define a bunch of logging/alerting sinks. Below are a list of options you can simply add tothe logger section in your config file,

"logger": {"class": "PyLogger","kwargs": {

"formatters": {"plain": {

"format": "%(message)s"},"syslog_rfc": {

"format": "opencanaryd[%(process)-5s:%(thread)d]: %(name)s→˓%(levelname)-5s %(message)s"

}},"handlers": {

"console": {"class": "logging.StreamHandler",


1.2. Configuration 5



"stream": "ext://sys.stdout"},"file": {


},"syslog-unix": {

"class": "logging.handlers.SysLogHandler","formatter":"syslog_rfc","address": [

"localhost",514

],"socktype": "ext://socket.SOCK_DGRAM"

},"json-tcp": {

"class": "opencanary.logger.SocketJSONHandler","host": "127.0.0.1","port": 1514

},"SMTP": {

"class": "logging.handlers.SMTPHandler","mailhost": ["smtp.yourserver.com", 25],"fromaddr": "[email protected]","toaddrs" : ["[email protected]"],"subject" : "OpenCanary Alert"

},"slack":{

"class":"opencanary.logger.SlackHandler","webhook_url":"https://hooks.slack.com/services/..."

},"teams": {

"class": "opencanary.logger.TeamsHandler","webhook_url":"https://my-organisation.webhook.office.com/webhookb2/..

→˓."}

}}

}

Please note that the above are not the only logging options. You can use any Python logging class. The above are themost popular. You can also head over to Email Alerts for more SMTP options that require authentication.

You may want to look through some other python logging options over at PyLogger page.

We have provided you with two different formatters. One is the plain message with incident information; the other isthe syslog rfc format. We have already added it to the syslog-unix handler for your convenience.

1.2.3 Default Configuration

When you generate the default OpenCanary config file using,

$ opencanaryd --copyconfig

you will receive a json formatted config file at /etc/opencanary/opencanary.conf such as the following,


https://docs.python.org/2/library/logging.handlers.html


{"device.node_id": "opencanary-1","ip.ignorelist": [ ],"git.enabled": false,"git.port" : 9418,"ftp.enabled": true,"ftp.port": 21,"ftp.banner": "FTP server ready","http.banner": "Apache/2.2.22 (Ubuntu)","http.enabled": false,"http.port": 80,"http.skin": "nasLogin","http.skin.list": [

{"desc": "Plain HTML Login","name": "basicLogin"

},{

"desc": "Synology NAS Login","name": "nasLogin"

}],"httpproxy.enabled" : false,"httpproxy.port": 8080,"httpproxy.skin": "squid","httproxy.skin.list": [

{"desc": "Squid","name": "squid"

},{

"desc": "Microsoft ISA Server Web Proxy","name": "ms-isa"

}],"logger": {

"class": "PyLogger","kwargs": {

"formatters": {"plain": {

"format": "%(message)s"}

},"handlers": {

"console": {"class": "logging.StreamHandler","stream": "ext://sys.stdout"

},"file": {


}}

}},"portscan.enabled": false,"portscan.logfile":"/var/log/kern.log",


1.2. Configuration 7



"portscan.synrate": 5,"portscan.nmaposrate": 5,"portscan.lorate": 3,"smb.auditfile": "/var/log/samba-audit.log","smb.enabled": false,"mysql.enabled": false,"mysql.port": 3306,"mysql.banner": "5.5.43-0ubuntu0.14.04.1","ssh.enabled": false,"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": false,"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_interval":300,"tcpbanner_1.keep_alive_idle": 300,"telnet.enabled": false,"telnet.port": "23","telnet.banner": "","telnet.honeycreds": [

{"username": "admin","password": "$pbkdf2-sha512$19000$bG1NaY3xvjdGyBlj7N37Xw

→˓$dGrmBqqWa1okTCpN3QEmeo9j5DuV2u1EuVFD8Di0GxNiM64To5O/Y66f7UASvnQr8.LCzqTm6awC8Kj/→˓aGKvwA"

},{

"username": "admin","password": "admin1"

}],"mssql.enabled": false,"mssql.version": "2012","mssql.port":1433,"vnc.enabled": false,"vnc.port":5000

}



Should you have any other questions regarding configuration or setup, please do not hesitate to contact us on github.

1.3 Correlator

1.3.1 Getting Started

To get started create a virtual environment to play in:

$ virtualenv env$ . env/bin/activate

Inside the virtualenv, install OpenCanary Correlator following the instructions in the README.

The correlator runs with a default config, which we’ll copy and edit to get started.

$ opencanary-correlatorWarning: no config file specified. Using the template config:/[...]/opencanary_correlator.conf$ cp /[...]/opencanary_correlator.conf opencanary-correlator.conf

In the config file, fill the twilio or mandrill details (or both), and the notification addresses for both.

{"console.sms_notification_enable": true,"console.sms_notification_numbers": ["+336522334455"],"console.email_notification_enable": true,"console.email_notification_address": ["[email protected]"],"console.slack_notification_enable": true,"console.slack_notification_webhook": ["https://hooks.slack.com/services/example/

→˓webhookdata"]"twilio.auth_token": "fae9206628714fb2ce00f72e94f2258f","twilio.from_number": ""+1201253234"","twilio.sid": "BD742385c0810b431fe2ddb9fc327c85ad","console.mandrill_key": "9HCjwugWjibxww7kPFej","scans.network_portscan_horizon": 1000,

}

With that in place, ensure that redis is running and then run the correlator daemon.

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

To configure OpenCanary daemons to send their events to correlator, edit the logger field in its config and restart thedaemon to reload the config.

"logger": {"class" : "PyLogger","kwargs" : {

"handlers": {"json-tcp": {

"class": "opencanary.logger.SocketJSONHandler","host": "127.0.0.1", # change to correlator IP"port": 1514

}}


1.3. Correlator 9

https://github.com/thinkst/opencanaryhttps://github.com/thinkst/opencanary-correlator



}}

1.3.2 Troubleshooting

You can test that the Correlator alerts are working be sending an event direclty to it (without using OpenCanary).

echo '{"dst_host": "9.9.9.9", "dst_port": 21, "local_time": "2015-07-20 13:38:21.→˓281259", "logdata": {"PASSWORD": "default", "USERNAME": "admin"}, "logtype": 2000,→˓"node_id": "AlertTest", "src_host": "8.8.8.8", "src_port": 49635}' | nc -v→˓localhost 1514

The tool JQ can be used to check that the config file is well-formed JSON.

$ jq . ./opencanary-correlator.conf


http://stedolan.github.io/jq/

CHAPTER 2

Services

Try these out in the OpenCanary configs for more typical server personalities.

2.1 Linux Web Server

Inside ~/.opencanary.conf:

{"ftp.banner": "FTP server ready","ftp.enabled": true,"ftp.port":21,"http.banner": "Apache/2.2.22 (Ubuntu)","http.enabled": true,"http.port": 80,"http.skin": "nasLogin","http.skin.list": [

{"desc": "Plain HTML Login","name": "basicLogin"

},{

"desc": "Synology NAS Login","name": "nasLogin"

}],"ssh.enabled": true,"ssh.port": 8022,"ssh.version": "SSH-2.0-OpenSSH_5.1p1 Debian-4",

[..] # logging configuration}

11


2.2 Windows Server

The Samba and RDP modules require an extra installation steps. It’s a good idea to consult the README beforetrying this out.


{"smb.auditfile": "/var/log/samba-audit.log","smb.enabled": true

}

Below is an example of an smb.conf for a Samba installation,

[global]workgroup = WORKGROUPserver string = blahnetbios name = SRV01dns proxy = nolog file = /var/log/samba/log.alllog level = 0vfs object = full_auditfull_audit:prefix = %U|%I|%i|%m|%S|%L|%R|%a|%T|%Dfull_audit:success = preadfull_audit:failure = nonefull_audit:facility = local7full_audit:priority = noticemax log size = 100panic action = /usr/share/samba/panic-action %d#samba 4server role = standalone server#samba 3#security = userpassdb backend = tdbsamobey pam restrictions = yesunix password sync = nomap to guest = bad userusershare allow guests = yes

[myshare]comment = All the stuff!path = /home/demo/shareguest ok = yesread only = yesbrowseable = yes

Please note that there are some details in the above config that you would want to change,

• server string

• netbios name

• [myshare] to the name of your share

• path

Of course you may change other settings as long as the smbd_audit logs to the file that your OpenCanary daemon iswatching (above we set it as /var/log/samba-audit.log).

In the above config, we are relying on Samba using syslog (rsyslog in newer systems). In order for our Samba to usersyslog, we will edit the /etc/rsyslog.conf file. Below is two lines we add to the bottom,

12 Chapter 2. Services

https://github.com/thinkst/opencanary


$FileCreateMode 0644local7.* /var/log/samba-audit.log

This will redirect any message of facility local7 to your /var/log/samba-audit.log file, which will be watched by ourOpenCanary daemon.

Please note this is all written up in the github README.md

2.3 MySQL Server


{"mysql.banner": "5.5.43-0ubuntu0.14.04.1","mysql.enabled": true,"mysql.port": 3306,"ssh.enabled": true,"ssh.port": 22,"ssh.version": "SSH-2.0-OpenSSH_5.1p1 Debian-4",[..] # logging configuration

}

2.4 MSSQL Server


{"mssql.enabled": true,"mssql.port": 1433,"mssql.version": "2012","rdp.enabled": true,"rdp.port", 3389,

[..] # logging configuration}

2.3. MySQL Server 13


14 Chapter 2. Services

CHAPTER 3

Alerting

Getting Started walks through two different ways to configure alerting: logging directly to a file, and sending alerts tothe Correlator for email and SMS alerts. Other possibilities are below:

3.1 Email Alerts

To have an OpenCanary daemon directly send email alerts edit the logger section of the ~/.opencanary.conf. The fileformat is JSON.

In the configurations below, set these configuration variables:

• mailhost - The SMTP mailhost and port.

• fromaddr - The from address. Usually does not have to exist.

• toaddres - An array of addresses that will receive the alert. Keep it short.

• subject - The email’s subject.

• credentials - Optional parameter, if the SMTP server requires authentication.

• secure - Optional parameter if TLS support is mandatory or wanted.

More information can be found on the PyLogger page.

3.1.1 Send to a GMail address

[..] # Services configuration"logger": {"class" : "PyLogger","kwargs" : {

"handlers": {"SMTP": {

"class": "logging.handlers.SMTPHandler",


15

https://docs.python.org/2/library/logging.handlers.html#logging.handlers.SMTPHandler



"mailhost": ["smtp.gmail.com", 25],"fromaddr": "[email protected]","toaddrs" : ["[email protected]"],"subject" : "OpenCanary Alert"

}}

}}

Depending on your ISP and their outbound spam protection mechanisms, you may need to send to TCP port 587, setup an app password and use credentials, as well as setting an empty tuple for the secure parameter. Your configurationwould then look like:



"class": "logging.handlers.SMTPHandler","mailhost": ["smtp.gmail.com", 587],"fromaddr": "[email protected]","toaddrs" : ["[email protected]"],"subject" : "OpenCanary Alert","credentials" : ["youraddress", "abcdefghijklmnop"],"secure" : []

}}

}}

3.1.2 Send with SMTP authentication



"class": "logging.handlers.SMTPHandler","mailhost": ["authenticated.mail.server", 25],"fromaddr": "[email protected]","toaddrs" : ["[email protected]"],"subject" : "OpenCanary Alert","credentials" : ["myusername", "password1"],"secure" : []

}}

}}

16 Chapter 3. Alerting

https://support.google.com/accounts/answer/185833?hl=en


3.2 HPFeeds

OpenCanary can be used directly (without the Correlator) with daemons supporting the hpfeeds protocol.

To enable hpfeeds add the following to the logging section of settings.json:

"hpfeeds": {"class": "opencanary.logger.HpfeedsHandler","host": "127.0.0.1","port": 10000,"ident": "test","secret":"12345","channels":["test.events"]

}

3.2. HPFeeds 17

https://github.com/rep/hpfeeds


18 Chapter 3. Alerting

CHAPTER 4

Upgrading

If you have a previous version of OpenCanary installed already, you can upgrade it easily.

Start by activating your virtual evnironment (env in the below example) that has your installed version of OpenCanary,

$ . env/bin/activate

Inside the virtualenv, you can upgrape your OpenCanary by,

$ pip install opencanary --upgrade

Please note that this will not wipe your existing OpenCanary config file. If you would like a new one (with the newsettings), please regenerate the config file using,

$ opencanaryd --copyconfig

19


20 Chapter 4. Upgrading

CHAPTER 5

Indices and tables

• genindex

• modindex

• search

21

Getting StartedServicesAlertingUpgradingIndices and tables

opencanary documentationsmb - a log watcher for samba logging ﬁles which allows opencanary to...

Documents