dns-suite.js/README.md

dns-suite

Fast, lightweight, and easy-to-extend pure JavaScript (ES5.1) implementation for DNS / mDNS.

Works great in Web Browsers and in node.js!

Detailed error checking makes it great for

• capture
• packing (JSON to DNS/mDNS)
• parsing (DNS/mDNS to JSON)
• linting (finding errors in packets)
• debugging

No external dependencies for node.js or modern browsers. Uses DataView, Uint8Array, Uint16Array, and ArrayBuffer

Similar API to dns.js and native-dns-packet.

{ "header": {
    "id": 5423
  , "qr": 0
  , "opcode": 0
  , "aa": 0
  , "tc": 0
  , "rd": 1
  , "ra": 0
  , "res1": 0
  , "res2": 0
  , "res3": 0
  , "rcode": 0
  }
, "question": [
    { "name": "bowie._sftp-ssh._tcp.local"
    , "type": 1
    , "typeName": "A"
    , "class": 1
    , "className": "IN"
    , "byteLength": 32
    }
  ]
, "answer": []
, "authority": []
, "additional": []
, "edns_options": []
, "byteLength": 44
}

Install

You can use git to install v1.x (and get updates) or just v1.0.x (and only get patches). The API will not break until v2.

# latest of v1.x
npm install 'git+https://git@git.daplie.com:Daplie/dns-suite#v1'

Don't have git? You can bow down to the gods of the centralized, monopolized, concentrated, dictatornet (as we like to call it here at Daplie Labs):

npm install --save dns-suite

Test:

pushd node_modules/dns-suite

npm test

Usage

CLI

You can work directly from node_modules/dns-suite:

pushd node_modules/dns-suite/

Capture mDNS broadcast packets

# example
# node bin/mdns-capture.js <file-prefix>
node bin/mdns-capture.js mdns-test

# in another terminal
dig @224.0.0.251 -p 5353 -t PTR _services._dns-sd._udp.local

Parsing a saved packet

# example
# node bin/dns-parse.js </path/to/packet.dns.bin>
node bin/dns-parse.js samples/a-0.mdns.bin

You can also parse a saved packet from the native-dns-packet directory. these test packets have the binary for each record type and what it's parsed output should be.

Library

• packet = dnsjs.unpack(arrayBuffer)
• packet = dnsjs.unpackRdatas(arrayBuffer, packet)
• packet.answers[0].data = dnsjs.unpackRdatas(arrayBuffer, packet, packet.answers[0])

node.js:

var nodeBuffer = fs.readFileSync('./samples/a-0.mdns.bin');
var arrayBuffer = nodeBuffer.buffer;

var dnsjs = require('dns-suite');
var packet = dnsjs.unpack(arrayBuffer);

console.log(packet);

Browser:

var arrayBuffer = new Uint8Array.from([ /* bytes */ ]).buffer;

var packet = pdns.unpack(arrayBuffer);

console.log(packet);

Contributing and Development

How to add a new parser

Each RR (aka Resource Record or RData) parser is individual. Examples include:

• A (parser/type.a.js)
• AAAA (parser/type.aaaa.js)
• CNAME (parser/type.cname.js)
• TXT (parser/type.txt.js)
• SRV (parser/type.srv.js)

Let's say that To create a parser for a type which we don't currently support, just add the appropriate information to dns.types.js and create a file for the name of the type in the format parser/type.<typename>.js.

For example, if CNAME wasn't already supported and I wanted to add support for it I would follow these steps:

1. Update dns.types.js

  A: 			0x01	//   1
, NS: 		0x02  //   2
, CNAME: 	0x05  //   5    // I would simply add this line
, SOA: 		0x06  //   6

2. Capture a packet to test/fixtures/<domain>.<tld>.<type>.bin

This will construct and send a DNS query and save the first result that comes back.

In some cases (such as CNAME), the typical (or required) way to illicit the desired response is to make a request of a different type.

If that's the case, manually rename the the file afterwards.

Ideally you should have some idea of what the result file should look like and should place that in test/fixtures/<domain>.<tld>.<type>.json

node bin/capture-query.js --name www.google.com --type CNAME

3. Create parser/type.cname.js

Copy parser/type.TEMPLATE.js to the type for which you wish to create support (parser/type.cname.js in this example) and fill in the blanks.

var unpackLabels = exports.DNS_UNPACK_LABELS || require('./dns.unpack-labels.js').DNS_UNPACK_LABELS;
exports.DNS_PARSER_TYPE_CNAME = function (ab, packet, record) {
  // record = { rdstart, rdlength, type, class }
  // example of not parsing and just leaving as binary data
  record.data = new Uint8Array(ab.slice(record.rdstart, record.rdstart + record.rdlength));

  return record;
};

}('undefined' !== typeof window ? window : exports));

4. Document what you've learned in doc/<type>.txt

You may be right or you might be wrong, but you might be right.

In any case, take a minute to document some of the gritty details of what you learned about this record type - tips, tricks, little-known facts, etc.

This may help (or wildly mislead) others if there's a bug in your parser that they need to track down. At the very least someone can follow a few links you followed and your thought process.

5. Check that my changes include these files

├── README.md
├── demo.html         (add the appropriate script tag)
├── doc
|   └── cname.txt
├── dns.classes.js    (not necessarily, but potentially)
├── dns.types.js
├── package.json      (bump the minor version)
├── packer
|   └── type.cname.js
├── parser
|   └── type.cname.js
└── test
    └── fixtures
        ├── www.google.com.cname.bin
        └── www.google.com.cname.js