ntblk / pcap-sanitizer

🛀 remove private data and remap IP addresses in network packet captures

pcap-sanitizer

pcap-sanitizer is a code module and utility that removes private information from packet capture files.

It can remap IPv4, IPv6, TCP, UDP, ARP and ethernet frame hardware addresses using a deterministic address generation algorithm.

Synopsis

Packet captures play an important role in the diagnosis of internet disruptions, but by design they take a full collection of network traffic that can introduce risk and harm privacy.

pcap-sanitizer makes it possible to remove data from packet captures that is not vital to the task at hand. This is done using a variety of techniques:

• Remapping IP addresses
• Generating pseudorandom hardware addresses
• Optionally removing data payloads
• Rebuilding checksums to preserve integrity
• Providing an audit trail of modifications

This package is maintained as part of the the NetBlocks.org network observation framework.

Features

• IPv4 and IPv6 support as well as a selection of higher layer protocols
• Checksum validation and generation for:
  • IPv4
  • UDP
• Stream-oriented modular programming interface
• A handy commandline tool is also provided for interactive work
• Reactive API: updates are immediately reflected in binary output

Usage guide

Command-line tool

A command-line utility is included that can be used for testing or to seed and exist a deployed cache instance.

$ npm install -g pcap-sanitizer

After installing globally the utility should be available on your PATH:

$ pcap-sanitizer --help
Usage: pcap-sanitizer [options]

Options:

  -r, --redact [ip]     IP, CIDR or subnet to redact (default: )
  -p, --redact-private  redact all subnets assigned for private use
  -m, --redact-mac      randomize ethernet hardware MAC addresses
  -a, --append          Append to existing pcap if [file] exists
  -o, --out [file]      Specify a single output file (default: -)
  -h, --help            output usage information

The NetBlocks Project <https://netblocks.org>

Programming interface

Installation

$ npm install pcap-sanitizer

pcap-sanitizer exposes a stream-based asynchronous programming interface that processes packets on the fly.

const sanitize = require('pcap-sanitizer');

sanitize(inStream, outStream, opts);
...

Tests and sources are currently the best place to look for usage examples.

Status

pcap-sanitizer is in use on probe equipment and also finds use as a commandline tool in research work. Although core functionality is considered reliable, it has not yet been tested with arbitrary inputs or deployed in high-bandwidth scenarios. The code is structured with the goal of supporting client-side operation.

pcap-sanitizer's Issues

Doesn't work at all

Your usage documentation is garbage, but I'm assuming this is how the command line is supposed to work:

pcap-sanitizer unsanitized.pcapng --out sanitized.pcapng -r 192.168.1.2

Except this results in the following:

      throw er; // Unhandled stream error in pipe.
      ^

TypeError: Cannot read property 'ip.src_raw' of undefined
    at getBuf (/home/dev/.npm-global/lib/node_modules/pcap-sanitizer/sanitize.js:338:38)
    at fixChecksums (/home/dev/.npm-global/lib/node_modules/pcap-sanitizer/sanitize.js:342:7)
    at convertFrame (/home/dev/.npm-global/lib/node_modules/pcap-sanitizer/sanitize.js:283:5)
    at /home/dev/.npm-global/lib/node_modules/pcap-sanitizer/sanitize.js:223:15
    at Stream.write (/home/dev/.npm-global/lib/node_modules/pcap-sanitizer/node_modules/event-stream/index.js:204:20)
    at Stream.stream.write (/home/dev/.npm-global/lib/node_modules/pcap-sanitizer/node_modules/through/index.js:26:11)
    at Stream.ondata (internal/streams/legacy.js:19:31)
    at Stream.emit (events.js:314:20)
    at drain (/home/dev/.npm-global/lib/node_modules/pcap-sanitizer/node_modules/through/index.js:36:16)
    at Stream.stream.queue.stream.push (/home/dev/.npm-global/lib/node_modules/pcap-sanitizer/node_modules/through/index.js:45:5)```