netprotocols 1.0.0__tar.gz → 1.0.1__tar.gz

{netprotocols-1.0.0 → netprotocols-1.0.1}/.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: CI
 
 on:
   push:
-    branches: [master, overhaul]
+    branches: [master]
   pull_request:
     branches: [master]
 

{netprotocols-1.0.0 → netprotocols-1.0.1}/.gitignore

@@ -146,4 +146,4 @@ amass.txt
 amass.log
 
 # Application-specific
-.logs/
+.logs/tests/fixtures/staging/

{netprotocols-1.0.0 → netprotocols-1.0.1}/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.1] - 2026-08-29
+
+### Fixed
+- `IPv4.next_protocol()` chained non-first fragments
+  (`fragment_offset > 0`) into garbage upper-layer decodes — a slice
+  from the middle of a fragmented payload has no header at its start.
+  Discovered by the new real-capture fixture corpus on live fragmented
+  traffic; the chain now ends at the IPv4 layer for those frames, as it
+  already did for unknown protocols.
+
+### Added (development)
+- A real-capture fixture corpus under `tests/fixtures/` (56 frames,
+  10 scenarios, every checksum internally verified — see its
+  MANIFEST.md) with corpus-wide invariant tests, plus the capture and
+  validation scripts under `scripts/`.
+
 ## [1.0.0] - 2026-08-21
 
 Complete rewrite. The public API is new; see the README and

