1<p align="center">
2  <img src="doc/scapy_logo.png" width=200>
3</p>
4
5# Scapy #
6
7[![Travis Build Status](https://travis-ci.org/secdev/scapy.svg?branch=master)](https://travis-ci.org/secdev/scapy)
8[![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/secdev/scapy?svg=true)](https://ci.appveyor.com/project/secdev/scapy)
9[![Codecov Status](https://codecov.io/gh/secdev/scapy/branch/master/graph/badge.svg)](https://codecov.io/gh/secdev/scapy)
10[![PyPI Version](https://img.shields.io/pypi/v/scapy.svg)](https://pypi.python.org/pypi/scapy/)
11[![Python Versions](https://img.shields.io/pypi/pyversions/scapy.svg)](https://pypi.python.org/pypi/scapy/)
12[![License: GPL v2](https://img.shields.io/badge/License-GPL%20v2-blue.svg)](LICENSE)
13[![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)
14
15
16Scapy is a powerful Python-based interactive packet manipulation program and
17library.
18
19It is able to forge or decode packets of a wide number of protocols, send them
20on the wire, capture them, store or read them using pcap files, match requests
21and replies, and much more. It is designed to allow fast packet prototyping by
22using default values that work.
23
24It can easily handle most classical tasks like scanning, tracerouting, probing,
25unit tests, attacks or network discovery (it can replace `hping`, 85% of `nmap`,
26`arpspoof`, `arp-sk`, `arping`, `tcpdump`, `wireshark`, `p0f`, etc.). It also
27performs very well at a lot of other specific tasks that most other tools can't
28handle, like sending invalid frames, injecting your own 802.11 frames, combining
29techniques (VLAN hopping+ARP cache poisoning, VoIP decoding on WEP protected
30channel, ...), etc.
31
32Scapy supports Python 2.7 and Python 3 (3.3 to 3.6). It's intended to
33be cross platform, and runs on many different platforms (Linux, OSX,
34*BSD, and Windows).
35
36## Hands-on ##
37
38### Interactive shell ###
39
40Scapy can easily be used as an interactive shell to interact with the network.
41The following example shows how to send an ICMP Echo Request message to
42`github.com`, then display the reply source IP address:
43
44```python
45sudo ./run_scapy
46Welcome to Scapy
47>>> p = IP(dst="github.com")/ICMP()
48>>> r = sr1(p)
49Begin emission:
50.Finished to send 1 packets.
51*
52Received 2 packets, got 1 answers, remaining 0 packets
53>>> r[IP].src
54'192.30.253.113'
55```
56
57### Python module ###
58
59It is straightforward to use Scapy as a regular Python module, for example to
60check if a TCP port is opened. First, save the following code in a file names
61`send_tcp_syn.py`
62
63```python
64from scapy.all import *
65conf.verb = 0
66
67p = IP(dst="github.com")/TCP()
68r = sr1(p)
69print(r.summary())
70```
71
72Then, launch the script with:
73```python
74sudo python send_tcp_syn.py
75IP / TCP 192.30.253.113:http > 192.168.46.10:ftp_data SA / Padding
76```
77
78### Resources ###
79
80To begin with Scapy, you should check [the notebook
81hands-on](doc/notebooks/Scapy%20in%2015%20minutes.ipynb) and the [interactive
82tutorial](http://scapy.readthedocs.io/en/latest/usage.html#interactive-tutorial).
83If you want to learn more, see [the quick demo: an interactive
84session](http://scapy.readthedocs.io/en/latest/introduction.html#quick-demo)
85(some examples may be outdated), or play with the
86[HTTP/2](doc/notebooks/HTTP_2_Tuto.ipynb) and [TLS](doc/notebooks/tls)
87notebooks.
88
89The [documentation](http://scapy.readthedocs.io/en/latest/) contains more
90advanced use cases, and examples.
91
92## Installation ##
93
94Scapy works without any external Python modules on Linux and BSD like operating
95systems. On Windows, you need to install some mandatory dependencies as
96described in [the
97documentation](http://scapy.readthedocs.io/en/latest/installation.html#windows).
98
99On most systems, using Scapy is as simple as running the following commands:
100```
101git clone https://github.com/secdev/scapy
102cd scapy
103./run_scapy
104>>>
105```
106
107To benefit from all Scapy features, such as plotting, you might want to install
108Python modules, such as `matplotlib` or `cryptography`. See the
109[documentation](http://scapy.readthedocs.io/en/latest/installation.html) and
110follow the instructions to install them.
111
112## Contributing ##
113
114Want to contribute? Great! Please take a few minutes to
115[read this](CONTRIBUTING.md)!
116