DNSDB Scout user guide¶
DNSDB Scout is a GUI for the Farsight DNSDB API. Available in all popular web browsers via a website or browser extension, it supports all of the major features of the DNSDB API including:
- A Dashboard for making queries
- An API key status tracker
- Punycode support for converting Internationalized Domain Names (IDN)
- Filters for queries, such as Time Fencing, Record Types, and Bailiwicks
- A locally stored history of recent queries for re-loading and re-running later
- Exporting of results to CSV, JSON, TXT, and PDF formats
- …and much more!
This guide introduces you to Scout and its many features. If you're new to passive DNS, DNSDB Scout's form and function might seem confusing at first, but this guide will help you get started.
DNSDB API keys¶
To use DNSDB Scout you must have a DNSDB API Key.
If you're already a DNSDB customer then your existing API Key works. If you don't have an API Key yet then please contact the DomainTools sales team.
Google Chrome extensions and Mozilla Firefox add-ons¶
If you plan on using DNSDB Scout as a browser extension in either Google Chrome or Mozilla Firefox then the rest of this guide assumes that it's already installed. If you haven't installed it, please visit the store page for your web browser and install it.
- Google Chrome - Select Add to Chrome to install the extension
- Mozilla Firefox - Select Add to Firefox to install the extension
After the extension has been added to your browser, click the orange Scout icon in the top-right corner to bring up the Scout Popup menu. This is the primary way to open the Scout extension to check on your API key status and to navigate to the Dashboard and Options pages.
Website version¶
Access DNSDB Scout by visiting https://scout.dnsdb.info/ in any popular web browser, including on smaller devices like phones and tablets. You might prefer or require this access method depending on your device owner's restrictions, device platform restrictions, or web browser compatibility. Some platforms, such as iOS, do not allow web browser extensions, and other web browsers might not have a DNSDB Scout extension release available yet.
Setting an API key in DNSDB Scout¶
Upon loading up DNSDB Scout for the first time you encounter a message stating that your API Key hasn't been set yet. DNSDB Scout doesn't ship with a default API Key so you need to set your own. To do this, visit the Options page by clicking the purple 'gear' icon near wherever you saw the warning message.
Most users visit the Options page only once to set and save their API keys. Enter yours into the field and click the Save API Key button.
When you click the save button, DNSDB Scout queries the default DNSDB server for your API Key status to verify its validity. API Key status checks do not count against your DNSDB query quota and are free of charge.
If your API Key is valid, a confirmation message appears and the API Status area at the top of the screen updates to resemble one of the following, depending on how your API Key was provisioned. The status indicates how many DNSDB queries you have left and time until your API Key expires (if applicable):
| DNSDB Community Edition |  |
|---|---|
| DNSDB Trial and Standard Editions |  |
If your API Key isn't valid, the API status area reverts to the message stating your API Key is expired or hasn't been set yet. In this case, ensure you've copy-pasted the correct API Key and try saving it again. If you continue to have trouble setting your API Key, contact our Technical Support team at EnterpriseSupport@domaintools.com.
You can now make DNSDB queries on the Dashboard page. Click the DNSDB Scout logo, the link that appeared when you entered your API Key, or the purple search button to go to the Dashboard:
Understanding pivots¶
A pivot is a sequential step between two sets of data, linked by some common factor or shared data element. Exploring DNSDB usually takes the form of following pivots to discover relationships between domains, IP addresses, and DNS infrastructure.
Understanding pivots is critical to utilizing DNSDB to its fullest potential. We've created a comprehensive tutorial guide that walks through the most common DNSDB pivots:
DNSDB Scout pivot tutorials - Learn the 9 most common investigative techniques including:
- Finding IP resolution history for domains
- Discovering domains hosted on an IP address
- Exploring entire netblocks
- Mapping unknown subdomains
- Finding domains using shared infrastructure (name servers, mail servers, CNAMEs)
- Searching across multiple TLDs
- Working with internationalized domain names
Feature explanation: recent queries¶
DNSDB Scout stores your DNSDB queries locally, via your web browser's cache. This is convenient for re-running and loading previous queries, but this may also be something you'll want to explicitly clear if you're conducting a sensitive investigation on a shared system.
Some web browsers automatically prune your Recent Query cache; if not, DNSDB Scout self-prunes whenever 2GB of queries have been stored or 75 queries have been made (the specific details of the pruning process depend on which web browser you're using).
To review queries you've previously made, click the "Recent Queries" tab in the Dashboard.
In the Recent Queries tab is a table that shows all of your previous queries.
Each query has a few functions:
- The Re-Run button performs the query again, from scratch, to fetch new results. This is useful if a domain is rapidly updating
- The View button loads the query from cache and displays it in the Dashboard. This is useful if you want to re-export a query into a CSV or JSON file later on
- Clicking the Request of a query expands the query to its raw form, revealing the raw API URL, HTTP Status code, and other information about the query when it was performed. This is useful for documenting or debugging a query that you've run
At the top-right of the Recent Queries tab is a button to clear the Recent Queries completely. If your Recent Queries are taking a while to load, you may want to clear them manually.
Feature explanation: time fencing¶
Time Fencing improves the signal to noise ratio of results by filtering results to specific time ranges that are more relevant to an investigation or event.
Control Time Fencing with a set of three query parameters, all of which are optional:
- Seen After: Allows for results where they were observed after a given date. This is the most frequently used Time Fencing option in DNSDB Scout.
- Seen Before: Allows for results where they were observed before a given date.
- Strict Mode: Only allow for observations that fall strictly on the specified side of a Time Fence. If enabled and both Time Fences are used, the observations are strictly between the Time Fences. This is also known as a 'complete' Time Fence.
By itself, the Seen After parameter defines a 'soft' limit for a date range and kicks off a 'Last Seen After' query where observations have a Last Seen date sometime after the date specified. When the Strict Mode is enabled, the Seen After parameter defines a 'hard' limit and kicks off a 'First Seen After' query where observations have a First Seen date sometime after the date specified. These types of queries are exclusive; you can't use both a 'Last Seen After' and 'First Seen After' query at the same time.
Similarly, the Seen Before parameter defines a 'soft' limit for a date range and kicks off a 'First Seen Before' query where observations have a First Seen date sometime before the date specified. When the Strict Mode is enabled, the Seen Before parameter defines a 'hard' limit and kicks off a 'Last Seen Before' query where observations have a Last Seen date sometime before the date specified. These types of queries are exclusive; you can't use both a 'First Seen Before' and 'Last Seen Before' query at the same time.
Using both Seen After and Seen Before parameters together define a left bound and right bound date range for query results, and the Strict Mode defines their strictness. When looking at a timeline, use Seen After as the left bounding parameter and Seen Before as the right bounding parameter. Results that appear in-between satisfy either the Seen After parameter, the Seen Before parameter, or both simultaneously.
In DNSDB Scout the Time Fencing parameters have their own section. Click the [+] Time Fencing header to expand the section. Once expanded, the fields for entering the Seen After and Seen Before parameters appear. Click the header again to hide the section.
DNSDB and DNSDB Scout operate using Coordinated Universal Time (UTC); when selecting a Time Fencing date, it is in UTC.
Click a Time Fencing field to open a date picker. In order, select the Year, Month, Day, Hour, and Minute for the date you want. DNSDB Scout also supports Unix timestamp conversion. Typing or pasting in a Unix timestamp automatically converts it to a human-readable date. For example, copy-pasting 1577959872 into a field results in January 2, 2020 10:11 AM.
The Clear button in the Time Fencing section only applies to the Time Fencing fields. Use this to quickly clear Time Fencing parameters between queries as needed.
For a more in-depth exploration into DNSDB Time Fencing we recommend:
Feature explanation: exporting to CSV, JSON, and PDF/Print¶
After running a successful query or loading a query from the Recent Query tab, a table of results appears on the main Dashboard. Just above the results is an Export dropdown. The CSV option exports the current table to a CSV file while the JSON option exports the current table to a JSON file. The JSONL option is a variation of JSON format where each result is on a newline. The TXT option exports the results in a text format resembling dig command output. The PDF/Print option takes you to a new tab to help optimize the table results for paper-like formats. If you have filtered your results using the fields just above the table, the Export Filtered options are enabled. Your browser handles the file exporting process and stores it in your default downloads directory.
Use these export options to transfer your query results to another tool and format.
Feature explanation: Copy-Cell-to-Clipboard behavior¶
DNSDB Scout provides a single-click copy feature for individual cells in the Results Table. Click any RRName, Bailiwick, or RData cell to copy its contents to your clipboard.
Default behavior¶
By default, copied data includes:
- Bracket defanging: Domain names and IP addresses are defanged using bracket notation (e.g.,
example[.]com,192.168[.]1[.]1) - Root dot removal: The trailing dot is removed from FQDNs where applicable
The RRType column copies without extra formatting.
Rationale¶
This default behavior addresses common workflow issues:
- Copying domain names and IP addresses with quotes into tools like Excel and Iris Investigate was cumbersome
- Users spent time manually removing quotes, making them counter-productive as a defanging mechanism
- Bracket defanging provides a safety mechanism while promoting interoperability with Iris Investigate, which can parse defanged inputs and doesn't expect root dots
Customizing copy behavior¶
Configure your Copy-Cell-to-Clipboard preferences in the Options page settings. Choose from:
- Bracket defanged with root dot removed (default)
- Original format with quotes
- No extra formatting
Note: This setting only affects single-click cell copying. Double-click row copying and exported files use different formatting rules.
Feature explanation: Exported FQDN behavior¶
Control how FQDNs appear in exported files through the Options page settings.
Root dot removal option¶
By default, exported RRName, Bailiwick, and RData values match the API response exactly, including trailing root dots. Enable the root dot removal option to automatically remove trailing dots from FQDNs in all exported file types (CSV, JSON, JSONL, TXT).
Rationale and limitations¶
This option addresses a common workflow issue where users manually removed root dots because other tools don't expect them.
Design decisions:
- No defanging in exports: Exported files remain faithful to the API response. Defanging would change the meaning of RData in ways inconsistent with the API and how users visually parse FQDNs
- Replicability: Exported files should maintain consistency with the API, especially in law-enforcement environments where replicability is critical
Limitations:
- Deep removal not available: Root dot removal doesn't apply to FQDNs embedded within other data (e.g., SPF/TXT records) to avoid false positives
- Reversed RRNames: Root dot removal doesn't apply to reversed RRNames for the same reason
- Regex Highlighting impact: If your query specified a root dot with
\.$or equivalent regex, highlighting may fail in PDF exports. The original regex won't match the transformed values (similar to how regex highlighting doesn't work with punycode domains converted to Unicode)
Feature explanation: Iris Investigate pivot¶
DNSDB Scout provides direct integration with Iris Investigate for domain analysis.
Using the Iris Investigate pivot¶
When viewing domain results, hover over any domain to reveal the pivot tooltip. Select Iris Investigate Inspect to open a new browser tab with the Iris Investigate Inspect modal window.
This integration allows you to:
- View additional information about the domain
- Create a new investigation in Iris Investigate
- Seamlessly transition from passive DNS research to active investigation
The pivot option appears for all domain-based results in the Results Table.
Feature explanation: CNAME chasing¶
DNSDB Scout includes a CNAME Chasing feature to resolve CNAME chains to a final A or AAAA record. With CNAME Chasing enabled, Scout repeatedly pivots on the latest available CNAME. This helps answer the question "where does this CNAME record actually point?" as quickly as possible.
The CNAME Chasing checkbox is available in Standard Search. The checkbox can be accessed and enabled/disabled when the CNAME RRType is selected:
When a CNAME Chasing query is performed, Scout "chases" the latest CNAME chain and provides a summary report for one of three outcomes:
- Scout finds an A or AAAA record, successfully ending the chase
- Scout can't find a CNAME, A, or AAAA record to follow, indicating an incomplete chase
- Scout reaches its chase limit or API quota limit and cuts the chase short. The typical chase limit is 10; Scout Export installations have a limit of 25
In the Recent Queries tab you can review previous queries that were part of a CNAME chase; these queries have the [CNAME Chase] label.
Examples¶
Using www.nytimes.com, you can see a completed and successful chase that includes five steps:
Successful Query for: RRSET prod.nytimes.map.fastlylb.net ANY(Limit5000)[CNAME Chase]
Found 35 results
CNAME Chase Sequence:
www.nytimes.com → www.prd.map.nytimes.com.
www.prd.map.nytimes.com → www.prd.map.nytimes.xovr.nyt.net.
www.prd.map.nytimes.xovr.nyt.net. → nytimes.map.fastly.net
nytimes.map.fastly.net → prod.nytimes.map.fastlylb.net
prod.nytimes.map.fastlylb.net → 146.75.53.164
Using abc.com, you can see an incomplete and unsuccessful chase because there aren't any CNAMEs to follow from the initial starting point:
Successful Query for: RRSet abc.com CNAME (Limit 5000) [CNAME Chase]
The API server processed the query but there are no results to display.
CNAME Chase Sequence:
abc.com → Chasing incomplete; can't follow CNAME.
No CNAME records were found from initial starting point.
You may want to try using a different RRType.
Summary¶
If you have followed this guide to the end, you should now be familiar with all of DNSDB Scout's major features.
For hands-on practice with DNSDB pivots, see the pivot tutorials.
If you have any feedback or would like to see us break down more complicated DNSDB pivots in the future, contact us with your feedback.
For definitions of DNS and DNSDB terminology, see the glossary.