README

/*
 * Copyright (c) 2023-2024 DomainTools LLC
 *               2014-2022 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

Introduction:

    dnsdbflex is a pure C99 program that accesses passive DNS database systems
    such as:
        * the DNSDB Flex API server at Farsight Security

    An API key is required for operation.

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/farsightsec/dnsdbflex.git
    cd dnsdbflex
    make install clean

    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 dnsdbflex binary on macOS,
    that is, one without any non-System library dependencies, you can
    rebuild dnsdbflex 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,
    DNSDB_API_KEY="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/

Optional Filter Scripts:

    There are three optional filter scripts which take dnsdbflex json
    output as input and produce different outputs.  These are not
    installed by default, as they are primarily examples to learn
    about post-processing the dnsdbflex outputs.

    * filter_rdata_json_to_csv.sh

        Takes JSON produced by `dnsdbflex -s rdata` and produces CSV
        output.

    * filter_rrnames_json_to_csv.sh

        Takes JSON produced by `dnsdbflex -s rrnames` and produces CSV
        output.

    * filter_rdata_raw_json_to_batch.sh

        Takes JSON produced by `dnsdbflex -s rdata` and produces dnsdbq
        batch file input data.  This is useful if dnsdbflex was run in -j
        mode, but you decide you want output from -F more.

    The three optional filter scripts require the "jq" command-line processor.
    jq is available in source from https://stedolan.github.io/jq/

    To install jq:

        On Linux (Debian 8 and higher):
            apt-get install jq

        On CentOS 7 Linux:
            yum -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
            yum install jq

        On CentOS 8 Linux:
            dnf install jq

        On macOS:
            brew install jq

        On FreeBSD 10:
            pkg install jq