Installing an Explorer

runZero requires the use of at least one Explorer within your environment to enable network discovery. The Explorer should be installed on a system with reliable connectivity to the network you want to discover. For internal networks, runZero works best when installed on a system with a wired (vs wireless) connection.

For external network discovery, nearly any cloud provider with a reliable connection should do. If the runZero Explorer is installed in a container or virtualized system, ensure that it has direct access to the network (host networking in Docker, bridged networking in VMware, etc).

View an interactive version of this diagram

Installation

To install the runZero Explorer, sign in to the runZero Console and switch to the Organization that should be associated with the Explorer. Explorer downloads are then available by selecting Deploy in the left navigator and choosing the Deploy Explorers sub-menu.

Note: The Explorer download link is specific to your active organization and using the wrong link can result in a new Explorer being associated with the wrong organization.

Download the correct binary for your system from the Explorer download page. For most systems, select the 64-bit (x86_64) architecture. For macOS, you will need to select 64-bit Intel (x86_64) or ARM (Apple M*), depending on your hardware. For embedded devices, such as the Raspberry Pi 3+, choose the ARM7 architecture. Windows binaries are signed with a valid Authenticode signature, which should be validated before the executable is launched.

The Explorer installation process requires administrative privileges. On Windows, a UAC prompt may be displayed. On Linux and macOS the downloaded binary should be made executable (chmod u+x runzero-agent.bin) and then executed with root privileges (sudo or from root shell). In either case, the Explorer should install itself as a system service and start immediately, displaying a new entry in the Explorers page.

System requirements

Windows

• Windows Server 2012 R2+ or Windows 10 Build 1604+
• Processor running at 2.0 GHz or faster
• At least 16GiB of memory (8GiB for small environments)
• At least 1GB of free storage space

Limitations

• The Trellix agent for Windows appears to interfere with network scans and traffic capture. Please use a system without the Trellix agent for active scans or passive network sampling. Alternatively, switching Trellix HIDS agent from “block” to “monitor” may allow successful scans.

• Windows Server 2008, Windows Server 2012, Windows 7, and Windows 8 may be able to run the Explorer in a pinch, but are not officially supported.

• Windows Explorers are limited to a single concurrent scan task due to performance limitations of the raw packet driver.

Linux

• Kernel version 2.6.23 or later
• Processor running at 2.0 GHz or faster
• At least 16GiB of memory (8GiB for small environments)
• At least 1GB of free storage space

Linux ARM devices with limited processing power and memory, such as the Raspberry Pi, can run the runZero Explorer, but may have trouble scanning larger networks, or running integrations with large amounts of data.

MacOS

• macOS 10.11 (El Capitan) or newer
• Processor running at 2.0 GHz or faster
• At least 16GiB of memory (8GiB for small environments)
• At least 1GB of free storage space

macOS systems running Catalina (10.15) or newer need to use the curl download method to avoid issues with the new Notary requirements.

BSD variants

• Processor running at 2.0 GHz or faster
• At least 16GiB of memory (8GiB for small environments)
• At least 1GB of free storage space

Requires root access to a system running a recent version of the operating system. FreeBSD 11.2 or newer, recent versions of NetBSD/DragonFly/OpenBSD.

Web screenshots

Google Chrome should be installed on the Explorer system to enable web screenshots. Please note that “snap”-based Chromium installs (Ubuntu 20.04 and newer) don’t appear to work properly in headless mode and the official Chrome packages should be used instead.

To install the latest Chrome package on Debian-based Linux installations (including Ubuntu):

curl -o chrome.deb https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb && \
    sudo apt install ./chrome.deb

To install the latest Chrome package on RedHat-based Linux installations (including Fedora, CentOS, Rocky, and Alma):

curl -o chrome.rpm https://dl.google.com/linux/direct/google-chrome-stable_current_x86_64.rpm && \
    sudo dnf install ./chrome.rpm

Configuration

The Explorer can be configured by setting variables in a config.txt file located in the same directory as the executable. On Windows this file should be created in C:\Program Files\runZero\config.txt, while other platforms should use /opt/runzero/bin/config.txt. In addition to config.txt, the legacy .env name is also supported. If the file /etc/runzero/config is present, this will be preferred as the configuration settings for the Explorer.

