Development

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

Documentation

Documentation can be build using:

$ python setup.py doc

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

$ 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-build using the following command:

$ python setup.py notebooks

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.

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.