diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index fd51da47570..f684a91d99d 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -1,39 +1,38 @@ #### Things to consider -1. Please check that you are using the latest scapy version, e.g. installed via: +1. Please check that you are using the latest scapy version, e.g. installed via: - `pip install https://github.com/secdev/scapy` + `pip install https://github.com/secdev/scapy` -2. If you are here to ask a question - please check previous issues and online resources, and consider using gitter instead: https://gitter.im/secdev/scapy +2. If you are here to ask a question - please check previous issues and online resources, and consider using gitter instead: -3. Please understand that **this is not a forum** but an issue tracker. The following article explains why you should limit questions asked on Github issues: https://medium.com/@methane/why-you-must-not-ask-questions-on-github-issues-51d741d83fde +3. Please understand that **this is not a forum** but an issue tracker. The following article explains why you should limit questions asked on Github issues: #### Brief description -< describe the main issue in one sentence > - -< if possible, describe what components / protocols could be affected by the issue (e.g. wrpcap() + IPv6, it is likely this also affects XXX) > +> describe the main issue in one sentence +> if possible, describe what components / protocols could be affected by the issue (e.g. wrpcap() + IPv6, it is likely this also affects XXX) #### Environment -- Scapy version: < scapy version and/or commit-hash > -- Python version: < e.g. 3.5 > -- Operating System: < e.g. Minix 3.4 > +- Scapy version: `scapy version and/or commit-hash` +- Python version: `e.g. 3.5` +- Operating System: `e.g. Minix 3.4` -< if needed - further information to get a picture of your setup (e.g. a sketch of your network setup) > +> if needed - further information to get a picture of your setup (e.g. a sketch of your network setup) #### How to reproduce -< step-by-step explanation or a short script, may reference section 'Related resources' > +> step-by-step explanation or a short script, may reference section 'Related resources' #### Actual result -< dump results that outline the issue, please format your code > +> dump results that outline the issue, please format your code #### Expected result -< describe the expected result and outline the difference to the actual one, could also be a screen shot (e.g. wireshark) > +> describe the expected result and outline the difference to the actual one, could also be a screen shot (e.g. wireshark) #### Related resources -< traces / sample pcaps (stripped to the relevant frames), related standards, RFCs or other resources > +> traces / sample pcaps (stripped to the relevant frames), related standards, RFCs or other resources diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 3ece4b20986..9c03bff9e61 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,17 +1,16 @@ This is just a checklist to guide you. You can remove it safely. - **Checklist:** -- [ ] If you are new to Scapy: I have checked https://github.com/secdev/scapy/blob/master/CONTRIBUTING.md (esp. section submitting-pull-requests) -- [ ] I squashed commits belonging together -- [ ] I added unit tests or explained why they are not relevant -- [ ] I executed the regression tests for Python2 and Python3 (using `tox` or, `cd test && ./run_tests_py2, cd test && ./run_tests_py3`) +- [ ] If you are new to Scapy: I have checked (esp. section submitting-pull-requests) +- [ ] I squashed commits belonging together +- [ ] I added unit tests or explained why they are not relevant +- [ ] I executed the regression tests for Python2 and Python3 (using `tox` or, `cd test && ./run_tests_py2, cd test && ./run_tests_py3`) -< brief description what this PR will do, e.g. fixes broken dissection of XXX > +> brief description what this PR will do, e.g. fixes broken dissection of XXX -< if required - short explanation why you fixed something in a way that may look more complicated as it actually is > +> if required - short explanation why you fixed something in a way that may look more complicated as it actually is -< if required - outline impacts on other parts of the library > +> if required - outline impacts on other parts of the library -fixes #< add issue number here if appropriate, else remove this line> +fixes #xxx (add issue number here if appropriate, else remove this line) diff --git a/.travis/install.sh b/.travis/install.sh index abe8a3a7b54..0796bb61619 100644 --- a/.travis/install.sh +++ b/.travis/install.sh @@ -1,3 +1,4 @@ +#!/bin/bash # Install on osx if [ "$TRAVIS_OS_NAME" = "osx" ] then diff --git a/.travis/test.sh b/.travis/test.sh index c08403ed490..c5f357f1499 100644 --- a/.travis/test.sh +++ b/.travis/test.sh @@ -1,3 +1,4 @@ +#!/bin/bash if [ "$TRAVIS_OS_NAME" = "linux" ] then # Linux diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 72e081c4e1a..c57a2903e5b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -64,14 +64,14 @@ First, Scapy "legacy" code contains a lot of code that do not comply with the following recommendations, but we try to comply with some guidelines for new code. - - The code should be PEP-8 compliant; you can check your code with +- The code should be PEP-8 compliant; you can check your code with [pep8](https://pypi.python.org/pypi/pep8). - - [Pylint](http://www.pylint.org/) can help you write good Python +- [Pylint](http://www.pylint.org/) can help you write good Python code (even if respecting Pylint rules is sometimes either too hard or even undesirable; human brain needed!). - - [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html) +- [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html) is a nice read! - - Avoid creating unnecessary `list` objects, particularly if they +- Avoid creating unnecessary `list` objects, particularly if they can be huge (e.g., when possible, use `scapy.modules.six.range()` instead of `range()`, `for line in fdesc` instead of `for line in fdesc.readlines()`; more generally prefer generators over lists). @@ -109,7 +109,7 @@ If you contribute to Scapy's core (e.g., `scapy/base_classes.py`, memory footprint, as it is easy to write Python code that wastes memory or CPU cycles. -As an example, Packet().__init__() is called each time a **layer** is +As an example, `Packet().__init__()` is called each time a **layer** is parsed from a string (during a network capture or a PCAP file read). Adding inefficient code here will have a disastrous effect on Scapy's performances. @@ -117,20 +117,21 @@ Scapy's performances. ### Python 2 and 3 compatibility The project aims to provide code that works both on Python 2 and Python 3. Therefore, some rules need to be applied to achieve compatibility: -- byte-string must be defined as `b"\x00\x01\x02"` -- exceptions must comply with the new Python 3 format: `except SomeError as e:` -- lambdas must be written using a single argument when using tuples: use `lambda x, y: x + f(y)` instead of `lambda (x, y): x + f(y)`. -- use int instead of long -- use list comprehension instead of map() and filter() -- use scapy.modules.six.moves.range instead of xrange and range -- use scapy.modules.six.itervalues(dict) instead of dict.values() or dict.itervalues() -- use scapy.modules.six.string_types instead of basestring -- `__bool__ = __nonzero__` must be used when declaring `__nonzero__` methods -- `__next__ = next` must be used when declaring `next` methods in iterators -- `StopIteration` must NOT be used in generators (but it can still be used in iterators) -- `io.BytesIO` must be used instead of `StringIO` when using bytes -- `__cmp__` must not be used. -- UserDict should be imported via `six.UserDict` + +- byte-string must be defined as `b"\x00\x01\x02"` +- exceptions must comply with the new Python 3 format: `except SomeError as e:` +- lambdas must be written using a single argument when using tuples: use `lambda x, y: x + f(y)` instead of `lambda (x, y): x + f(y)`. +- use int instead of long +- use list comprehension instead of map() and filter() +- use scapy.modules.six.moves.range instead of xrange and range +- use scapy.modules.six.itervalues(dict) instead of dict.values() or dict.itervalues() +- use scapy.modules.six.string_types instead of basestring +- `__bool__ = __nonzero__` must be used when declaring `__nonzero__` methods +- `__next__ = next` must be used when declaring `next` methods in iterators +- `StopIteration` must NOT be used in generators (but it can still be used in iterators) +- `io.BytesIO` must be used instead of `StringIO` when using bytes +- `__cmp__` must not be used. +- UserDict should be imported via `six.UserDict` ### Code review diff --git a/README.md b/README.md index fb1738b249a..ab74b31f84b 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@