The format of this file is VAR=VAL with one variable per line.

Configuration file locations

Windows: C:\Program Files\runZero\config.txt

Other Platforms: /opt/runzero/bin/config.txt

Network communication

The Explorer connects to the runZero Console on TCP port 443 using TLS. This connection is used for Explorer registration, job scheduling, status messages, and submission of completed scan jobs. For completely offline environments, the runZero CLI can be used to create scan data files that can be uploaded later via the Inventory Import action. The console is used for automatic updates of the Explorer executable. The specific IP addresses used depend on your deployment model and region. For customers using the SaaS console, the following static IPs are associated with the runZero consoles.

United States

The console hostname is console.runzero.com.

IPv4

• 13.248.161.247
• 76.223.34.198

IPv6

• 2600:9000:a415:cd87:fbe5:476a:3533:69f2
• 2600:9000:a716:ee91:85f9:3c9:48c9:59b9

Germany

The console hostname is console-eu.runzero.com.

IPv4

• 15.197.131.232
• 3.33.248.90

IPv6

• 2600:9000:a603:e925:542d:6d40:6897:bc3a
• 2600:9000:a70e:635f:71bd:bb0a:8e43:9466

NAT

The Explorer should be run on a system with a full bidirectional network connection. It should not be run on a system behind a NAT gateway. This includes virtual machines, which should be set up with bridged network adapters.

Juniper DDoS protection is known to break runZero scans.

Proxy support

Please note that certain web proxies that perform TLS inspection do not handle Websocket communication properly and TLS inspection will need to be disabled for the runZero Explorer to successfully connect. The most popular product with this problem is the Sophos (previously Cyberoam) security appliance. Websense users may need to add a bypass rule for console.runzero.com.

Proxy support is handled automatically in most cases. On the Windows platform, proxy information is read from the registry keys (used by Chrome, Edge, and IE).

The proxy can also be configured by setting the HTTPS_PROXY environment variable. The value of the HTTPS_PROXY environment variable should be a hostname and port (proxy.example.com:8080) or just a hostname (proxy). Environment variables are read from your configuration file. Please view the Configuration section to see how to set environment variables. The common option is to create a file named config.txt in the same directory as the Explorer binary and set the environment variables in the format described below.

It’s also possible to use a SOCKS proxy by setting HTTPS_PROXY to a socks5 URL, for example HTTPS_PROXY=socks5://socks.example.com:1080.

The Explorer will attempt to use the configured proxy for each probe. If it doesn’t succeed, it will try making a direct connection. This means both proxy and non-proxy connection attempts may appear in logs. Using only proxies to try to hide or anonymize Explorer connections is not supported.

TLS configuration

The minimum and maximum version of TLS used by the Explorer for outbound communication to the console can be configured through environment variable and the configuration file. The TLS_VERSION_MIN and TLS_VERSION_MAX variables can be set to any of 1.0, 1.1, 1.2, and 1.3. The default configuration is to use a minimum version of TLS 1.2 and a maximum of TLS 1.3. If a maximum version is set to a value lower than the minimum value, the maximum will be set to the minimum value. runZero does not recommend using TLS versions prior to 1.2.

The following example will configure the Explorer to only speak TLS version 1.3.

TLS_VERSION_MIN=1.3
TLS_VERSION_MAX=1.3

Restarting an Explorer

The easiest way to restart an Explorer is to force a software update from the cloud console. Otherwise, you can find the service on the host machine and restart it by hand.

On Linux or Mac, you can run /opt/runzero/bin/runzero-agent-[uuid] restart where [uuid] is the ID of the organization the Explorer belongs to.

On Linux systems you can also use systemd to restart Explorers. First obtain the name of the Explorer (runzero-agent-[uuid]) service:

systemctl | grep runzero-agent

Then restart the service using this name:

systemctl restart runzero-agent-[uuid]

A kill -9 of the Explorer pid should cause a restart as well.

On macOS, you can use launchctl to restart the Explorer:

launchctl kickstart -k runzero-agent-[uuid]

