Server Install - Docker Image
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.
Complete Prerequisites
Ensure that the installation prerequisites (Install Container Tool and Download Setup Archive) are completed before following the steps on this page.
Run Server Install 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 will be used later to start the server and scanning nodes.
Security Requirement — Run Sandfly in an Isolated EnvironmentFor security reasons, we strongly recommend running Sandfly in its own isolated environment, such as a dedicated virtual machine (VM) or bare metal host. Running Sandfly alongside other applications increases the risk of unauthorized access to private Sandfly keys and sensitive data, which could enable attackers to expand their compromise. If you choose to run Sandfly in a shared environment, you must verify that no port conflicts exist and that other applications cannot access Sandfly files and data.
Go to the setup directory.
cd ~/sandfly-setup/setupRun server install script.
./install.shLoading the Docker Images
To start off, the install script will automatically load the containers, downloading them if they are not available in the local archive included with the setup package.
Installing Sandfly server version 5.7.0.
Copyright (c) Sandfly Security Ltd.
Welcome to the Sandfly 5.7.0 server setup.
7bb6e344d8ba2d2e0fc4bab24edbb635012e8ae103b81772e7c1b09a6f497699
** Loading images from local archive:
** ../../docker_images/sandfly-docker-images-5.7.0.tgz
** There will be a slight delay before further output...
Loaded image: postgres:14.21
Loaded image: postgres:18.2
Loaded image: quay.io/sandfly/sandfly:5.7.0
Sandfly Setup Helper
Copyright (c) Sandfly Security Ltd.
Sandfly version: 5.7.0
Unless the install script encounters errors at this stage, it will automatically proceed to the Server Hostname setup.
Server Hostname
Enter the IP address or hostname of the system that is hosting the server and 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 AddressDo 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 Hostname *
****************************************************************************
Please enter the fully qualified domain name (FQDN) or the IP address
of the Sandfly server. It is important that the address supplied is
reachable by your web browser and the scanning nodes.
If you choose to use a Let's Encrypt HTTPS certificate on the Sandfly
server, this is the address that the certificate request will use, so
it must match the internet-accessible FQDN of the server.
Do NOT use localhost (127.0.0.1) as the address; the address must be
one that is reachable from the scanning nodes and from users' web
browsers to access the Sandfly UI.
--> Enter server hostname (e.g. sandfly.example.com): myhost.mycompany.comOr enter an externally reachable IP address if DNS is not available for this host:
...
--> Enter server hostname (e.g. sandfly.example.com): 198.51.100.100TLS (HTTPS Certificate) Mode
This install script will prompt you to select how to generate the TLS certificate for the Sandfly sever. The default option is to automatically generate a self signed certificate.
The second option is to use Let's Encrypt (or another ACME certificate service) to request a signed certificate. To use Let's Encrypt, the Sandfly server must be accessible on the internet on port 443, and the hostname from the previous step must be the internet-facing FQDN of the server.
To provide your own TLS certificates, choose self-signed mode and then place your certificates in the setup_data\server_ssl_cert folder. See Installing a Custom SSL Certificate for more information.
...
****************************************************************************
* TLS (HTTPS Certificate) Mode *
****************************************************************************
The Sandfly server runs an HTTPS web service and needs a TLS server
certificate.
By default, Sandfly will automatically generate a self-signed
certificate.
Alternatively, Sandfly can use Let's Encrypt (or another ACME
certificate service) to request a signed certificate. To use Let's
Encrypt, the Sandfly server must be accessible on the internet on
port 443, and the hostname entered above must be the internet-facing
FQDN of the server.
(If the server has a problem requesting the certificate, it will fall
back on using an auto-generated self-signed certificate so you can
still log in and adjust these settings through the UI later.)
To provide your own certificates, choose self-signed mode and place
your certificates in the correct location before starting the server.
See the documentation for more details.
Select TLS mode:
1) self_signed (default)
2) acme (Let's Encrypt)
Choice [1]: 1Optional: ACME Certificate Service
If you choose option 2 acme (Let's Encrypt) there are some additional details required.
IMPORTANT: Port 443 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 443 will need to be open for the Let's Encrypt server to validate the host.
Ensure that the hostname is publicly resolvable and port 443 can be reached from the internet. The ACME service will not sign any certificate for servers that are not reachable on the internet.
...
Select TLS mode:
1) self_signed (default)
2) acme (Let's Encrypt)
Choice [1]: 2
Let's Encrypt requires an email address. By configuring Sandfly to
use Let's Encrypt to generate a server certificate and providing an
email address, you are indicating acceptance of the current Let's
Encrypt terms of service. For more information, see
https://letsencrypt.org/
--> Enter Let's Encrypt contact email: Enter the Let's Encrypt contact e-mail. We recommend entering a valid e-mail in case there is a security alert about the certificates.
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.
Admin Password
You may set an initial password for the admin user account. Alternatively, to have Sandfly automatically generate the admin password, just press <Enter> at the prompt.
...
****************************************************************************
* Admin Password *
****************************************************************************
Please set an initial password for the "admin" user account.
Passwords must be at least 12 characters long.
To generate a random password, leave blank and press enter.
--> Enter admin password:
--> Confirm admin password:
If you generate a random password, make note of the new password as it will not be displayed again. You must also enter the password to confirm and continue setup.
...
****************************************************************************
* Admin Password *
****************************************************************************
Please set an initial password for the "admin" user account.
Passwords must be at least 12 characters long.
To generate a random password, leave blank and press enter.
--> Enter admin password:
**********************************************************************
*** MAKE NOTE OF YOUR NEW PASSWORD. IT WILL NOT BE DISPLAYED AGAIN ***
magnetize-superbowl-widely-sleep-quizzical-blot-encounter
**********************************************************************
--> Enter generated password to confirm:
Setup Complete
When the install script finishes the following output will be displayed.
...
Configuration files generated:
/home/sandfly/sandfly-setup/setup/setup_data/config.server.env
/home/sandfly/sandfly-setup/setup/setup_data/config.node.env
******************************************************************************
Server Setup Complete!
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/sandfly/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.
******************************************************************************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.env *
* 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]: YESFor now, type YES, and hit enter. After we copy the config under the Node Install instructions we will delete the node config file 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
2e8d54e0ec23 quay.io/sandfly/sandfly:5.7.0 "/opt/sandfly/start_…" 6 seconds ago Up 5 seconds 0.0.0.0:80->8000/tcp, [::]:80->8000/tcp, 0.0.0.0:443->8443/tcp, [::]:443->8443/tcp sandfly-server
4e78425c7719 postgres:18.2 "docker-entrypoint.s…" 21 seconds ago Up 20 seconds 5432/tcp sandfly-postgresBrowse 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 initial password that was set during the install 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.
Updated 6 days ago