-# Scapy # +# Scapy [![Travis Build Status](https://travis-ci.org/secdev/scapy.svg?branch=master)](https://travis-ci.org/secdev/scapy) [![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/secdev/scapy?svg=true)](https://ci.appveyor.com/project/secdev/scapy) @@ -12,7 +12,6 @@ [![License: GPL v2](https://img.shields.io/badge/License-GPL%20v2-blue.svg)](LICENSE) [![Join the chat at https://gitter.im/secdev/scapy](https://badges.gitter.im/secdev/scapy.svg)](https://gitter.im/secdev/scapy?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) - Scapy is a powerful Python-based interactive packet manipulation program and library. @@ -31,11 +30,11 @@ channel, ...), etc. Scapy supports Python 2.7 and Python 3 (3.4 to 3.6). It's intended to be cross platform, and runs on many different platforms (Linux, OSX, -*BSD, and Windows). +\*BSD, and Windows). -## Hands-on ## +## Hands-on -### Interactive shell ### +### Interactive shell Scapy can easily be used as an interactive shell to interact with the network. The following example shows how to send an ICMP Echo Request message to @@ -54,7 +53,7 @@ Received 2 packets, got 1 answers, remaining 0 packets '192.30.253.113' ``` -### Python module ### +### Python module It is straightforward to use Scapy as a regular Python module, for example to check if a TCP port is opened. First, save the following code in a file names @@ -70,12 +69,13 @@ print(r.summary()) ``` Then, launch the script with: + ```python sudo python send_tcp_syn.py IP / TCP 192.30.253.113:http > 192.168.46.10:ftp_data SA / Padding ``` -### Resources ### +### Resources To begin with Scapy, you should check [the notebook hands-on](doc/notebooks/Scapy%20in%2015%20minutes.ipynb) and the [interactive @@ -89,7 +89,7 @@ notebooks. The [documentation](http://scapy.readthedocs.io/en/latest/) contains more advanced use cases, and examples. -## Installation ## +## Installation Scapy works without any external Python modules on Linux and BSD like operating systems. On Windows, you need to install some mandatory dependencies as @@ -97,11 +97,11 @@ described in [the documentation](http://scapy.readthedocs.io/en/latest/installation.html#windows). On most systems, using Scapy is as simple as running the following commands: -``` + +```bash git clone https://github.com/secdev/scapy cd scapy ./run_scapy ->>> ``` To benefit from all Scapy features, such as plotting, you might want to install @@ -109,8 +109,9 @@ Python modules, such as `matplotlib` or `cryptography`. See the [documentation](http://scapy.readthedocs.io/en/latest/installation.html) and follow the instructions to install them. -[//]: # (stop_pypi_description) -## Contributing ## + + +## Contributing Want to contribute? Great! Please take a few minutes to [read this](CONTRIBUTING.md)! diff --git a/setup.py b/setup.py index da48f727e5d..105094e972e 100755 --- a/setup.py +++ b/setup.py @@ -44,7 +44,7 @@ def make_ezipfile(base_name, base_dir, verbose=0, dry_run=0, **kwargs): def get_long_description(): try: with io.open(os.path.join(os.path.dirname(__file__), "README.md"), encoding="utf-8") as f: - return f.read().partition("[//]: # (stop_pypi_description)")[0] + return f.read().partition("")[0] except IOError: return None