Skip to content

AGENTS.md

Latest commit

 

History

History
87 lines (64 loc) · 3.12 KB

AGENTS.md

File metadata and controls

87 lines (64 loc) · 3.12 KB
Raw

Scapy checkout instructions for agents

CONTRIBUTING.md is Scapy's contribution guide; this file is its operational companion for agents working in this checkout, not a replacement.

Put code in the right place

A layer is a Packet subclass with a fields_desc list. For packet, field, binding, and layer-test patterns, use scapy-packet-fields.

  • New protocols may go in either location: scapy/layers/ normally contains protocols found on common networks, while scapy/contrib/ normally contains uncommon or specific protocols.
  • Code in scapy/layers/ should not import scapy/contrib/. Contrib code may import from either location. Contrib modules are loaded with load_contrib() rather than by the default layer loader.
  • Implement protocol-related features in the module containing that protocol. Other features may live in scapy/modules/ or scapy/contrib/.
  • Be especially careful about CPU and memory costs in Scapy core code such as scapy/packet.py; packet initialization is a hot path.

Add UTScapy tests

Follow CONTRIBUTING.md's test requirements. Scapy's test suite uses UTScapy .uts campaigns under test/.

A campaign has this form:

% Packet regression
+ Build and dissect
= Round trip
~ protocol_keyword
packet = Protocol(field=value)
decoded = Protocol(bytes(packet))
decoded.field == value

%, +, and = start a campaign, test set, and unit test. ~ assigns keywords. Unprefixed lines inside a unit test are Python; the truth value of the last expression decides the result.

Run the affected campaign directly while developing, for example:

./test/run_tests -t test/contrib/automotive/autosar/pdu.uts -K tshark -N

Run the portable suite from the repository root with Python and tox installed:

./test/run_tests

Check source changes

Follow CONTRIBUTING.md's coding style and conventions. Flake8 checks scapy/ with an 88-column limit and the per-file exceptions in tox.ini. CI invokes the lint and type-check environments under Python 3.12. Because tox.ini does not select that interpreter for these environments, install tox for Python 3.12 and invoke it explicitly to match CI:

python3.12 -m tox -e flake8
python3.12 -m tox -e mypy

The mypy environment runs both Linux and Windows configurations.

Do not hand-edit generated content

  • Do not modify files in scapy/layers/msrpce/raw/ whose header says they are generated by midl-to-scapy.
  • Update the encoded data in scapy/libs/bluetoothids.py, scapy/libs/manuf.py, and scapy/libs/ethertypes.py through their matching scapy/tools/generate_*.py scripts.

Prepare commits and pull requests

Follow CONTRIBUTING.md's guidance on AI-assisted reports and PRs and submitting pull requests.

Potential security bugs

If a change uncovers something that may be a security bug, follow SECURITY.md for classification and reporting.