Development

If you are interested in contribute to the project, this part of the documentation should contain the start point.

The Testing guide guide covers the core unit and integration suites, the test harness, and the recommended commands for local development and CI runs.

Documentation

Documentation can be built using:

$ python3 setup.py doc

This command invokes Sphinx directly and writes the HTML output under docs/_build/html. The docs/Makefile remains available for direct Sphinx workflows.

A build is also available at Read the Docs.

The build process requires several packages and libraries to be available. The operative system libraries required are:

  • pandoc

  • A LaTex environment, for example TexLive on Linux or MikTex on Windows.

For example, installation on a Ubuntu box would require the following commands:

$ sudo apt install pandoc texlive-latex-base

Python packages can be installed using

$ python3 -m pip install pysap[docs]

Notebooks

Documentation include a graphical representation of the most commonly used protocol packets and file formats. This graphical representations are built using Scapy, The Jupyter Notebook , nbconvert and nbsphinx.

Jupyter notebooks containing the protocol packets’ representation can be re-built in place using the following command:

$ python3 setup.py notebooks

The command executes all protocol and file format notebooks by default and writes the executed outputs back to the source .ipynb files. A single notebook or subset can be selected with --notebooks using a pattern relative to docs/:

$ python3 setup.py notebooks --notebooks protocols/SAPDiag.ipynb

Notebook execution also accepts --timeout, --kernel-name, --allow-errors and --clean options for slow notebooks, alternate kernels, diagnostic runs or validating notebooks without keeping executed cell outputs.

Code contributions

When contributing code, follow this checklists:

  1. Fork the repository on GitHub.

  2. Run the tests to check that all current tests pass on the system. If they don’t, some investigation might be required to determine why they fail. Note that current tests are limited and only covers some of the protocols and client interfaces.

  3. If possible, write tests that demonstrate the bug you’re fixing or the feature being added.

  4. Make the desired changes.

  5. Run the tests again and ensure they are passing again and remain valid.

  6. Send a GitHub Pull Request to the repository’s master branch.

For a focused guide to the test suites, harness layout, and recommended commands, see Testing guide.

Bug reporting

Bug reports are important to keep the project up. It’s important to clarify that examples are not mean to be valid for all current software versions, and in most of the cases they are demonstrations over the capabilities of having the packages implemented in the library. However, improvements are highly appreciated on both library’s core components and example scripts.

When submitting bugs, follow this checklist:

  1. Check current GitHub issues for potential duplicates.

  2. Create a new issue detailing as much information as possible. Packet captures are always helpful when dealing with specific packets missing or client interface errors.