pycapng 0.3__tar.gz → 0.4__tar.gz

pycapng-0.4/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.2
+Name: pycapng
+Version: 0.4
+Summary: Python bindings for libpcapng — read/write pcapng files and live packet capture
+Keywords: pcapng,pcap,packet-capture,network,packet,wireshark
+Author-Email: Seb Tricaud <sebastien.tricaud@proton.me>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C++
+Classifier: Topic :: System :: Networking :: Monitoring
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Project-URL: Homepage, https://github.com/stricaud/libpcapng
+Project-URL: Repository, https://github.com/stricaud/libpcapng
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# pycapng
+
+Python library for reading, writing, and capturing network traffic in the
+[pcapng](https://github.com/pcapng/pcapng) file format.
+
+```
+pip install pycapng
+```
+
+- **Read** pcapng files packet by packet
+- **Write** pcapng files with hand-crafted Ethernet/IP/TCP/UDP/ICMP/DNS/DHCP/NTP/TLS packets
+- **Capture** live traffic with a Wireshark-style display filter (Linux / macOS)
+- **Reassemble** fragmented IP packets
+- **Script** packet flows with the built-in pcapsh engine
+
+---
+
+## Reading a pcapng file
+
+```python
+import pycapng
+
+p = pycapng.PcapNG()
+p.OpenFile("capture.pcapng", "r")
+
+def on_packet(data: bytes, ts: int) -> None:
+    print(f"packet {len(data)} bytes  ts={ts}")
+
+p.ForeachPacket(on_packet)
+p.CloseFile()
+```
+
+---
+
+## Writing packets
+
+### Raw bytes
+
+```python
+import pycapng
+
+p = pycapng.PcapNG()
+p.OpenFile("out.pcapng", "w")
+
+raw = bytes([0x45, 0x00, 0x00, 0x28])   # any bytes
+p.WritePacket(raw)
+
+p.CloseFile()
+```
+
+### TCP
+
+```python
+p.WriteTcpPacket(
+    src_ip="192.168.1.10", dst_ip="93.184.216.34",
+    src_port=54321,        dst_port=80,
+    payload=b"GET / HTTP/1.1\r\nHost: example.com\r\n\r\n",
+    flags=0x02,   # SYN
+)
+```
+
+### Build a packet without writing it
+
+```python
+syn = p.BuildTcpPacket(
+    src_ip="10.0.0.1", dst_ip="10.0.0.2",
+    src_port=1234, dst_port=443,
+    payload=b"", flags=0x02,
+)
+# syn is bytes — inspect it, modify it, write it later
+p.WritePacket(syn)
+```
+
+### UDP / ICMP
+
+```python
+pkt = p.BuildUdpPacket(
+    src_ip="10.0.0.1", dst_ip="8.8.8.8",
+    src_port=12345, dst_port=53,
+    payload=b"\x00\x01...",   # your DNS query bytes
+)
+
+icmp = p.BuildIcmpPacket(
+    src_ip="10.0.0.1", dst_ip="10.0.0.2",
+    icmp_type=8, icmp_code=0,   # Echo Request
+    payload=b"hello",
+)
+```
+
+### Application-layer helpers
+
+```python
+# DNS
+query    = p.BuildDnsQuery("example.com")
+response = p.BuildDNSResponse("example.com", "93.184.216.34")
+
+# DHCP
+discover = p.BuildDhcpDiscover()
+offer    = p.BuildDhcpOffer(client_mac="aa:bb:cc:dd:ee:ff",
+                             offered_ip="192.168.1.100")
+
+# NTP
+req  = p.BuildNtpRequest()
+resp = p.BuildNtpReply()
+
+# TLS handshake (produces realistic-looking bytes for testing)
+ch = p.BuildTlsClientHello()
+sh = p.BuildTlsServerHello()
+ct = p.BuildTlsCertificate()
+fin = p.BuildTlsFinished()
+app = p.BuildTlsApplicationData(b"GET / HTTP/1.1\r\n")
+```
+
+### Write with a timestamp
+
+```python
+import time
+
+p.WritePacketTime(raw_bytes, int(time.time() * 1e9))   # nanoseconds
+```
+
+---
+
+## Live capture
+
+Requires **root** or `CAP_NET_RAW` on Linux, **root** or the network entitlement
+on macOS.
+
+### Simple callback loop
+
+```python
+import pycapng
+
+with pycapng.Capture("eth0") as cap:
+    cap.set_filter("tcp.dstport == 443")
+    cap.loop(0, lambda pkt: print(f"{pkt.captured_len} bytes"))
+```
+
+### Full example
+
+```python
+import pycapng, signal
+
+cap = pycapng.Capture(pycapng.capture_default_device())
+cap.set_snaplen(65535)
+cap.set_promisc(True)
+cap.set_timeout(100)                        # ms between ring deliveries
+cap.set_filter("ip and not arp")
+
+signal.signal(signal.SIGINT, lambda *_: cap.break_loop())
+
+def on_packet(pkt: pycapng.PacketInfo) -> None:
+    ts = pkt.timestamp_ns // 1_000_000_000
+    print(f"[{ts}] {pkt.direction}  {pkt.captured_len}/{pkt.original_len} bytes")
+
+cap.loop(0, on_packet)
+
+stats = cap.get_stats()
+print(f"received={stats.received}  dropped={stats.dropped}")
+cap.close()
+```
+
+### Display filter syntax
+
+The filter language is a subset of Wireshark's display filter syntax.
+
+| Example | Meaning |
+|---|---|
+| `tcp` | any TCP packet |
+| `tcp.dstport == 443` | TCP to port 443 |
+| `ip.src == 192.168.0.0/16` | source in subnet |
+| `tcp.flags.syn and not tcp.flags.ack` | SYN-only |
+| `udp.port == 53` | DNS (src or dst) |
+| `ip.addr == 10.0.0.1` | any direction to/from IP |
+| `tcp and not (tcp.dstport == 80 or tcp.dstport == 443)` | non-web TCP |
+| `eth.addr == aa:bb:cc:dd:ee:ff` | by MAC (src or dst) |
+
+Built-in fields: `eth.{src,dst,type,addr}` · `ip.{src,dst,proto,ttl,len,addr}` ·
+`ip6.{src,dst}` · `tcp.{srcport,dstport,flags,flags.syn/ack/rst/fin,port}` ·
+`udp.{srcport,dstport,port}` · `icmp.{type,code}`
+
+### Capture directly to a pcapng file
+
+```python
+# one-liner: capture 500 TLS packets and save to a file
+pycapng.capture_to_file("eth0", "tls.pcapng",
+                         filter="tcp.dstport == 443", count=500)
+```
+
+### List available interfaces
+
+```python
+for dev in pycapng.capture_list_devices():
+    print(dev["name"], "(loopback)" if dev["loopback"] else "")
+
+iface = pycapng.capture_default_device()
+```
+
+---
+
+## IP fragment reassembly
+
+```python
+import pycapng
+
+r = pycapng.Reassembler()
+p = pycapng.PcapNG()
+p.OpenFile("fragments.pcapng", "r")
+
+def on_packet(data: bytes, ts: int) -> None:
+    complete = r.add(data)
+    if complete:
+        print(f"reassembled datagram: {len(complete)} bytes")
+
+p.ForeachPacket(on_packet)
+```
+
+---
+
+## pcapsh script engine
+
+The `pycapng.pcapsh` submodule exposes a scripting engine for building and
+replaying packet flows declaratively.
+
+```python
+from pycapng import pcapsh
+
+engine = pcapsh.PcapSH()
+engine.RunScript("my_flow.pcapsh", "out.pcapng")
+```
+
+TLS record builders are also available as standalone functions:
+
+```python
+from pycapng.pcapsh import (
+    tls_client_hello, tls_server_hello,
+    tls_certificate, tls_finished,
+    tls_application_data,
+)
+```
+
+---
+
+## C library
+
+pycapng is the Python interface to [libpcapng](https://github.com/stricaud/libpcapng),
+a C library that also ships a standalone command-line tool (`pcapsh`) and a
+full C API.  See the repository for C usage, build instructions, and the
+[capture API reference](docs/capture.md).

pycapng-0.4/README-pypi.md

@@ -0,0 +1,249 @@
+# pycapng
+
+Python library for reading, writing, and capturing network traffic in the
+[pcapng](https://github.com/pcapng/pcapng) file format.
+
+```
+pip install pycapng
+```
+
+- **Read** pcapng files packet by packet
+- **Write** pcapng files with hand-crafted Ethernet/IP/TCP/UDP/ICMP/DNS/DHCP/NTP/TLS packets
+- **Capture** live traffic with a Wireshark-style display filter (Linux / macOS)
+- **Reassemble** fragmented IP packets
+- **Script** packet flows with the built-in pcapsh engine
+
+---
+
+## Reading a pcapng file
+
+```python
+import pycapng
+
+p = pycapng.PcapNG()
+p.OpenFile("capture.pcapng", "r")
+
+def on_packet(data: bytes, ts: int) -> None:
+    print(f"packet {len(data)} bytes  ts={ts}")
+
+p.ForeachPacket(on_packet)
+p.CloseFile()
+```
+
+---
+
+## Writing packets
+
+### Raw bytes
+
+```python
+import pycapng
+
+p = pycapng.PcapNG()
+p.OpenFile("out.pcapng", "w")
+
+raw = bytes([0x45, 0x00, 0x00, 0x28])   # any bytes
+p.WritePacket(raw)
+
+p.CloseFile()
+```
+
+### TCP
+
+```python
+p.WriteTcpPacket(
+    src_ip="192.168.1.10", dst_ip="93.184.216.34",
+    src_port=54321,        dst_port=80,
+    payload=b"GET / HTTP/1.1\r\nHost: example.com\r\n\r\n",
+    flags=0x02,   # SYN
+)
+```
+
+### Build a packet without writing it
+
+```python
+syn = p.BuildTcpPacket(
+    src_ip="10.0.0.1", dst_ip="10.0.0.2",
+    src_port=1234, dst_port=443,
+    payload=b"", flags=0x02,
+)
+# syn is bytes — inspect it, modify it, write it later
+p.WritePacket(syn)
+```
+
+### UDP / ICMP
+
+```python
+pkt = p.BuildUdpPacket(
+    src_ip="10.0.0.1", dst_ip="8.8.8.8",
+    src_port=12345, dst_port=53,
+    payload=b"\x00\x01...",   # your DNS query bytes
+)
+
+icmp = p.BuildIcmpPacket(
+    src_ip="10.0.0.1", dst_ip="10.0.0.2",
+    icmp_type=8, icmp_code=0,   # Echo Request
+    payload=b"hello",
+)
+```
+
+### Application-layer helpers
+
+```python
+# DNS
+query    = p.BuildDnsQuery("example.com")
+response = p.BuildDNSResponse("example.com", "93.184.216.34")
+
+# DHCP
+discover = p.BuildDhcpDiscover()
+offer    = p.BuildDhcpOffer(client_mac="aa:bb:cc:dd:ee:ff",
+                             offered_ip="192.168.1.100")
+
+# NTP
+req  = p.BuildNtpRequest()
+resp = p.BuildNtpReply()
+
+# TLS handshake (produces realistic-looking bytes for testing)
+ch = p.BuildTlsClientHello()
+sh = p.BuildTlsServerHello()
+ct = p.BuildTlsCertificate()
+fin = p.BuildTlsFinished()
+app = p.BuildTlsApplicationData(b"GET / HTTP/1.1\r\n")
+```
+
+### Write with a timestamp
+
+```python
+import time
+
+p.WritePacketTime(raw_bytes, int(time.time() * 1e9))   # nanoseconds
+```
+
+---
+
+## Live capture
+
+Requires **root** or `CAP_NET_RAW` on Linux, **root** or the network entitlement
+on macOS.
+
+### Simple callback loop
+
+```python
+import pycapng
+
+with pycapng.Capture("eth0") as cap:
+    cap.set_filter("tcp.dstport == 443")
+    cap.loop(0, lambda pkt: print(f"{pkt.captured_len} bytes"))
+```
+
+### Full example
+
+```python
+import pycapng, signal
+
+cap = pycapng.Capture(pycapng.capture_default_device())
+cap.set_snaplen(65535)
+cap.set_promisc(True)
+cap.set_timeout(100)                        # ms between ring deliveries
+cap.set_filter("ip and not arp")
+
+signal.signal(signal.SIGINT, lambda *_: cap.break_loop())
+
+def on_packet(pkt: pycapng.PacketInfo) -> None:
+    ts = pkt.timestamp_ns // 1_000_000_000
+    print(f"[{ts}] {pkt.direction}  {pkt.captured_len}/{pkt.original_len} bytes")
+
+cap.loop(0, on_packet)
+
+stats = cap.get_stats()
+print(f"received={stats.received}  dropped={stats.dropped}")
+cap.close()
+```
+
+### Display filter syntax
+
+The filter language is a subset of Wireshark's display filter syntax.
+
+| Example | Meaning |
+|---|---|
+| `tcp` | any TCP packet |
+| `tcp.dstport == 443` | TCP to port 443 |
+| `ip.src == 192.168.0.0/16` | source in subnet |
+| `tcp.flags.syn and not tcp.flags.ack` | SYN-only |
+| `udp.port == 53` | DNS (src or dst) |
+| `ip.addr == 10.0.0.1` | any direction to/from IP |
+| `tcp and not (tcp.dstport == 80 or tcp.dstport == 443)` | non-web TCP |
+| `eth.addr == aa:bb:cc:dd:ee:ff` | by MAC (src or dst) |
+
+Built-in fields: `eth.{src,dst,type,addr}` · `ip.{src,dst,proto,ttl,len,addr}` ·
+`ip6.{src,dst}` · `tcp.{srcport,dstport,flags,flags.syn/ack/rst/fin,port}` ·
+`udp.{srcport,dstport,port}` · `icmp.{type,code}`
+
+### Capture directly to a pcapng file
+
+```python
+# one-liner: capture 500 TLS packets and save to a file
+pycapng.capture_to_file("eth0", "tls.pcapng",
+                         filter="tcp.dstport == 443", count=500)
+```
+
+### List available interfaces
+
+```python
+for dev in pycapng.capture_list_devices():
+    print(dev["name"], "(loopback)" if dev["loopback"] else "")
+
+iface = pycapng.capture_default_device()
+```
+
+---
+
+## IP fragment reassembly
+
+```python
+import pycapng
+
+r = pycapng.Reassembler()
+p = pycapng.PcapNG()
+p.OpenFile("fragments.pcapng", "r")
+
+def on_packet(data: bytes, ts: int) -> None:
+    complete = r.add(data)
+    if complete:
+        print(f"reassembled datagram: {len(complete)} bytes")
+
+p.ForeachPacket(on_packet)
+```
+
+---
+
+## pcapsh script engine
+
+The `pycapng.pcapsh` submodule exposes a scripting engine for building and
+replaying packet flows declaratively.
+
+```python
+from pycapng import pcapsh
+
+engine = pcapsh.PcapSH()
+engine.RunScript("my_flow.pcapsh", "out.pcapng")
+```
+
+TLS record builders are also available as standalone functions:
+
+```python
+from pycapng.pcapsh import (
+    tls_client_hello, tls_server_hello,
+    tls_certificate, tls_finished,
+    tls_application_data,
+)
+```
+
+---
+
+## C library
+
+pycapng is the Python interface to [libpcapng](https://github.com/stricaud/libpcapng),
+a C library that also ships a standalone command-line tool (`pcapsh`) and a
+full C API.  See the repository for C usage, build instructions, and the
+[capture API reference](docs/capture.md).

pycapng-0.4/README.md

@@ -0,0 +1,86 @@
+# libpcapng
+
+C library (with Python bindings) for reading, writing, and capturing network
+traffic in the [pcapng](https://github.com/pcapng/pcapng) file format.
+
+## Features
+
+- Full pcapng block support: SHB, IDB, EPB, SPB, NRB, ISB, DSB
+- TLV options on every block type
+- Zero-copy live capture — Linux `TPACKET_V3` ring buffer, macOS BPF
+- Wireshark-style display filter engine operating on decoded packet fields
+- POSA protocol extension hook for custom field providers
+- IP fragment reassembly
+- pcapsh scripting engine for building and replaying packet flows
+- Python bindings (`pip install pycapng`) — see [README-pypi.md](README-pypi.md)
+
+## Building
+
+```bash
+mkdir build && cd build
+cmake .. -DCMAKE_BUILD_TYPE=Release
+make -j$(nproc)
+```
+
+## Python bindings
+
+```bash
+pip install pycapng
+```
+
+See [README-pypi.md](README-pypi.md) for the full Python API reference.
+
+## C quick-start
+
+Write a TCP SYN packet to a pcapng file:
+
+```c
+#include <libpcapng/libpcapng.h>
+
+FILE *fp = fopen("out.pcapng", "wb");
+libpcapng_write_header_to_file(fp);
+
+/* raw Ethernet frame bytes */
+uint8_t frame[...];
+libpcapng_write_enhanced_packet_to_file(fp, frame, sizeof(frame));
+
+fclose(fp);
+```
+
+Compile:
+
+```bash
+gcc main.c -o main $(pkg-config libpcapng --libs --cflags)
+```
+
+## Live capture (C)
+
+```c
+#include <libpcapng/capture.h>
+
+char errbuf[PCAPNG_CAPTURE_ERRBUF_SIZE];
+pcapng_capture_t *cap = pcapng_capture_open("eth0", errbuf);
+pcapng_capture_set_filter(cap, "tcp.dstport == 443", errbuf);
+
+void on_packet(const pcapng_packet_info_t *pkt, void *ud) {
+    printf("%u bytes\n", pkt->captured_len);
+}
+
+pcapng_capture_loop(cap, 0, on_packet, NULL);
+pcapng_capture_close(cap);
+```
+
+See [docs/capture.md](docs/capture.md) for the full capture API.
+
+## pcapsh
+
+An interactive shell and scripting engine for building packet flows:
+
+```bash
+./pcapsh
+pcapsh> tcp src 10.0.0.1:1234 dst 10.0.0.2:80 payload "hello"
+```
+
+## License
+
+MIT

{pycapng-0.3 → pycapng-0.4}/pyproject.toml

@@ -20,7 +20,7 @@ build-backend = "scikit_build_core.build"
 name = "pycapng"
 dynamic = ["version"]
 description = "Python bindings for libpcapng — read/write pcapng files and live packet capture"
-readme = "README.md"
+readme = "README-pypi.md"
 requires-python = ">=3.9"
 license = { text = "MIT" }
 authors = [{ name = "Seb Tricaud", email = "sebastien.tricaud@proton.me" }]

pycapng-0.3/PKG-INFO

@@ -1,79 +0,0 @@
-Metadata-Version: 2.2
-Name: pycapng
-Version: 0.3
-Summary: Python bindings for libpcapng — read/write pcapng files and live packet capture
-Keywords: pcapng,pcap,packet-capture,network,packet,wireshark
-Author-Email: Seb Tricaud <sebastien.tricaud@proton.me>
-License: MIT
-Classifier: Development Status :: 3 - Alpha
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Operating System :: MacOS :: MacOS X
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: C++
-Classifier: Topic :: System :: Networking :: Monitoring
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Project-URL: Homepage, https://github.com/stricaud/libpcapng
-Project-URL: Repository, https://github.com/stricaud/libpcapng
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-
-# libpcapng
-
-C library with Python bindings to read and write pcapng buffers. It follows the pcapng standard from https://github.com/pcapng/pcapng
-
-## Writing your first packet
-
-Let's write a TCP SYN using libdumbnet and push the buffer into a pcapng file:
-
-```c
-#include <stdio.h>
-#include <stdlib.h>
-#include <string.h>
-
-#include <dumbnet.h>
-#include <libpcapng/libpcapng.h>
-
-int main(int argc, char **argv)
-{
-	FILE *pcapout;
-
-	char *pkt;
-	size_t pktsize = 40;
-
-	pkt = (char *)malloc(pktsize);
-	if (!pkt) {
-	   fprintf(stderr, "Cannot allocate pkt!\n");
-	   return -1;
-	}
-
-	pcapout = fopen("pkts.pcap", "wb");
-
-	libpcapng_write_header_to_file(pcapout);
-
-	uint32_t saddr = 0x0100a8c0;
-	uint32_t daddr = 0x561c1268;
-
-	ip_pack_hdr(pkt, 0, pktsize, 1, 0, 128, IP_PROTO_TCP, saddr, daddr);
-	tcp_pack_hdr(pkt + 20, 4096, 80, 1, 0, TH_SYN, 14, 0);
-	ip_checksum(pkt, pktsize);
-
-	libpcapng_write_enhanced_packet_to_file(pcapout, pkt, pktsize);
-
-	fflush(pcapout);
-	fclose(pcapout);
-
-	free(pkt);
-
-	return 0;
-}
-```
-
-Compile using:
-```
-gcc test.c -o test -ldumbnet $(pkg-config libpcapng --libs --cflags)
-```
-
-And after running, open the created pcap with wireshark:
-
-<p align="center"><img src="doc/firstpkt.png" size="30%"/></p>