Sensor

The Safetybits sensor is delivered preinstalled on a purpose-built network appliance, ready for deployment in your infrastructure. This appliance is a critical component of the system, designed to seamlessly integrate into your network environment while maintaining robust security and performance.

This guide provides step-by-step instructions for setting up and managing the sensor, ensuring it functions optimally to protect and monitor your industrial operations.

Requirements

The specifications of the network appliance depend on the size and complexity of the facility where it will be deployed. Safetybits provides appliances with different capacities, ensuring optimal performance regardless of the scale of the operation. During the planning phase, our team will work with you to determine the appropriate appliance model based on your infrastructure and operational needs.

To operate effectively, the sensor requires access to three distinct networks:

Management Network: Used for administrative tasks, configuration, and secure communication with the Safetybits platform.
OT Network: Enables the discovery and monitoring of operational technology (OT) devices within the infrastructure.
Port Mirroring/Network Sniffing: Facilitates the collection and analysis of network traffic to identify potential threats and vulnerabilities.

Installation

The Safetybits sensor typically comes preinstalled on a dedicated network appliance, simplifying the deployment process. The primary requirement during installation is to properly connect the appliance to the necessary networks in the customer’s infrastructure.

Identify the appropriate network ports on the appliance, which are typically designated for Management, OT, and Port Mirroring.
Use the table below to match each port with its corresponding network:

Ethernet Port 1: Management
Ethernet Port 2: Empty
Ethernet Port 3: Discovery within the OT network
Ethernet Port 4: Network Capture ingestion from switch or router

Connect each port to the respective network using the correct wiring. A set of labels are provided to mark the cables.
Confirm that the connections are active by checking the link status on the appliance or through a management interface.

With the appliance properly wired, the system is ready for further configuration and operation. If any additional setup is required, such as specifying IP addresses or VLAN configurations, refer to the Administrator Guide for detailed instructions.

Configuring the Safetybits sensor

Before starting the sensor, it is necessary to retrieve the sensor ID from the Safetybits backend and configure it. This step ensures the sensor is correctly registered and operational within your environment.

The default credentials required for initial access will be securely provided by the Safetybits support team.

Please contact support if you have not received this information.

Step 1. Retrieve the sensor ID from the Safetybits Console

Log in to the Safetybits console using your administrator credentials.
Navigate to the Sources section.
Select the option to add a new source. The system will generate a unique sensor ID for the new sensor.
Note down the sensor ID or copy it securely for the next step.

Step 2. Configure the sensor

Once you have the sensor ID, you’ll need to configure the sensor on the appliance:

Access the appliance through SSH or the local terminal.
Open the sensor configuration file, located at /etc/safetybits-sensor:

sudo vi /etc/safetybits-sensor

Update the configuration with the retrieved sensor ID:

sensor_ID="YOUR_sensor_ID"

Configure additional options as required, such backend server URL, logging levels or network preferences:

LOG_JSON = "true"

3. Start the sensor

After configuring, start the sensor using the following command:

sudo systemctl start safetybits-sensor

You can verify the sensor’s status with:

sudo systemctl status safetybits-sensor

Sensor Configuration

The Safetybits Sensor can be fully configured through environment variables.

These variables control how the sensor captures traffic, performs network discovery, connects to the Safetybits backend, and integrates with third-party systems such as Fortinet and Stormshield.

You can set the variables directly in the environment or by editing the configuration file located at /etc/safetybits-agent. This file contains key value pairs defining all environment variables used by the sensor.

Core Settings

These parameters define the fundamental behavior of the sensor: which interface to monitor, how to aggregate flows, and how to expose internal metrics.

Variable	Type	Default	Required	Description
`CAPTURE_INTERFACE`	`string`	–	✅	Network interface used for traffic capture (e.g. `eth0`, `enp3s0`).
`ENDPOINT`	`string`	`connect.safetybits.io`	❌	Safetybits backend endpoint for gRPC communication.
`FLOW_AGGREGATION_INTERVAL`	`duration`	`10m`	❌	Time window for aggregating network flows before sending.
`PROMETHEUS_PORT`	`int`	`9110`	❌	Port where Prometheus metrics are exposed.
`RING_BUFFER_SIZE`	`int`	`1024000`	❌	Size of the AF_PACKET ring buffer used for packet capture (in packets).
`AGENT_ID`	`uuid`	–	✅	Unique identifier of the sensor instance, assigned at installation time.

