Skip to content

AGENTS.md

Latest commit

 

History

History
110 lines (82 loc) · 6.88 KB

AGENTS.md

File metadata and controls

110 lines (82 loc) · 6.88 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.

Code guidelines for Agents

  • Follow the coding guidelines from CONTRIBUTING.md
  • Follow the code patterns that already exist in the file you are editing, in similar layers when editing a layer (in both layers/ or contrib/) or in the rest of the project. Some of those guidelines are detailed below.
  • Do not declare functions for very simple checks or operations. Prefer code readability over trying to reduce code duplication.
  • Never declare a function that is only used once, unless it is meant to be a public API.
  • Avoid silent exception suppression (try: ... except Exception: pass or bare except: pass). Catch specific exception types (e.g., (AttributeError, OSError)). When the exception is unexpected, log the caught exception using scapy.error.log_runtime.debug(...) or the module's child logger (e.g., protocol_log.debug(...)), or document explicitly why suppression is necessary. Use WARNING or above only against bugs or unexpected behaviors.
  • Do not introduce backward-compatibility alias redefinitions for new or modified symbols introduced within the current branch or PR. Rename symbols directly at their original definition site and update all references across the codebase.
  • Adhere strictly to protocol prefix naming conventions: prefix lowercase functions and module-level variables with <protocol>_ (e.g., protocol_scan, protocol_log), uppercase constants and registries with <PROTOCOL>_ (e.g., PROTOCOL_GLOBAL_ADDRESS, PROTOCOL_MANUFACTURERS), and classes with <Protocol> (e.g., ProtocolNativeSocket).
  • Never import internal methods or constants (those starting with a leading underscore) across modules. If a function or constant is shared across multiple modules, make it public by removing the leading underscore and prefixing it with the protocol prefix.
  • Place all imports at the top of the file. Do not use local/deferred imports inside functions or methods unless strictly required to prevent circular import dependencies.
  • Keep all import blocks and __all__ lists sorted alphabetically.
  • Packet layer classes (Packet subclasses) bound to other protocols must declare explicit bind_layers() bindings.

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 the skill 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.

Preparing commits, pull requests or advisories messages

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

You MUST follow the following guidelines, or the report may be dismissed:

  • You MUST use a perfectly neutral English. Only state factual statements, never use superlatives.
  • You MUST focus on keeping the commit messages, PR messages or advisory reports as succint as possible. Stick to the bare minimum: one or two sentences explaining the bug, some code or a pcap that reproduces the issue, and optionally a fix suggestion, that's it.
  • Use github links to point towards the lines you are talking about.
  • Assume that readers / maintainers know how most of the code works already.
  • Do NOT talk about whether tests pass or not, or coverage, since those are already shown by github.
  • ALWAYS disclose that the message was written with the help of AI. For instance: *This message was written with the help of AI (GPT-5.6-Cyber).*.

When adding 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

Please note the following guidelines when adding tests:

  • Do not create a new .uts if there is already a file that contains tests for that layer. Only create a .uts file when no previous tests exist for that layer.
  • When adding tests to an existing .uts file, try to place the tests contextually close to tests that are related to the same or similar features.

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.

Potential security bugs

If a change uncovers something that may be a security bug, follow SECURITY.md for classification and reporting. You may use the skill scapy-security-audit.

Security findings that are researched or found using AI MUST include code that reproduces the issue, and draft a pull request on the Github Advisories Private Repositories with code to patch said issue. If it is impossible to provide code that reproduces the issue, a short explanation of why must be provided.