Overview

netdumplings allows you to run multiple packet sniffers on any number of hosts. Those sniffers – called dumpling kitchens – pass any sniffed network packets to your Python code for processing. Your Python code is implemented as classes called dumpling chefs which use the network packets to generate dumplings. Dumpling contents are entirely up to you but they’ll usually describe the information contained in the sniffed network packets.

The dumplings created by the dumpling chefs are sent from the dumpling kitchens to a single dumpling hub, which forwards them on to any connected dumpling eaters for display or for any other sort of processing or visualization.

The kitchens, chefs, dumplings, hub, and eaters, are shown below. You write the bits in green (the chefs and eaters) and netdumplings does the rest:

Dumplings are sent between the kitchens, hub, and eaters, over WebSockets.

Note

Every network packet sniffed by a single kitchen is passed to every chef registered with that kitchen. Also, every dumpling sent to the hub is forwarded on to every connected eater. Any packet filtering should be done by the kitchen’s PCAP filter (see the --filter flag to nd-sniff) or by the chef implementation. Eaters can also filter out dumplings they don’t care about.

Dumpling chefs are written in Python by subclassing DumplingChef. Dumpling eaters can be written in any language but netdumplings provides the DumplingEater convenience class for writing them in Python.

Dumpling kitchens are started with the nd-sniff commandline tool (which is told where to find the chefs), and the hub is started with the nd-hub commandline tool.

Even though the above diagram shows everything running on different hosts, you can instead run everything on the same host if that better suits your needs.

What does a dumpling look like?

Dumplings are just JSON data. Following is an example dumpling created from the work of a chef which takes every network packet it’s given and maintains a count of packets by protocol:

{
    "metadata": {
        "chef": "PacketCountChef",
        "creation_time": 1515990765.925951,
        "driver": "interval",
        "kitchen": "default_kitchen"

    },
    "payload": {
        "packet_counts": {
            "Ethernet": 1426745,
            "IP": 1423352,
            "TCP": 12382,
            "UDP": 1413268
        }
    }
}

The payload section is generated by the dumpling chef and the metadata section is created automatically when the dumpling is sent to the hub by the kitchen.

See the PacketCountChef source code to see how the above dumpling is created.

What’s in the box?

netdumplings comes with:

• The packet sniffer kitchen commandline tool nd-sniff

• The dumpling hub commandline tool nd-hub

• Sample dumpling chefs in the netdumplings.dumplingchefs module

• Sample dumpling eater commandline tools nd-print, nd-hubdetails, and nd-hubstatus

• Classes to help you write your own chefs and eaters: DumplingChef and DumplingEater

There’s enough in the installation package to get started without writing any code, but to get the most out of netdumplings you’ll write your own chefs and eaters.