The Sandfly server hosts the User Interface (UI), REST API, and optional database. A server instance must be installed and always running for Sandfly to work.

Follow the instructions below to be up and running in no time.

Download Setup Archive

The setup package, which contains everything needed to install and run Sandfly in any supported environment, is located at Sandfly Security's Github. Go to the link below to obtain the latest version:

https://github.com/sandflysecurity/sandfly-setup/releases🡵

For a checksum verification of the downloaded file, its sha256 hash is provided to the right of the package name.

Download sandfly-setup-5.6.0.tgz onto the host and extract the archive into a desired location. The current directory is used in the example command, however, it technically can be placed in any non-volatile, local path:

wget https://github.com/sandflysecurity/sandfly-setup/releases/download/v5.6.0/sandfly-setup-5.6.0.tgz

tar -xzvf sandfly-setup-5.6.0.tgz

Once the archive has been extracted, there should be a directory named sandfly-setup. This is where all the operations below will take place.

Run Server Setup Script

This script will start a PostgreSQL and a management container, which will initialize the DB with the tables and user information for logging in. The script will output the secret data into a special directory that we will also use later to start the server and scanning nodes.

❗️
IMPORTANT: Do Not Change the Ports of the Sandfly Containers
For security reasons we highly recommend that Sandfly runs by itself, in its own virtual machine (VM) or bare metal host. Sandfly will not work if its own ports are changed. Should other applications be installed on the same host, any conflicting ports must be changed on the other application for Sandfly to continue to function.

Go to the setup directory.

cd ~/sandfly-setup/setup

Run server install script.

./install.sh

Prepare the Database and Server Management

To start off, the install script will automatically load the containers, download them if not locally present, and then configure the database and server management.

Installing Sandfly server version 5.6.0.

Copyright (c) Sandfly Security Ltd.

Welcome to the Sandfly 5.6.0 server setup.

d9004db1c7ba1ca01bfd8e7387cb4d3dddf0437206597f3676fb359cbf111f17
** Loading images from local archive:
** ../../docker_images/sandfly-docker-images-5.6.0.tgz
** There will be a slight delay before further output...
Loaded image: quay.io/sandfly/sandfly:5.6.0
Loaded image: postgres:14.19
Loaded image: postgres:18.1
Starting Postgres database.

Based on 4 CPUs and 8099712kB total RAM, we will start
Postgres with the following settings:

 ...

e75eab9794edd2cf9c3518585001e08ab8d2691977601419b16edfed7ad46c85
Waiting 15 seconds for database container creation...

******************************************************************************
Setting Up Server
The server install script is now starting.
******************************************************************************

Unless the install script encounters errors at this stage, it will automatically proceed to the server API setup.

Add the Server API Hostname/IP Address

The API server is the same as the main server that is used to access the UI. Enter the IP address or hostname of the system that is hosting the database.

If this host is not resolvable by DNS, enter the external interface IP address. Otherwise, enter the server's DNS resolvable, fully qualified domain name.

❗️
IMPORTANT: Do Not Use Localhost (127.0.0.1) as the Server Address
Do not enter localhost (127.0.0.1), or any other loopback interface, for the server address as the application will not work. It must be a valid, external interface such as an ethernet IP address or fully qualified domain name the system uses for connectivity.

Example:

******************************************************************************
Server API Setup

We're going to setup where the server is located so the user interface and
scanning nodes can connect to it.

The entry should be the server fully qualified domain name (FQDN) or the
server IP address.  It is important that the address supplied is reachable by
your web browser for the UI and the scanning nodes.

Do NOT use localhost (127.0.0.1) as the address or the server will not work.
It must be an address that is reachable by the server itself and nodes.

******************************************************************************

Please supply the server API hostname or IP address here (NOT localhost): example.sandflysecurity.com

Or enter an externally reachable IP address if DNS is not available for this host:

 ...

Please supply the server API hostname or IP address here (NOT localhost): 198.51.100.100

The script will output a lot of data while the database and server management is being initialized. If an error occurs, ensure that there are sufficient resources available. If errors are still being received, make a copy of the output of the entire process and contact Sandfly for help.

SSL Setup

This install script will automatically generate self-signed SSL keys for use by the scanning nodes and server. It is also possible to make a signed key after setup completes.

When generating keys we also generate Diffie Hellman parameters. This can take a while depending on the system and other factors. As long as the screen is moving, then it is generating the keys fine.

 ...

*****************************************************************************
*** Creating SSL Keys for Server
*****************************************************************************

*** Using hostname from environment: 198.51.100.100
*** Server SSL key creation completed.

Optional: Generate a Signed SSL Certificate

At the end of the install script you will be asked to generate signed SSL certificates. This is recommended, but if Sandfly is running on internal systems it may not be possible to use the built-in script to do this and this step can be skipped.

If the system has access to the Internet and can be reached on port 80, use the built-in script to make signed certs. A signed certificate can be generated for the server using the Let's Encrypt service from the EFF. Having this will stop the SSL errors when connecting to the UI with a modern browser.

❗️
IMPORTANT: Port 80 Must Be Visible from the Internet During Signing!
Make sure the server has a legitimate hostname that is reachable from the Internet and resolves correctly. Port 80 will need to be open for the EFF server to validate the host.
Yes, the server needs to be reachable by the EFF certificate generation process on the HTTP port (80).
This port can be blocked after receiving the certificate from Let’s Encrypt, however, the port must be open during the generation process.

