doc/scapy/installation.rst

.. highlight:: sh

*************************
Download and Installation
*************************

Overview
========

 0. Install `Python 2.7.X or 3.3+ <https://www.python.org/downloads/>`_.
 1. `Download and install Scapy. <#installing-scapy-v2-x>`_
 2. `Follow the platform specific instructions (depedencies) <#platform-specific-instructions>`_.
 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 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.

.. note::

   In Scapy v2 use ``from scapy.all import *`` instead of ``from scapy import *``.


Installing Scapy v2.x
=====================

The following steps describe how to install (or update) Scapy itself.
Dependent on your platform, some additional libraries might have to be installed to make it actually work.
So please also have a look at the platform specific chapters on how to install those requirements.

.. note::

   The following steps apply to Unix-like operating systems (Linux, BSD, Mac OS X).
   For Windows, see the  `special chapter <#windows>`_ below.

Make sure you have Python installed before you go on.

Latest release
--------------

.. note::
   To get the latest versions, with bugsfixes and new features, but maybe not as stable, see the `development version <#current-development-version>`_.

Use pip::

$ pip install scapy


You can also download the `latest version <http://scapy.net>`_ to a temporary directory and install it in the standard `distutils <http://docs.python.org/inst/inst.html>`_ way::

$ cd /tmp
$ wget --trust-server-names scapy.net   # or wget -O scapy.zip scapy.net
$ unzip scapy-x.x.x.zip
$ cd scapy
$ sudo python setup.py install

Alternatively, you can execute the zip file::

$ chmod +x scapy-x.x.x.zip
$ sudo ./scapy-x.x.x.zip

or::

$ sudo sh scapy-x.x.x.zip

or::

$ mv scapy-x.x.x.zip /usr/local/bin/scapy
$ sudo scapy

or::

$ chmod +x scapy-x.x.x.zip
$ ./scapy-x.x.x.zip

or download and run in one command::

$ sh <(curl -sL scapy.net)

.. note::

   To make a zip executable, some bytes have been added before the zip header.
   Most zip programs handle this, but not all. If your zip program complains
   about the zip file to be corrupted, either change it, or download a
   non-executable zip at https://github.com/secdev/scapy/archive/master.zip


Current development version
----------------------------

.. index::
   single: Git, repository

If you always want the latest version with all new features and bugfixes, use Scapy's Git repository:

1. Install the Git version control system. For example, on Debian/Ubuntu use::

      $ sudo apt-get install git

   or on OpenBSD::

      $ doas pkg_add git

2. Check out a clone of Scapy's repository::

   $ git clone https://github.com/secdev/scapy

3. Install Scapy in the standard distutils way::

   $ cd scapy
   $ sudo python setup.py install

Then you can always update to the latest version::

   $ git pull
   $ sudo python setup.py install

.. note::

   You can run scapy without installing it using the ``run_scapy`` (unix) or ``run_scapy.bat`` (Windows) script or running it directly from the executable zip file (see previous section).

Installing Scapy v1.2 (Deprecated)
==================================

As Scapy v1 consists only of one single Python file, installation is easy:
Just download the last version and run it with your Python interpreter::

 $ wget https://raw.githubusercontent.com/secdev/scapy/v1.2.0.2/scapy.py
 $ sudo python scapy.py

Optional software for special features
======================================

For some special features you have to install more software.
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 `Matplotlib <https://matplotlib.org/>`_. 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 <http://pyx.sourceforge.net/>`_ which in turn needs a LaTeX distribution: `texlive (Unix) <http://www.tug.org/texlive/>`_ or `MikTex (Windows) <https://miktex.org/>`_. For viewing the PDF and PS files interactively, you also need `Adobe Reader <http://www.adobe.com/products/reader/>`_ (``acroread``) and `gv <http://wwwthep.physik.uni-mainz.de/~plass/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

     >>> p=IP()/ICMP()
     >>> p.pdfdump("test.pdf")

* Graphs. ``conversations()`` needs `Graphviz <http://www.graphviz.org/>`_ and `ImageMagick <http://www.imagemagick.org/>`_.

  .. code-block:: python

     >>> p=readpcap("myfile.pcap")
     >>> p.conversations(type="jpg", target="> test.jpg")

* 3D graphics. ``trace3D()`` needs `VPython <http://www.vpython.org/>`_.

  .. code-block:: python

     >>> a,u=traceroute(["www.python.org", "google.com","slashdot.org"])
     >>> a.trace3D()

.. index::
   single: WEP, unwep()

