User Guides

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 &lt;&lt; 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, &quot;Dashboard&quot;.

    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 = &#039;OPTIONS&#039;) {
        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.