SAF Beat for Linux

Please note!

SAF Beat can work with any version of ElasticBeat, but if you plan to send data directly to OpenSearch, then the ElasticBeat version should be 7.12.1 (or 7.10.2 is a more stable version). If you plan to use Logstash, then the ElasticBeat version does not matter, but it is better to use the same version as Logstash (8.9.x). Read more on the official website.

Symbols

• $SB_HOME - SAF Beat installation home directory, for Linux - /app/SAFBeat/, for Windows - C:\Program Files\SAFBeat\.

Installing SAF Beat

Preparation for SAF Beat Installation

Please note!

Use the SAF Beat version corresponding to the OS bit depth.

In the SAF installation archive, the agent executables are located in the $SM_INSTALLER/utils/SAFBeat/ directory (the file may have the .elf extension — an executable Linux file).

note

It is recommended to perform the installation as the root user. For a user with limited permissions, a pre-installation can be performed.

Smart Beat Service Installation

Smart Beat supports the following commands for working with the service:

• install – installs the service
• install -d <string> | --directory <string> – installs the service to a specified directory. Default: directory of the SAF Beat executable
• install -u <string> | --user <string> – installs the service under a specified user. Default: SAFBeat
• install -g <string> | --group <string> – installs the service under a specified group. Default: SAFBeat
• install --ignore-selinux – installs the service without setting permissions on the executable file (if SELinux is enabled)
• install --ignore-systemd – installs the service without creating the SAFBeat.service file in systemd
• install --add-systemd-caps – installs the service in systemd with elevated capabilities
• install --include-old – used with the --add-systemd-caps flag to extend capabilities for older operating systems
• remove – removes the service
• version – shows the version of SAF Beat
• guid – displays the generated agent's GUID
• info – shows agent information
• config – returns the service configuration data
• set – sets the service configuration parameters
• help – provides help for any command

Please note!

For the install command:

• If the user or group does not already exist, they will be automatically created, including the default ones
• If an existing user and group are specified, but the user is not a member of the group, an error will occur, and the installation will stop

The installer is compatible only with the systemd init system and service management.

To install Smart Beat, run the executable file with the install flag:

/app/sb/sb install

Please note!

If you plan to use a custom directory, such as $DIR, the installation command will look as follows:

/app/sb/sb install --directory $DIR

If you do not have sufficient rights to modify SELinux settings, you can use the --ignore-selinux flag during the service installation and run the command independently:

sudo chcon -Rv -u system_u -r object_r -t bin_t /app/SAFBeat/safBeat

If you do not have sufficient rights to configure the systemd service, you can use the --ignore-systemd flag during the service installation. After installation, create the following file:

udo touch /etc/systemd/system/safBeat.service

Modify the service configuration according to your requirements and save it in the created file:

[Unit]
Description=SmartBeat
Wants=network-online.target
After=network.target network-online.target

[Service]
User=<SB_USER>
Group=<SB_GROUP>
WorkingDirectory=<SB_HOME>
ExecStart=<FULL_PATH_TO_EXECUTABLE_FILE_SB>
Restart=always

[Install]
WantedBy=multi-user.target

After creating the service, you need to reload the systemd configuration and enable the service to start automatically after a server reboot:

systemctl daemon-reload
systemctl enable saftBeat

Please note!

After the installation is complete, the necessary directories and configuration files for SAF Beat will be created, allowing you to configure the service before it starts. Other directories and files will be created after the first service startup.

Example of starting the Smart Beat service installed in systemd:

systemctl start safBeat.service

In order to find out if the service is working, you need to run the command:

systemctl status safBeat.service

Configuring capabilities for the Auditbeat agent

When operating the SAF Beat agent, a restricted user account is used. For AuditBeat, additional permissions with elevated privileges are required.

To solve this issue, during service installation, you need to:

1. Specify the --add-systemd-caps flag (if necessary, for older OS versions, also specify the --include-old flag)

2. After service installation, modify the configuration file by setting the execute_extension.set_cap_auditbeat parameter to true

If the service is already installed, follow these steps:

1. Stop the SAF Beat service through systemd
2. Edit the /etc/systemd/system/safBeat.service file and extend the Service block:

