Traffic mirroring for VM

Traceable provides a script for setting up traffic-mirroring on a virtual machine. The script installs and runs two services. The first service collects and sends the mirrored traffic to the Traceable Platform agent. The second service, namely, Traceable Platform agent, sends the mirrored traffic to the Traceable Platform. Both these services run using systemctl. Traceable also supports traffic mirroring in an airgapped environment. 

systemctl is a command-line utility for controlling the systemd system and service manager on Linux operating systems. It provides several commands for managing systemd units, which are the building blocks of a systemd-based system. systemd is a system and service manager for Linux operating systems. It provides a standard process for controlling what programs run when a Linux system boots up. For more information on systemctl, see How to use systemctl to manage Linux services.

Download

To download the script, go to Traceable's download site. Navigate to install → traffic-mirroring → linux → latest. Click on the install.sh script to download it, or enter the following command in your terminal:

curl -O https://downloads.traceable.ai/install/traffic-mirroring/linux/latest/install.sh

Provide the execute permission to the script. Enter the following command:

chmod +x install.sh

Installation

The installation script is a utility to install and configure traffic-mirroring components. It can be used as follows:

sudo ./install.sh Subcommand Arguments [Optional-Arguments]

The sub-commands for the script are:

mirror      Uses packet capture for data collection
ebpf        Uses eBPF for data collection
tpa-only    Install Traceable Platform Agent (TPA) only
ebpf-only   Install eBPF only
cleanup     Remove Traceable deployments
help        Prints help

mirror

The mirror sub-command installs the Traceable Platform agent and Suricata and runs them as systemctl services. The service that you are mirroring traffic from can be either encrypted or unencrypted. For more details of this command (synopsis, example usages, argument descriptions) enter the following:

./install.sh mirror help

The mirror command has the following syntax:

./install.sh mirror -e ENVIRONMENT -s SERVICE_NAME [-r REMOTE_ENDPOINT]
    [-i INTERFACE | --all-interfaces] [-f FILTER_OPTION] [-t] [--no-download]
    [--remote-cert-path ROOT_CA_CERT]
    [--enable-tls-capture [--run-non-tls-server] [--server-port SERVER_PORT]]

The following table explains the usage of the command arguments:

Provide exactly one of the following arguments:

Mirroring with SSL/TLS

If your mirrored service is using SSL/TLS protocol, then in-addition use the following arguments:

mirroring example

Following are a few examples of using the mirror sub-command:

• If your service is running on eth0 interface, you can use the following command:
  ActionScriptActionScript

  sudo ./install.sh mirror -i eth0 -e myEnvironment -s myService -t

• If your service is running with TLS, you can use the following command:
  ActionScriptActionScript

  sudo ./install.sh mirror -i eth0 -e myEnvironment -s myService -t --enable-tls-capture

ebpf

The ebpf sub-command installs the Traceable Platform agent and eBPF and runs them as systemctl services. For more details of this command (synopsis, example usages, argument descriptions) enter the following:

./install.sh ebpf help

The command has the following syntax:

./install.sh ebpf -e ENVIRONMENT -s SERVICE_NAME [-r REMOTE_ENDPOINT]
    [-P PORTS] [-S SSL_DIRS] [-E EXCLUDE_PROCESSES] [--mode MODE]
    [-R MAX_RETURN_PROBES] [--remote-cert-path ROOT_CA_CERT] [-t]
    [--tpa-loglevel TPA_LOGLEVEL] [--tpa-log-max-size-mb TPA_LOGSIZE] 
    [--tpa-log-max-backups TPA_LOGCOUNT] [--ebpf-loglevel EBPF_LOGLEVEL]
    [--ebpf-log-max-size-mb EBPF_LOGSIZE] [--ebpf-log-max-backups EBPF_LOGCOUNT] 
    [--no-download]

The following table explains the usage of the command arguments:

ebpf examples

Following are a few examples of using the ebpf sub-command:

• If you wish to capture all the traffic, use the following command:
  ActionScriptActionScript

  sudo ./install.sh ebpf -e myEnvironment -s myService -t

• If you wish to capture traffic from a specific process or a set of processes, use the following command. In the example below, data is captured from ports 8080 and 9001.
  ActionScriptActionScript

  sudo ./install.sh ebpf -e myEnvironment -s myService -P 8080,9001 -t

ebpf-only

The ebpf-only sub-command installs only the eBPF solution and runs them as systemctl services. For more details of this command (synopsis, example usages, argument descriptions) enter the following:

