How do I build a customized user module?

How to build a customized user module for your Canary device by setting up a Python virtual environment, developing and testing your module, and uploading it to your Canary device in configuration mode, enabling tailored services to enhance your security monitoring.

User Modules are a way for you to create and deploy your own custom services to your Canaries. Once deployed, your Canary will listen on the specified port, and once hit, will behave in the way you want it to.

Creating your custom service is quick and can be easily done by following the below steps.

Step 1: Setup environment

The user modules use python2.7 and to simplify the development we use docker to create the environment in.

docker run --name canary-user-module -v code:/code -ti ubuntu:jammy bash -c "apt update; apt-get install -y python2 sudo; apt-get install -y python-pip python2-dev; pip2 install wheel; ln -s /usr/bin/python{2,}; exec bash"

Next, install canaryusermodule python module:

Caveat!

As of v0.31.0, the python wheel format no longer includes the metadata.json file. The Canary expects this, so the user module will fail to load. This is easily fixed by installing the 0.30.0 version of wheel in your Virtual env.

root@cf606ea9aa58:#

pip2 install canaryusermodule wheel==0.30.0 opencanary==0.3.2

Step 2: Generate test module and install into Virtual env

root@cf606ea9aa58:#

usermodgen HelloTest

Install test module into Virtual env:

root@cf606ea9aa58:#

cd hellotest

python setup.py develop

Step 3: Dev and test module

Test with and watch raw json logs in foreground:

root@cf606ea9aa58:/hellotest#

opencanaryd --usermodule

Hack!, hack!, hack! (Repeat above as desired)

Step 4: (Optional) Clean Up Test Module

delete test user module from Virtual environment:

root@cf606ea9aa58:/hellotest#

pip uninstall -y hellotest

Step 5: Build and upload

Build test module:

root@cf606ea9aa58:/hellotest#

./build.sh

The usermodule will be the *.whl in dist. Upload this to Canary.

root@cf606ea9aa58:/hellotest#

./dist/HelloTest-1.0-py2-none-any.whl