netprotocols 2.6.0__tar.gz → 2.7.0__tar.gz

{netprotocols-2.6.0 → netprotocols-2.7.0}/.github/workflows/ci.yml

@@ -33,7 +33,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           python-version: "3.12"
       - run: uv run ruff check
@@ -43,7 +43,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           python-version: "3.12"
       - run: uv run mypy
@@ -55,7 +55,7 @@ jobs:
         python-version: ["3.12", "3.13", "3.14"]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           python-version: ${{ matrix.python-version }}
       - run: uv run --frozen pytest --cov=netprotocols --cov-report=term
@@ -70,7 +70,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           python-version: "3.12"
       - name: Export dev dependencies
@@ -86,7 +86,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
       - run: uv build
       - run: uv run --isolated --no-project --with dist/*.whl python -c "import netprotocols; print(netprotocols.__version__)"
       # Builds are supposed to be a pure function of the source tree, so
@@ -119,11 +119,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           python-version: "3.12"
       - run: uv build
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
           node-version: "22"
       - run: npm ci
@@ -151,7 +151,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           python-version: "3.12"
       - name: Corpus decode throughput

netprotocols-2.7.0/.github/workflows/codeql.yml

@@ -0,0 +1,100 @@
+name: CodeQL
+
+# Advanced-setup workflow (a checked-in file) rather than GitHub's
+# built-in "default setup", so this analysis lives in version control
+# alongside the rest of this repository's CI (ci.yml, fuzz.yml,
+# release.yml, mutation.yml, scorecard.yml) and its action pins are
+# reviewable the same way theirs are. Default setup is configured
+# through repository settings instead of a file, so it isn't available
+# to author from here.
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+  schedule:
+    # Arbitrary; weekly on Sundays, clear of fuzz.yml's and mutation.yml's
+    # daily 03:00/04:00 UTC slots and scorecard.yml's own Sunday 05:00
+    # UTC slot.
+    - cron: "0 6 * * 0"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  analyze:
+    name: Analyze (python)
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      # Python is interpreted, so there is nothing for autobuild (or a
+      # manual build step) to do: build-mode: none has CodeQL extract
+      # the database straight from source instead. This is the build
+      # mode the CodeQL Action's own docs recommend for interpreted
+      # languages, and it sidesteps the question of an autobuild step
+      # fitting this project's uv-based build at all.
+      - uses: github/codeql-action/init@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
+        with:
+          languages: python
+          build-mode: none
+
+      # analyze writes the SARIF without uploading it, the filter step
+      # drops one query's results on two paths, and upload-sarif uploads
+      # what is left. py/weak-sensitive-data-hashing flags the MD5 that
+      # RADIUS (#265) and STUN (#267) mandate, which their tests and
+      # scripts/check_fixtures.py compute over published test secrets
+      # with usedforsecurity=False to verify captured traffic.
+      # The CodeQL config can't scope a query to paths: query-filters
+      # drops it everywhere, src/ included, and paths-ignore drops the
+      # paths from every query. So the filter removes only that query's
+      # results whose primary location is under tests/ or scripts/; the
+      # query still runs on src/, every other query on all three.
+      #
+      # upload: failure-only is the action's documented mode for a
+      # workflow that post-processes the SARIF: analyze uploads nothing
+      # when it succeeds. It still marks the analysis as completed, so
+      # init's post step does not upload a failed-run SARIF for a later
+      # step's failure either: if the filter or upload-sarif fails, the
+      # job goes red and no new analysis replaces the previous one
+      # (upload-sarif can fail after uploading, while it waits for
+      # processing). That fails closed; unfiltered SARIF is never
+      # uploaded. (Any value the action does not recognize means
+      # `always`, which would upload before the filter runs.)
+      #
+      # Neither analyze nor upload-sarif sets `category`, and that is
+      # what keeps the analysis the same one: with no category the CLI
+      # writes no runs[].automationDetails, and both actions then fill
+      # it in from the workflow path, job id and matrix,
+      # ".github/workflows/codeql.yml:analyze/", the same in both
+      # steps of this job. Existing alerts keep tracking (fixed ones
+      # close, the rest stay) rather than reappearing under a new
+      # category. Setting one on either step alone would start a second
+      # analysis next to the first.
+      - id: analyze
+        uses: github/codeql-action/analyze@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
+        with:
+          upload: failure-only
+
+      # Rewrites each *.sarif under analyze's output directory, at any
+      # depth and skipping symlinks (as upload-sarif finds them), in
+      # place and logs one line per file, by its path under the
+      # directory, naming every result it dropped; malformed SARIF fails
+      # the job instead of uploading unfiltered results.
+      # Stdlib only, so the runner's own python3 runs it.
+      - name: Drop weak-hashing results on tests/ and scripts/
+        env:
+          SARIF_DIR: ${{ steps.analyze.outputs.sarif-output }}
+        run: python3 scripts/filter_codeql_sarif.py "$SARIF_DIR"
+
+      - uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
+        with:
+          sarif_file: ${{ steps.analyze.outputs.sarif-output }}

{netprotocols-2.6.0 → netprotocols-2.7.0}/.github/workflows/fuzz.yml

@@ -38,7 +38,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           python-version: "3.12"
       # Keyed by run id with a prefix restore-key: a fixed key would
@@ -65,7 +65,7 @@ jobs:
       # repo write access to re-run the job locally.
       - name: Upload the failing example database
         if: failure()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: hypothesis-nightly-failure-${{ github.run_id }}
           path: .hypothesis
@@ -85,7 +85,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           python-version: "3.12"
       - name: Run Atheris against decode_frame
@@ -98,7 +98,7 @@ jobs:
             python tests/fuzz/fuzz_http_decode.py -max_total_time=300
       - name: Upload crash artifacts
         if: failure()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: atheris-crash-${{ github.run_id }}
           path: crash-*

{netprotocols-2.6.0 → netprotocols-2.7.0}/.github/workflows/mutation.yml

@@ -30,7 +30,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           python-version: "3.12"
       # mutmut hashes each mutated file plus the tests that cover it and
@@ -104,7 +104,7 @@ jobs:
       # doesn't exist is silently skipped.
       - name: Upload mutmut results on failure
         if: failure()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: mutmut-nightly-failure-${{ github.run_id }}
           path: |

{netprotocols-2.6.0 → netprotocols-2.7.0}/.github/workflows/release.yml

@@ -35,7 +35,7 @@ jobs:
       contents: read
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
       - run: uv build
       # The QA ladder cannot catch a mistagged release: every check
       # passes because the code is fine and only the tag is wrong. Read
@@ -99,7 +99,7 @@ jobs:
             --pyproject pyproject.toml --mc-type library \
             -o "netprotocols-${GITHUB_REF_NAME#v}.cdx.json"
       - name: Upload release assets
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: release-assets
           path: |
@@ -123,7 +123,7 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Download release assets
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           name: release-assets
       # CHANGELOG.md is the single source of truth for release notes, so

{netprotocols-2.6.0 → netprotocols-2.7.0}/.github/workflows/scorecard.yml

@@ -48,7 +48,7 @@ jobs:
       # Upload the SARIF results as a workflow artifact, per the action's
       # standard setup.
       - name: Upload artifact
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: SARIF file
           path: results.sarif
@@ -56,6 +56,6 @@ jobs:
 
       # Upload the results to GitHub's code scanning dashboard.
       - name: Upload to code-scanning
-        uses: github/codeql-action/upload-sarif@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
+        uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
         with:
           sarif_file: results.sarif

{netprotocols-2.6.0 → netprotocols-2.7.0}/ARCHITECTURE.md

@@ -214,6 +214,42 @@ raises. Ethernet's zero padding reaches only a message with no entries,
 since one entry already fills the minimum frame. See
 [`layer7/rip.py`](src/netprotocols/layer7/rip.py)'s module docstring.
 
+`NTP` is the same case: after its 48-byte header come NTPv4 extension
+fields (RFC 7822) and a MAC, both optional, up to the end of the UDP
+datagram, which nothing in the message bounds. It keeps the whole
+buffer after the header, so `bytes(NTP.decode(x)) == x`, and its
+accessors split it: extension fields until what is left has a MAC's
+length (4, 20 or 24 bytes, the rule RFC 7822 §3's minimum field length
+is there for), then the MAC, and anything else as `remainder`. A
+4-byte Ethernet FCS after a plain message has a crypto-NAK's length,
+and only the UDP length could tell them apart. Past the header
+neither `decode()` nor any accessor raises, and Ethernet's padding
+never reaches it: the header alone fills the minimum frame. See
+[`layer7/ntp.py`](src/netprotocols/layer7/ntp.py)'s module docstring.
+
+`TFTP` has no length field either, but most of its messages bound
+themselves: an ACK is 4 bytes, an ERROR ends at the zero byte after its
+message, and a request or an OACK after its last whole option pair, a
+zero byte where the next name would start ending the options. So it
+obeys rule 3 like a header with a length field,
+`bytes(TFTP.decode(x)) == x[:header_len]`, and leaves Ethernet's
+padding (which every ACK, at 4 bytes, gets in an untagged frame over
+IPv4 with no options) and an FCS undecoded, except that a trailer
+holding a zero byte can be read in, which only the UDP length could
+rule out (#235): after a name with no value, the trailer's first zero
+byte ends that value, so padding decodes `("tsize", "")` and takes one
+byte, and after whole pairs an FCS that holds a name, a zero byte, a
+value and a zero byte, such as `12 00 34 00`, reads as one more pair. A
+DATA message cannot bound itself at all: its data has no terminator, so
+it runs to the end of the buffer, and a trailer joins it, as it joins
+an ICMP `body`. Its
+strings are terminated rather than length-prefixed, so a missing
+terminator is TFTP's truncation case: a filename, mode or error message
+with no zero byte after it raises `TruncatedHeaderError`, as a lying
+length does in rule 2, while an option pair cut short is left undecoded,
+since only UDP's length could tell it from a trailer. See
+[`layer7/tftp.py`](src/netprotocols/layer7/tftp.py)'s module docstring.
+
 `VRRP` has no length field either, but needs no walk: its version and
 address count give its exact length (8 bytes, the addresses, and
 VRRPv2's 8 bytes of authentication data), so it obeys rule 3 like a
@@ -363,12 +399,15 @@ unless the Security Association uses a confidentiality-free transform
 (e.g. NULL, RFC 2410, or AES-GMAC, RFC 4543), and at an offset only
 the SA determines, so the decoder never reads it).
 
-`BGP`, `MPLS` and `LLC` are the three exceptions: they answer from
-decode context rather than from a wire field alone. A BGP message
+`BGP`, `STUN`, `MPLS` and `LLC` are the four exceptions: they answer
+from decode context rather than from a wire field alone. A BGP message
 carries no payload: a TCP segment can hold several messages back to
 back, each decoded as its own layer, so `BGP.next_protocol()` names the
 next message *beside* it — `BGP` when the bytes after this message
-begin another one, `None` when they do not. An MPLS label stack carries
+begin another one, `None` when they do not. STUN over TCP is the same
+case, and `STUN.next_protocol()` answers `STUN` the same way, when the
+8 bytes after the message begin like a message's header, its magic
+cookie in place. An MPLS label stack carries
 a packet but no field naming its protocol (see *MPLS: dispatch by
 convention* below), so `MPLS.next_protocol()` infers one, partly from
 the first byte after the stack. SAP 0x42 carries GARP's PDUs (Protocol
@@ -382,11 +421,12 @@ records what it saw on the instance in a field kept out of the
 dataclass's comparison and hash (`compare=False`, the mechanism `HTTP`
 uses for its `_message` parse cache). Two equal headers compare equal
 however they were found, and can still chain differently. The rules of
-the decode contract hold for all three unchanged; see *Port-based
+the decode contract hold for all four unchanged; see *Port-based
 dispatch is best-effort* below,
 [`_base.py`](src/netprotocols/_base.py)'s *Decode context in
 next_protocol*, the module docstrings of
-[`layer7/bgp.py`](src/netprotocols/layer7/bgp.py) and
+[`layer7/bgp.py`](src/netprotocols/layer7/bgp.py),
+[`layer7/stun.py`](src/netprotocols/layer7/stun.py) and
 [`layer2/mpls.py`](src/netprotocols/layer2/mpls.py), and
 [`layer2/llc.py`](src/netprotocols/layer2/llc.py)'s *DSAP 0x42*.
 
@@ -453,8 +493,15 @@ flowchart LR
   U -->|4789| VX[VXLAN]
   VX -->|always| E
   U -->|520| R[RIP]
+  U -->|69, the request only| TF[TFTP]
+  U -->|1812, 1813| RAD[RADIUS]
+  U -->|123| NT[NTP]
+  U -->|1985| HS[HSRP]
   T -->|179| BGP[BGP message]
   BGP -->|another message in the segment| BGP
+  U -->|3478| STUN[STUN message]
+  T -->|3478| STUN
+  STUN -->|another message in the segment| STUN
 ```
 
 IPv6 extension headers (Hop-by-Hop Options, Routing, Fragment,
@@ -722,7 +769,7 @@ header cannot reject more than it does: RFC 7348 says to ignore its
 reserved bits, so rejecting those would refuse real traffic, such as
 the Group Based Policy extension's.
 
-RIP on UDP 520 rejects the most, because two of its four header bytes
+RIP on UDP 520 rejects far more, because two of its four header bytes
 have values no RIP message carries: `RIP.decode()` requires version 1
 or 2 and a nonzero command, which 510 of the 65,536 two-byte prefixes
 satisfy, so about 99.2% of random datagrams are rejected. Measured the
@@ -736,6 +783,112 @@ does a RIPv1 message with nonzero must-be-zero fields, which RFC 1058
 tells a receiver to ignore but a decoder should show. Past the header,
 any 20 bytes are an entry.
 
+RADIUS on UDP 1812 and 1813 (RFC 2865, RFC 2866) rejects a little
+more again, through its Length alone: `RADIUS.decode()` requires at least
+the 20 bytes of its header (`InvalidFieldError` below that) and no more
+than the buffer holds (`TruncatedHeaderError` past it). A random
+300-byte payload therefore passes only when its third and fourth bytes
+read 20-300, 281 of 65,536 values, and one of n bytes with n - 19 of
+them, which over lengths drawn uniformly from 0-600 averages 281 too.
+Measured the same way (`random.Random` seeds 0-2), the walk stopped
+for about 99.6% in each case (99.57% expected): the 300-byte payloads
+and the 0-600 byte ones, padded or not, on either port. The Code is
+not checked: every value decodes, and the codes of RFC 2865, RFC 2866,
+RFC 5997 and RFC 5176 are named (IANA assigns others, such as 6-10,
+21-34 and 50-52, which are not). Nor are the attributes: a packet
+whose attribute list does not walk still decodes, and
+`parsed_attributes` raises when asked, so an accepted guess can still
+read as garbage. Bytes past the Length are padding (RFC 2865 §3) and
+stay undecoded, past `packet.consumed`. The walk does not yet end the
+buffer at UDP's length (#235), though, so a Length that overstates the
+datagram reaches into whatever follows it in the frame, such as an
+Ethernet FCS, and reads it as attributes instead of raising. Only 1812
+and 1813 are registered: the legacy 1645 and 1646, and Dynamic
+Authorization's 3799 (RFC 5176, whose Disconnect and CoA packets share
+the format), need `decode_as`.
+
+TFTP on UDP 69 (RFC 1350) rejects more: `TFTP.decode()` requires an
+opcode of 1-6, which 6 of the 65,536 two-byte prefixes are, and then the
+mandatory fields that opcode carries, whole. Measured the same way, over
+three seeds, the walk stopped for 99.98-100% of the 300-byte payloads
+sent to 69 and of the 0-600 byte ones unpadded and padded: about 5 of
+the 90,000 decoded a `TFTP` layer, a count small enough to vary by a few
+between runs. The opcode alone lets through 6 in 65,536, about 8 of
+90,000; of those, a DATA, ACK or OACK almost always decodes, but an RRQ
+or WRQ needs two zero bytes after its opcode and an ERROR one after its
+code, which random bytes lack about two thirds and one third of the
+time, so about 6 are expected. What the port cannot do is find the
+transfer. Only the request goes to port 69: the server answers from an
+ephemeral port of its own, its transfer identifier, and every DATA, ACK,
+OACK and ERROR after that runs between two ephemeral ports (RFC 1350
+§4), which no port table can name. So a stateless walk decodes a `TFTP`
+layer for the RRQ or WRQ alone, and stops at UDP for the rest of the
+transfer, as for any datagram between unregistered ports; of the 33
+frames in `tests/fixtures/tftp.pcap`, the 6 requests decode one. A
+caller who follows the transfer has the server's port from the source
+port of its first reply, and names it for the walk,
+`decode_as={"udp.port": {tid: TFTP}}`, which covers both directions
+since every later datagram has it as one of its two ports; tracking the
+transfer is the caller's, as reassembly is for `HTTP` and `BGP`. A
+server that answers from port 69 itself, which RFC 1350 does not allow,
+has its replies dispatched by the source-port fallback.
+
+NTP on UDP 123 (RFC 5905) rejects less: of the first byte's 256
+values, 96 are a time message, a version from 1 to 4 and a mode other
+than 6 or 7, the control messages (RFC 9327's mode 6, ntpd's private
+mode 7) whose headers `NTP.decode()` does not read; anything shorter
+than the 48-byte header is rejected too. Measured the same way, the
+walk stopped for 61.2-62.9% of the 300-byte payloads (`random.Random`
+seeds 0-2), against the 62.5% the first byte predicts, and for
+65.5-66.3% of the 0-600 byte ones, padded or not: padding never makes
+a payload 48 bytes long. Past the first byte any 47 bytes are a
+header, and the stratum, the Reference ID and the timestamps are not
+judged, so a Kiss-o'-Death and a reserved stratum decode.
+
+The first byte is judged before the length, so every control message
+raises `InvalidFieldError` with `field` `"mode"`, however long, and a
+bad version raises with `field` `"version"`; only a time message's
+first byte, or an empty buffer, can end in `TruncatedHeaderError`.
+That makes real traffic fail a strict walk: `ntpq` (mode 6, a 12-byte
+request and longer responses) and `ntpdc` (mode 7) talk to port 123,
+and `decode_frame()` raises on every one of their messages. Walk them
+with `lax=True`, which keeps Ethernet, IP and UDP and reports the
+rejection as `stopped_by`. A typed way to take a port out of dispatch for one
+walk, and decoding mode 6, are planned follow-ups.
+
+HSRP on UDP 1985 (RFC 2281) rejects far more, though less than BGP and
+STUN below: its first three bytes must be a Version of 0, one of the
+three Op Codes (Hello, Coup, Resign) and one of the six States, which
+18 of the 2^24 values of those bytes are, about one in 932,000, and
+the payload must then hold the whole 20-byte message. Measured the
+same way (`random.Random` seeds 0-2, each 10,000 random 300-byte
+payloads and 10,000 of uniformly random length 0-600, the latter
+walked both unpadded and padded: 90,000 walks to port 1985 in all),
+about 0.1 of those walks are expected to decode an HSRP layer
+(90,000 x 18 / 2^24 = 0.097, a little less in fact, since a few of the
+random-length payloads are too short to reach 20 bytes), and 2 did:
+the same 46-byte payload of seed 2, whose first
+bytes, `00 00 04`, are a Hello in Speak, once unpadded and once padded.
+The other 89,998 ended with `stopped_by` set. Padding cannot make a message,
+since a minimum-size frame leaves 18 bytes after the UDP header. With
+the Version forced to 0,
+`HSRP.decode()` accepted 31 of 100,000 random 300-byte payloads
+(`random.Random(0)`), near the 27 expected. Past those three bytes any
+17 are a message: the timers, the Priority, the Group, the Reserved
+byte, the Authentication Data and the Virtual IP Address are not
+judged.
+
+The guard is also what keeps HSRPv2 (Cisco's TLV-based successor,
+sent to 224.0.0.102 on the same port) from being read as HSRPv1: an
+HSRPv2 message starts with a TLV type, 1, where HSRPv1 has its
+Version, so `HSRP.decode()` rejects every one at `version`, and it
+rejects Cisco's Op Code 3 interface-state Advertise, version 0 but
+laid out as a TLV, at `opcode`. Each byte is judged before the length,
+so either is reported as what it is however short. Neither is decoded,
+and as with NTP's control messages a strict walk raises on them: walk
+such traffic with `lax=True`. Only 1985 is registered; HSRPv2 over
+IPv6 uses port 2029, which nothing here decodes.
+
 BGP on TCP 179 (RFC 4271) has the strongest guard of any port entry:
 every message opens with a 16-byte Marker of all ones, which random
 bytes match once in 2^128, and then a Length and Type whose bounds
@@ -770,6 +923,32 @@ offload off, carries 7. Reassembling
 the stream is the caller's, as it is for `HTTP` below: see
 [`layer7/bgp.py`](src/netprotocols/layer7/bgp.py)'s module docstring.
 
+STUN on UDP and TCP 3478 (RFC 8489, RFC 5389) is guarded nearly as
+well, by its fixed header: the two bits above the Message Type must be
+zero, the 32-bit Magic Cookie `0x2112A442` must follow the Message
+Length, and the Length must be a multiple of 4, so random bytes pass
+once in 2^36, before the Length is held against the buffer. Measured
+the same way, every walk to port 3478 ended with `stopped_by` set and
+none decoded a STUN layer, over UDP for 10,000 random 300-byte payloads
+and 10,000 of uniformly random length 0-600, padded or not, and over
+TCP for 10,000 random 300-byte segments (`random.Random` seeds 0-2).
+With the cookie forced in place, `STUN.decode()` accepted 28 of
+100,000 random 300-byte payloads (`random.Random(0)`), near the 27
+expected: a quarter have the two top bits clear, and 71 of the 65,536
+Lengths are multiples of 4 that fit in the 280 bytes after the header.
+The cookie is also what separates STUN from RFC 3489, its first
+version, whose 16-byte transaction ID took the cookie's place:
+`STUN.decode()` rejects a classic message at `magic_cookie`, which is
+what RFC 5389 put the cookie there for. Over TCP, messages follow one
+another with no framing but their own Length, as BGP's do, and chain
+the same way, so `max_depth` bounds correctness here too: a message
+can be a bare 20-byte header, the default leaves room for 29 after
+Ethernet, IPv4 and TCP, and a 1448-byte segment holds 72, so a strict
+walk of a valid segment can raise `MaxDepthExceededError` and a lax
+one stop short. BGP's two ways past it work the same, with
+`start=STUN`; the corpus's TCP segments carry 2. See
+[`layer7/stun.py`](src/netprotocols/layer7/stun.py)'s module docstring.
+
 A rejected guess takes the ordinary decode-error path: the chain keeps
 the layers it did decode and records the failure. An accepted one
 yields a layer that decoded cleanly and is wrong, and nothing in the
@@ -842,6 +1021,16 @@ one transport that does not use the internet checksum: its CRC32c
 (`crc32c()`, RFC 9260 Appendix A) covers the whole packet with no
 pseudo-header, and goes on the wire least significant byte first, so
 `compute()` returns it byte-swapped to match the field as decoded.
+STUN's FINGERPRINT is a checksum that lives in an attribute rather
+than a header field: the IEEE CRC-32 of the message up to it, XORed
+with `0x5354554E` (RFC 8489 §14.7). `compute()` returns it for a
+message whose last attribute is one, `verify()` accepts a message with
+none, and `with_checksums()` rewrites it. A message has none only when
+its attributes walk whole, none of them a FINGERPRINT, and its last 8
+bytes do not begin like one, so a corrupted earlier Length cannot hide
+it from `verify()`. MESSAGE-INTEGRITY, the keyed
+HMAC beside it, needs the credential's key, which this library never
+has, so it is carried raw, like an AH ICV.
 VRRP's checksum is the internet checksum of the message alone in
 VRRPv2 and behind the IP pseudo-header in VRRPv3. RFC 5798 §5.2.8
 cites only IPv6's pseudo-header; adding IPv4's too is keepalived's
@@ -849,6 +1038,20 @@ default, and `compute()`'s. RFC 9568, which obsoletes RFC 5798, leaves
 it out over IPv4, and `verify()` returns `False` for an advert
 checksummed that way.
 
+Behind an IPv6 Routing header with segments left, RFC 8200 §8.1 puts
+the route's *final* destination in the pseudo-header, while `ip.dst`
+is the next hop. `compute()`, `verify()` and `flow_key()` take the
+Routing header as a keyword-only `routing`, and `Packet.with_checksums()`
+and `Packet.flow_key()` pass the last one with segments left between
+the nearest IP header and the transport (a receiver skips one with
+none left: RFC 8200 §4.4 for unrecognized types, and each type's own
+processing rules, RFC 2460 §4.4, RFC 6554 §4.2 and RFC 8754 §4.3, so
+the route ends at the last that has some).
+`IPv6Routing.final_destination(dst)` resolves it for types 0, 2, 3
+(RPL, from `dst`'s prefix) and 4 (SRH, Segment List[0]); for another
+type, malformed data, no segments left or IPv4 the address stays
+`ip.dst`.
+
 That is also why `SCTP.decode()` bounds its own extent (see "The decode
 contract" above): otherwise Ethernet's padding would land inside the
 CRC's span, and a packet under 46 bytes from a real NIC would fail to
@@ -879,15 +1082,17 @@ src/netprotocols/
 ├── __init__.py     public API re-exports, __version__, registry install
 ├── _base.py        Protocol ABC, decode contract, address helpers
 ├── _tlv.py         walk_kind_length_value(): shared TCP/IPv4/IPv6
-│                   options and PIM Hello options TLV walker
+│                   options, PIM Hello options and STUN attributes
+│                   TLV walker
 ├── _enums.py       EtherType, IPProtocol, ARPOperation (imports nothing)
 ├── registry.py     public dispatch tables: register(), Registry
 ├── walk.py         decode_frame(): the shipped chain walker
 ├── _defaults.py    the built-in decoder map, installed at import
 ├── packet.py       Packet composition, with_checksums(), flow_key()
 ├── checksum.py     RFC 1071 internet_checksum, SCTP's crc32c,
-│                   compute, verify (CDP's odd-byte sum among them),
-│                   OSPF's LSA Fletcher checksum
+│                   compute, verify (CDP's odd-byte sum and STUN's
+│                   FINGERPRINT among them), OSPF's LSA Fletcher
+│                   checksum
 ├── flow.py         FlowKey, flow_key(): canonical bidirectional keys
 ├── pcap.py         read_captures()/read_pcap()/read_pcapng(): classic
 │                   pcap and pcapng readers, from bytes not filenames
@@ -909,7 +1114,12 @@ src/netprotocols/
 │                   dispatch)
 ├── layer7/         dns.py, dhcp.py, http.py (the HTTP/1.1 grammar
 │                   and the HTTP codec class), vxlan.py, rip.py
-│                   (RIPv1 + RIPv2), bgp.py (BGP-4 messages)
+│                   (RIPv1 + RIPv2), bgp.py (BGP-4 messages),
+│                   tftp.py (TFTP, with RFC 2347 options),
+│                   radius.py (RADIUS + RADIUSAttribute),
+│                   stun.py (STUN messages, over UDP and TCP),
+│                   ntp.py (NTPv1-v4 time messages),
+│                   hsrp.py (HSRPv1 Hello, Coup and Resign)
 └── utils/          validators (mac.py, ipv4.py), exceptions.py
 tests/              one file per protocol + test_contract.py
                     (truncation, lying lengths, chain walks),