DEV Community: Carvilsi [Char]

CanaryUsb

Carvilsi [Char] — Sat, 09 Sep 2023 16:48:52 +0000

Introducing Canary Tokens

Some time ago I found Thinkst Canary and I fall in love with it.

It's already well know but, the idea behind Canary Tokens is to have a notification if you have security breach. The notification is via email, and you have different types of tokens, these will trigger a notification under certain situation, for example a URL token will be triggered when a URL is visited.

One of my favorites is the QR code token, it's meant for physical things; e.g. You can stick the QR code inside of your prototype case, and if someone scans it, at least you know that someone is snooping around.

Just want to mention, that when you create a new Canary Token, apart of email, where you want to receive the notification, you need to provide a reminder note to describe the token.

You can check the different types of Canary tokens that Thinkst Canary have, and they explain all the things better than me.

CanaryUsb

So now that we now about CanaryTokens; Lets see what CanaryUsb is.

What is it?

CanaryUsb monitors the USB activity on a Linux system, and will call a CanaryToken when a not known USB is connected.

Here we are thinking about removable media threats like BadUSB or physical attacks to extract data e.g. on remote servers or on unattended laptops.

The code is in c and right now, and unless someone borrow me a Mac, canaryusb only works on Linux (is not even an idea to support Windows).

The DNS Canary token

CanaryUsb uses a CanaryToken of type DNS token that alerts when a hostname is requested. As it's described at the DNS token Documentation one of the features is that the token can carry a small extra data.
This is used by canaryusb to send the fingerprint of the connected usb; so the notification via mail will include this info.

A USB fingerprint

Since the total number of bytes that could be included among the DNS token is ~125 bytes, we need to restrict the amount of data that we take from from USB attributes.
We choose the next format for the usb fingerprint:

<vendor>:<product>-<product_name>-<serial>

e.g. for a USB with the next attributes:

vendor: 18d1
product: 4ee8
product name: OnePlus Nord
serial: d3115c34

The USB fingerprint will be: 18d1:4ee8-OnePlus_Nord-d3115c34

The struct that holds the usb fingerprint looks like:

typedef struct
{
        char *vendor;
        char *product;
        char *product_name;
        char *serial;
        char *syspath;
} UsbAttrs;

Note that the syspath variable is there just for debugging pourposes and it's not used to define the usb fingerptint.
We initialize this struct as:

UsbAttrs usbattr = {"0000", "0000", "no", "no", "no-path"};

So we fill the gaps in case of a missing attribute.
It's not guaranteed that the 4 attributes which with we want to build the usb fingerprint will be present.

Monitoring the USB devices

The USB attributes, to build the usb fingerprint, are retrieved with libsystemd, specifically usage of sd-device and monitoring the USB devices activity.

The monitor code is quite brief; failure handling and finishing actions are omitted for brevity:

void monitor_usb()
{
        sd_device_monitor *sddm = NULL;
        sd_device_monitor_new(&sddm);

        sd_device_monitor_filter_add_match_subsystem_devtype(sddm, SUBSYSTEM, DEVICE_TYPE);

        sd_device_monitor_start(sddm, usb_monitor_handler, NULL);

        sd_event *event = sd_device_monitor_get_event(sddm);
        sd_event_loop(event);

        /*
         * Deal with errors and exit actions
         * like stooping monitor and un-references
         */
}

Once the event is triggered the handler function, usb_monitor_handler, takes care of the rest; retrieve the USB attributes to build the the usb fingerprint, build the DNS Canary Token and perform the DNS call.

Building the DNS Canary Token

We need to convert the usb fingerprint into base32 removing the padding '=' characters adding a dot after every 63-bytes and prepare the hostname call for DNS token, from the Documentation is something like:

<base32-string>.<base32-string>.G<2-random-digits>.<dns-token>

Also we'll strip the usb fingerprint if the length exceeds the maximum data to encode; 63 bytes for each base32-string block.

Calling the Canary

Once we have the DNS Canary Token, we just need to call it, using getaddrinfo (netdb.h):

int call_the_canary(const char *canary_dns_token)
{
        int canaryrsp;
        struct addrinfo hints, *res;
        memset(&hints, 0, sizeof(hints));
        canaryrsp = getaddrinfo(canary_dns_token, CANARY_PORT, &hints, &res);
        return canaryrsp;
}

The parameter canary_dns_token it's the value that we get on previous step, and for CANARY_PORT we use 80.
We do not care about the response, variable res of getaddrinfo but the return integer of it, a nonzero means an error.

Here you can see the notification that I received from the above example of usb fingerprint:

Some other things

In order to avoid notifications from your own devices, canaryusb supports a usb trusted list, so only the devices that are not at this list will send a notification.
To make the life easer canaryusb could read values for the CanaryToken and the usb fingerprint trusted list from a config file. The format of the config file is toml and I found very useful tomlc99.

Linux; monitor USB devices; libudev replacement with sd-device