{netprotocols-1.0.0 → netprotocols-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: netprotocols
-Version: 1.0.0
+Version: 1.0.1
 Summary: Low-level implementations of common networking protocols
 Project-URL: Homepage, https://github.com/EONRaider/NETProtocols
 Project-URL: Repository, https://github.com/EONRaider/NETProtocols

{netprotocols-1.0.0 → netprotocols-1.0.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "netprotocols"
-version = "1.0.0"
+version = "1.0.1"
 description = "Low-level implementations of common networking protocols"
 readme = "README.md"
 license = "MIT"

netprotocols-1.0.1/scripts/capture_fixtures.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+# Capture the real-frame fixture corpus (issue #27, plan item L-0).
+#
+# Run once with sudo from the repository root:
+#
+#     sudo scripts/capture_fixtures.sh
+#
+# Writes per-scenario pcaps into tests/fixtures/staging/ and finishes by
+# running scripts/check_fixtures.py over them. Frames used for checksum
+# ground truth are captured INBOUND only (outbound frames often carry
+# checksums left unfilled for NIC offload). Nothing is committed by this
+# script: review the checker report, then hand the staging directory to
+# the test-writing step.
+
+set -euo pipefail
+
+if [[ $EUID -ne 0 ]]; then
+    echo "This script needs root for tcpdump (or run it via sudo)." >&2
+    exit 1
+fi
+
+command -v tcpdump >/dev/null || { echo "tcpdump is required." >&2; exit 1; }
+
+OUT="tests/fixtures/staging"
+mkdir -p "$OUT"
+
+IFACE=$(ip route show default | awk '/default/ {print $5; exit}')
+GATEWAY=$(ip route show default | awk '/default/ {print $3; exit}')
+[[ -n $IFACE ]] || { echo "No default interface found." >&2; exit 1; }
+echo "[*] Default interface: $IFACE (gateway $GATEWAY)"
+echo "[*] Writing to $OUT/"
+
+# capture NAME IFACE COUNT FILTER -- TRAFFIC_CMD...
+# Starts a bounded tcpdump, runs the traffic generator, waits.
+capture() {
+    local name=$1 iface=$2 count=$3 filter=$4; shift 4; shift # consume --
+    echo "[>] $name"
+    tcpdump -i "$iface" -c "$count" -w "$OUT/$name.pcap" --immediate-mode \
+        -q $filter >/dev/null 2>&1 &
+    local pid=$!
+    sleep 1
+    "$@" >/dev/null 2>&1 || true
+    # Give tcpdump up to 15s to fill its count, then stop it either way.
+    for _ in $(seq 15); do kill -0 $pid 2>/dev/null || break; sleep 1; done
+    kill $pid 2>/dev/null || true
+    wait $pid 2>/dev/null || true
+}
+
+# --- Loopback scenarios (checksum ground truth: lo has no offload issue
+# --- for inbound copies; we still filter inbound where it matters).
+capture icmpv4_echo_lo lo 6 "icmp" -- ping -c 3 -i 0.3 127.0.0.1
+capture icmpv6_echo_lo lo 6 "icmp6" -- ping -c 3 -i 0.3 ::1
+
+# --- Default-interface scenarios, inbound-only where checksums matter.
+capture udp_dns "$IFACE" 4 "inbound and udp and port 53" -- \
+    sh -c 'dig +tries=1 +time=3 example.com @1.1.1.1; dig +tries=1 +time=3 AAAA example.com @1.1.1.1'
+capture tcp_http "$IFACE" 12 "inbound and tcp and port 80" -- \
+    curl -s -m 8 -o /dev/null http://example.com/
+capture tcp_https "$IFACE" 12 "inbound and tcp and port 443" -- \
+    curl -s -m 8 -o /dev/null https://example.com/
+capture icmpv4_external "$IFACE" 4 "inbound and icmp" -- \
+    ping -c 3 -i 0.4 -W 2 1.1.1.1
+# A 2000-byte ping fragments on any 1500-MTU path: inbound echo replies
+# arrive as an IPv4 fragment pair.
+capture ipv4_fragments "$IFACE" 6 "inbound and (icmp or ip[6:2] & 0x3fff != 0)" -- \
+    ping -c 3 -i 0.4 -W 2 -s 2000 1.1.1.1
+# TTL-exceeded errors from intermediate hops.
+capture icmpv4_ttl_exceeded "$IFACE" 4 "inbound and icmp[icmptype] == 11" -- \
+    sh -c 'ping -c 2 -W 2 -t 2 1.1.1.1; ping -c 2 -W 2 -t 3 1.1.1.1'
+
+# --- ARP (no checksums; both directions welcome). Flush the gateway
+# --- neighbor entry to force a fresh exchange.
+arp_traffic() {
+    ip neigh del "$GATEWAY" dev "$IFACE" 2>/dev/null || true
+    ping -c 1 -W 2 "$GATEWAY"
+}
+capture arp_exchange "$IFACE" 4 "arp" -- arp_traffic
+
+# --- IPv6 NDP / MLD, ambient + provoked. MLD reports ride behind a
+# --- hop-by-hop header (the L-1 fixture). Joining a multicast group
+# --- provokes a report; pinging the all-nodes address provokes NDP.
+ipv6_traffic() {
+    ping -6 -c 2 -W 2 "ff02::1%$IFACE" || true
+    python3 - "$IFACE" <<'PY' || true
+import socket, struct, sys, time
+sock = socket.socket(socket.AF_INET6, socket.SOCK_DGRAM)
+ifindex = socket.if_nametoindex(sys.argv[1])
+group = socket.inet_pton(socket.AF_INET6, "ff02::deca:fbad")
+sock.setsockopt(socket.IPPROTO_IPV6, socket.IPV6_JOIN_GROUP,
+                group + struct.pack("@I", ifindex))
+time.sleep(3)
+PY
+}
+capture ipv6_ndp_mld "$IFACE" 10 "icmp6" -- ipv6_traffic
+
+echo
+echo "[*] Captures done. Validating..."
+CHECKER_PY=$(command -v python3)
+if [[ -n ${SUDO_USER:-} ]]; then
+    chown -R "$SUDO_USER" "$OUT"
+    sudo -u "$SUDO_USER" "$CHECKER_PY" scripts/check_fixtures.py "$OUT"
+else
+    "$CHECKER_PY" scripts/check_fixtures.py "$OUT"
+fi

netprotocols-1.0.1/scripts/capture_fixtures_supplement.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# Supplementary corpus capture: the two scenarios the first run missed
+# (see tests/fixtures/MANIFEST.md "Known gaps").
+#
+#     sudo scripts/capture_fixtures_supplement.sh
+#
+# 1. MLD behind hop-by-hop: the original run filtered with BPF `icmp6`,
+#    which matches next_header == 58 directly and therefore *excludes*
+#    MLD (which rides behind a hop-by-hop header, next_header == 0).
+#    This captures `ip6 proto 0` while joining/leaving a multicast
+#    group to provoke reports.
+# 2. IPv6 fragment pair: an oversized ping -6 to an external host
+#    fragments on any 1500-MTU path (ip6 proto 44, inbound).
+
+set -euo pipefail
+
+if [[ $EUID -ne 0 ]]; then
+    echo "This script needs root for tcpdump (or run it via sudo)." >&2
+    exit 1
+fi
+
+OUT="tests/fixtures/staging"
+mkdir -p "$OUT"
+IFACE=$(ip route show default | awk '/default/ {print $5; exit}')
+echo "[*] Default interface: $IFACE"
+
+capture() {
+    local name=$1 iface=$2 count=$3 filter=$4; shift 4; shift
+    echo "[>] $name"
+    tcpdump -i "$iface" -c "$count" -w "$OUT/$name.pcap" --immediate-mode \
+        -q $filter >/dev/null 2>&1 &
+    local pid=$!
+    sleep 1
+    "$@" >/dev/null 2>&1 || true
+    for _ in $(seq 20); do kill -0 $pid 2>/dev/null || break; sleep 1; done
+    kill $pid 2>/dev/null || true
+    wait $pid 2>/dev/null || true
+}
+
+mld_traffic() {
+    python3 - "$IFACE" <<'PY' || true
+import socket, struct, sys, time
+ifindex = socket.if_nametoindex(sys.argv[1])
+group = socket.inet_pton(socket.AF_INET6, "ff02::deca:fbad")
+mreq = group + struct.pack("@I", ifindex)
+for _ in range(3):
+    sock = socket.socket(socket.AF_INET6, socket.SOCK_DGRAM)
+    sock.setsockopt(socket.IPPROTO_IPV6, socket.IPV6_JOIN_GROUP, mreq)
+    time.sleep(1.5)
+    sock.close()  # leaving also emits an MLD Done/Report
+    time.sleep(1.5)
+PY
+}
+capture ipv6_mld "$IFACE" 4 "ip6 proto 0" -- mld_traffic
+
+ipv6_frag_traffic() {
+    # An IPv6-reachable anycast resolver; 2000-byte payload fragments
+    # on the way back.
+    ping -6 -c 3 -i 0.5 -W 3 -s 2000 2606:4700:4700::1111
+}
+capture ipv6_fragments "$IFACE" 8 "inbound and ip6 proto 44" -- ipv6_frag_traffic
+
+echo
+echo "[*] Validating supplement..."
+CHECKER_PY=$(command -v python3)
+if [[ -n ${SUDO_USER:-} ]]; then
+    chown -R "$SUDO_USER" "$OUT"
+    sudo -u "$SUDO_USER" "$CHECKER_PY" scripts/check_fixtures.py "$OUT"
+else
+    "$CHECKER_PY" scripts/check_fixtures.py "$OUT"
+fi

netprotocols-1.0.1/scripts/check_fixtures.py

@@ -0,0 +1,225 @@
+#!/usr/bin/env python3
+"""Validate the internal checksum consistency of captured fixture pcaps.
+
+Deliberately standalone (stdlib only, its own RFC 1071 implementation,
+its own minimal parsers): it must be able to disqualify a capture even
+if netprotocols itself has a bug, and later it cross-validates the
+library's checksum module (plan item L-2) with an independent
+implementation.
+
+Usage: python3 scripts/check_fixtures.py tests/fixtures/staging
+"""
+
+from __future__ import annotations
+
+import struct
+import sys
+from collections import Counter
+from pathlib import Path
+
+
+def internet_checksum(data: bytes) -> int:
+    if len(data) % 2:
+        data += b"\x00"
+    total = sum(struct.unpack(f"!{len(data) // 2}H", data))
+    while total >> 16:
+        total = (total & 0xFFFF) + (total >> 16)
+    return ~total & 0xFFFF
+
+
+def read_pcap(path: Path):
+    data = path.read_bytes()
+    if len(data) < 24:
+        raise ValueError("not a pcap: too short")
+    magic = data[:4]
+    if magic in (b"\xa1\xb2\xc3\xd4", b"\xa1\xb2\x3c\x4d"):
+        endian = ">"
+    elif magic in (b"\xd4\xc3\xb2\xa1", b"\x4d\x3c\xb2\xa1"):
+        endian = "<"
+    else:
+        raise ValueError(f"not a pcap: magic {magic.hex()}")
+    (network,) = struct.unpack_from(f"{endian}I", data, 20)
+    if network != 1:
+        raise ValueError(f"linktype {network} is not Ethernet")
+    cursor = 24
+    while cursor + 16 <= len(data):
+        _, _, incl_len, _ = struct.unpack_from(f"{endian}IIII", data, cursor)
+        cursor += 16
+        yield data[cursor : cursor + incl_len]
+        cursor += incl_len
+
+
+def pseudo_v4(src: bytes, dst: bytes, proto: int, length: int) -> bytes:
+    return src + dst + struct.pack("!BBH", 0, proto, length)
+
+
+def pseudo_v6(src: bytes, dst: bytes, proto: int, length: int) -> bytes:
+    return src + dst + struct.pack("!IBBBB", length, 0, 0, 0, proto)
+
+
+def check_frame(frame: bytes, stats: Counter) -> list[str]:
+    """Validate one Ethernet frame; returns a list of failure strings."""
+    failures: list[str] = []
+    if len(frame) < 14:
+        stats["runt"] += 1
+        return failures
+    ethertype = struct.unpack_from("!H", frame, 12)[0]
+    payload = frame[14:]
+
+    if ethertype == 0x0806:
+        stats["arp"] += 1
+        return failures
+
+    if ethertype == 0x0800 and len(payload) >= 20:
+        ihl = (payload[0] & 0x0F) * 4
+        header = payload[:ihl]
+        stats["ipv4"] += 1
+        if (
+            internet_checksum(header[:10] + b"\x00\x00" + header[12:ihl])
+            != struct.unpack_from("!H", header, 10)[0]
+        ):
+            failures.append("ipv4-header-checksum")
+        src, dst = header[12:16], header[16:20]
+        proto = header[9]
+        total_length = struct.unpack_from("!H", header, 2)[0]
+        flags_frag = struct.unpack_from("!H", header, 6)[0]
+        if flags_frag & 0x1FFF:
+            stats["ipv4-fragment"] += 1
+            return failures  # non-first fragment: no upper-layer header
+        if flags_frag & 0x2000 == 0x2000 and flags_frag & 0x1FFF == 0:
+            stats["ipv4-first-fragment"] += 1
+            return failures  # first fragment: upper checksum spans all parts
+        upper = payload[ihl:total_length]
+        upper_len = len(upper)
+        if proto == 1 and upper_len >= 8:
+            stats["icmpv4"] += 1
+            if (
+                internet_checksum(upper[:2] + b"\x00\x00" + upper[4:])
+                != struct.unpack_from("!H", upper, 2)[0]
+            ):
+                failures.append("icmpv4-checksum")
+        elif proto == 6 and upper_len >= 20:
+            stats["tcp"] += 1
+            zeroed = upper[:16] + b"\x00\x00" + upper[18:]
+            if (
+                internet_checksum(pseudo_v4(src, dst, 6, upper_len) + zeroed)
+                != struct.unpack_from("!H", upper, 16)[0]
+            ):
+                failures.append("tcp-checksum")
+        elif proto == 17 and upper_len >= 8:
+            stats["udp"] += 1
+            wire = struct.unpack_from("!H", upper, 6)[0]
+            if wire == 0:
+                stats["udp-no-checksum"] += 1
+            else:
+                zeroed = upper[:6] + b"\x00\x00" + upper[8:]
+                computed = (
+                    internet_checksum(
+                        pseudo_v4(src, dst, 17, upper_len) + zeroed
+                    )
+                    or 0xFFFF
+                )
+                if computed != wire:
+                    failures.append("udp-checksum")
+        return failures
+
+    if ethertype == 0x86DD and len(payload) >= 40:
+        stats["ipv6"] += 1
+        payload_length, next_header = struct.unpack_from("!HB", payload, 4)
+        src, dst = payload[8:24], payload[24:40]
+        upper = payload[40 : 40 + payload_length]
+        # Walk extension headers (hop-by-hop 0, routing 43, dest-opts 60).
+        while next_header in (0, 43, 60) and len(upper) >= 8:
+            stats["ipv6-ext-header"] += 1
+            ext_len = (upper[1] + 1) * 8
+            next_header, upper = upper[0], upper[ext_len:]
+        if next_header == 44 and len(upper) >= 8:
+            stats["ipv6-fragment"] += 1
+            if struct.unpack_from("!H", upper, 2)[0] & 0xFFF8:
+                return failures
+            next_header, upper = upper[0], upper[8:]
+        upper_len = len(upper)
+        if next_header == 58 and upper_len >= 4:
+            stats["icmpv6"] += 1
+            zeroed = upper[:2] + b"\x00\x00" + upper[4:]
+            if (
+                internet_checksum(pseudo_v6(src, dst, 58, upper_len) + zeroed)
+                != struct.unpack_from("!H", upper, 2)[0]
+            ):
+                failures.append("icmpv6-checksum")
+        elif next_header == 6 and upper_len >= 20:
+            stats["tcp6"] += 1
+            zeroed = upper[:16] + b"\x00\x00" + upper[18:]
+            if (
+                internet_checksum(pseudo_v6(src, dst, 6, upper_len) + zeroed)
+                != struct.unpack_from("!H", upper, 16)[0]
+            ):
+                failures.append("tcp6-checksum")
+        elif next_header == 17 and upper_len >= 8:
+            stats["udp6"] += 1
+            zeroed = upper[:6] + b"\x00\x00" + upper[8:]
+            computed = (
+                internet_checksum(pseudo_v6(src, dst, 17, upper_len) + zeroed)
+                or 0xFFFF
+            )
+            if computed != struct.unpack_from("!H", upper, 6)[0]:
+                failures.append("udp6-checksum")
+        return failures
+
+    stats[f"other-0x{ethertype:04x}"] += 1
+    return failures
+
+
+def main() -> int:
+    staging = Path(
+        sys.argv[1] if len(sys.argv) > 1 else "tests/fixtures/staging"
+    )
+    pcaps = sorted(staging.glob("*.pcap"))
+    if not pcaps:
+        print(f"No pcaps found in {staging}/")
+        return 1
+
+    corpus_stats: Counter = Counter()
+    bad_files = 0
+    total_frames = 0
+    for pcap in pcaps:
+        stats: Counter = Counter()
+        failures: Counter = Counter()
+        frames = 0
+        try:
+            for frame in read_pcap(pcap):
+                frames += 1
+                for failure in check_frame(frame, stats):
+                    failures[failure] += 1
+        except ValueError as e:
+            print(f"[FAIL] {pcap.name}: {e}")
+            bad_files += 1
+            continue
+        total_frames += frames
+        corpus_stats.update(stats)
+        verdict = "OK  " if not failures else "FAIL"
+        detail = ", ".join(f"{k}x{v}" for k, v in sorted(stats.items()))
+        print(f"[{verdict}] {pcap.name}: {frames} frames ({detail})")
+        for failure, count in sorted(failures.items()):
+            print(f"       !! {failure} x{count}")
+        if failures:
+            bad_files += 1
+
+    print(f"\nCorpus: {total_frames} frames across {len(pcaps)} files")
+    print(
+        "Coverage:",
+        ", ".join(f"{k}={v}" for k, v in sorted(corpus_stats.items())),
+    )
+    if bad_files:
+        print(
+            f"\n{bad_files} file(s) FAILED checksum consistency — "
+            f"do not commit these; re-capture or investigate offload "
+            f"(ethtool -K <iface> tx off rx off)."
+        )
+        return 1
+    print("\nAll files internally consistent.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{netprotocols-1.0.0 → netprotocols-1.0.1}/src/netprotocols/__init__.py

@@ -30,7 +30,7 @@ from netprotocols.utils.exceptions import (
 from netprotocols.utils.ipv4 import validate_ipv4_addr
 from netprotocols.utils.mac import random_mac, validate_mac_addr
 
-__version__ = "1.0.0"
+__version__ = "1.0.1"
 
 __all__ = [
     "ARP",

{netprotocols-1.0.0 → netprotocols-1.0.1}/src/netprotocols/layer3/ip.py

@@ -172,6 +172,14 @@ class IPv4(Protocol):
         return self.ihl * 4
 
     def next_protocol(self) -> type[Protocol] | None:
+        """See :meth:`Protocol.next_protocol`.
+
+        A non-first fragment (``fragment_offset > 0``) carries a slice
+        from the middle of the original payload — no upper-layer header
+        exists at its start — so the chain ends here for those.
+        """
+        if self.fragment_offset > 0:
+            return None
         return _ip_protocol_class(self.protocol)
 
     @property

{netprotocols-1.0.0 → netprotocols-1.0.1}/tests/conftest.py

@@ -2,11 +2,47 @@
 
 Sources include the Wireshark sample captures at
 https://wiki.wireshark.org/SampleCaptures (arp-storm.pcap, among
-others) and locally captured frames.
+others), locally captured frames, and the real-capture corpus under
+``tests/fixtures/`` (see its MANIFEST.md).
 """
 
+import struct
+from pathlib import Path
+
 import pytest
 
+FIXTURES = Path(__file__).parent / "fixtures"
+
+
+def read_pcap(path: Path) -> list[bytes]:
+    """Minimal classic-pcap reader for the fixture corpus (test-only;
+    independent of any library or application pcap code)."""
+    data = path.read_bytes()
+    magic = data[:4]
+    if magic in (b"\xa1\xb2\xc3\xd4", b"\xa1\xb2\x3c\x4d"):
+        endian = ">"
+    elif magic in (b"\xd4\xc3\xb2\xa1", b"\x4d\x3c\xb2\xa1"):
+        endian = "<"
+    else:
+        raise ValueError(f"{path.name}: not a pcap")
+    frames = []
+    cursor = 24
+    while cursor + 16 <= len(data):
+        (incl_len,) = struct.unpack_from(f"{endian}I", data, cursor + 8)
+        cursor += 16
+        frames.append(data[cursor : cursor + incl_len])
+        cursor += incl_len
+    return frames
+
+
+def corpus_frames() -> list[tuple[str, int, bytes]]:
+    """Every corpus frame as ``(pcap_name, index, frame_bytes)``."""
+    return [
+        (pcap.name, index, frame)
+        for pcap in sorted(FIXTURES.glob("*.pcap"))
+        for index, frame in enumerate(read_pcap(pcap))
+    ]
+
 
 @pytest.fixture
 def raw_eth_header() -> bytes:

netprotocols-1.0.1/tests/fixtures/MANIFEST.md

@@ -0,0 +1,48 @@
+# Real-capture fixture corpus
+
+Captured 2026-08-29 with `scripts/capture_fixtures.sh` (tcpdump on `lo`
+and the default interface) and validated by
+`scripts/check_fixtures.py`: **every frame's checksums verify
+internally** (IPv4 header, TCP/UDP pseudo-header, ICMPv4/v6). Frames
+used as checksum ground truth were captured **inbound only** — outbound
+frames routinely leave checksums to NIC offload. 56 frames across 10
+scenarios. Addresses are as-captured from the capture host's network.
+
+| File | Frames | Contents |
+|---|---|---|
+| `arp_exchange.pcap` | 4 | ARP requests ×3 + reply ×1 (fresh exchange after neighbor flush) |
+| `icmpv4_echo_lo.pcap` | 6 | Loopback echo request/reply pairs (types 8 and 0) |
+| `icmpv4_external.pcap` | 2 | Inbound echo replies from 1.1.1.1 |
+| `icmpv4_ttl_exceeded.pcap` | 3 | Time Exceeded (type 11) errors from intermediate hops |
+| `icmpv6_echo_lo.pcap` | 6 | Loopback ICMPv6 echo pairs (types 128/129) |
+| `ipv4_fragments.pcap` | 5 | Fragmented 2028-byte echo replies: first fragments (offset 0, MF) + non-first fragments |
+| `ipv6_ndp_mld.pcap` | 10 | NDP Neighbor Solicitation/Advertisement (135/136) + echo 128/129 |
+| `tcp_http.pcap` | 4 | Inbound HTTP-port segments over IPv6: ACK, PSH-ACK ×2, FIN-ACK — all carrying options |
+| `tcp_https.pcap` | 12 | Inbound HTTPS segments over IPv4 (7) and IPv6 (5): ACK/PSH-ACK with options |
+| `udp_dns.pcap` | 4 | DNS responses (src port 53) over IPv4 (1) and IPv6 (3), with payloads |
+
+Consumed by `tests/test_corpus.py` (corpus-wide invariants +
+representative field asserts), mirrored into Packet-Sniffer's test
+suite, and later reused as fuzz seeds and pcap-replay goldens.
+
+## Known gaps (pending `scripts/capture_fixtures_supplement.sh`)
+
+- **MLD behind a hop-by-hop extension header** — the original capture
+  filter used BPF `icmp6`, which matches only `next_header == 58`
+  *directly*; MLD hides behind hop-by-hop (`next_header == 0`) and was
+  filtered out. The supplement captures `ip6 proto 0`.
+- **IPv6 fragment pair** — no fragmented IPv6 traffic was generated in
+  the first run; the supplement sends an oversized `ping -6`.
+- No inbound SYN-ACK was caught (handshake timing vs. capture start);
+  options-bearing segments are otherwise abundant.
+- Unknown-EtherType frames are exercised by deliberately synthetic
+  fixtures in the unit tests (their point is being unknown), not by the
+  corpus.
+
+## Provenance note
+
+This corpus exposed a real defect on arrival: non-first IPv4 fragments
+were chained into garbage upper-layer decodes ("ICMPv4 type 192" from
+mid-payload bytes) because `IPv4.next_protocol()` ignored
+`fragment_offset`. Fixed alongside the corpus's introduction; see
+`tests/test_corpus.py::TestFragmentHandling`.

netprotocols-1.0.1/tests/test_corpus.py

@@ -0,0 +1,167 @@
+"""Corpus-wide invariants over the real-capture fixtures.
+
+Every frame in tests/fixtures/ was captured from live traffic and
+validated for internal checksum consistency by scripts/check_fixtures.py
+before being committed (see tests/fixtures/MANIFEST.md). These tests
+hold the library to its contract against all of them at once.
+"""
+
+import contextlib
+
+import pytest
+
+from conftest import FIXTURES, corpus_frames, read_pcap
+from netprotocols import (
+    ARP,
+    TCP,
+    UDP,
+    Ethernet,
+    ICMPv4,
+    ICMPv6,
+    IPv4,
+    IPv6,
+    Protocol,
+    ProtocolError,
+)
+
+CORPUS = corpus_frames()
+
+
+def walk(frame: bytes) -> tuple[list[Protocol], int]:
+    """The documented chain walk; returns (layers, bytes consumed)."""
+    layers: list[Protocol] = []
+    cursor = 0
+    protocol: type[Protocol] | None = Ethernet
+    while protocol is not None:
+        header = protocol.decode(frame[cursor:])
+        layers.append(header)
+        cursor += header.header_len
+        protocol = header.next_protocol()
+    return layers, cursor
+
+
+def corpus_ids() -> list[str]:
+    return [f"{name}#{index}" for name, index, _ in CORPUS]
+
+
+class TestCorpusInvariants:
+    def test_corpus_is_present_and_generous(self):
+        assert len(CORPUS) >= 40
+        assert len(list(FIXTURES.glob("*.pcap"))) >= 10
+
+    @pytest.mark.parametrize(
+        "frame", [f for _, _, f in CORPUS], ids=corpus_ids()
+    )
+    def test_decodes_raising_nothing_outside_protocol_error(self, frame):
+        # ProtocolError is acceptable by contract; nothing else is.
+        with contextlib.suppress(ProtocolError):
+            walk(frame)
+
+    @pytest.mark.parametrize(
+        "frame", [f for _, _, f in CORPUS], ids=corpus_ids()
+    )
+    def test_every_layer_round_trips_byte_exactly(self, frame):
+        layers, _ = walk(frame)
+        cursor = 0
+        for layer in layers:
+            assert bytes(layer) == frame[cursor : cursor + layer.header_len]
+            cursor += layer.header_len
+
+    @pytest.mark.parametrize(
+        "frame", [f for _, _, f in CORPUS], ids=corpus_ids()
+    )
+    def test_consumption_never_exceeds_frame(self, frame):
+        _, consumed = walk(frame)
+        assert consumed <= len(frame)
+
+
+class TestCorpusCoverage:
+    """The corpus must keep exercising every protocol the library ships."""
+
+    def test_protocol_coverage(self):
+        seen = {
+            type(layer) for _, _, frame in CORPUS for layer in walk(frame)[0]
+        }
+        assert {Ethernet, ARP, IPv4, IPv6, ICMPv4, ICMPv6, TCP, UDP} <= seen
+
+    def test_arp_covers_both_operations(self):
+        opers = {
+            layer.oper
+            for _, _, frame in CORPUS
+            for layer in walk(frame)[0]
+            if isinstance(layer, ARP)
+        }
+        assert {1, 2} <= opers
+
+    def test_tcp_options_present_in_real_traffic(self):
+        assert any(
+            layer.options
+            for _, _, frame in CORPUS
+            for layer in walk(frame)[0]
+            if isinstance(layer, TCP)
+        )
+
+
+class TestFragmentHandling:
+    """Regression: real fragmented traffic exposed that IPv4 chained
+    non-first fragments into garbage upper-layer decodes (mid-payload
+    bytes decoded as 'ICMPv4 type 192')."""
+
+    def fragments(self) -> list[IPv4]:
+        frames = read_pcap(FIXTURES / "ipv4_fragments.pcap")
+        layers = [walk(frame)[0] for frame in frames]
+        return [stack[1] for stack in layers if isinstance(stack[1], IPv4)]
+
+    def test_corpus_contains_a_fragment_pair(self):
+        offsets = {ip.fragment_offset for ip in self.fragments()}
+        assert 0 in offsets
+        assert any(offset > 0 for offset in offsets)
+
+    def test_non_first_fragments_do_not_chain(self):
+        for ip in self.fragments():
+            if ip.fragment_offset > 0:
+                assert ip.next_protocol() is None
+
+    def test_first_fragments_chain_to_real_icmp(self):
+        for ip in self.fragments():
+            if ip.fragment_offset == 0:
+                assert ip.next_protocol() is ICMPv4
+
+
+class TestRepresentativeFrames:
+    """Hand-verified field asserts, one frame per scenario family."""
+
+    def test_ttl_exceeded_error_message(self):
+        frame = read_pcap(FIXTURES / "icmpv4_ttl_exceeded.pcap")[0]
+        layers, _ = walk(frame)
+        assert [type(layer) for layer in layers] == [Ethernet, IPv4, ICMPv4]
+        icmp = layers[2]
+        assert isinstance(icmp, ICMPv4)
+        assert icmp.type == 11
+        assert icmp.type_name == "Time Exceeded"
+
+    def test_loopback_echo_pair(self):
+        frames = read_pcap(FIXTURES / "icmpv4_echo_lo.pcap")
+        types = [walk(frame)[0][2].type for frame in frames]  # type: ignore[attr-defined]
+        assert 8 in types and 0 in types
+
+    def test_ndp_neighbor_discovery(self):
+        frames = read_pcap(FIXTURES / "ipv6_ndp_mld.pcap")
+        types = {
+            layer.type
+            for frame in frames
+            for layer in walk(frame)[0]
+            if isinstance(layer, ICMPv6)
+        }
+        assert 135 in types  # Neighbor Solicitation
+        assert 136 in types  # Neighbor Advertisement
+
+    def test_dns_responses_over_both_ip_versions(self):
+        frames = read_pcap(FIXTURES / "udp_dns.pcap")
+        stacks = [[type(layer) for layer in walk(frame)[0]] for frame in frames]
+        assert any(stack[1] is IPv4 and stack[2] is UDP for stack in stacks)
+        assert any(stack[1] is IPv6 and stack[2] is UDP for stack in stacks)
+        for frame in frames:
+            udp = walk(frame)[0][2]
+            assert isinstance(udp, UDP)
+            assert udp.src_port == 53

{netprotocols-1.0.0 → netprotocols-1.0.1}/uv.lock

@@ -353,7 +353,7 @@ wheels = [
 
 [[package]]
 name = "netprotocols"
-version = "1.0.0"
+version = "1.0.1"
 source = { editable = "." }
 
 [package.dev-dependencies]