dns-lint ======== Fast, lightweight, **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) * parsing (DNS to JSON) * linting (finding errors in packets) * debugging **No external dependencies** for modern browsers. Uses `DataView`, `Uint8Array`, `Uint16Array`, and `ArrayBuffer` Similar API to `dns.js` and `native-dns-packet`. ```json { "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 ------- ```bash npm install git+https://git@git.daplie.com:Daplie/dns-lint ``` **Test**: ```bash pushd node_modules/dns-lint npm test ``` Usage ----- **CLI** You can work directly from `node_modules/dns-lint`: ```bash pushd node_modules/dns-lint/ ``` Capture mDNS broadcast packets ```bash # example # node bin/mdns-capture.js node bin/mdns-capture.js mdns-test ``` ```bash # in another terminal dig @224.0.0.251 -p 5353 -t PTR _services._dns-sd._udp.local ``` Parsing a saved packet ```bash # example # node bin/dns-parse.js 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: ```js var nodeBuffer = fs.readFileSync('./samples/a-0.mdns.bin'); var arrayBuffer = nodeBuffer.buffer; var dnsjs = require('dns-lint'); var packet = dnsjs.unpack(arrayBuffer); console.log(packet); ``` Browser: ```js 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..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/...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/...json` ```bash 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/.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 ``` mDNS Documentation ==== This document is currently used and update for testing purposes of DNS packets with Daplie applications. Please make note of any errata, as the organization of this document is based on the step by step process of debugging current issues regarding DNS, and not necessarily a demonstration on how to fix those issues. This document is for learning purposes and meant to assist future developers avoid similar bugs. ## Objective Create a robust DNS library that checks all possible combinations of DNS flags and messages in order to debug current DNS state for Daplie system and potentially develope DNS library with built in linting for use of Daplie, inc and community. ### How to duplicate DNS crash: ``` >> cd ~/dns_test >> node listen.jss ``` Then in another terminal enter: ``` >> dig @224.0.0.251 -p 5353 -t PTR _cloud._tcp.local ``` The listener then crashes with an output of: ``` START DNS PACKET /home/daplie/dns_test/node_modules/dns-js/lib/bufferconsumer.js:52 throw new Error('Buffer overflow') ^ Error: Buffer overflow at BufferConsumer.slice (/home/daplie/dns_test/node_modules/dns-js/lib/bufferconsumer.js:52:13) s at Function.DNSRecord.parse (/home/daplie/dns_test/node_modules/dns-js/lib/dnsrecord.js:237:46) at /home/daplie/dns_test/node_modules/dns-js/lib/dnspacket.js:164:30 at Array.forEach (native) at Function.DNSPacket.parse (/home/daplie/dns_test/node_modules/dns-js/lib/dnspacket.js:159:17) at /home/daplie/dns_test/cloud-respond.js:86:31 at Array.forEach (native) at /home/daplie/dns_test/cloud-respond.js:11:21 at Array.forEach (native) at Object.module.exports.respond (/home/daplie/dns_test/cloud-respond.js:10:11) ``` After commenting out lines 45-53 in dns_test/node_modules/dns-js/lib/bufferconsumer.js and rerunning the previous commands, the result is a new error: ``` START DNS PACKET buffer.js:829 throw new RangeError('Index out of range'); ^ RangeError: Index out of range at checkOffset (buffer.js:829:11) at Buffer.readUInt8 (buffer.js:867:5) at BufferConsumer.byte (/home/daplie/dns_test/node_modules/dns-js/lib/bufferconsumer.js:67:22) at BufferConsumer.name (/home/daplie/dns_test/node_modules/dns-js/lib/bufferconsumer.js:120:14) at Function.DNSRecord.parse (/home/daplie/dns_test/node_modules/dns-js/lib/dnsrecord.js:187:14) at /home/daplie/dns_test/node_modules/dns-js/lib/dnspacket.js:164:30 at Array.forEach (native) at Function.DNSPacket.parse (/home/daplie/dns_test/node_modules/dns-js/lib/dnspacket.js:159:17) at /home/daplie/dns_test/cloud-respond.js:86:31 at Array.forEach (native) ``` which is located in the node.js buffer module. The API is [here](https://nodejs.org/api/buffer.html). However, the error we are working with will most likely be dealt with by parsing through the binary and putting it in a format that is acceptable to a custom buffer, since the current buffer.js does doesn't seem to do the trick. Using ```javascript function pad(str, len, ch) { while (str.length < len) { str = ch + str; } return str; } ``` the binary output comes out as: ``` 11100001 10001000 00000001 00100000 00000000 00000001 00000000 00000000 00000000 00000000 00000000 00000001 00000110 01011111 01100011 01101100 01101111 01110101 01100100 00000100 01011111 01110100 01100011 01110000 00000101 01101100 01101111 01100011 01100001 01101100 00000000 00000000 00001100 00000000 00000001 00000000 00000000 00101001 00010000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 ``` In order to figure out where the dnspacket code is going wrong, We will have to write our own test code to see if the dns code is doing what it's supposed to be doing. Looking at the code below: ```javascript // parses through the flags // val can be 1 or 0 // (val & 0x8000) >> 15 does the following // val = 0000 0000 0000 0001 // & 1001 0000 0000 0000 // _______________________ // 0000 0000 0000 0000 // same if val were 0 // but if val were 0x8000 // then // (val & 0x8000) >> 15 does the following // val = 1001 0000 0000 0001 // & 1001 0000 0000 0000 // _______________________ // 1001 0000 0000 0000 // >>15= 0000 0000 0000 0001 function parseFlags(val, packet) { packet.header.qr = (val & 0x8000) >> 15; packet.header.opcode = (val & 0x7800) >> 11; packet.header.aa = (val & 0x400) >> 10; packet.header.tc = (val & 0x200) >> 9; packet.header.rd = (val & 0x100) >> 8; packet.header.ra = (val & 0x80) >> 7; packet.header.res1 = (val & 0x40) >> 6; packet.header.res2 = (val & 0x20) >> 5; packet.header.res3 = (val & 0x10) >> 4; packet.header.rcode = (val & 0xF); } ``` One effective way to check is to create a dns packet, pass it to a custom packer and parser function and compare the input and output: ```javascript 'use strict'; // order one http://www.binarytides.com/dns-query-code-in-c-with-linux-sockets/ // order two http://www.zytrax.com/books/dns/ch15/ function parse(i) { var header = { // first byte appears to be reverse qr: (i & 0x8000) >> 15 , opcode: (i & 0x7800) >> 11 , aa: (i & 0x400) >> 10 , tc: (i & 0x200) >> 9 , rd: (i & 0x100) >> 8 // second byte appears to be second byte, but also in reverse , ra: (i & 0x80) >> 7 , res1: (i & 0x40) >> 6 // z , res2: (i & 0x20) >> 5 // ad , res3: (i & 0x10) >> 4 // cd , rcode: (i & 0x1F) }; return header; } function pack(header) { var val = 0; val += (header.qr << 15) & 0x8000; val += (header.opcode << 11) & 0x7800; val += (header.aa << 10) & 0x400; val += (header.tc << 9) & 0x200; val += (header.rd << 8) & 0x100; val += (header.ra << 7) & 0x80; val += (header.res1 << 6) & 0x40; val += (header.res2 << 5) & 0x20; val += (header.res3 << 4) & 0x10; val += header.rcode & 0x1F; return val; } var start = { qr: 1 , opcode: 12 , aa: 0 , tc: 0 , rd: 1 , ra: 0 , res1: 0 , res2: 0 , res3: 0 , rcode: 0 }; var i = pack(start); var obj = parse(i); console.log(i); console.log(start); console.log(obj); // does a recursive check to see if start and obj are equal require('assert').deepEqual(start, obj); ``` How to print out hex values of the DNS message in node.js? ```javascript socket.on('message', function (message, rinfo) { console.log('Received %d bytes from %s:%d\n', message.length, rinfo.address, rinfo.port); //console.log(msg.toString('utf8')); console.log(message.toString('hex')); ``` DNS sec: security puts a signature on a DNS packet and imprints a signature so that the sender of the packet is confirmed