secdev / secdev/scapy

`Packet.fields_desc` type annotation is inconsistent with runtime behavior

Open Beginner friendly
#5,018 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
12.6k
Forks
2.2k
Avg merge
1d 4h
Merged PRs (30d)
56

Description

Brief description

Packet.fields_desc supports Packet / Packet_metaclass but typed as List[AnyField]

Scapy version

2.7.0

Python version

3.14

Operating system

Windows11

Additional environment information

No response

How to reproduce

The type annotation for fields_desc on Packet classes is declared as List[AnyField]:

# scapy/packet.py, line 108
fields_desc = []  # type: List[AnyField]

However, at runtime, the Packet_metaclass.__new__ method explicitly handles the case where elements in fields_desc are Packet metaclass instances (i.e., references to other Packet subclasses), not just Field instances:

# scapy/base_classes.py, lines 371-380
        if "fields_desc" in dct:  # perform resolution of references to other packets  # noqa: E501
            current_fld = dct["fields_desc"]  # type: List[Union[scapy.fields.Field[Any, Any], Packet_metaclass]]  # noqa: E501
            resolved_fld = []  # type: List[scapy.fields.Field[Any, Any]]
            for fld_or_pkt in current_fld:
                if isinstance(fld_or_pkt, Packet_metaclass):
                    # reference to another fields_desc
                    for pkt_fld in fld_or_pkt.fields_desc:
                        resolved_fld.append(pkt_fld)
                else:
                    resolved_fld.append(fld_or_pkt)

This means fields_desc can contain:

  1. Field instances — the documented/typed behavior
  2. Packet classes (metaclass instances) — which get inlined/expanded by flattening their fields_desc
Actual result

No response

Expected result

The type should be updated to something like:

fields_desc = []  # type: List[Union[AnyField, Type[Packet]]]
Related resources

No response

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the fields_desc annotation in scapy/packet.py, then read the Packet_metaclass.__new__ handling in scapy/base_classes.py around lines 371-380. Confirm that the annotation represents both field instances and referenced Packet classes, and that it matches the runtime flattening behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
networking
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.