Carvilsi [Char] — Sat, 09 Sep 2023 11:09:42 +0000

Some context

Recently I was writing a post related with a c project to monitor and send notifications when a unknown USB device is connected to a Linux system and just notice that the library that I was using, libudev even still supported but should not be used in new projects. The project is quite new, so I started to update it in order to use the equivalent replacement with a more modern API; sd-device that is part of libsystemd.

sd-device.h is part of libsystemd(3) and provides an API to introspect and enumerate devices on the local system. It provides a programmatic interface to the database of devices and their properties mananaged by systemd-udevd.service(8). This API is a replacement for libudev(3) and libudev.h.

The case is that the replacement took me more effort than I expected, almost all the concepts still the same, but there are some changes.

The code

The code is just a simple example that reads some values of a new connected USB to a Linux system.
It's written in C and uses two components from libsystemd sd-device and sd-event that we include with:

#include <systemd/sd-event.h>
#include <systemd/sd-device.h>

Then at the main block we have the part for monitor the device and deal with the events. Despite failure handling and related stop actions, these are the basic steps:

create a new monitor device

int sd_device_monitor_new(sd_device_monitor **ret);
add a filter that will match by subsystem and device type, for our purpose will use "usb" and "usb_device" respectively. With the second value for device type we restrict the amount of triggers for the monitor, e.g. if we do not specify (NULL) we'll be catching also the "usb_interface" related with the device.

int sd_device_monitor_filter_add_match_subsystem_devtype(sd_device_monitor *m, const char *subsystem, const char *devtype);
start the monitor, passing as parameter a handler function, to react when the filter will be triggered. We'll take a look to this handler later.

int sd_device_monitor_start(sd_device_monitor *m, sd_device_monitor_handler_t callback, void *userdata);
get the event for this device monitor

sd_event *sd_device_monitor_get_event(sd_device_monitor *m);
start the event loop. Run the event in loop mode, sd_event_run(), waiting for a sd_event_exit() or a SIGTERM

int sd_event_loop(sd_event *e);

Notice that both, sd-event and sd-device return a negative errno-style error code.

The main function is something like:

int main()
{
        int r;
        sd_device_monitor *sddm = NULL;
        // create a new monitor device
        r = sd_device_monitor_new(&sddm);
        // check for errors, sd-device functions returns negative values on errors
        if (r < 0) 
                goto finish;

        // we would like to monitor USB activity
        r = sd_device_monitor_filter_add_match_subsystem_devtype(sddm, "usb", "usb_device");
        if (r < 0)
                goto finish;

        // start monitoring and attach a handler function to it
        r = sd_device_monitor_start(sddm, monitor_handler, NULL);
        if (r < 0) 
                goto finish;

        // get the event related with device monitor
        sd_event *event = sd_device_monitor_get_event(sddm);
        // starts the event loop
        r = sd_event_loop(event);
        if (r < 0)
                goto finish;

finish:
        if (r < 0) {
                errno = -r;
                fprintf(stderr, "Error: %m\n");
        }

        // stop and unref monitor and event
        sd_device_monitor_stop(sddm);
        sd_device_monitor_unref(sddm);
        sd_event_unref(event);
        return r < 0 ? EXIT_FAILURE : EXIT_SUCCESS;
}

About the monitor handler function, with this signature:

typedef int (*sd_device_monitor_handler_t)(sd_device_monitor *m, sd_device *device, void *userdata);

It's main purpose is to print values of the connected USB device, and has a condition in order to only print the values when the action from the device is SD_DEVICE_ADD.

The list for different actions are:

typedef enum sd_device_action_t {
        SD_DEVICE_ADD,
        SD_DEVICE_REMOVE,
        SD_DEVICE_CHANGE,
        SD_DEVICE_MOVE,
        SD_DEVICE_ONLINE,
        SD_DEVICE_OFFLINE,
        SD_DEVICE_BIND,
        SD_DEVICE_UNBIND,
        _SD_DEVICE_ACTION_MAX,
        _SD_DEVICE_ACTION_INVALID = -EINVAL,
        _SD_ENUM_FORCE_S64(DEVICE_ACTION)
} sd_device_action_t;

In order to retrieve the action inside the monitor handler we use:

int sd_device_get_action(sd_device *device, sd_device_action_t *ret);

And to retrieve e.g. the idVendor value of the device we use, passing "idVendor" as sysattr parameter:

int sd_device_get_sysattr_value(sd_device *device, const char *sysattr, const char **_value);

const char *id_vendor;
sd_device_get_sysattr_value(d, "idVendor", &id_vendor);
printf("idVendor: %s\n", id_vendor);

The whole example is available at GitHub in case that you want to take a look or run it on your machine.

Dependencies

I tried the code on a Arch Linux and on a Ubuntu lunar (23.04) and for this one I needed to install libsystemd-dev; seems that Arc Linux has the package already installed.

If you want to install the package on Ubuntu lunar:

sudo apt install libsystemd-dev