AGENTS.md · secdev/scapy

Sections

1. Code guidelines for Agents
2. Put code in the right place
3. Preparing commits, pull requests or advisories messages
4. When adding UTScapy tests
5. Check source changes
6. Do not hand-edit generated content
7. Potential security bugs

First lines (shown under the repo's GPL-2.0 license)

# Scapy checkout instructions for agents

[`CONTRIBUTING.md`](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`](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`](.github/skills/scapy-packet-fields/SKILL.md).

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

## Reviewing changes

For code reviews and re-reviews, use
[`scapy-code-review`](.github/skills/scapy-code-review/SKILL.md). Apply its
checklist only when relevant.

- Establish the actual base and head revisions. Read the original code,
  related callers, existing tests, review discussion, and subsequent fixes.
- Verify findings from a concrete trigger through the affected code to its
  observable consequence. Separate pre-existing issues from regressions and
  label untested conclusions as code-inspection only.
- For protocol changes, check wire details against a specification or
  independent packet bytes; round-trip tests alone can preserve symmetric
  encoding mistakes. Preserve Scapy's ability to craft explicit malformed
  values.
- Keep findings concise, actionable, linked to the affected lines, and within
  the user's requested scope. Do not report speculative style preferences.
- For possible security vulnerabilities, follow `SECURITY.md` and its private
  reporting process; do not post vulnerability details in a public review.

## Preparing commits, pull requests or advisories messages

Follow [`CONTRIBUTING.md`'s guidance on AI-assisted reports and PRs](CONTRIBUTING.md#ai-assisted-reports-and-prs) and [submitting pull requests](CONTRIBUTING.md#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](CONTRIBUTING.md#tests). Scapy's test suite uses UTScapy `.uts` campaigns under `test/`.

A campaign has this form:

```text
% 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:

```console
./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:

```console
./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](CONTRIBUTING.md#coding-style--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:

```console
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`](SECURITY.md) for classification and reporting. You may use the skill [`scapy-security-audit`](.github/skills/scapy-security-audit/SKILL.md).

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.