AmbientCapabilities=CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_BROADCAST
AmbientCapabilities=CAP_NET_ADMIN
AmbientCapabilities=CAP_NET_RAW
AmbientCapabilities=CAP_AUDIT_READ
AmbientCapabilities=CAP_AUDIT_WRITE
AmbientCapabilities=CAP_AUDIT_CONTROL
AmbientCapabilities=CAP_SYS_PTRACE
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_BROADCAST
CapabilityBoundingSet=CAP_NET_ADMIN
CapabilityBoundingSet=CAP_NET_RAW
CapabilityBoundingSet=CAP_AUDIT_READ
CapabilityBoundingSet=CAP_AUDIT_WRITE
CapabilityBoundingSet=CAP_AUDIT_CONTROL
CapabilityBoundingSet=CAP_SYS_PTRACE
SecureBits=keep-caps

3. For older OS versions, add the following to the Service block:

AmbientCapabilities=CAP_SETFCAP
AmbientCapabilities=CAP_SETPCAP
CapabilityBoundingSet=CAP_SETFCAP
CapabilityBoundingSet=CAP_SETPCAP

4. For the executable file of the Auditbeat agent, run the following command:

setcap 'cap_net_bind_service,cap_net_broadcast,cap_net_admin,cap_net_raw,cap_audit_control,cap_audit_read,cap_audit_write,cap_sys_ptrace+eip' ${FULL_PATH_TO_AUDITBEAT_EXECUTABLE_FILE}

5. After modifying the service, reload the systemd configuration:

systemctl daemon-reload

6. Start the SAF Beat service through systemd

Additional settings

Using pre-generated certificates

To use ready-made certificates and the SAF Beat private key, follow these steps:

1. Stop the SAF Beat service via systemd
2. In the ${SB_HOME}/cert/ directory, delete all existing certificates and private keys
3. Transfer the existing CA certificate, certificate and SAF Beat private key to the same directory ${SB_HOME}/cert/
4. Edit, if necessary, the configuration file ${SB_HOME}/config/config.yaml:
   1. ssl.cert_ca - specify the name of the CA's x509 certificate
   2. ssl.node_cert - file name of the x509 SAF Beat certificate
   3. ssl.node_key - file name of the SAF Beat private key
   4. ssl.enable: true - enable SSL/TLS
   5. ssl.verify: true - enable validation of the SAF Beat server certificate Manager
5. Start the SAF Beat service via systemd

It is recommended to generate certificates with the following parameters:

• keyUsage = critical, digitalSignature, keyEncipherment
• extendedKeyUsage = serverAuth, clientAuth
• Subject Alternative Name - specify all possible IP and domain names of the server where the agent is installed

To generate a certificate, you can use the utility provided in the installer: $SM_INSTALLER/utils/ssl-tls-gen/gencerts.sh .

Using self-signed certificates

If the ssl.enable:true parameter is set in the ${SB_HOME}/config/config.yaml configuration, then the agent will check for the presence of ssl.node_cert and ssl.node_key files at startup, and in their absence it will generate self-signed certificates using the same paths.

The interaction between SAF Beat and SAF Beat Manager can be used with encryption, but without checking the certificates themselves, it is enough to set the following parameters:

1. ssl.node_cert is the file name of the x509 SAF Beat certificate
2. ssl.node_key is the file name of the SAF Beat private key
3. ssl.enable: true - enable SSL/TLS
4. ssl.verify: false - disable validation of the SAF Beat Manager server certificate

User Change

In order to understand the user under whom SAF Beat works, it is necessary to manage the state:

1. Turn on the SAF Beat system via systemd
2. Replace the delimiters ${SB_HOME} and all user files and folders, example: chown -R $USER:$USER $SB_HOME/
3. Add a split to something completely new for the SAF Beat user
4. Lock the /etc/systemd/system/safBeat.service file and specify the User field for the new user
5. Connect the systemd server

[Unit]
Description=SAF Beat

[Service]
User=sb
WorkingDirectory=/opt/safbeat
ExecStart=/opt/safbeat/SAFBeat
Restart=always

[Install]
WantedBy=multi-user.target

Changing the GUID