gRPC Configuration (`GRPC_`)

The sensor communicates with the Safetybits cloud or on-prem console through gRPC.
These parameters adjust the communication layer and connection reliability.

Variable	Type	Default	Description
`GRPC_TLS`	`bool`	`true`	Enables encrypted TLS communication.
`GRPC_KEEPALIVE_TIME`	`duration`	`1m`	Interval between keepalive pings to maintain the connection active.
`GRPC_KEEPALIVE_TIMEOUT`	`duration`	`10s`	Timeout waiting for a keepalive response before reconnecting.

Logging (`LOG_`)

The logging subsystem controls verbosity and output format.

Variable	Type	Default	Description
`LOG_LEVEL`	`string`	`info`	Log verbosity (`debug`, `info`, `warn`, `error`).
`LOG_JSON`	`bool`	`false`	Output logs in JSON format, useful for integration with logging systems.
`LOG_ADD_SOURCE`	`bool`	`false`	Include source file and line number in logs for troubleshooting.

Discovery (`DISCOVERY_`)

The discovery engine scans and profiles the industrial network to build an asset inventory.
It can use multiple strategies (ARP, ICMP, etc.) and supports port scanning for deeper visibility.

Variable	Type	Default	Required	Description
`DISCOVERY_INTERFACE_PREFIX`	`string`	–	✅	Prefix for network interfaces to include (e.g. `eth`, `enp`).
`DISCOVERY_STRATEGY`	`string`	`arp`	❌	Discovery method to use (`arp`, `icmp`, …).
`DISCOVERY_RETRIES`	`int`	`4`	❌	Number of retries per target in the discovery phase.
`DISCOVERY_DURATION`	`duration`	`90s`	❌	Maximum time per discovery cycle.
`DISCOVERY_BUFFER_SIZE`	`int`	`2048`	❌	Size of the device buffer used during discovery.

Port Scanning (`DISCOVERY_PORTSCAN_`)

Variable	Type	Default	Description
`DISCOVERY_PORTSCAN_MAX_CONCURRENT`	`int`	`32`	Maximum number of concurrent hosts scanned.
`DISCOVERY_PORTSCAN_DURATION`	`duration`	`3m`	Maximum duration of the port scanning phase.

Stormshield Integration (`STORMSHIELD_`)

If your industrial network includes Stormshield SNS firewalls, the sensor can automatically extract topology and policy data from them using snscli.

Variable	Type	Default	Description
`STORMSHIELD_SNSCLI_PATH`	`string`	–	Path to the `snscli` binary.
`STORMSHIELD_HOST`	`string`	–	IP address or hostname of the Stormshield device.
`STORMSHIELD_USER`	`string`	–	Username used for authentication.
`STORMSHIELD_PASSWORD`	`string`	–	Password for authentication.

Fortinet Integration (`FORTINET_`)

The sensor can connect to FortiGate or FortiManager appliances to enrich network data with policy and event context.

Variable	Type	Default	Description
`FORTINET_HOST`	`string`	–	IP address or hostname of the Fortinet device.
`FORTINET_TOKEN`	`string`	–	API access token for authenticating to the Fortinet REST API.

Machine Learning (`ML_`)

The ML module continuously analyzes aggregated network behavior to establish baselines and detect anomalies.

Variable	Type	Default	Description
`ML_INTERVAL`	`duration`	`10m`	Time interval between each learning cycle or recalculation.
`ML_MIN_SAMPLES`	`int`	`288`	Minimum number of samples required to establish a baseline (≈ 2 days at 10-minute intervals).

Upgrade

Upgrading the Safetybits sensor is efficient and seamless, thanks to its integration with custom repositories and the use of standard Debian package management tools.

To upgrade the sensor:

Ensure Repository Access: Verify that the Safetybits custom repository is configured on the appliance. This configuration is typically preinstalled, but you can confirm it by checking /etc/apt/sources.list.d/.
Update the Package List: Refresh the list of available packages to ensure you get the latest version:

sudo apt update