Make sure that the hostname is legitimate and port 80 can be reached from the Internet. The Let's Encrypt service will not sign any certificate for servers that are not reachable on the Internet.

 ...

******************************************************************************
Make Signed SSL Key with Let's Encrypt?

If the Sandfly server has port 80 open to the Internet, we can generate a
signed certificate with Let's Encrypt. Answer below if you'd like to do this.
******************************************************************************

Generate signed SSL certificate (type YES)?

Indicate whether to use signed SSL keys or not. If so, then answer the certificate questions:

 ...

****************************************************************************
Signed Certificate Install

EFF's Let's Encrypt bot needs your fully qualified hostname to reach this
host. It must be visible online with TCP port 80 access for this to work.
****************************************************************************

What is your fully qualified hostname for the signed SSL cert? example.sandflysecurity.com

Next enter a contact e-mail. We recommend entering a valid e-mail in case there is a security alert about the certificates. Opt in or out of the EFF mailing list as desired.

When starting the server, the scripts look for the signed versions first before trying to use the unsigned versions if present.

If all is well, no warnings will come from the browser about invalid certificates when connecting to the UI.

If using an internal server to host Sandfly, then this method may not be possible. The server certificate would then need to be signed in another way. If you take the responsibility for using a self-signed certificate, accept the warning in the browser and then skip this step.

If you have a way to generate signed keys with your own CA, base64 encode the certificate and key and place them in the fields in the config.server.json file located under setup_data:

server.ssl.server.cert_signed
server.ssl.server.private_key_signed

Setup Complete

When the install script finishes the following output will be displayed.

 ...

******************************************************************************
Server Setup Complete!

Your server setup is complete. Please see below for the path to the admin
password to login. Before you can add hosts and scan with Sandfly, you need
to set up one or more scanning nodes as well.

To start the server, go to /home/steve/dev/sandfly-source/_dist/sandfly-setup/start_scripts
and run the Sandfly start script:

./start_sandfly.sh

*** YOU MUST ALSO START A SCANNING NODE TO USE SANDFLY.
*** See the installation documentation for instructions on setting up the
*** node on a separate server (recommended for production deployments),
*** or start the node on this machine with the ./start_node.sh script
*** in the start_scripts directory.

Your randomly generated password for the admin account is located at:

/root/sandfly-setup/setup/setup_data/admin.password.txt
******************************************************************************

The admin password is a randomly generated diceware🡵 string of words. It can be changed at any time in the UI after logging in.

cat /root/sandfly-setup/setup/setup_data/admin.password.txt

agentless-proof-hardened-heroic-utility-shells-sandfly

Start the Server

It is now time to start the server. Go to the start_scripts directory and run the script start_sandfly.sh.

cd ~/sandfly-setup/start_scripts/
./start_sandfly.sh

*** Starting Postgres.
...

*** Starting Sandfly Server.
...

<server is started>

When starting the server after the installation process, the node config will be present until we copy and delete it as detailed under the node install instructions. In this case this warning will be received when first running the server:

********************************* WARNING *********************************
*                                                                         *
* The node config data file at:                                           *
*     ../setup/setup_data/config.node.json                                *
* is present on the server.                                               *
*                                                                         *
* This file must be deleted from the server to fully protect the SSH keys *
* stored in the database. It should only be on the nodes.                 *
*                                                                         *
********************************* WARNING *********************************

Are you sure you want to start the server with the node config data present?
Type YES if you're sure. [NO]: YES

For now, type YES, and hit enter. After we copy the config under the Node Install instructions we will delete the node config JSON and this warning should not be seen any more.

Standard Security Install Ignore Warning

If running in the Standard Security mode, with the server and node on the same system, the warning about the node config file present can be ignored.

Check Containers are Running

Check if PostgreSQL and the Sandfly server containers are running:

docker ps

CONTAINER ID   IMAGE                           COMMAND                  CREATED          STATUS          PORTS                                                                            NAMES
4b24ab50f1c5   quay.io/sandfly/sandfly:5.6.0   "/opt/sandfly/start_…"   4 seconds ago    Up 3 seconds    0.0.0.0:80->8000/tcp, :::80->8000/tcp, 0.0.0.0:443->8443/tcp, :::443->8443/tcp   sandfly-server
f23041d1b2b4   postgres:14.15                   "docker-entrypoint.s…"   4 seconds ago    Up 3 seconds    5432/tcp                                                                         sandfly-postgres

Next, copy the diceware password generated for the admin user and use it to log into the web interface:

cat ~/sandfly-setup/setup/setup_data/admin.password.txt

agentless-proof-hardened-heroic-utility-shells-sandfly

Browse to the Server

Using a reasonably modern, graphical web browser, go to the hostname of the Sandfly server, for example:

https://example.sandflysecurity.com/

If the certificate was not signed with a valid certificate authority, a warning will likely be received. This warning can be ignored while testing, however, for use in production we recommend using a signed certificate.

At the login screen enter the username admin and the diceware password that was generated during this process. A successful authentication will open the user interface for administering Sandfly.

The server is now ready. Next we will load the node and connect it all together.