patron-it-opencanary 0.7.1
OpenCanary daemon
License: BSD 3-Clause License
Requires Python: >=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*
Keywords: canary,honeypot,monitoring,network,security

[![Release @ PyPI](https://img.shields.io/pypi/v/patron-it-opencanary.svg)](https://pypi.org/project/patron-it-opencanary)
[![Linux build @ Travis CI](https://img.shields.io/travis/com/patron-it/opencanary/master.svg?label=Linux%20build%20%40%20Travis%20CI)](https://travis-ci.com/patron-it/opencanary)
[![Docs @ RTD](https://readthedocs.org/projects/patron-it-opencanary/badge/?version=latest)](https://patron-it-opencanary.readthedocs.io/en/latest/?badge=latest)
[![BSD License](https://img.shields.io/badge/license-BSD-blue.svg)](https://pypi.org/project/patron-it-opencanary)

OpenCanary
=================
Thinkst Applied Research

Overview
----------

OpenCanary is a daemon that runs several canary versions of services that alerts when a service is (ab)used. It's a low interaction honeypot intended to be run on internal networks.

Prerequisites
----------------

* Python 2.7+
* [Optional] Samba module needs a working installation of samba

Install
----------

Installation on Ubuntu:

```
$ sudo apt-get install python-dev python-pip python-virtualenv
$ virtualenv env/
$ . env/bin/activate
$ pip install patron-it-opencanary[rdp,snmp,remote_logging]  # rdp, snmp and remote_logging are optional extras
```

Ubuntu users installing rdpy should run the following before installing OpenCanary:

```
$ sudo apt-get install -y build-essential libssl-dev libffi-dev python-dev
```

Installation OS X needs an extra step, as multiple OpenSSL versions
may exist which confounds the python libraries using to it.

```
$ virtualenv env/
$ . env/bin/activate
```

Macports users should then run:
```
$ sudo port install openssl
$ env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/opt/local/lib" CFLAGS="-I/opt/local/include" pip install cryptography
```

Alternatively homebrew users run:
````
$ 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
````

Now installation can run as usual:
```
$ pip install patron-it-opencanary[rdp,snmp]
```

To install from source, instead of running pip do the following:

```
$ git clone https://github.com/thinkst/opencanary
$ cd opencanary
$ pip install .
```

If you are looking to get OpenCanary working on OpenBSD, take a look at https://github.com/8com/opencanary. 

Run
----

OpenCanary is started by running:

```
$ . env/bin/activate
$ opencanaryd --start
```

On the first run, instructions are printed that will get to a working config.


Samba Setup (optional)
----------------------

The Samba OpenCanary module monitors a log file produced by the Samba
full_audit VFS module. Setup relies on:

* Having Samba installed.
* A modified Samba config file, to write file events to syslog's LOCAL7 facility.
* A modified syslog file, to output LOCAL7 to a samba-audit.log file.

As template Samba config, modify the following and install it to the
right location (often /etc/samba/smb.conf). The lines you'll likely
want to change are:

* path
* workgroup
* server string
* netbios name
* [myshare]
* comment


```
    [global]
       workgroup = WORKGROUP
       server string = blah
       netbios name = SRV01
       dns proxy = no
       log file = /var/log/samba/log.all
       log level = 0
       syslog only = yes
       syslog = 0
       vfs object = full_audit
       full_audit:prefix = %U|%I|%i|%m|%S|%L|%R|%a|%T|%D
       full_audit:success = pread
       full_audit:failure = none
       full_audit:facility = local7
       full_audit:priority = notice
       max log size = 100
       panic action = /usr/share/samba/panic-action %d

       #samba 4
       server role = standalone server

       #samba 3
       #security = user

       passdb backend = tdbsam
       obey pam restrictions = yes
       unix password sync = no
       map to guest = bad user
       usershare allow guests = yes
    [myshare]
       comment = All the stuff!
       path = /home/demo/share
       guest ok = yes
       read only = yes
       browseable = yes
       #vfs object = audit
```

Configure syslog to write the Samba logs out to the file that
OpenCanary monitors. With rsyslog, adding these two lines to
/etc/rsyslog will do that:

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

For other syslog implementations similar lines might work.