Sensor configuration

The sensor is configured entirely through environment variables, set as KEY=VALUE lines in /etc/safetybits on the appliance. See Configure and start for how to edit that file and apply a change.

Core settings

Variable	Type	Default	Required	Effect
`AGENT_ID`	uuid	none	yes	The sensor ID assigned when you register a facility in the console.
`CAPTURE_INTERFACE`	string	none	yes	The interface receiving mirrored traffic.
`ENDPOINT`	string	`connect.safetybits.io`	no	The console address the sensor reports to.
`PROMETHEUS_PORT`	int	`9110`	no	Port for the sensor’s own metrics, scraped by the local monitoring stack.
`RING_BUFFER_SIZE`	int	`1024000`	no	Size, in packets, of the capture ring buffer. Raise this if the local dashboard shows dropped packets on a high traffic segment.

gRPC (`GRPC_`)

Variable	Type	Default	Effect
`GRPC_TLS`	bool	`true`	Encrypts the connection to the console. Leave enabled outside of a lab setup.
`GRPC_KEEPALIVE_TIME`	duration	`1m`	Interval between keepalive pings.
`GRPC_KEEPALIVE_TIMEOUT`	duration	`10s`	How long to wait for a keepalive response before reconnecting.

Logging (`LOG_`)

Variable	Type	Default	Effect
`LOG_LEVEL`	string	`info`	One of `debug`, `info`, `warn`, `error`.
`LOG_JSON`	bool	`false`	Log in JSON instead of plain text, useful if you forward the journal to a log pipeline.
`LOG_ADD_SOURCE`	bool	`false`	Include the source file and line in each log entry.

Discovery (`DISCOVERY_`)

Variable	Type	Default	Required	Effect
`DISCOVERY_INTERFACE_PREFIX`	string	none	yes	Matches every interface name starting with this prefix as an OT network connection. Used for active identification, see Discovery and the inventory.
`DISCOVERY_STRATEGY`	string	`arp`	no	How the sensor finds active addresses. `arp` for the local segment, or `icmp` for broader reach.
`DISCOVERY_RETRIES`	int	`4`	no	Retries per target address.
`DISCOVERY_DURATION`	duration	`90s`	no	Maximum time for one discovery cycle.
`DISCOVERY_BUFFER_SIZE`	int	`2048`	no	Size of the internal device buffer during discovery.

Port scanning (`DISCOVERY_PORTSCAN_`)

Variable	Type	Default	Effect
`DISCOVERY_PORTSCAN_MAX_CONCURRENT`	int	`64`	Maximum hosts scanned at once.
`DISCOVERY_PORTSCAN_DURATION`	duration	`90s`	Maximum time for the port scanning phase.

Machine learning (`ML_`)

Variable	Type	Default	Effect
`ML_INTERVAL`	duration	`10m`	How often baselines are recalculated.
`ML_MIN_SAMPLES`	int	`288`	Samples needed before a baseline is usable, roughly two days at the default interval. See Baselines and anomaly detection.

Stormshield (`STORMSHIELD_`) and Fortinet (`FORTINET_`)

Set these only if you also configure the matching integration, see integrations/.

Variable	Type	Effect
`STORMSHIELD_SNSCLI_PATH`	string	Path to the `snscli` binary on the appliance.
`STORMSHIELD_HOST`	string	Address of the Stormshield SNS appliance.
`STORMSHIELD_USER`	string	Username for that appliance.
`STORMSHIELD_PASSWORD`	string	Password for that appliance.
`FORTINET_HOST`	string	Address of the FortiGate or FortiManager appliance.
`FORTINET_TOKEN`	string	API token for that appliance.

Port mirroring cookbook

The exact steps depend on your switch, but the shape is the same everywhere:

Log in to the switch’s management interface.
Identify the source ports or VLANs carrying the traffic you want visibility into.
Set the port connected to the sensor’s port mirroring interface as the destination.
Create the mirroring session, specifying the sources and the destination, and save it.
Confirm traffic arrives by checking the switch’s own session counters, and then checking the sensor’s side, see Health checks.

For example, on a Cisco switch, mirroring two source ports to a third:

monitor session 1 source interface GigabitEthernet0/1 - 2
monitor session 1 destination interface GigabitEthernet0/3

VLAN access cookbook

The appliance’s network configuration is managed declaratively with systemd-networkd. If the sensor’s OT network connection needs to reach a tagged VLAN, add a VLAN sub interface for it. The sensor matches any interface starting with DISCOVERY_INTERFACE_PREFIX, so naming it <parent>.<vlan id> is enough for it to be picked up automatically.

Define the VLAN device, for example in /etc/systemd/network/25-ot-vlan.netdev:

[NetDev]
Name=enp5s0.100
Kind=vlan

[VLAN]
Id=100

Attach it to the parent interface, for example in /etc/systemd/network/20-enp5s0.network:

[Match]
Name=enp5s0

[Network]
VLAN=enp5s0.100

Give the new interface an address, for example in /etc/systemd/network/26-ot-vlan.network:

[Match]
Name=enp5s0.100

[Network]
Address=192.0.2.10/24

Apply the change and restart the sensor so it picks up the new interface:

sudo systemctl restart systemd-networkd
sudo systemctl restart safetybits

Sensor configuration

Core settings

gRPC (GRPC_)

Logging (LOG_)

Discovery (DISCOVERY_)

Port scanning (DISCOVERY_PORTSCAN_)

Machine learning (ML_)

Stormshield (STORMSHIELD_) and Fortinet (FORTINET_)