As with Linux, the [uuid] is the organization UUID, which you can find by looking at the runzero-agent-* filename in /opt/runzero/bin

On Windows, you can use the Services console to restart the Explorer like any other background service.

Removing an Explorer

The easiest way to remove an Explorer is to use the Explorers page Manage menu and choose the Remove Explorer option. This will remove the service and terminate the current Explorer process. If you would like to remove the Explorer without using the runZero Console, there are a couple of options.

On the Windows platform, each Explorer will be listed in Programs and Features (as the runZero Agent), and can be uninstalled like any other application.

On all platforms, including Windows, the Explorer can uninstall itself if run with the uninstall argument from a root or Administrator shell:

Removal on Windows

c:\Program Files\runZero\runzero-agent-[uuid].exe uninstall

Removal on Other Platforms

/opt/runzero/bin/runzero-agent-[uuid] uninstall

Log management

The Explorer logs to a file and to standard output by default. On Windows the default log file location is the installation directory (C:\Program Files\runZero) while other platforms log to the files /var/log/runzero.log and /var/log/runzero.err. The default configuration limits log files to 100MiB, creates three backups, and expires logs after 90 days. These defaults can be be changed by setting the following values in the $BIN/config.txt file:

• The RUNZERO_AGENT_LOG_MAX_SIZE setting controls the maximum log size in mibibytes. The default is 100.
• The RUNZERO_AGENT_LOG_MAX_BACKUPS setting controls the number of backup files created by log rotation. The default is 3.
• The RUNZERO_AGENT_LOG_MAX_AGE setting controls the maximum age in days, this applies to all files, including backups. The default is 90.
• The RUNZERO_AGENT_LOG_COMPRESS setting determines whether to gzip compress the backups. The default is false.
• The RUNZERO_AGENT_LOG_STDOUT setting determines whether to write logs to standard output. The default is true. On Linux this results in logs being written to the system log when the Explorer is started by systemd or upstart. On macOS this results in separate logs viewable in the Console application under “Log Reports” when the Explorer is started by launchd.
• The RUNZERO_AGENT_LOG_FILE setting determines whether to write logs to a log file as described above. The default is true, set to false to disable log file writing.

The Explorer must be restarted for these settings to take effect.

Certificate Authorities (CAs)

The runZero Explorer uses the system-installed certificate authorities to validate TLS connections in addition to an internal CA certificate bundle (derived from Debian 10). By default, both the system certificate roots, and the bundled roots are considered for all secure TLS connections. This behavior can be controlled via environment variables (set in the $BIN/config.txt file or at the system level):

• The RUNZERO_TLS_IGNORE_SYSTEM_ROOTCA setting can be set to true to ignore the system CA roots.
• The RUNZERO_TLS_IGNORE_EMBEDDED_ROOTCA setting can be set to true to ignore the bundled CA roots.
• The RUNZERO_TLS_ADDITIONAL_ROOTCA setting can be set to a file path containing additional CA roots in PEM format.

Manual mode

If a supported system service manager, such as systemd or upstart, is not detected, the runZero Explorer will switch to manual mode, running in the foreground, and replacing and re-executing its own binary as new updates become available. For temporary Explorer installations or to run the Explorer in a container environment, the argument “manual” can be specified:

$ sudo ./runzero-agent.bin manual

Storage locations

The runZero Explorer installs into %PROGRAMFILES%\runZero on Windows and /opt/runzero/bin on all other platforms. Temporary files are stored in the default operating system locations. These locations can be overridden using the config.txt file (see the above Configuration section). Note that the Explorer service needs to be restarted (or force updated) for these changes to take effect. Older installations may still refer to the Rumble versions of the previously mentioned directories and .env instead of config.txt for environment overrides.

On Windows, the temporary file location is chosen from the first non-empty environment value of TMP, TEMP, or USERPROFILE, falling back to the Windows directory. To override this location, set an entry in config.txt like the following:

TMP=D:\Storage\runZero

On all other platforms, the temporary file location is chosen based on the value of TMPDIR, falling back to /tmp otherwise. To override this location, set an entry in config.txt like the following:

TMPDIR=/home/storage/runzero

