Over-the-wire 


The project is currently under active development.
Overview
over-the-wire is a Node.js packet manipulation library supporting:
- Packet crafting and parsing
- Capturing network traffic and sending packets in all formats
- Parsing and serializing pcap and pcapng file formats
- Creating custom non-TCP/UDP socket instances
System Requirements
- Libpcap/WinPcap/Npcap library installed (if Wireshark is installed on your system, you are good to go)
- Node.js 18 or higher. The package is an ES module: use
import.require('over-the-wire')works on Node.js versions that can load ES modules throughrequire(20.19+, 22.12+) and returns the module namespace, so the callable isrequire('over-the-wire').default. - C++ compiler, if there are no prebuilt bindings for your system
Installation
npm install over-the-wire --save
Recipes
Familiar tools rewritten as short scripts, and a few everyday tasks. They live in recipes/ and are the first chapter of the documentation:
pingtraceroutedigarpingtcpdumpnmap -sS- Did my handshake get an answer?
- Send a packet and wait for the reply
- Capture traffic into a pcapng file
- Read a capture file
- Craft a packet byte for byte
Getting started
This is traceroute, written with the Node.js standard library and over-the-wire. Each probe is described from the IP layer up; the interface, the source addresses and the gateway's link-layer address are filled in the way the host would send it. The script waits for each answer with a timeout and saves the whole exchange to a pcapng file.
import fs from 'node:fs';
import dns from 'node:dns/promises';
import otw, { icmp } from 'over-the-wire';
const MAX_HOPS = 30;
const ANSWER_TIMEOUT_MS = 1000;
const traceroute = async (host) => {
const { address: target } = await dns.lookup(host, { family: 4 });
const wire = otw();
const capture = await wire.capture(wire.filter().icmp());
const dump = otw.pcap.createWriteStream({ format: 'pcapng' });
dump.pipe(fs.createWriteStream('traceroute.pcapng'));
capture.pipe(dump);
const id = Math.floor(Math.random() * 0xffff);
console.log(`traceroute to ${host} (${target}), ${MAX_HOPS} hops max`);
for (let timeToLive = 1; timeToLive <= MAX_HOPS; timeToLive++) {
const probe = await wire.packet()
.ipv4({ dst: target, timeToLive })
.icmp({ type: icmp.ECHO_REQUEST, id, sequence: timeToLive });
const addressedToUs = wire.filter()
.ipv4({ dst: probe.layers.IPv4.src })
.icmp({ type: [icmp.ECHO_REPLY, icmp.TIME_EXCEEDED] });
const sentAt = Date.now();
capture.write(probe);
const answer = await capture.expect(addressedToUs, { timeout: ANSWER_TIMEOUT_MS });
if (answer === null) {
console.log(`${timeToLive} *`);
continue;
}
console.log(`${timeToLive} ${answer.layers.IPv4.src} ${Date.now() - sentAt} ms`);
if (answer.layers.ICMP.type === icmp.ECHO_REPLY) {
break;
}
}
capture.destroy();
dump.end();
};
traceroute(process.argv[2] ?? '8.8.8.8').catch((err) => {
console.error(err);
process.exitCode = 1;
});
Capturing needs the same privileges as tcpdump, so run it with sudo unless your user can already open capture devices.
Building packets the way the host would send them
otw() returns a context that knows the routing table, the neighbour table and the local interfaces. A packet described through it can be awaited: the interface, the source addresses and the next hop's link-layer address are filled in the way the network stack would, and the Ethernet layer is added when it's left out.
import otw, { icmp } from 'over-the-wire';
const wire = otw();
const pkt = await wire.packet()
.ipv4({ dst: '8.8.8.8' })
.icmp({ type: icmp.ECHO_REQUEST, id: 1, sequence: 1 });
console.log(pkt.iface.name, pkt.layers.Ethernet.dst, pkt.layers.IPv4.src);
- Anything set explicitly is kept as written.
- Without
await, nothing is looked up:.build()and.buffergive the packet exactly as described, and writing the un-awaited builder to a device sends that. otw({ iface: 'en0' })binds the context to one interface. Lookups are cached per context for a few seconds,wire.flush()drops them.- The link layer follows the interface: Ethernet where there is one, the loopback header on tunnels and loopback interfaces, none where the interface carries bare IP.
- An unknown next hop is resolved by the host: one empty-handed datagram is sent to it so the kernel performs ARP or neighbour discovery, and the answer is read back from the neighbour table.
- When something can't be resolved the promise rejects with a
code:ENOROUTE,ENONEIGHBOUR(the next hop did not answer) orENOADDRESS. otw.registerLayer(MyLayer)adds a protocol to the builders.
Filters, capturing and waiting for an answer
wire.filter() describes packets with the same layer and field names as the packet builder. A filter compiles to a capture filter expression where one exists, and matches parsed packets in process either way.
const handshake = wire.filter()
.ipv4({ host: '203.0.113.10' })
.udp({ port: 51820 });
handshake.toString();
// 'ip and ip host 203.0.113.10 and udp and udp port 51820'
handshake.matches(packet);
- Values can be a single value, a list of alternatives, a comparison (
{ lt: 5 },gt,lte,gte,ne) or a function. hostandportmatch either direction. TCP flags are matched by name:.tcp({ flags: { syn: 1, ack: 0 } })..or(other)and.not(other)take a filter or a function describing one;.raw('...')embeds a capture filter expression.- Fields with no capture filter equivalent still match in process;
filter.expressibletells which kind a filter is.
Devices and socket streams can wait for a packet. expect resolves with the next packet matching a filter, or null when the timeout passes. Packets that arrive between two calls are kept, so nothing is missed in between.
const capture = await wire.capture(handshake);
const outgoing = await capture.expect(wire.filter().ipv4({ dst: '203.0.113.10' }), { timeout: 30000 });
const incoming = await capture.expect(wire.filter().ipv4({ src: '203.0.113.10' }), { timeout: 5000 });
console.log(incoming === null ? 'no reply' : 'answered');
wire.send(packet) resolves the packet if it is still a description, writes it to the interface it routes through, and can wait for the answer:
const reply = await wire
.send(wire.packet().ipv4({ dst: '203.0.113.10' }).udp({ src: 40000, dst: 51820 }).payload({ data }))
.expect(wire.filter().udp({ src: 51820 }), { timeout: 2000 });
wire.close() closes the devices opened by send.
Protocol constants
Every protocol has a lowercase namespace with the numbers its fields take, so a script never has to declare them:
import otw, { icmp, dns, tcp, ethernet, arp } from 'over-the-wire';
wire.packet().ipv4({ dst }).icmp({ type: icmp.ECHO_REQUEST });
wire.filter().icmp({ type: [icmp.ECHO_REPLY, icmp.TIME_EXCEEDED] });
wire.packet().ipv4({ dst }).udp({ src: 40000, dst: dns.PORT }).dns({ questions: [{ name, type: dns.TYPE_A }] });
wire.packet().ethernet({ dst: ethernet.BROADCAST }).arp({ opcode: arp.WHO_HAS, protocolDst: dst });
otw docs lists the protocols, otw docs icmp prints the fields and constants of one.
Both come from the layer itself: the comments in its struct describe the protocol and its fields, and one attach.docs(Layer, { constants }) call lists the constants. A layer added with otw.registerLayer(MyLayer) gets its namespace in otw.protocols and its otw docs page the same way.
The otw command
The package installs a command called otw. Without a global install it runs as npx over-the-wire.
otw [options] start the interactive shell
otw [options] <file> [args...] run a script
otw docs [protocol] describe a protocol: fields, constants, filter support
-i, --iface <name> interface to use, otherwise chosen by the routing table
In the shell and in a script run through otw, wire and the protocol namespaces are global, and import ... from 'over-the-wire' resolves to the installed package, so the recipes run unchanged with otw ping.js 8.8.8.8.
The shell awaits what you type: a packet description is resolved and printed, a send is delivered.
otw> wire.p.ipv4({ dst: '8.8.8.8' }).icmp()
<Packet en0 | 50 bytes | Ethernet 5c:e9:1e:9d:fc:40 > 84:aa:9c:af:3f:71 / IPv4 192.168.1.36 > 8.8.8.8 / ICMP>
otw> wire.s(_).ex(wire.f.icmp({ type: icmp.ECHO_REPLY }))
<Packet en0 | 50 bytes | Ethernet 84:aa:9c:af:3f:71 > 5c:e9:1e:9d:fc:40 / IPv4 8.8.8.8 > 192.168.1.36 / ICMP>
otw> .docs icmp
Short names for typing: wire.p is wire.packet(), wire.f is wire.filter(), wire.c() is wire.capture(), wire.s() is wire.send(), and .ex() on a send is .expect().
Documentation
Questions or Suggestions
Feel free to open any issue in the Issues section of this repository. Currently, there are no restrictions on the format.