Notifications

If you run sn0int unattended nobody might see the sn0int output. For cases like this you can configure notifications to send you a push notification in case something interesting happens. This is also especially useful if you have sn0int setup to run automatically.

Receiving notifications

Notifications are just regular sn0int modules. You can install them just like any other module or write your own. This section contains walkthroughs on how to setup common integrations.

Telegram

Install the telegram notification module from the registry:

sn0int pkg install kpcyrd/notify-telegram

Open your telegram app and open a chat with @botfather. Send /newbot and answer the questions. Copy bot_token and open this url in your browser:

Back on your app, open the t.me link to start a new chat with your bot, then send /start. Reload the page in your browser, you should see the new message you sent. Copy the chat_id.

Test your tokens are working correctly by sending yourself a notification:

sn0int notify exec kpcyrd/notify-telegram -o bot_token=1337:foobar -o chat_id=1337 'hello world'

You should receive hello world from your bot on Telegram.

Pushover

Install the pushover notification module from the registry:

sn0int pkg install kpcyrd/notify-pushover

Signup for pushover and configure the app on your device. Copy th user key visible on the pushover dashboard. Click “Create an Application/API Token”. Set “sn0int” as name and set an icon if you want to. Copy the api token.

Test your tokens are working correctly by sending yourself a notification:

sn0int notify exec kpcyrd/notify-pushover -o user_key=asdf1337 -o api_token=asdf1337 'hello world'

You should receive hello world as a push notification.

Discord

Install the discord notification module from the registry:

sn0int pkg install kpcyrd/notify-discord

Decide which channel should receive notifications (or create a new one). Open the “Server Settings” of your discord server. Click on “Webhooks”. Click “Create Webhook”. Configure the Name and Channel. Copy the Webhook URL.

Test your tokens are working correctly by sending yourself a notification:

sn0int notify exec kpcyrd/notify-discord -o url=https://discord.com/api/webhooks/1337/asdf 'hello world'

You should receive hello world in your discord channel.

Signal

Install the sn0int notification module from the registry:

sn0int pkg install kpcyrd/notify-signal

This module allows end-to-end encrypted notifications, but it’s also difficult to setup. You need a second phone number and install both signal-cli and sn0int-signal.

After you’ve registered your second phone number with signal-cli, you can use sn0int-signal to expose a minimal api for notify-signal. For more detailed instructions and how to start the api at boot, see the sn0int-signal README.

Read the secret key generated at /etc/sn0int-signal.key and send a notification to the signal phone number:

sn0int notify exec kpcyrd/notify-signal -o to=+31337 -o secret=asdf 'hello world'

You should receive hello world from the number signed up with signal-cli.

Writing your own module

Make sure you’ve read the detailed instructions on how to get setup with module development.

Create a new sn0int module like this:

sn0int new ~/repos/sn0int-modules/notify-custom.lua

Edit the -- Source: so it takes notifications as input:

-- Description: TODO your description here
-- Version: 0.1.0
-- License: GPL-3.0
-- Source: notifications

function run(arg)
    -- TODO your code here
    -- https://sn0int.readthedocs.io/en/stable/reference.html

    debug(arg)
    info(arg['subject'])
    info(arg['body'])
end

Execute your script:

sn0int notify exec notify-custom 'hello world'

You most likely need to pass options to avoid hard-coding keys into your script. Options can be fetched like this:

-- Description: TODO your description here
-- Version: 0.1.0
-- License: GPL-3.0
-- Source: notifications

function run(arg)
    -- TODO your code here
    -- https://sn0int.readthedocs.io/en/stable/reference.html

    local foo = getopt('foo')
    if not foo then return 'Missing -o foo= option' end

    info('foo: ' .. foo)
    info('subject: ' .. arg['subject'])
end

And passed like this:

sn0int notify exec notify-custom -o "foo=hello world" 'ohai'

Setting up notification rules

We now know how to trigger notifications manually, but we would rather trigger notifications if a module runs into something interesting.

You can setup subscriptions on specific topics and then have a notification script execute automatically.

Lookup the location of your sn0int config file:

sn0int paths

And open it in an editor of your choice:

vim /home/user/.config/sn0int.toml

A basic configuration could look like this:

# You can have multiple notification sections, this one is named
# `demo-telegram-integration`
# The label can be set to whatever you want, but you may need to add
# double-quotes to use some characters.
[notifications.demo-telegram-integration]
# If this option is present, the notification must originate from one of
# the following workspaces.
workspaces = ["default", "some-workspace"]
# If this option is present, the notification must match one of the
# filters. You can use `*` as a wildcard to match everything except `:`.
topics = ["activity:harness/activity-ping:*"]
# Mandatory: the module to execute.
script = "kpcyrd/notify-telegram"
# The options to pass to the module, if any.
# Can be accessed with `getopt`
options = [
    "bot_token=1337:foobar",
    "chat_id=1337",
]

All options except script are optional, but setting filters is highly recommended.

Testing notifications

To test if your configuration works correctly you can create an event manually:

sn0int -w some-workspace notify send activity:harness/activity-ping:dummy "hello world"

If it matches any of your rules you should receive a push notifications.

Note

If you want to test just the routing without actually sending something, add --dry-run.

Running sn0int automatically

Support for this is going to improve in the future, but you can already set this up if you’re ok with a slightly buggy experience.

Monitors

Some modules are long-running and either wait for an event from a server or have custom polling built in that’s usually configurable with an -o interval= option. If your module has a non-trivial setup phase, an author may take this approach.

Enable the service to run on boot:

systemctl enable --now sn0int-your-new-service.service

Timers

If the module is only one-shot you can set it up to run with a timer:

Setup the timer like this:

systemctl enable --now sn0int-your-other-service.timer