diff --git a/README.md b/README.md index 25110b3f7..d3a76c213 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,8 @@ channel, ...), etc. Latest version of scapy now supports both Python 2.7 and Python 3. It's intended to be cross platform, and supports many different platforms such as Linux, OSX, Windows... +[Documentation](http://scapy.readthedocs.io/en/latest/) + ## Hands-on ## ### Interactive shell ### diff --git a/doc/scapy/conf.py b/doc/scapy/conf.py index a1d8daf6a..70ff4a1dd 100644 --- a/doc/scapy/conf.py +++ b/doc/scapy/conf.py @@ -35,7 +35,7 @@ master_doc = 'index' # General substitutions. project = 'Scapy' -copyright = '2008, 2016 Philippe Biondi and the Scapy community' +copyright = '2008, 2018 Philippe Biondi and the Scapy community' # The default replacements for |version| and |release|, also used in various # other places throughout the built documents. diff --git a/doc/scapy/graphics/scapy-main-console.png b/doc/scapy/graphics/scapy-main-console.png new file mode 100644 index 000000000..fba3eae07 Binary files /dev/null and b/doc/scapy/graphics/scapy-main-console.png differ diff --git a/doc/scapy/graphics/scapy-win-screenshot1.png b/doc/scapy/graphics/scapy-win-screenshot1.png index 21ca2860e..2429d98f6 100644 Binary files a/doc/scapy/graphics/scapy-win-screenshot1.png and b/doc/scapy/graphics/scapy-win-screenshot1.png differ diff --git a/doc/scapy/graphics/scapy-win-screenshot2.png b/doc/scapy/graphics/scapy-win-screenshot2.png index e5989acfd..2fef46b99 100644 Binary files a/doc/scapy/graphics/scapy-win-screenshot2.png and b/doc/scapy/graphics/scapy-win-screenshot2.png differ diff --git a/doc/scapy/graphics/scapy_logo.png b/doc/scapy/graphics/scapy_logo.png new file mode 100644 index 000000000..5b8e9ebd6 Binary files /dev/null and b/doc/scapy/graphics/scapy_logo.png differ diff --git a/doc/scapy/index.rst b/doc/scapy/index.rst index 4258628cc..d7af30b88 100644 --- a/doc/scapy/index.rst +++ b/doc/scapy/index.rst @@ -5,6 +5,10 @@ Welcome to Scapy's documentation! ================================= +.. image:: graphics/scapy_logo.png + :scale: 20 + :align: center + :Release: |version| :Date: |today| diff --git a/doc/scapy/installation.rst b/doc/scapy/installation.rst index a34732599..5b9da8afb 100644 --- a/doc/scapy/installation.rst +++ b/doc/scapy/installation.rst @@ -7,21 +7,20 @@ Download and Installation Overview ======== - 0. Install `Python 2.7.X `_. + 0. Install `Python 2.7.X or 3.3+ `_. 1. `Download and install Scapy. <#installing-scapy-v2-x>`_ 2. `Follow the platform specific instructions (depedencies) <#platform-specific-instructions>`_. - 3. (Optional): `Install additional software <#optional-packages>`_ for `special features <#optional-software-for-special-features>`_. + 3. (Optional): `Install additional software for special features <#optional-software-for-special-features>`_. 4. Run Scapy with root privileges. Each of these steps can be done in a different way dependent on your platform and on the version of Scapy you want to use. At the moment, there are two different versions of Scapy: -* **Scapy v1.x**. It consists of only one file and works on Python 2.4, so it might be easier to install. +* **Scapy v2.x**. The current up-to-date version. It consists of several files packaged in the standard distutils way. + Scapy v2 <= 2.3.3 needs Python 2.5, Scapy v2 > 2.3.3 needs Python 2.7 or 3.3+. +* **Scapy v1.x (deprecated)**. It does not support Python 3. It consists of only one file and works on Python 2.4, so it might be easier to install. Moreover, your OS may already have a specially prepared packages or ports for it. Last version is v1.2.2. -* **Scapy v2.x**. The current development version adds several features (e.g. IPv6). It consists of several - files packaged in the standard distutils way. Scapy v2 <= 2.3.3 needs Python 2.5, Scapy v2 > 2.3.3 needs - Python 2.7. .. note:: @@ -139,20 +138,22 @@ Optional software for special features ====================================== For some special features you have to install more software. -Platform-specific instructions on how to install those packages can be found in the next chapter. +Most of those softwares are installable via ``pip``. Here are the topics involved and some examples that you can use to try if your installation was successful. .. index:: single: plot() -* Plotting. ``plot()`` needs `Gnuplot-py `_ which needs `GnuPlot `_ and `NumPy `__. +* Plotting. ``plot()`` needs `Matplotlib `_. It is installable via ``pip install matplotlib`` .. code-block:: python >>> p=sniff(count=50) >>> p.plot(lambda x:len(x)) -* 2D graphics. ``psdump()`` and ``pdfdump()`` need `PyX `_ which in turn needs a `LaTeX distribution `_. For viewing the PDF and PS files interactively, you also need `Adobe Reader `_ (``acroread``) and `gv `_ (``gv``). +* 2D graphics. ``psdump()`` and ``pdfdump()`` need `PyX `_ which in turn needs a LaTeX distribution: `texlive (Unix) `_ or `MikTex (Windows) `_. For viewing the PDF and PS files interactively, you also need `Adobe Reader `_ (``acroread``) and `gv `_ (``gv``). + + Note: PyX requires version 0.12 on Python 2.7. This means that on Python 2.7, it needs to be installed via ``pip install pyx==0.12``. Otherwise ``pip install pyx`` .. code-block:: python @@ -178,6 +179,8 @@ Here are the topics involved and some examples that you can use to try if your i * WEP decryption. ``unwep()`` needs `cryptography `_. Example using a `Weplap test file `_: + Cryptography is installable via ``pip install cryptography`` + .. code-block:: python >>> enc=rdpcap("weplab-64bit-AA-managed.pcap") @@ -201,11 +204,13 @@ Here are the topics involved and some examples that you can use to try if your i Received 19 packets, got 4 answers, remaining 4 packets (0.88749999999999996, ['Draytek Vigor 2000 ISDN router']) +* Queso is used withing the queso module: `queso-980922.tar.gz `_. Extract the tar.gz file (e.g. using `7-Zip `_) and put ``queso.conf`` into your Scapy directory + .. index:: single: VOIP * VOIP. ``voip_play()`` needs `SoX `_. - + Platform-specific instructions ============================== @@ -214,7 +219,7 @@ Linux native Scapy can run natively on Linux, without libdnet and libpcap. -* Install `Python 2.7 `_. +* Install `Python 2.7 or 3.3+ `_. * Install `tcpdump `_ and make sure it is in the $PATH. (It's only used to compile BPF filters (``-ddd option``)) * Make sure your kernel has Packet sockets selected (``CONFIG_PACKET``) * If your kernel is < 2.6, make sure that Socket filtering is selected ``CONFIG_FILTER``) @@ -377,105 +382,18 @@ Scapy is primarily being developed for Unix-like systems and works best on those You need the following software packages in order to install Scapy on Windows: - * `Python `_: `python-2.7.13.amd64.msi `_ (64bits) or `python-2.7.13.msi `_ (32bits). After installation, add the Python installation directory and its \Scripts subdirectory to your PATH. Depending on your Python version, the defaults would be ``C:\Python27`` and ``C:\Python27\Scripts`` respectively. + * `Python `_: `Python 2.7.X or 3.3+ `_. After installation, add the Python installation directory and its \Scripts subdirectory to your PATH. Depending on your Python version, the defaults would be ``C:\Python27`` and ``C:\Python27\Scripts`` respectively. * `Npcap `_: `the latest version `_. Default values are recommanded. Scapy will also work with Winpcap. * `Scapy `_: `latest development version `_ from the `Git repository `_. Unzip the archive, open a command prompt in that directory and run "python setup.py install". Just download the files and run the setup program. Choosing the default installation options should be safe. -For your convenience direct links are given to the version that is supported (Python 2.7). If these links do not work or if you are using a different Python version (which will surely not work), just visit the homepage of the respective package and look for a Windows binary. As a last resort, search the web for the filename. +For your convenience direct links are given to the version that is supported (Python 2.7 and 3.3+). If these links do not work or if you are using a different Python version (which will surely not work), just visit the homepage of the respective package and look for a Windows binary. As a last resort, search the web for the filename. After all packages are installed, open a command prompt (cmd.exe) and run Scapy by typing ``scapy``. If you have set the PATH correctly, this will find a little batch file in your ``C:\Python27\Scripts`` directory and instruct the Python interpreter to load Scapy. If really nothing seems to work, consider skipping the Windows version and using Scapy from a Linux Live CD -- either in a virtual machine on your Windows host or by booting from CDROM: An older version of Scapy is already included in grml and BackTrack for example. While using the Live CD you can easily upgrade to the latest Scapy version by typing ``cd /tmp && wget scapy.net``. -Optional packages -^^^^^^^^^^^^^^^^^ - -.. note:: - If you are using OpenBSD, follow `this <#optional-packages-openbsd-only>`__ instead - -1. (Recommanded) Auto install: Using pip -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Plotting (``plot``): - - * GnuPlot and Gnuplot-py need a manual install. - * Install Numpy: - - .. code-block:: text - - # pip install numpy - - 2D Graphics (``psdump``, ``pdfdump``): - - * MikTeX need a manual install. - * Install pyx: - - .. code-block:: text - - # pip install pyx - - Graphs (conversations): - - * Install graphviz: - - .. code-block:: text - - # pip install graphviz - - 3D Graphics (trace3d): - - * Install VPython: - - .. code-block:: text - - # pip install vpython - - WEP decryption: - - * Install cryptography: - - .. code-block:: text - - # pip install cryptography - - Fingerprinting: - - * Nmap and Queso need to be installed manualy. - -2. (Advanced) Manual install -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Plotting (``plot``) - - * `GnuPlot `_: `gp504-win64-mingw.exe `_ (64bits) or `gp504-win32-mingw.exe `_ (32bits). - * `NumPy `_: `numpy-1.11.2.zip `_. Extract to temp dir, open command prompt, change to tempdir and type ``python setup.py install``. Gnuplot-py 1.8 needs NumPy. - * `Gnuplot-py `_: `gnuplot-py-1.8.zip `_. As numpy, use a tempdir. - - 2D Graphics (``psdump``, ``pdfdump``) - - * `PyX `_: `PyX-0.14.1.tar.gz `_. Extract to temp dir, open command prompt, change to tempdir and type ``python setup.py install`` - * `MikTeX `_: `Basic MiKTeX 2.8 Installer `_. PyX needs a LaTeX installation. Choose an installation directory WITHOUT spaces (e.g. ``C:\MikTex2.8`` and check that the ``(INSTALLDIR)\miktex\bin`` subdirectory is added to your PATH. - - Graphs (conversations) - - * `Graphviz `_: `graphviz-2.38.exe `_. Add ``(INSTALLDIR)\ATT\Graphviz\bin`` to your PATH. - - 3D Graphics (trace3d) - - * `VPython `_: `VPython-Win-64-Py2.7-6.11.exe `_ (64bits) or `VPython-Win-32-Py2.7-6.11.exe `_ (32bits). - - WEP decryption - - * `cryptography `_: `HowTo `_ - - Fingerprinting - - * `Nmap `_. `nmap-4.20-setup.exe `_. If you use the default installation directory, Scapy should automatically find the fingerprints file. - * Queso: `queso-980922.tar.gz `_. Extract the tar.gz file (e.g. using `7-Zip `_) and put ``queso.conf`` into your Scapy directory - - Screenshot ^^^^^^^^^^ diff --git a/doc/scapy/usage.rst b/doc/scapy/usage.rst index 1edb81c3b..7db3ff4be 100644 --- a/doc/scapy/usage.rst +++ b/doc/scapy/usage.rst @@ -29,6 +29,14 @@ some features will not be available:: The basic features of sending and receiving packets should still work, though. +Screenshot +---------- + +If you have installed IPython, scapy will hook to it and you will be able to use auto-completion using the TAB. + +.. image:: graphics/scapy-main-console.png + :align: center + Interactive tutorial ====================