libpnet-pyo3

pyo3 bindings for libpnet.

Status: alpha. Wheels published for Linux + macOS in v0.1. libpnet itself supports Windows (via Npcap or winpkfilter); the Windows wheel build for this wrapper is planned for a later release.

Install

pip install libpnet-pyo3

Wheels published for Linux (x86_64, aarch64) and macOS (x86_64, aarch64), Python 3.10+ (abi3).

Raw sockets need elevated privilege:

• Linux: sudo or grant CAP_NET_RAW to the Python interpreter
• macOS: sudo (BPF and raw sockets are root-only)

Quick start

from libpnet_pyo3 import tcp_sr1, icmp_ping, sniff, arp_who_has

# TCP SYN probe
resp = tcp_sr1(dst="1.2.3.4", dport=80, flags="S", timeout=1.0)
if resp and resp.is_synack():
    print(f"open, ttl={resp.ttl}, window={resp.window}")

# Ping
echo = icmp_ping("1.1.1.1", timeout=1.0)
if echo and echo.is_echo_reply():
    print(f"reply from {echo.src} ttl={echo.ttl}")

# ARP
reply = arp_who_has("192.168.1.1")
if reply:
    print(f"{reply.ip} is at {reply.mac}")

# Sniff
for pkt in sniff(count=10, timeout=5.0):
    print(pkt)

API

Send-and-receive

Send-only

Capture

sniff(*, iface=None, count=None, timeout=None) -> list[SniffedPacket] — at least one of count/timeout is required.

Packet builders (return raw bytes)

build_tcp_packet, build_udp_packet, build_icmp_echo, build_arp_request — same kwargs as the send-receive equivalents.

Helpers

Response objects

• TcpResponse: src dst sport dport flags seq ack window ttl payload, methods has_flag(f), is_synack(), is_rst()
• UdpResponse: src dst sport dport ttl payload
• IcmpResponse: src icmp_type icmp_code ttl ident seq payload, method is_echo_reply()
• ArpReply: ip mac iface
• SniffedPacket: iface bytes ts_secs, method ethertype()

TCP flag constants

SYN, ACK, RST, FIN, PSH, URG, ECE, CWR — combine with | or pass a string like "SA" to flags=.

Not in v0.1 (planned)

• IPv6 (IPv4 only today)
• BPF filter expressions on sniff
• pcap read/write
• Multi-reply send (sr returning a list)
• Windows wheels (libpnet supports Windows via Npcap / winpkfilter — this wrapper just hasn't wired it up yet)

Build from source

Requires Rust (stable, 1.74+) and Python 3.10+.

git clone https://github.com/ropoctl/libpnet-pyo3
cd libpnet-pyo3
python -m venv .venv && source .venv/bin/activate
pip install maturin
maturin develop --release

License

Dual-licensed under Apache-2.0 or MIT at your option.