* WEP decryption. ``unwep()`` needs `cryptography <https://cryptography.io>`_. Example using a `Weplap test file <http://weplab.sourceforge.net/caps/weplab-64bit-AA-managed.pcap>`_:

    Cryptography is installable via ``pip install cryptography``

  .. code-block:: python

     >>> enc=rdpcap("weplab-64bit-AA-managed.pcap")
     >>> enc.show()
     >>> enc[0]
     >>> conf.wepkey="AA\x00\x00\x00"
     >>> dec=Dot11PacketList(enc).toEthernet()
     >>> dec.show()
     >>> dec[0]

* PKI operations and TLS decryption. `cryptography <https://cryptography.io>`_ is also needed.

* Fingerprinting. ``nmap_fp()`` needs `Nmap <http://nmap.org>`_. You need an `old version <http://nmap.org/dist-old/>`_ (before v4.23) that still supports first generation fingerprinting.

  .. code-block:: python

     >>> load_module("nmap")
     >>> nmap_fp("192.168.0.1")
     Begin emission:
     Finished to send 8 packets.
     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 <http://www.packetstormsecurity.org/UNIX/scanners/queso-980922.tar.gz>`_. Extract the tar.gz file (e.g. using `7-Zip <http://www.7-zip.org/>`_) and put ``queso.conf`` into your Scapy directory

.. index::
   single: VOIP

* VOIP. ``voip_play()`` needs `SoX <http://sox.sourceforge.net/>`_.

Platform-specific instructions
==============================

Linux native
------------

Scapy can run natively on Linux, without libdnet and libpcap.

* Install `Python 2.7 or 3.3+ <http://www.python.org>`_.
* Install `tcpdump <http://www.tcpdump.org>`_ 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``)

Debian/Ubuntu
-------------

Just use the standard packages::

$ sudo apt-get install tcpdump graphviz imagemagick python-gnuplot python-cryptography python-pyx

Scapy optionally uses python-cryptography v1.7 or later. It has not been packaged for ``apt`` in less recent OS versions (e.g. Debian Jessie). If you need the cryptography-related methods, you may install the library with:

.. code-block:: text

    # pip install cryptography

Fedora
------

Here's how to install Scapy on Fedora 9:

.. code-block:: text

    # yum install git python-devel
    # cd /tmp
    # git clone https://github.com/secdev/scapy
    # cd scapy
    # python setup.py install

Some optional packages:

.. code-block:: text

    # yum install graphviz python-cryptography sox PyX gnuplot numpy
    # cd /tmp
    # wget http://heanet.dl.sourceforge.net/sourceforge/gnuplot-py/gnuplot-py-1.8.tar.gz
    # tar xvfz gnuplot-py-1.8.tar.gz
    # cd gnuplot-py-1.8
    # python setup.py install


Mac OS X
--------

On Mac OS X, Scapy does not work natively. You need to install Python bindings
to use libdnet and libpcap. You can choose to install using either Homebrew or
MacPorts. They both work fine, yet Homebrew is used to run unit tests with
`Travis CI <https://travis-ci.org>`_.


Install using Homebrew
^^^^^^^^^^^^^^^^^^^^^^

1. Update Homebrew::

   $ brew update

2. Install Python bindings::


   $ brew install --with-python libdnet
   $ brew install https://raw.githubusercontent.com/secdev/scapy/master/.travis/pylibpcap.rb
   $ sudo brew install --with-python libdnet
   $ sudo brew install https://raw.githubusercontent.com/secdev/scapy/master/.travis/pylibpcap.rb


Install using MacPorts
^^^^^^^^^^^^^^^^^^^^^^

1. Update MacPorts::

   $ sudo port -d selfupdate

2. Install Python bindings::

   $ sudo port install py-libdnet py-pylibpcap


OpenBSD
-------

Here's how to install Scapy on OpenBSD 5.9+

.. code-block:: text

 $ doas pkg_add py-libpcap py-libdnet git
 $ cd /tmp
 $ git clone http://github.com/secdev/scapy
 $ cd scapy
 $ doas python2.7 setup.py install


Optional packages (OpenBSD only)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

py-cryptography

.. code-block:: text

 # pkg_add py-cryptography

gnuplot and its Python binding:

.. code-block:: text

 # pkg_add gnuplot py-gnuplot

Graphviz (large download, will install several GNOME libraries)

.. code-block:: text

 # pkg_add graphviz


ImageMagick (takes long to compile)