Upgrade the sensor: Install the latest version of the sensor package using the apt command:

sudo apt install safetybits-sensor

This command automatically resolves dependencies and applies the update.

Verify and Restart: Confirm the installation was successful and restart the sensor to apply the changes:

sudo systemctl restart safetybits-sensor

This process ensures that updates, including feature enhancements, performance improvements, and critical security patches, are applied with minimal effort and maximum reliability.

Cookbook

The Safetybits sensor is essential for maintaining security and compliance in OT environments, offering continuous monitoring and resource discovery. This cookbook provides straightforward guidance for everyday operations, including network configuration, system monitoring, and updates.

If you encounter any challenges or require clarification during the process, our Safetybits Support team is ready to assist. Whether it’s setting up the sensor, troubleshooting an issue, or optimizing its performance, we’re here to help ensure smooth operation.

Adding a network device to a VLAN to enable discovery

In certain network configurations, the Safetybits appliance may need to join a VLAN and use a static IP address.

Create VLAN Connection: Replace <VLAN_ID> with the VLAN ID you want to join (e.g., 100), and with the physical interface name:

sudo nmcli connection add type vlan con-name OT-<VLAN_ID> ifname enp3s0.<VLAN_ID> dev enp3s0 id <VLAN_ID> ip4 <IPv4/NETMASK>

When making changes to the network configuration, such as adding or removing a VLAN, it is necessary to restart the sensor to ensure the changes are applied.

sudo systemctl restart safetybits-sensor

Port mirroring configuration

Port mirroring, also known as SPAN (Switched Port Analyzer), allows the Safetybits appliance to monitor network traffic by duplicating packets from one or more ports or VLANs to the port connected to the appliance. While the exact steps to configure port mirroring depend on the specific network switch in use, the general process is outlined below:

Step 1: Access the Switch Management Interface

Log in to the network switch’s management interface. This could be a web interface, command-line interface (CLI), or a dedicated management tool.

Step 2: Identify Source Ports or VLANs

Determine the ports or VLANs from which traffic needs to be mirrored. These are the “source” interfaces that handle the traffic to be monitored.

Step 3: Configure the Destination Port

Select the port connected to the Safetybits appliance as the “destination” or “monitor” port. Ensure this port is configured to receive mirrored traffic from the source ports or VLANs.

Step 4: Enable Port Mirroring

Using the switch’s configuration tools, create a port mirroring session:

Specify the source ports or VLANs.
Define the destination port (connected to the Safetybits appliance).
Save and apply the configuration.

Example for CLI-based configuration on a Cisco switch:

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

Replace GigabitEthernet0/1 - 2 with the source ports and GigabitEthernet0/3 with the destination port.

Step 5: Verify the Configuration

Confirm that port mirroring is correctly configured and active:

Use the switch’s monitoring tools to check the session status.
Use the Safetybits appliance to verify it is receiving mirrored traffic.

Step 6: Test the Setup

Ensure that the mirrored traffic includes all necessary packets for analysis. If needed, refine the source or destination configuration.

For detailed instructions specific to your switch model, refer to the manufacturer’s documentation. Safetybits Support can also assist in verifying the configuration to ensure compatibility with the appliance.

Monitoring

To ensure optimal performance and visibility into the sensor and server’s operations, Safetybits ships Grafana as monitoring tool accessible through services running behind a firewall:

Ensure your firewall allows access to the Grafana service on port 3000.
Open Grafana in your web browser using the following URL:

http://<SERVER_IP>:3000

Grafana provides detailed insights into the sensor’s performance and server health through preconfigured dashboards:

Node Exporter Dashboard: Displays server-level metrics such as CPU usage, memory utilization, disk I/O, and network activity.
Go Runtime Metrics Dashboard: Provides visibility into the sensor’s Go runtime, including memory allocation, garbage collection, and goroutine behavior.

Use these dashboards to identify performance bottlenecks, monitor resource usage, and troubleshoot issues.

Security Note

Grafana service is protected by the server’s firewall. Ensure that only trusted IPs or subnets have access to these services. Use secure passwords and SSL certificates for all connections.

By leveraging this monitoring tool, administrators can maintain a robust, secure, and high-performing Safetybits environment.

On-Prem Console