BitBlazr: Main configuration file

The main configuration file defines options like logging targets, and backoff settings, and specifies which features to enable. An example configuration file can be found here: https://github.com/auseckas/bitblazr/blob/main/config/config.yaml

Below is the description of different sections of the config and options that can be configured there.

Features

Features section specifies which probes should be turned on.

features:
  lsm: false
  tracepoints: true

Specifies which features should be enabled

lsm is disabled by default as it enables blocking rules, which should be used with caution

lsm - tuns on Linux Security Modules and enables in-kernel blocking rules.
tracepoints - enables syscall tracing, this feature monitors events and pushes events to the user space. It cannot block. Enabled by default.

Limits

On resource-constrained IoT devices, every CPU cycle counts. BitBlazr tackles this challenge by providing configurable backoff limits. When event processing reaches a user-defined threshold, the sensor gracefully pauses to prevent overwhelming the system.

limits:
  backoff: 60
  max_events: 500

Backoff Options

Once the sensor processes more events per second than the configured "max_events" limit, it pauses operations for a user-defined "backoff" time in seconds

max_events - maximum events per second, per CPU core. Setting this to 0 disables limits.
backoff - backoff time in seconds, monitoring events will be suspended for this amount of time

Tracing

This is another section that is used to manage events to make sure they do not overwhelm the system. Only "open_prefixes" option is currently supported.

There can be a lot of "open" events on a given system and not all of them are related to security incidents.

tracing:
  open_prefixes:
  - /etc
  - /usr/local/
  - /opt
  - /proc/config.gz
  - /proc/kcore
  - /sys/kernel
  - /sys/firmware
  - /var/log
  - /var/www
  - /home
  - /root
  - /tmp

Tracing Options

You can configure up to 100 "open" syscall prefixes that you would like to monitor. Of course, one can always use "/", but that may result in way too many events.

open_prefixes - path prefixes used by eBPF routines that watch syscalls related to files being open. 100 different prefixes are allowed.

Logs

This section is used to define logging targets.

logs:
  default:
    enable: true
    target: stdout

Logging

Example of a minimal configuration required

Separate targets can be defined for different log classes. Currently, supported log classes are:

default - this is the only required logging class configuration, if the other classes are missing, the default will be used.
errors - if this log class is configured, errors will be sent to the configured target.
alerts - if this log class is configured, alerts will be sent to the configured target.
events - if this log class is configured, all remaining events will be sent to the configured target.Each target class can take the following options:

enable - has to be set to "true" to enable the logging class.
target - defines a logging target, values can be: "stdout", "stderr", "file", or "mqtt". format - log format can be: "full", which is also a default, "compact", "pretty", "json", or "cloudevents". More information on CloudEvents can be found here: https://cloudevents.io/
directory - directory where the log files will be created. This option can only be used for the "file" target.
prefix - log file prefix. This option can only be used for the "file" target.
rotation - Desired file rotation, supported values are: "hourly", "daily", and "never". This option can only be used for the "file" target.
max_files - If file rotation is enabled, this defines how many files to keep. This option can only be used for the "file" target.
mqtt_uri - URI for MQTT client. This option can only be used for "mqtt" target.
mqtt_user - Username to be used by the MQTT client. This option can only be used for "mqtt" target.
mqtt_pwd - Depending on the service used this will be either a password or JWT token used by the MQTT client. This option can only be used for "mqtt" target.
mqtt_topic - Topic uses by MQTT cl. This option can only be used for "mqtt" target.

Process Labels

BitBlazr features a contextual rule engine. You can specify the context in which a rule applies, dramatically reducing false positives.

Context is configured in "process_labels" part of the configuration. Labels are based on the process path.

Once labels are configured, they can be used in rules.

process_labels:
  shell:
  - eq: bash
  - ends_with: /bash
  - ends_with: /sh
  - ends_with: /csh
  - ends_with: /ksh

Context

This example defines "shell" context