npcap icon indicating copy to clipboard operation
npcap copied to clipboard

Fix and update Npcap example code

Open fyodor opened this issue 9 months ago • 1 comments

The code examples we provide with Npcap (which we inherited from the now-obsolete WinPcap) need to be updated for several reasons:

  • Doesn't always handle the new VLAN tags feature properly. For example it treats ethernet headers as always 14 bytes in various places like "ih = (ip_header *) (pkt_data + 14); //length of ethernet header"
  • The fact that we have 2 separate trees: one is supposed to be mingw-compatible, I think, but we haven't really tried that.
  • Most uses older libpcap API functions like pcap_open_live instead of pcap_create/pcap_activate.
  • There are likely bugs in general that we've never checked for.
  • very ugly code with mixed tabs/spaces
  • Only enable promiscuous mode in the examples in cases where it is likely to be particularly useful rather than as a general approach. Most users don't need it and it harms performance when they set it (sometimes by copying our samples) in cases where it isn't needed. The switch to the pcap_create/pcap_activate API may resolve this since it doesn't have the promisc boolean like pcap_open_live does.

Some users may (reasonably) start from our sample code, so it is especially important for us to set a good example.

fyodor avatar Apr 10 '25 19:04 fyodor

Added a bullet point about only enabling promiscuous mode when necessary based in this note that @dmiller-nmap sent to a customer:

Promiscuous mode (https://npcap.com/guide/wpcap/pcap.html#promiscuous) is used to capture incoming traffic that is not directed to the network adapter's own address nor any broadcast nor subscribed multicast addresses. If your application is only concerned with traffic that could be received and interpreted by the system itself, it is not necessary to set promiscuous mode. In fact, it is often beneficial to not set it, simply because promiscuous mode can only serve to increase the amount of traffic that Npcap must process. Many guides and examples use it because one of the original purposes of libpcap was to capture all traffic on a network segment using an Ethernet hub, but modern switched networks make it unlikely that an endpoint will receive such traffic, and most captures today would be better served by not enabling it.

fyodor avatar May 27 '25 20:05 fyodor