.. code-block:: text

 # cd /tmp
 # ftp ftp://ftp.openbsd.org/pub/OpenBSD/4.3/ports.tar.gz
 # cd /usr
 # tar xvfz /tmp/ports.tar.gz
 # cd /usr/ports/graphics/ImageMagick/
 # make install

PyX (very large download, will install texlive etc.)

.. code-block:: text

 # pkg_add py-pyx

/etc/ethertypes

.. code-block:: text

 # wget http://git.netfilter.org/ebtables/plain/ethertypes -O /etc/ethertypes

python-bz2 (for UTscapy)

.. code-block:: text

 # pkg_add python-bz2

.. _windows_installation:

Windows
-------

.. sectionauthor:: Dirk Loss <mail at dirk-loss.de>

Scapy is primarily being developed for Unix-like systems and works best on those platforms. But the latest version of Scapy supports Windows out-of-the-box. So you can use nearly all of Scapy's features on your Windows machine as well.

.. note::
   If you update from Scapy-win v1.2.0.2 to Scapy v2 remember to use ``from scapy.all import *`` instead of ``from scapy import *``.

.. image:: graphics/scapy-win-screenshot1.png
   :scale: 80
   :align: center

You need the following software packages in order to install Scapy on Windows:

  * `Python <http://www.python.org>`_: `Python 2.7.X or 3.3+ <https://www.python.org/downloads/>`_. 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 <https://nmap.org/npcap/>`_: `the latest version <https://nmap.org/npcap/#download>`_. Default values are recommanded. Scapy will also work with Winpcap.
  * `Scapy <http://www.secdev.org/projects/scapy/>`_: `latest development version <https://github.com/secdev/scapy/archive/master.zip>`_ from the `Git repository <https://github.com/secdev/scapy>`_. 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 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``.

Screenshot
^^^^^^^^^^

.. image:: graphics/scapy-win-screenshot2.png
   :scale: 80
   :align: center

Known bugs
^^^^^^^^^^

 * You may not be able to capture WLAN traffic on Windows. Reasons are explained on the Wireshark wiki and in the WinPcap FAQ. Try switching off promiscuous mode with ``conf.sniff_promisc=False``.
 * Packets sometimes cannot be sent to localhost (or local IP addresses on your own host).

Winpcap/Npcap conflicts
^^^^^^^^^^^^^^^^^^^^^^^

As Winpcap is becoming old, it's recommanded to use Npcap instead. Npcap is part of the Nmap project.

1. If you get the message 'Winpcap is installed over Npcap.' it means that you have installed both winpcap and npcap versions, which isn't recommanded.

You may uninstall winpcap from your Program Files, then you will need to remove:
 * C:/Windows/System32/wpcap.dll
 * C:/Windows/System32/Packet.dll

To use npcap instead.

2. If you get the message 'The installed Windump version does not work with Npcap' it means that you have installed an old version of Windump.
Download the correct one on https://github.com/hsluoyz/WinDump/releases

Build the documentation offline
===============================
The Scapy project's documentation is written using reStructuredText (files \*.rst) and can be built using
the `Sphinx <http://www.sphinx-doc.org/>`_ python library. The official online version is available
on `readthedocs <http://scapy.readthedocs.io/>`_.

HTML version
------------
The instructions to build the HTML version are: ::

   (activate a virtualenv)
   pip install sphinx
   cd doc/scapy
   make html

Or on windows, simply run ``BuildDoc.bat``

You can now open the resulting HTML file ``_build/html/index.html`` in your favorite web browser.

To use the ReadTheDocs' template, you will have to install the corresponding theme with: ::

   pip install sphinx_rtd_theme

If installed, it will be automatically used, but you may disable it by setting ``auto_rtd`` to ``False`` in ``doc/scapy/conf.py``

UML diagram
-----------
Using ``pyreverse`` you can build an UML representation of the Scapy source code's object hierarchy. Here is an
example on how to build the inheritence graph for the Fields objects : ::

   (activate a virtualenv)
   pip install pylint
   cd scapy/
   pyreverse -o png -p fields scapy/fields.py

This will generate a ``classes_fields.png`` picture containing the inheritance hierarchy. Note that you can provide as many
modules or packages as you want, but the result will quickly get unreadable.

To see the dependencies between the DHCP layer and the ansmachine module, you can run: ::

   pyreverse -o png -p dhcp_ans scapy/ansmachine.py scapy/layers/dhcp.py scapy/packet.py

In this case, Pyreverse will also generate a ``packages_dhcp_ans.png`` showing the link between the different python modules provided.