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-correlator
Warning: no config file specified. Using the template config:
$ 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": [""],
  "console.slack_notification_enable": true,
  "console.slack_notification_webhook": [""],
  "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 the correlator, edit the logger field in its config and restart the daemon to reload the config.

"logger": {
  "class": "PyLogger",
  "kwargs": {
    "handlers": {
      "json-tcp": {
        "class": "opencanary.logger.SocketJSONHandler",
        "host": "",  // change to correlator IP
        "port": 1514


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

echo '{"dst_host": "", "dst_port": 21, "local_time": "2015-07-20 13:38:21.281259", "logdata": {"PASSWORD": "default", "USERNAME": "admin"}, "logtype": 2000, "node_id": "AlertTest", "src_host": "", "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