massdns

node-massdns

MassDNS wrapper for node.js

• node-massdns
  • What is MassDNS
  • Requirements
  • Installation
  • Usage
    • Result example
      • massdns
      • lookup('www.gihub.com', massdnsResults)
    • returnAsKeyValueObject option
  • API
    • massdns(hostnames, [options])
      • hostnames: array of hostname string
      • options: optional object
  • Known issues
  • Changelog
  • See also

What is MassDNS

Quoted from MassDNS github:

MassDNS is a simple high-performance DNS stub resolver targeting those who seek to resolve a massive amount of domain names in the order of millions or even billions. Without special configuration, MassDNS is capable of resolving over 350,000 names per second using publicly available resolvers.

Requirements

• node.js >= v16.x
• massdns binary Tested using up-to-date master branch and latest release (massdns v1.0.0)
• File containing list of resolvers to use. You can use file generated by get-resolvers.py script from MassDNS.

Installation

npm i massdns

Usage

const { massdns, lookup } = require('massdns');

(async () => {
  const massdnsResults = await massdns(
    [
      'example.org',
      'www.github.com'
    ],
    {
      resolvers: [
        '8.8.8.8',
        '8.8.4.4',
        '1.1.1.1'
      ]
    }
  );

  lookup('example.org', massdnsResults);
  lookup('www.github.com', massdnsResults);
})();

Result example

massdns

[
  {
    "name": "example.org.",
    "type": "A",
    "class": "IN",
    "status": "NOERROR",
    "rx_ts": 1703233801103924700,
    "data": {
      "answers": [
        {
          "ttl": 1633,
          "type": "A",
          "class": "IN",
          "name": "example.org.",
          "data": "93.184.216.34"
        }
      ]
    },
    "flags": [
      "rd",
      "ra"
    ],
    "resolver": "8.8.4.4:53",
    "proto": "UDP"
  },
  {
    "name": "www.example.org.",
    "type": "A",
    "class": "IN",
    "status": "NOERROR",
    "rx_ts": 1703233801108079900,
    "data": {
      "answers": [
        {
          "ttl": 15373,
          "type": "A",
          "class": "IN",
          "name": "www.example.org.",
          "data": "93.184.216.34"
        }
      ]
    },
    "flags": [
      "rd",
      "ra"
    ],
    "resolver": "8.8.4.4:53",
    "proto": "UDP"
  },
  {
    "name": "www.github.com.",
    "type": "A",
    "class": "IN",
    "status": "NOERROR",
    "rx_ts": 1703233801111802600,
    "data": {
      "answers": [
        {
          "ttl": 3487,
          "type": "CNAME",
          "class": "IN",
          "name": "www.github.com.",
          "data": "github.com."
        },
        {
          "ttl": 60,
          "type": "A",
          "class": "IN",
          "name": "github.com.",
          "data": "140.82.112.3"
        }
      ]
    },
    "flags": [
      "rd",
      "ra"
    ],
    "resolver": "8.8.4.4:53",
    "proto": "UDP"
  },
  {
    "name": "asd.am21l32ml2.com.",
    "type": "A",
    "class": "IN",
    "status": "NXDOMAIN",
    "rx_ts": 1703233801120768500,
    "data": {
      "authorities": [
        {
          "ttl": 900,
          "type": "SOA",
          "class": "IN",
          "name": "com.",
          "data": "a.gtld-servers.net. nstld.verisign-grs.com. 1703233784 1800 900 604800 86400"
        }
      ]
    },
    "flags": [
      "rd",
      "ra"
    ],
    "resolver": "8.8.4.4:53",
    "proto": "UDP"
  }
]

lookup('www.gihub.com', massdnsResults)

[
  {
    "ttl": 3487,
    "type": "CNAME",
    "class": "IN",
    "name": "www.github.com.",
    "data": "github.com."
  },
  {
    "ttl": 60,
    "type": "A",
    "class": "IN",
    "name": "github.com.",
    "data": "140.82.112.3"
  }
]

returnAsKeyValueObject option

Looking up item on big array is inefficient. For processing big result, consider to use "returnAsKeyValueObject" option. Return value will be a key-value object so you can lookup easily without "lookup" method in more efficient.

const { massdns, lookup } = require('massdns');

(async () => {
  const massdnsResults = await massdns(
    [
      'example.org',
      'www.github.com'
    ],
    {
      resolvers: [
        '8.8.8.8',
        '8.8.4.4',
        '1.1.1.1'
      ],
      returnAsKeyValueObject: true
    }
  );
})();

Will return:

{
  "example.org.": {
    "name": "example.org.",
    "type": "A",
    "class": "IN",
    "status": "NOERROR",
    "rx_ts": 1703233801103924700,
    "data": {
      "answers": [
        {
          "ttl": 1633,
          "type": "A",
          "class": "IN",
          "name": "example.org.",
          "data": "93.184.216.34"
        }
      ]
    },
    "flags": [
      "rd",
      "ra"
    ],
    "resolver": "8.8.4.4:53",
    "proto": "UDP"
  },
  "www.github.com": {
    "name": "www.github.com.",
    "type": "A",
    "class": "IN",
    "status": "NOERROR",
    "rx_ts": 1703233801111802600,
    "data": {
      "answers": [
        {
          "ttl": 3487,
          "type": "CNAME",
          "class": "IN",
          "name": "www.github.com.",
          "data": "github.com."
        },
        {
          "ttl": 60,
          "type": "A",
          "class": "IN",
          "name": "github.com.",
          "data": "140.82.112.3"
        }
      ]
    },
    "flags": [
      "rd",
      "ra"
    ],
    "resolver": "8.8.4.4:53",
    "proto": "UDP"
  }
}

API

massdns(hostnames, [options])

/**
 * Call massdns
 *
 * @param {string[]} hostnames
 * @param {MassDNSOptions} [options] - at lease specify resolvers or resolverFile
 * @returns {Promise<MassDnsResultItem[]|object>}
 */
async (hostnames, options);

hostnames: array of hostname string

options: optional object

/**
 * @typedef MassDNSOptions
 * @type {object}
 *
 * @property {string} [bin] - massdns binary file to use, will use "massdns" from $PATH if not specified
 * @property {string[]} [resolvers] - resolvers to use, ignored if resolverFile option specifed
 * @property {string} [resolverFile] - file containing resolvers, will override resolvers option
 * @property {string} [tempDir] - temp dir, will use temp dir from OS if not specified
 * @property {boolean} [preserveTempDir] - do not delete temp dir at end, default to true if tempDir specified and false if tempDir not specified
 * @property {string} [logFile] - massdns log file
 * @property {number} [hashMapSize] - optional number of concurent lookup, will use massdns default if not specified (10000)
 * @property {boolean} [returnAsKeyValueObject] - if it is set to true, will return key-value object instead of array of MassDnsResultItem
 */

Known issues

MassDNS is very fast and has very little memory footprint. But using this wrapper might produce high memory usage (around 400-500 MB for 100k hostnames) because this wrapper wraps the result in ready to use json so you can traverse it just like a standard array of object in javascript. Passing big object on javascript would also have big impact, but I think it's still acceptable on my use.

I have consider to pass result as file (not passing result as array of object values), but I think it just defeat our goal to provide easy to access MassDNS result.

Let me know if you have any consideration or recomendation. Please raise an issue. I will very happy if there is someone has interest and care of this package.

If you want to lookup on big result, use returnAsKeyValueObject option. It will improve lookup speed dramatically.

Changelog

See CHANGELOG.md file.

See also

• node-crtsh: query crt.sh from node.js