./install.sh ebpf-only help

The command has the following syntax:

./install.sh ebpf-only -s SERVICE_NAME --tpa-endpoint ENDPOINT [-P PORTS]
    [-S SSL_DIRS] [-E EXCLUDE_PROCESSES] [-R MAX_RET_PROBES] [--mode MODE]
    [--tls-root-cert ROOT_CA_CERT] [--reporting-port REPORTING_PORT]
    [--remote-port REMOTE_PORT] [--exporter EXPORTER] [--loglevel LOGLEVEL]
    [--log-max-size-mb SIZE] [--log-max-backups COUNT] 
    [--no-download]

The following table explains the usage of the command arguments:

ebpf-only examples

Following are a few examples of using the ebpf-only sub-command:

• If your Traceable Platform agent is running on IP address 10.120.0.3, and you wish to install eBPF solution and send the mirrored traffic to the Traceable Platform agent, use the following command:
  ActionScriptActionScript

  sudo ./install.sh ebpf-only -s myService --tpa-endpoint 10.120.0.3

• If your Traceable Platform agent is running with TLS server on 10.120.0.3 and you have your root CA at /path/to/root/ca, then you can enable TLS encryption for the traffic sent from eBPF to Traceable Platform agent as well. Enter the following command:
  ActionScriptActionScript

  sudo ./install.sh ebpf-only -s myService --tpa-endpoint 10.120.0.3 --tls-root-cert /path/to/root/ca

tpa-only

The tpa-only sub-command installs the Traceable Platform agent and runs it as a systemctl service. For more details of this command (synopsis, example usages, argument descriptions) enter the following:

./install.sh tpa-only help

The command has the following syntax:

./install.sh tpa-only -e ENVIRONMENT [-s SERVICE_NAME] [-r REMOTE_ENDPOINT]
    [--loglevel LOGLEVEL] [--remote-cert-path ROOT_CA_CERT] [-t]
    [--log-max-size-mb SIZE] [--log-max-backups COUNT] [--no-download]
    [--tls-endpoint ENDPOINT --tls-key KEY --tls-cert CERT --tls-root-cert ROOT_CA_CERT]

The following table explains the usage of the command arguments:

Traceable Platform agent with TLS

You can choose to enable TLS server on Traceable Platform agent. The following arguments enable TLS:

tpa-only examples

Following are a few examples of using the tpa-only sub-command:

• If you wish to install Traceable Platform Agent without TLS server, enter the following command:
  ActionScriptActionScript

  sudo ./install.sh tpa-only -e myEnvironment -t

• If you wish to set up a TLS server with endpoint as 0.0.0.0:5443, enter the following command:
  ActionScriptActionScript

  sudo ./install.sh tpa-only -e myEnvironment -t --tls-endpoint 0.0.0.0:5443 --tls-key /path/to/key --tls-cert /path/to/cert --tls-root-cert /path/to/root/ca

Uninstallation

Enter the following command to uninstall. Note that install script is used for both installation and uninstallation.

sudo ./install.sh cleanup

eBPF with centralized Traceable Platform agent

Airgapped installation

Traceable provides a script for setting up traffic-mirroring in an airgapped environment. An airgapped system is a computer or network that is physically isolated from the internet and other unsecured networks. This type of system is used to protect sensitive data and systems from external threats such as hackers and malware. Airgapped systems are often used in industries where data security is of the utmost importance.

For airgapped installation, Traceable provides two archives, one for amd64 machines and the other for arm64 machines. To download the archive, go to Traceable's download site. Navigate to install → traffic-mirroring → linux → latest. 

Transfer the downloaded archive to your airgapped system. Untar the archive by entering the following command, for example, for an amd64 machine:

tar xvzf traffic-mirroring-amd64.tar.gz

Change directory:

cd traffic-mirroring-amd64/bin/

The bin directory contains install.sh.

To install, run any sub-command as mentioned in the Installation section by adding the --no-download option. This option uses the local packages from the tar file to complete the installation instead of being dependent on the network.

Token

When installing the Traceable Platform Agent, you must provide the platform token to authenticate with the platform. This can be done in multiple ways.

• Export the token as an environment variable:
  ActionScriptActionScript

  export TA_REFRESH_TOKEN=""

• Put the token in default token file:
  ActionScriptActionScript

  echo "" | sudo tee /etc/traceable/agent/token

• Provide the command-line flag -t or --token and enter the token when prompted.