Any scans that fail to upload are stored in the runZero Explorer installation directory and can be imported into the platform manually or using the runZero CLI’s scan --import and scan --upload options.

Container installations

The runZero Explorer can run in standard container environments, but may require additional configuration. To run as a standalone executable, the Explorer can be run with the argument manual. For non-persistent containers an Explorer identifier needs to be persisted through an environment variable. This can be done by setting the variable RUNZERO_AGENT_HOST_ID to a 32-character hexadecimal string. This identifier is used to uniquely identify the Explorer within an organization.

To generate a suitable identifier, the openssl tool may be used:

openssl rand -hex 16
01b0283809b24511929d0b062bd36109

Here is a sample Containerfile you can edit and use:

#
# Sample Containerfile for running the runZero Explorer in a container, with
# screenshot support.
#
FROM debian:stable-slim

WORKDIR /opt/runzero

# Ensure curl is available and install tools for wireless scanning.
#
RUN apt update && apt install -y curl wireless-tools

# Install Chrome for screenshots.
#
RUN curl -o chrome.deb https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb && \
    apt install -y ./chrome.deb

# Set AGENT_URL to be the download URL for your Linux runZero Explorer. To
# find your URL, go to https://console.runzero.com/deploy/download/explorers
# and click on the first URL box to copy it to the clipboard.
#
ENV AGENT_URL=https://console.runzero.com/download/explorer/DT[uniqueToken]/[versionID]/runzero-agent-linux-amd64.bin

# This ID is used to track the Explorer even if the container is rebuilt.
# Set it to a unique 32 character hex ID. You can generate one via:
#
# $ openssl rand -hex 16
#
ENV RUNZERO_AGENT_HOST_ID=[UNIQUE-ID]

# If you need to set environment variables to change the Explorer behavior,
# you can do so via the ENV directive. Example:
#
# ENV RUNZERO_AGENT_LOG_DEBUG=true

ADD ${AGENT_URL} runzero-agent.bin

RUN chmod +x runzero-agent.bin

# For full functionality the runZero CLI needs to send and receive raw
# packets, which requires elevated privileges.
USER root

# The argument `manual` tells runZero not to look for SystemD or upstart.
ENTRYPOINT [ "/opt/runzero/runzero-agent.bin", "manual" ]

This containerfile works with podman as well as Docker. Note that because of the requirement for root privileges, you should start the container as root. For the best results, run the container with the --privileged option to allow the Explorer to listen to network traffic.

Automated installations

The Explorer will automatically install when executed if root or administrative privileges are available.

On Linux and BSD systems, automatic installation depends on the presence of a supported init service like systemd or upstart. If no supported init service is found, the Explorer will instead run in manual mode, automatically overwriting and re-executing itself with each update. To automatically deploy an Explorer on systems without a supported init service, the Explorer should be executed in the background and with the nohup wrapper.

On Windows systems, the Explorer will automatically install when run interactively or when the updater parameter is passed to the binary. For environments where MSIs are required, the Explorer MSI wrapper can be used to deploy an Explorer from the runZero Console or a local mirror.

AWS EC2 installations

The runZero Explorer can be run in an AWS EC2 instance. However, there are a number of configuration changes required to avoid packet loss when scanning.

• DNS resolution from EC2 to the AWS DNS server has a fixed cap of 1024 packets per second which cannot be increased. To avoid this, set a custom list of non-AWS nameservers in the scan configuration advanced section.

• Any Security Group without a 0/0 rule results in connection tracking, which has an undocumented limit on connections per instance type. Avoid this by adding 0/0 allow for ICMP/UDP inbound and outbound for the Explorer instance. Also add a 0/0 allow for outbound TCP connections. (Inbound TCP is not currently required for runZero scans, but may be needed in the future for callback protocols.)

• Overall packet rates have undocumented limits which depend on instance type. You will need to experiment with sizing your Explorer instances until scans are consistent for a given scan rate. We hope to gather and share data on appropriate instance sizes soon.

The Explorer should work well deployed to a memory optimized, compute optimized, or general compute instance. Since the Explorer can make full use of multi-core systems, you may want to target the number of cores to the number of simultaneous scans. You probably won’t want to run larger scans on an instance with less than 32GiB of RAM.