Installing the Sandfly Server
Server Installation
The Sandfly server hosts the User Interface (UI), REST API, and optional database. A server instance must always be installed and running for Sandfly to work.
Please follow these instructions exactly and you will be up and going in no time.
Download Setup Scripts
The Sandfly setup scripts are located on Github. Please visit the URL below to obtain the latest version:
https://github.com/sandflysecurity/sandfly-setup/releases
The version format is X.X.X (e.g. 4.0.0)
wget https://github.com/sandflysecurity/sandfly-setup/releases/download/vX.X.X/sandfly-setup-X.X.X.tgz tar -xzvf sandfly-setup-X.X.X.tgz
There should be a directory named sandfly-setup after you decompress the image. This is where all the operations below will take place.
Install Container Tool
Sandfly uses Docker or Podman as everything runs inside a container for security and performance reasons. It is important to use the latest, supported version of Docker or Podman.
If Docker is already installed and up-to-date, proceed to the Start Docker step. This can be checked with the following command:
docker -v
WARNING: CentOS Repositories Are Too Old for Docker Some Linux distributions (such a CentOS) contain old versions of Docker that are not compatible with Sandfly. Please perform the installation via one of the provided scripts to ensure that a supported version of Docker is used.
WARNING: Do Not Install Alternate / Additional Versions of Docker Some Linux distributions (such a Ubuntu via the use of snap and apt) or manual docker installations allow for two versions of docker packages to exist without a warning. This can potentially cause problems when starting Sandfly containers. Please ensure that there is only one supported version of docker installed on the host OS.
For Podman installations, first complete the steps found in the Run Sandfly with Podman documentation, then return to this page and proceed to the Run Server Setup Script section to continue the server installation.
For Docker installations, use one of the scripts below to install the latest version:
CentOS 7 Docker Install
~/sandfly-setup/setup/install_docker_centos7.sh
Ubuntu 18 Docker Install
~/sandfly-setup/setup/install_docker_ubuntu18.sh
Ubuntu 20 and Newer Docker Install
~/sandfly-setup/setup/install_docker_ubuntu20.sh
Debian 9 and Newer Docker Install
~/sandfly-setup/setup/install_docker_debian.sh
Start Docker
Make sure the Docker daemon starts automatically or you can start it manually on Linux with the following command:
service docker start
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.
Go to the setup directory.
cd ~/sandfly-setup/setup
Run server install script.
./install.sh
Prepare the Database and Server Management
Initially the install script will automatically download and configure the database and server management.
Installing Sandfly server version 3.1.0. Copyright (c)2016-2021 Sandfly Security Ltd. Welcome to the Sandfly 3.1.0 server setup. Starting Postgres database. Unable to find image 'postgres:14.0' locally 14.0: Pulling from library/postgres 7d63c13d9b9b: Pull complete ... 79300c1d4f7a: Pull complete Digest: sha256:db927beee892dd02fbe963559f29a7867708747934812a80f83bff406a0d54fd Status: Downloaded newer image for postgres:14.0 f3fbec3e0a79a25f42c3ba42ddf1c4018b60a47a5d103a029a1811d1f74bdf1f ****************************************************************************** Setting Up Server The server install script is now starting. ****************************************************************************** Unable to find image 'quay.io/sandfly/sandfly-server-mgmt:3.1.0' locally 3.1.0: Pulling from sandfly/sandfly-server-mgmt 7b1a6ab2e44d: Pull complete ... f7c7df9b3f0f: Pull complete Digest: sha256:2225b94c351cbfcdee9fc408ee94ec72866fdd6c0baddf5f9c7c91936d15f3fb Status: Downloaded newer image for quay.io/sandfly/sandfly-server-mgmt:3.1.0
Unless the install script encountered 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 you connect to in order to access the UI. Enter the IP address or hostname of the system that is hosting the database.
If your host is not resolvable in DNS, you can enter the external interface IP address. Otherwise, put in your DNS resolvable, fully qualified domain name.
WARNING: Do Not Use Localhost (127.0.0.1) As Your 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 ... Please supply the server API hostname or IP address here (NOT localhost): example.sandflysecurity.com
Or you can put in your externally reachable IP address if DNS is not available for your host:
... Please supply the server API hostname or IP address here (NOT localhost): 198.51.100.100
Add the RabbitMQ Hostname/IP Address
Supply the RabbitMQ hostname where the messaging queue server will be located. Most of the time this will be the same system address as the Server API above. The install will use this as the default if you hit enter.
Again, if your host is not resolvable in DNS, you can enter the external interface IP address. Otherwise, put in your DNS resolvable, fully qualified domain name.
Like the server address, do not use localhost (127.0.0.1), or any other loopback interface, for the RabbitMQ address as it will not work. It must be a valid IP address or hostname.
WARNING: Do Not Use Localhost (127.0.0.1) As Your RabbitMQ 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:
****************************************************************************** Rabbit Setup ... Please supply the rabbit server hostname or IP address here (Enter: example.sandflysecurity.com): <enter>
The script will have scrolled by a lot of data on the database and server management being initialized. If you get an error, please ensure that there are sufficient resources available. If you are still receiving errors, then make a copy of the output of the entire process and contact Sandfly for help.
SSL Setup
This install script will generate self-signed SSL keys for use by the scanning nodes and server. You will have a chance 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.
You will be asked to enter your hostname only during key generation for internal Sandfly keys. Please enter your hostname only for the server and not the FQDN.
If you are installing to an IP address and not an FQDN, then enter the IP address here.
WARNING: ENTER HOSTNAME ONLY! Do not enter the fully qualified domain name (FQDN) here. HOSTNAME ONLY! If you are installing to an IP address and not an FQDN, then enter the IP address here. If you enter the fully qualified domain name for the Common Name you will get SSL errors later.
RabbitMQ will reject the SSL certificate if you use the FQDN here. Just use the hostname or IP address and it will be signed by the Sandfly CA and work as expected.
Example: For example.sandflysecurity.com we do the following:
***************************************************************************** *** Creating SSL Keys for Server ***************************************************************************** Enter server hostname ONLY or IP address if not resolvable: example Or if using externally reachable IP address for servers as setup above: Enter server hostname ONLY or IP address if not resolvable: 198.51.100.100
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 you are running Sandfly on internal systems it may not be possible to use the built-in script to do this and you can skip this step.
If the system has access to the Internet and can be reached on port 80, you can use the built-in script to make signed certs for you. You can generate a signed certificate for the server using the Let's Encrypt service from the EFF. This will stop you from having SSL errors when connecting to the UI with a modern browser.
WARNING: Port 80 Must Be Visible From The Internet During Signing! Make sure the server you are using 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). You can block this port again after you receive your certificate from Let’s Encrypt, but it must be open during the generation process.
***************************************************************************** *** Creating SSL Keys for Server ***************************************************************************** ... Enter server hostname ONLY or IP address if not resolvable: example.sandflysecurity.com
Make sure, again, that the hostname you put in 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? ... Generate signed SSL keys (type YES)?
Indicate whether to use signed SSL keys or not. If so, then answer the certificate questions:
What is your fully qualified hostname for the signed SSL cert? example.sandflysecurity.com
Next you will be asked for a contact e-mail. We recommend you put in a valid e-mail in case there is a security alert about the certificates. You can opt in or out of the EFF mailing list.
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, when you connect to the UI you will not get any warnings from your browser about invalid certificates.
If you are using an internal server to host Sandfly, then you probably cannot use this method. You will have to find another way to get the server certificate signed. If you are fine using a self-signed certificate and just telling your browser to accept it manually, then skip this step.
If you have a way to generate signed keys with your own CA, you will want to 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 you will see the following output.
****************************************************************** Setup Complete! Your setup is complete. Please see below for the path to the admin password to login. You will need to go to /root/sandfly-setup/start_scripts and run the following to start the server: ./start_sandfly.sh Your randomly generated password for the admin account is located under: /root/sandfly-setup/setup/setup_data/admin.password.txt ******************************************************************
The admin password is a randomly generated diceware string of words. You can change it once you login and the generated password will no longer work:
cat ~/sandfly-setup/setup/setup_data/admin.password.txt serrated-heroics-proofing-hardening-utility-shell-frisk
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 RabbitMQ server. ... Waiting for RabbitMQ to configure and start. This will take about 45 seconds. ...... *** Starting Sandfly Server. ... <server is started>
When you start the server after install the node config will be present until we copy and delete it as detailed under the node install instructions. In this case you will receive this warning when you first run the server:
********* WARNING *********** The node config data (../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 you should not see this warning any more.
Standard Security Install Ignore Warning
If you are running the Standard Security mode with the server and node on the same system, you can ignore this warning about the node config file present.
Check Containers are Running
Check if PostgreSQL, RabbitMQ and the server are running:
docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES f6d2ca683b8d quay.io/sandfly/sandfly-server:3.1.0 "/opt/sandfly/start_…" About a minute ago Up About a minute 0.0.0.0:80->8000/tcp, :::80->8000/tcp, 0.0.0.0:443->8443/tcp, :::443->8443/tcp sandfly-server c7afee82ad68 quay.io/sandfly/sandfly-rabbit:3.1.0 "/bin/sh -c /usr/loc…" 2 minutes ago Up 2 minutes 4369/tcp, 5671-5672/tcp, 15691-15692/tcp, 25672/tcp, 0.0.0.0:5673->5673/tcp, :::5673->5673/tcp sandfly-rabbit 599aac326c37 postgres:14.0 "docker-entrypoint.s…" 2 minutes ago Up 2 minutes 5432/tcp
Now copy the diceware password generated for the admin user so we can test logging in:
cat ~/sandfly-setup/setup/setup_data/admin.password.txt <diceware password here>
Access the Server with Your Browser
Go to your new web server address for the Sandfly server, for example:
https://example.sandflysecurity.com
If you did not sign your certificate with a valid certificate authority, you will receive a warning. You can ignore this while testing. However, for operational purposes we recommend that you use 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.
 | Previous Article: | Next Article: |  |