/*
* Copyright (c) 2014-2021 by Farsight Security, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
Table of Contents:
* Introduction
* Dependencies needed
* Installing dependencies
* Building and installing
* Getting Started
* Background on ASINFO/CIDR lookups and annotations
Introduction:
This is a pure C99 program that accesses passive DNS database
systems such as:
* the DNSDB API server at Farsight Security
* the CIRCL pDNS server at Computer Incident Response Center
(LU)
An API key is required for operation. The command syntax was
inspired by a python script called dnsdb_query, but significant
departure has occured, largely inspired by a modern understanding
of "time fencing" and a desire for new features such as CSV output
and JSON reprocessing.
NOTE: Prior to version 2.5.3, the default pDNS system supported
was Farsight Security APIv1, and it was called "dnsdb". As of
version 2.5.3, the default system is Farsight Security APIv2 and
system "dnsdb2" is synonymous with "dnsdb". For APIv1, specify
"dnsdb1" using the command line -u option or the DNSDBQ_SYSTEM
variable.
Dependencies needed:
jansson (2.5 or later)
libcurl (7.28 or later)
modern compiler (clang or GCC)
Installing dependencies:
On Debian 8 Linux:
apt-get install libcurl4-openssl-dev
apt-get install libjansson-dev
On CentOS 6 Linux:
# Based on PHP instructions for installing libcurl...
wget http://curl.haxx.se/download/curl-7.28.1.tar.gz
tar xvzf curl-7.28.1.tar.gz
cd curl-7.28.1/
./configure --with-libssh2 --enable-ares=/usr/local/ --enable-ipv6
make
make install
# lib jansson
wget http://www.digip.org/jansson/releases/jansson-2.5.tar.gz
tar -xpzf jansson-2.5.tar.gz
cd jansson-2.5
./configure
make
make install
echo /usr/local/lib >> /etc/ld.so.conf.d/local.conf
ldconfig
On CentOS 7 Linux:
yum install libcurl-devel.x86_64
yum install jansson-devel.x86_64
yum install centos-release-scl
yum install devtoolset-8
scl enable devtoolset-8 bash
# do the build from that bash
On CentOS 8 Linux:
dnf install gcc
dnf install jansson.x86_64 jansson-devel.x86_64
dnf install libcurl-devel.x86_64
On FreeBSD 10:
pkg install curl jansson
On macOS:
brew install jansson
Building and installing:
(Assumes you have "git")
git clone https://github.com/dnsdb/dnsdbq.git
cd dnsdbq
make install clean
On FreeBSD, you may need to remove -lresolv in the LIBS line of
the Makefile.
On macOS on Apple M1 processors, Homebrew now defaults to be
installed in /opt/homebrew instead of /usr/local. If that is the
case on your system, in the Makefile, uncomment the line
#JANSBASE=/opt/homebrew
On macOS, if you want an almost static dnsdbq binary on macOS,
that is, one with minimal non-System library dependencies, you can
rebuild dnsdbq with a static jansson library. That binary could
then be deployed on any identical macOS version and architecture.
1. Find the static jansson library, probably as installed by brew
/usr/local/lib/libjansson.a or /opt/homebrew/lib/libjansson.a
2. Change the Makefile's line
JANSLIBS = -L$(JANSBASE)/lib -ljansson
to instead specify the static library location, probably to:
JANSLIBS = $(JANSBASE)/lib/libjansson.a
3. Then run make
Getting Started:
Add the API key to ~/.dnsdb-query.conf in the below given format,
APIKEY="YOURAPIKEYHERE"
If you're interested in purchasing a Farsight DNSDB subscription,
please contact sales@farsightsecurity.com. Farsight also has a
grant program for selected researchers, investigative journalists,
and cybersecurity workers at some public benefit non-profits.
See https://www.farsightsecurity.com/grant-access/
Here's an example query and output after dnsdbq is compiled:
$ ./dnsdbq -r farsightsecurity.com/A -l 1
;; record times: 2013-09-25 15:37:03 .. 2015-04-01 06:17:25 (~1y ~187d)
;; count: 6350; bailiwick: farsightsecurity.com.
farsightsecurity.com. A 66.160.140.81
Background on ASINFO/CIDR lookups and annotations:
Annotating IP addresses with ASN information can help an analyst
focus their attention on unusual or unexpected ASNs (for example,
perhaps a domestic US corporation's IP address inexplicably ended
up being originated by a foreign consumer ISP).
This code has been tested against three sources of ASN information,
each of which are valid arguments to the -D parameter.
1. asn.routeviews.org (the default value for the -D parameter).
Given an IPv4 in reverse order, this returns a space
separated three-tuple:
"ASN" "CIDR prefix" "prefix length"
For badly formatted addresses, it returns:
"4294967295" "0" "0"
For unknown addresses, it returns no answers.
Examples:
$ dig +short 34.168.254.125.asn.routeviews.org TXT
"23724" "125.254.168.0" "21"
$ dig +short a.b.c.d.asn.routeviews.org TXT
"4294967295" "0" "0"
$ dig +short 0.0.0.128.aspath.routeviews.org TXT
$
2. aspath.routeviews.org
The same as asn.routeviews.org, except it returns a
three-tuple: AS path, CIDR prefix, prefix length.
Examples:
$ dig +short 0.0.0.4.aspath.routeviews.org TXT
"3303 3356" "4.0.0.0" "9"
3. origin.asn.cymru.com
Given an IPv4 in reverse order, this returns a pipe-separated
five-tuple:
ASN | CIDR prefix/prefix length | CC | Registry | Allocated date
Example:
$ dig +short 0.0.0.4.origin.asn.cymru.com TXT
"3356 | 4.0.0.0/9 | US | arin | 1992-12-01"
Function asinfo_from_dns() in asinfo.c has specific code to parse
those formats. asn.routeviews.org and aspath.routeviews.org do
not currently handle IPv6 addresses properly, so dnsdbq does not
support IPv6 annotation now.
There is a complication that arises when doing those sort of IP to
ASN mappings, however: publicly available IP to ASN zones are
based on currently observed IP to ASN mappings, while the IPs that
are being mapped may have been seen in passive DNS months or even
years earlier, when that IP may have been originated by a
different ASN.
Often the IP to ASN mappings are quite static, in which case
historical IPs will map just fine using the current IP to ASN
data. On the other hand, some IPs may have been hijacked and used
without authorization, or transferred, or otherwise ended up going
from one ASN to another.
Therefore the IP to ASN mapping should be viewed as an
experimental best effort feature, and interpreted with care.
In addition to the issue of potential ASN misalignment, the size
and origin of the reported origin IP and prefix length may also
have changed over time. For example, a /19 may have been
de-aggregated into a set of more specific /24's. Again, we report
the state of the world as it is currently seen by the service used
for the IP to ASN mapping.
Other miscellaneous notes:
* dnsdbq does not support mapping IPv6 addresses to ASNs at this
time.
* In the case of Multiple Origin ASNs, typically IP to ASN
services will report one of the multiple ASNs; other origin
ASNs may also exist but not be reported.
* We do not map ASNs to their owner or the owner description
string. Please see WHOIS for information about the entity
currently assigned a given ASN.
We welcome feedback on this feature. Do you use it and find it
useful? Are there IP-to-ASN service providers we've inadvertently
omitted? Share your feedback by writing
<support@farsightsecurity.com>.