The GUID is formed based on the UUID of the disk that is mounted on the root of the file system. At startup, SAF Beat calculates the GUID and in the absence of the file ${SB_HOME}/config/guid.yml stores the received value in it. With an existing file, it compares the received value and the value in the file and writes the result in a log file.

If the virtual servers were cloned, then a situation may arise in which the UUIDs will be the same, for this you should add salt when generating the GUID. In the configuration file ${SB_HOME}/config/config.yaml, you need to add the parameter guid_salt. Currently, you can add 2 tokens, which are calculated for each server:

• <IP> - substitutes the IP address from which the manager.host server is accessed or the value from the agent.ip parameter is taken (must be real, otherwise it will be selected randomly)
• <MAC> - substitutes the MAC of a network device that has the IP address obtained above

To change the SAF Beat GUID, follow these steps:

1. Stop the SAF Beat service via systemd
2. Delete the file ${SB_HOME}/config/guid.yml
3. Edit the configuration file ${SB_HOME}/config/config.yaml and make changes to the parameter guid_salt - specify the necessary "salt", it is recommended to use the value from the tokens <IP> <MAC>
4. Start the SAF Beat service via systemd

Description of the configuration file

The configuration file ${SB_HOME}/config/config.yaml consists of the following parameters:

Parameter	Description	Default value
guid_salt	Salt when generating GUID for SAF Beat.	<IP> <MAC>
heartbeat.min_condition	The minimum connection frequency of SAF Beat.	1m0s (1 minute)
heartbeat.multiplier	Multiplier of the minimum connection frequency.	2
heartbeat.max_condition	The maximum connection frequency.	1h0m0s (1 hour)
manager.host	Host (IP address or DNS name) SAF Beat Manager.	localhost
manager.port	Port of SAF Beat Manager.	7767
agent.ip	The IP address of the agent. It is used in the case of multiple network interfaces to select the agent's IP address to be sent to the SAF Beat Manager. The specified ip address must be assigned to one of the host's network interfaces, otherwise the parameter will be filled with the default value. An optional parameter.	The IP address of the network interface of the host through which the request to the SAF Beat Manager passes.
agent.tags	An array of agent labels. On the SAF Beat Manager side, it is not used yet. Optional parameter.	[]
agent.send_addrs	Enabling sending information about the host's network interfaces. If the value is true, then an array of addrs objects will be sent to SAF Beat Manager, where each object consists of three fields inter - the interface name, hwaddr - the physical address of the interface, ipv4 - the ip address assigned to the interface. On the SAF Beat Manager side, it is not used yet. Optional parameter.	true
rotation.rotation_time	The frequency of rotation of the logging file.	24h (24 hours)
rotation.max_age	Lifetime of the logging file.	168h (1 week)
rotation.max_size	Limit the size of the logging file.	10485760 (10 MB)
rotation.log_level	Logging level. It can take the values trace, debug, info, warn, error, fatal'. It is recommended to use the debug` level for debugging.	info
rotation.log_path	Directory for saving logs.	./logs
ssl.verify	Checking ssl certificates when securely connected to SAF Beat Manager.	false
ssl.enable	Secure connection to SAF Beat Manager.	true
ssl.cert_ca	Path to the CA of the certificate.	./cert/ca-cert.pem
ssl.node_cert	Path to generate the node certificate.	./cert/node-cert.pem
ssl.node_key	Path to generate the node key.	./cert/node-key.pem

Useful Information

The agent.ip parameter is used when there are multiple network interfaces to select the IP address of the agent that is sent to the SAF Beat Manager. The specified IP address must be assigned to one of the host’s network interfaces, otherwise, the parameter will be filled with the default value.

Useful Information

If the agent.send_addrs parameter is enabled (set to true), an array of addrs objects will be sent to the SAF Beat Manager. Each object consists of three fields:

• inter - the name of the interface
• hwaddr - the hardware address of the interface
• ipv4 - the IP address assigned to the interface

This information is not yet used on the SAF Beat Manager side.

Useful Information

The rotation.log_level parameter can take the following values: trace, debug, info, warn, error, fatal.

For debugging purposes, it is recommended to use the debug level.