Description
A cross-platform binding for performing packet capturing with node.js.
Requirements
-
node.js -- v0.10.0 or newer
-
For Windows: WinPcap
-
For *nix: libpcap and libpcap-dev/libpcap-devel packages
Install
npm install cap
Examples
- Capture and decode all outgoing TCP data packets destined for port 80 on the interface for 192.168.0.10:
var Cap = Cap decoders = decoders PROTOCOL = decodersPROTOCOL; var c = device = Cap filter = 'tcp and dst port 80' bufSize = 10 * 1024 * 1024 buffer = 65535; var linkType = c; csetMinBytes && c; c;
- Send an arbitrary packet: An arp request for example
var Cap = Cap c = device = Cap filter = 'arp' bufSize = 10 * 1024 * 1024 buffer = 65535; var linkType = c; // To use this example, change Source Mac, Sender Hardware Address (MAC) and Target Protocol addressvar buffer = // ETHERNET 0xff 0xff 0xff 0xff 0xff0xff // 0 = Destination MAC 0x84 0x8F 0x69 0xB7 0x3D 0x92 // 6 = Source MAC 0x08 0x06 // 12 = EtherType = ARP // ARP 0x00 0x01 // 14/0 = Hardware Type = Ethernet (or wifi) 0x08 0x00 // 16/2 = Protocol type = ipv4 (request ipv4 route info) 0x06 0x04 // 18/4 = Hardware Addr Len (Ether/MAC = 6), Protocol Addr Len (ipv4 = 4) 0x00 0x01 // 20/6 = Operation (ARP, who-has) 0x84 0x8f 0x69 0xb7 0x3d 0x92 // 22/8 = Sender Hardware Addr (MAC) 0xc0 0xa8 0x01 0xc8 // 28/14 = Sender Protocol address (ipv4) 0x00 0x00 0x00 0x00 0x00 0x00 // 32/18 = Target Hardware Address (Blank/nulls for who-has) 0xc0 0xa8 0x01 0xc9 // 38/24 = Target Protocol address (ipv4); try // send will not work if pcap_sendpacket is not supported by underlying `device` c; catch e console; // TCPDUMP. Note: Some values are changed by the network stack when the broadcast arp message is received.//12:28:33.230319 ARP, Ethernet (len 6), IPv4 (len 4), Request who-has 192.168.1.200 tell 192.168.1.199, length 46//0x0000: ffff ffff ffff 848f 69b7 3d92 0806 0001 ........i.=.....//0x0010: 0800 0604 0001 848f 69b7 3d92 c0a8 01c7 ........i.=.....//0x0020: 0000 0000 0000 c0a8 01c8 0000 0000 0000 ................//0x0030: 0000 0000 0000 0000 0000 0000 ............//12:28:33.230336 ARP, Ethernet (len 6), IPv4 (len 4), Reply 192.168.1.200 is-at 74:ea:3a:a3:e6:69, length 28//0x0000: 848f 69b7 3d92 74ea 3aa3 e669 0806 0001 ..i.=.t.:..i....//0x0010: 0800 0604 0002 74ea 3aa3 e669 c0a8 01c8 ......t.:..i....//0x0020: 848f 69b7 3d92 c0a8 01c7 ..i.=.....
- List all network devices:
var Cap = Cap; consoledirCap; // example output on Linux:// [ { name: 'eth0',// addresses:// [ { addr: '192.168.0.10',// netmask: '255.255.255.0',// broadaddr: '192.168.0.255' } ] },// { name: 'nflog',// description: 'Linux netfilter log (NFLOG) interface',// addresses: [] },// { name: 'any',// description: 'Pseudo-device that captures on all interfaces',// addresses: [] },// { name: 'lo',// addresses:// [ { addr: '127.0.0.1', netmask: '255.0.0.0' },// { addr: '::1',// netmask: 'ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff' } ],// flags: 'PCAP_IF_LOOPBACK' } ]
API
Cap events
- packet(< integer >nbytes, < boolean >truncated) - A packet
nbytes
in size was captured.truncated
indicates if the entire packet did not fit inside the Buffer supplied to open().
Cap methods
-
(constructor)() - Creates and returns a new Cap instance.
-
open(< string >device, < string >filter, < integer >bufSize, < Buffer >buffer) - (void) - Opens
device
and starts capturing packets usingfilter
. To see the syntax forfilter
checkpcap-filter
man page.bufSize
is the size of the internal buffer that libpcap uses to temporarily store packets until they are emitted.buffer
is a Buffer large enough to store one packet. If open() is called again without a previous call to close(), an implicit close() will occur first. -
close() - (void) - Stops capturing.
-
setMinBytes(< integer >nBytes) - (void) - (Windows ONLY) This sets the minimum number of packet bytes that must be captured before the full packet data is made available. If this value is set too high, you may not receive any packets until WinPCap's internal buffer fills up. Therefore it's generally best to pass in 0 to this function after calling open(), despite it resulting in more syscalls.
-
send(< Buffer >buffer[, < integer >nBytes]) - (void) - Sends an arbitrary, raw packet on the opened device.
nBytes
is the number of bytes inbuffer
to send (starting from position 0) and defaults tobuffer.length
.
Cap static methods
-
findDevice([< string >ip]) - mixed - If
ip
is given, the (first) device name associated withip
, or undefined is returned if not found. Ifip
is not given, the device name of the first non-loopback device is returned. -
deviceList() - array - Returns a list of available devices and related information.
Decoders static methods
The following methods are available off of require('cap').decoders
. They parse the relevant protocol header and return an object containing the parsed information:
-
Link Layer Protocols
- Ethernet(< Buffer buf[, < integer >bufOffset=0])
-
Internet Layer Protocols
-
IPV4(< Buffer buf[, < integer >bufOffset=0])
-
IPV6(< Buffer buf[, < integer >bufOffset=0])
-
ICMPV4(< Buffer buf, < integer >nbytes[, < integer >bufOffset=0])
-
-
Transport Layer Protocols
-
TCP(< Buffer buf[, < integer >bufOffset=0])
-
UDP(< Buffer buf[, < integer >bufOffset=0])
-
SCTP(< Buffer buf, < integer >nbytes[, < integer >bufOffset=0])
-