gui774ume / nfprobe

Netfilter hooks tracing tool

NFProbe

NFProbe is a NetFilter event tracing utility powered by eBPF.

NFProbe is useful to debug NetFilter issues and understand which table is dropping a packet, on which interface and in which namespace. It can be used to insert log lines the kernel trace_pipe so that you can correlate you skb pointers or even the checksum of your packets. NFProbe comes with many powerful filters that can be leveraged to surface only the events you care about:

• NetFilter hook point: filter by NetFilter hook points.
• Network namespace ID: filter by netns ID.
• Packet type: (see sk_buff->pkt_type) surface NetFilter event on packets of a specific packet type.
• NetFilter protocol: filter by the address family of the NetFilter table.
• Verdict: filter by the verdict of the NetFilter table.
• Table name: filter by the name of the NetFilter table.
• Input device: filter by the name or ifindex of the input device.
• Output device: filter by the name or ifindex of the output device.

System requirements

This project was developed on a Ubuntu Focal machine (Linux Kernel 5.4).

• golang 1.16+
• Kernel headers are expected to be installed in lib/modules/$(uname -r), update the Makefile with their location otherwise.
• clang & llvm 11.0.1+

Build

1. To rebuild the eBPF programs, run the following command:

# ~ make build-ebpf

2. To build NFProbe, run:

# ~ make build

3. To install NFProbe (copy to /usr/bin/nfprobe) run:

# ~ make install

Getting started

NFProbe needs to run as root. Run sudo nfprobe -h to get help.

# ~ nfprobe -h
NFProbe is a NetFilter event tracing utility, powered by eBPF

Usage:
  nfprobe [flags]

Flags:
      --debug                  prints a kernel level debug line for each event
  -h, --help                   help for nfprobe
      --hook array             list of hook filters, leave empty to disable this filter. options: NF_INET_PRE_ROUTING, NF_INET_LOCAL_IN, NF_INET_FORWARD, NF_INET_LOCAL_OUT, NF_INET_POST_ROUTING (default [])
      --in-ifindex array       list of input device ifindex filters, leave empty to disable this filter. Example: 2 (default [])
      --in-name stringArray    list of input device name filters, leave empty to disable this filter. Example: eth0
  -l, --log-level string       log level, options: panic, fatal, error, warn, info, debug or trace (default "debug")
      --netns array            list of network namespace filters, leave empty to disable this filter. Example: 4026531992 (default [])
      --out-ifindex array      list of output device ifindex filters, leave empty to disable this filter. Example: 2 (default [])
      --out-name stringArray   list of output device name filters, leave empty to disable this filter. Example: eth0
      --packet-type array      list of packet-type filters, leave empty to disable this filter. options: PACKET_HOST, PACKET_BROADCAST, PACKET_MULTICAST, PACKET_OTHERHOST, PACKET_OUTGOING, PACKET_LOOPBACK, PACKET_USER, PACKET_KERNEL (default [])
      --proto array            list of proto filters, leave empty to disable this filter. options: NFPROTO_INET, NFPROTO_IPV4, NFPROTO_ARP, NFPROTO_NETDEV, NFPROTO_BRIDGE, NFPROTO_IPV6, NFPROTO_DECNET (default [])
      --stdout                 prints the collected events to stdout (default true)
      --table stringArray      list of table name filters, leave empty to disable this filter. Example: nat
      --verdict array          list of verdict filters, leave empty to disable this filter. options: NF_DROP, NF_ACCEPT, NF_STOLEN, NF_QUEUE, NF_REPEAT (default [])

Example

Dump all the NetFilter events generated by the nat table

# ~ sudo nfprobe --table nat
Time     | CPU | Hook                 | Proto           | Type            | Table      | Verdict    | Netns      | Input           | Output          | Addr               | Csum
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
12:52:10 |  0  | NF_INET_LOCAL_OUT    | NFPROTO_IPV4    | PACKET_HOST     | nat        | NF_ACCEPT  | 4026532192 |                 | lo              | 0xffff951feb990000 | 60024
12:52:10 |  0  | NF_INET_POST_ROUTING | NFPROTO_IPV4    | PACKET_HOST     | nat        | NF_ACCEPT  | 4026532192 |                 | lo              | 0xffff951feb990000 | 60024
12:52:10 |  0  | NF_INET_LOCAL_OUT    | NFPROTO_IPV4    | PACKET_HOST     | nat        | NF_ACCEPT  | 4026531992 |                 | lo              | 0xffff951feb990000 | 60024
12:52:10 |  0  | NF_INET_POST_ROUTING | NFPROTO_IPV4    | PACKET_HOST     | nat        | NF_ACCEPT  | 4026531992 |                 | lo              | 0xffff951feb990000 | 60024
12:52:10 |  0  | NF_INET_LOCAL_OUT    | NFPROTO_IPV4    | PACKET_HOST     | nat        | NF_ACCEPT  | 4026532192 |                 | eth0            | 0xffff951feb990800 | 34a9cb56
12:52:10 |  0  | NF_INET_POST_ROUTING | NFPROTO_IPV4    | PACKET_HOST     | nat        | NF_ACCEPT  | 4026532192 |                 | eth0            | 0xffff951feb990800 | 34a9cb56
12:52:10 |  0  | NF_INET_PRE_ROUTING  | NFPROTO_IPV4    | PACKET_HOST     | nat        | NF_ACCEPT  | 4026531992 | br-abbea84d3b85 |                 | 0xffff951feb990800 | 263cd9c3
12:52:10 |  0  | NF_INET_POST_ROUTING | NFPROTO_IPV4    | PACKET_HOST     | nat        | NF_ACCEPT  | 4026531992 |                 | enp0s3          | 0xffff951feb990800 | 263cd9c3

License

• The golang code is under Apache 2.0 License.
• The eBPF programs are under the GPL v2 License.