Support multiple entries in IPOption_Timestamp

[itzzdev09]

Fixes #4513

Problem

RFC 791 says the originating host "must compose this option with a large enough timestamp data area to hold all the timestamp information expected", so that each router along the path can append an entry.

IPOption_Timestamp modelled exactly one entry — a single conditional internet_address plus a single timestamp. There was no way to reserve room for more, so a target host had nowhere to record its timestamp and would reply with the overflow flag set.

Change

The data area is now a list, sized from the option length on dissection, following the pattern IPOption_RR already uses for routers:

• flg=0 (timestamp_only) → timestamps, a list of 32-bit timestamps.
• flg=1/flg=3 → pairs, a list of IPOption_Timestamp_Pair (an internet address followed by its timestamp).

Reserving space for four replies now works:

>>> raw(IPOption_Timestamp(pairs=[IPOption_Timestamp_Pair() for _ in range(4)]))
# 36 bytes, length field = 36

and dissection round-trips:

>>> p = IPOption_Timestamp(b'D\x14\x05\x01\xc0\xa8\x0f\x07\x00\x00\x00\x01\n\x00\x00\x01\x00\x00\x00\x02')
>>> [(e.internet_address, e.timestamp) for e in p.pairs]
[('192.168.15.7', 1), ('10.0.0.1', 2)]

Notes for review

Two deliberate decisions worth flagging:

1. This replaces the internet_address / timestamp fields. Callers move to pairs=[IPOption_Timestamp_Pair(internet_address=..., timestamp=...)] or timestamps=[...]. I couldn't see a way to keep the scalar names while supporting a list of interleaved address/timestamp pairs; happy to add compatibility properties if you'd like.

2. Defaults are empty lists, matching IPOption_RR, so pointer now defaults to 5 — the RFC minimum, pointing at the first free octet — instead of 9, which assumed one entry was already present. A non-empty default is not safe here: scapy shallow-copies list defaults (value.copy() in Packet.do_init_cached_fields), so a Packet inside a default list would be shared across instances. I verified that with a mutation test while developing this.

The two existing assertions in inet.uts are updated to the new spelling and keep their original expected bytes; the checksum test keeps its 12-byte option (and so its existing checksum) by passing one explicit empty pair.

Test plan

• UTscapy -t test/scapy/layers/inet.uts → 67 passed, 0 failed (same as before the change).
• New assertions cover multi-entry build for both flg shapes and dissection back into the lists.
• flake8 scapy/layers/inet.py with the project config: 15 pre-existing issues before and after, none introduced.

[itzzdev09]

Disclosure, per the "AI-assisted reports and PRs" section of CONTRIBUTING: this PR was drafted with AI assistance (Claude Code, Claude Opus 5). I should have said so in the original description — apologies for the omission.

Everything in it was verified by running it rather than assumed:

• UTscapy -t test/scapy/layers/inet.uts passes 67/67, the same count as before the change.
• The multi-entry build and dissection cases in the new assertions were checked against hand-written expected bytes.
• flake8 scapy/layers/inet.py with the project config reports the same 15 pre-existing issues before and after — none introduced.
• The two updated assertions keep their original expected bytes, and the checksum test keeps its original checksum by passing one explicit empty pair.

One thing worth calling out, since it drove a design decision: a non-empty PacketListField default is not safe here. Packet.do_init_cached_fields shallow-copies list defaults via value.copy(), so a Packet inside the default list ends up shared across instances. I hit that with a mutation test while developing, which is why the defaults are empty lists as in IPOption_RR.

Happy to adjust anything, including the field naming, if you'd prefer a different shape.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.33%. Comparing base (23808d9) to head (24ee34b).
⚠️ Report is 9 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #5117      +/-   ##
==========================================
- Coverage   80.63%   80.33%   -0.30%     
==========================================
  Files         390      390              
  Lines       96895    96908      +13     
==========================================
- Hits        78127    77850     -277     
- Misses      18768    19058     +290     

Files with missing lines	Coverage Δ
scapy/layers/inet.py	72.03% <100.00%> (+0.09%)	⬆️

... and 27 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.