DNSDB Scout Export Installation for Debian Buster
Introduction
DNSDB Scout is a Graphical User Interface (GUI) for the DNSDB API that runs in a web browser. DNSDB Scout implements all of the features exposed by the DNSDB API and provides a dashboard-like experience that will be recognizable to most users. DNSDB Scout Export is a version of Scout intended for installation and use locally by DNSDB Export customers.
This installation guide is a supplement to the README file provided with a DNSDB Scout Export tarball (“package”). It will help you configure a DNSDB Scout deployment for use with an existing DNSDB Export instance; it will help you make requests to your private DNSDB API. It will provide step-by-step instructions for configuring a customized installation and webserver to make the tool accessible to a network on a Debian 10 (Buster) system.
DNSDB Scout Export is implemented as a self-hosted website served by an NGINX webserver. The package contains the necessary HTML, minified Javascript and CSS files, and a shell script that can customize Export-specific variables in the Javascript. A deployed DNSDB Scout will issue DNSDB API queries to the DNSDB API server you will configure below in the “Customizations” section.
Audience
This document is intended for system administrators responsible for the administration of a DNSDB Scout installation for use with a DNSDB Export instance. Unless otherwise specified, all commands are run as root
. Please contact us if you have any issues installing and configuring DNSDB Scout.
Preparation for installing DNSDB Scout
You will need to aquire the DNSDB Scout Export package provided directly by Farsight. DNSDB Scout Export is not publicly published, and is proprietary software. Use of DNSDB Scout is governed by the License Agreement between you, your organization, and Farsight.
Server configuration and setup
These instructions have been written for use on Debian 10 (Buster). The specific
installation package used for our testing was: debian-10.7.0-amd64-DVD-1.iso
.
The file name includes the version number of the release, which is 10.7.0.
Please make sure you’re using this major version release for this installation.
These instructions assume your server has access to a Debian package repository
and has the ability to download and access packages via apt-get
or dpkg
to load necessary software and updates.
Server accounts
These instructions assume the ownership of web content under the default NGINX
user; www-data
is normally the default and is usually available on Debian
systems. If your server and NGINX configuration is different then supplement
www-data
for your preferred user and group.
Server Security
Farsight requires that you not make your system widely available on the Internet. Please consult with Farsight’s sales and support teams on how to properly configure your access and firewall systems for this server. DNSDB systems are often online but with limited access to their ports (for instance: ssh or https) to localhost or their organization’s networks only, or placed behind firewalls.
A Note About Shells
The bash shell is the default shell and the installation scripts assume its use. If you are using an alternative shell, such as csh or sh, some of the commands might fail, so we recommend installing (if needed) and using bash for the installation.
This installation is written assuming the commands are run as the root
user (via su root
or logging in as root) as designated by the #
prompt.
Choose a hostname
Please carefully consider what hostname you would like to use for accessing your DNSDB Scout deployment. As an example, Farsight has .
It is strongly recommended that you generate an SSL certificate for your host.
You may need to configure DNS or /etc/hosts
on your client systems to point
them at your server depending on whether or not you selectively publish
access to this server outside your network.
Further instructions will use the $HOSTNAME
environment variable as part
of their configuration.
# export HOSTNAME=scout.mydomain.com
Installing NGINX
We’ll use apt-get
to download and install NGINX and its components.
# apt-get install nginx
Configuring NGINX
The NGINX server configuration is stored in /etc/nginx
and starts with
nginx.conf.
There are subdirectories called sites-available
and
sites-enabled
in which server configurations can be added and loaded.
We’ll create a new NGINX configuration for a DNSDB Scout deployment in
/etc/nginx/sites-available/dnsdb_scout.conf
.
# rm /etc/nginx/sites-enabled/default
# cat >/etc/nginx/sites-available/dnsdb_scout.conf << EOF
server {
listen 80;
listen [::]:80;
server_name _;
return 301 https://$HOSTNAME\$request_uri;
}
server {
listen 443 ssl;
listen [::]:443 ssl;
server_name $HOSTNAME;
#NGINX logs use /var/log/nginx by default; can be changed.
access_log /var/log/nginx/access.scout.log;
error_log /var/log/nginx/error.scout.log;
#This can be changed; be sure it reflects later steps.
root /var/www/dnsdb_scout;
index dashboard.html; #The top level page of DNSDB Scout, "Dashboard".
try_files \$uri/index.html \$uri.html \$uri/ \$uri =404;
location ~* \.(html|jpg|jpeg|png|gif|ico|css|js)\$ {
expires 1d;
}
location / {
if (\$request_method = 'OPTIONS') {
add_header Content-Length 0;
add_header Content-Type text/plain;
return 200;
}
}
#Very simple SSL configuration. More modern features
#can be enabled/changed depending on your NGINX version.
ssl_certificate /etc/ssl/certs/nginx-cert.crt;
ssl_certificate_key /etc/ssl/private/nginx-key.key;
ssl_session_cache shared:SSL:1m;
ssl_session_timeout 10m;
ssl_ciphers HIGH:!aNULL:!MD5;
ssl_prefer_server_ciphers on;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
}
EOF
# ln -s /etc/nginx/sites-available/dnsdb_scout.conf /etc/nginx/sites-enabled/dnsdb_scout
Note: If you create the above file without using the cat
command,
the file on disk must not contain the backslashes near the $
‘s. The
backslashes are to keep your shell from substituting $VARIABLE
during the
cat
.
Important: This NGINX configuration uses TLS, you must install a
valid TLS certificate or create a self-signed TLS certificate for NGINX to start
properly. If you need a self-signed cert, use openssl
.
Considering that you are about to start the web server, now is an
excellent time to consider how to modify the system firewall to allow
access to your server. A reminder that Farsight requires that you not
make your system widely available on the Internet. At least disallow
public access and allow access from your own network only. Look at
packages like ferm
or iptables-persistent
for long-term management
of firewall rules. For testing, you’ll be using your localhost access
which permits everything. If you have a client on a nearby network (for
example, 10.10.10.2) that you want to test with, you’ll need to add a
temporary firewall rule.
# iptables -A INPUT -s 10.10.10.0/24 -p tcp --dport 80 -j ACCEPT
# iptables -A INPUT -s 10.10.10.0/24 -p tcp --dport 443 -j ACCEPT
Starting NGINX
Start the nginx
server and see if it works:
# systemctl daemon-reload
# systemctl start nginx
# systemctl status nginx
If nginx
was already started then you should reload the current configuration:
# systemctl reload nginx
If the status of nginx
appears ok then enable it to start upon boot:
# systemctl enable nginx
Installing DNSDB Scout
Typically, the installation of NGINX creates /var/www
, which is a convenient
location for web assets. We will be using it, as noted by the “root” directory
in the NGINX configuration, above.
Extract the contents of the DNSDB Scout package acquired from Farsight.
# tar -xzf dnsdb_scout_export_v2.1.4.tar.gz
At this point you may customize your DNSDB Scout Deployment. Refer to the “Customizing a DNSDB Scout Deployment” section, below, for details.
Copy the extracted (or customized) dnsdb_scout
directory to /var/www
. This
directory should correspond with the NGINX server “root” directory.
# cp -r dnsdb_scout_export_v2.1.4/dnsdb_scout/ /var/www/
Finally, change the user/group of the dnsdb_scout directory to the one used by
NGINX. By default, this is www-data
.
# chown -R www-data:www-data /var/www/dnsdb_scout
Customizing a DNSDB Scout Deployment
Within the DNSDB Scout package provided by Farsight is a customization script. Run the script to add the following customizations to your DNSDB Scout deployment and to overwrite an existing customization file.
# cd dnsdb_scout_export_v2.1.4
# chmod +x customize.sh
# ./customize.sh
Upon running the script you will be prompted for the following customizations, all of which are optional and are visible to anyone with access to the DNSDB Scout deployment:
DNSDB Server: The server for which all users of this DNSDB Scout deployment will use by default. Users may change this client-side in their browsers if they wish. If you operate an Export instance then this is where you’d enter it. HTTPS is assumed, so only enter a hostname. The default (blank) results in: api.dnsdb.info
API Key: The API Key for which all users of this DNSDB Scout deployment will use by default. Users may change this client-side in their browsers if they wish. The default (blank) is recommended, but can be changed if you believe access to this deployment is adequately secured.
Help Link: The resource used for ‘Need Help?’ links. Change this if you would like users to go to a specific resource for requesting assistance. By default, this Farsight link will be used: https://www.farsightsecurity.com/about-farsight-security/contacts/?referrer=Scout
Docs Link: The resource used for API Documentation links. Change this if you would like users to go to a specific resource for learning about the DNSDB API being used. By default, this Farsight link will be used: https://docs.dnsdb.info/?referrer=Scout
Guide Link: The resource used for DNSDB Scout specific user guides and how-to tutorials. Change this if you would like users to learn about DNSDB Scout from a different resource. By default, this Farsight link will be used: https://www.farsightsecurity.com/assets/media/download/dnsdb-scout-introductory-guide.pdf?referrer=Scout
Max Query Limit: The maximum query size that will be allowed from this DNSDB Scout deployment. The default, Fifty Thousand (50000), strikes a balance of usefulness and efficiency with regard to results transmission rate, local browser storage, browser performance, and human digestibility. Raise or lower this number as your DNSDB API server resources allow. The minimum query limit size is Ten (10) and the maximum is One Million (1000000). Enter a whole integer between these values without commas or decimals.
Message of the Day (MOTD): The message that should appear to first-time users of DNSDB Scout. First-time users are users that have not set their own client-side API Key. Enter an HTML or Plaintext message to display to new users, such as an introduction or link to a resource for more information about the access and expectations for this deployment. The default is the following HTML:
Welcome to DNSDB Export and DNSDB Scout!
It looks like this is your first time using DNSDB Scout and you don't have
an API Key set yet.You'll want to set an API Key on the
Settings page before making DNSDB Queries.
This instance of DNSDB Scout may be pre-configured with settings to use a
specific DNSDB Export server - please consult the operator for details.
Running the customization script from an extracted DNSDB Scout Export tarball
directory will save changes to ./dnsdb_scout/export_customizations.json
.
You can use your text editor of choice to modify the customizations file,
however, running the customization script again will overwrite the file
entirely. Please ensure futher modifications to the export_customizations.json
file follow standard JSON formatting and syntax otherwise the customizations
will be ignored.
Testing NGINX and DNSDB Scout
You will need to use the SSL server name you used in the
/etc/nginx/sites-available/dnsdb_scout.conf
file. If you don’t have a public
address for it yet, consider adding your HOSTNAME to the /etc/hosts
file:
# echo 127.0.0.1 $HOSTNAME >>/etc/hosts
You’ll see an NGINX process listening to port 80 and 443 and can access it from
the server itself. Tools like telnet
may be useful for debugging.
# ps awwx | grep nginx
# ss -antp | grep nginx
Let’s try accessing the server via HTTPS using its server name:
# curl -sk https://$HOSTNAME/ | head -7
If successful you should see the top of the DNSDB Scout Dashboard HTML page, like so:
<!DOCTYPE html>
<!--
Description: Farsight DNSDB Scout® Dashboard
Author: Farsight Security, Inc.
Copyright: 2021 Farsight Security. All Rights Reserved.
License: Unlicensed, Proprietary
-->
If not, check systemctl status nginx
and see if there were any typos or other
configuration issues.
If everything to this point is working correctly, you should now be able to open DNSDB Scout in a web browser from a computer with access to this host and perform DNSDB queries against your DNSDB API installation.