README
1<p align="center">
2<img src="doc/scapy_logo.png" width=200>
3</p>
4
5<!-- start_ppi_description -->
6
7# Scapy
8
9[](https://github.com/secdev/scapy/actions?query=workflow%3A%22Scapy+unit+tests%22+branch%3Amaster+event%3Apush) <!-- ignore_ppi -->
10[](https://ci.appveyor.com/project/secdev/scapy/branch/master) <!-- ignore_ppi -->
11[](https://codecov.io/gh/secdev/scapy) <!-- ignore_ppi -->
12[](https://www.codacy.com/app/secdev/scapy) <!-- ignore_ppi -->
13[](https://pypi.python.org/pypi/scapy/)
14[](https://pypi.python.org/pypi/scapy/)
15[](LICENSE)
16[](https://gitter.im/secdev/scapy) <!-- ignore_ppi -->
17
18Scapy is a powerful Python-based interactive packet manipulation program and
19library.
20
21It is able to forge or decode packets of a wide number of protocols, send them
22on the wire, capture them, store or read them using pcap files, match requests
23and replies, and much more. It is designed to allow fast packet prototyping by
24using default values that work.
25
26It can easily handle most classical tasks like scanning, tracerouting, probing,
27unit tests, attacks or network discovery (it can replace `hping`, 85% of `nmap`,
28`arpspoof`, `arp-sk`, `arping`, `tcpdump`, `wireshark`, `p0f`, etc.). It also
29performs very well at a lot of other specific tasks that most other tools can't
30handle, like sending invalid frames, injecting your own 802.11 frames, combining
31techniques (VLAN hopping+ARP cache poisoning, VoIP decoding on WEP protected
32channel, ...), etc.
33
34Scapy supports Python 2.7 and Python 3 (3.4 to 3.8). It's intended to
35be cross platform, and runs on many different platforms (Linux, OSX,
36\*BSD, and Windows).
37
38## Getting started
39
40Scapy is usable either as a **shell** or as a **library**.
41For further details, please head over to [Getting started with Scapy](https://scapy.readthedocs.io/en/latest/introduction.html), which is part of the documentation.
42
43### Shell demo
44
45
46
47Scapy can easily be used as an interactive shell to interact with the network.
48The following example shows how to send an ICMP Echo Request message to
49`github.com`, then display the reply source IP address:
50
51```python
52sudo ./run_scapy
53Welcome to Scapy
54>>> p = IP(dst="github.com")/ICMP()
55>>> r = sr1(p)
56Begin emission:
57.Finished to send 1 packets.
58*
59Received 2 packets, got 1 answers, remaining 0 packets
60>>> r[IP].src
61'192.30.253.113'
62```
63
64### Resources
65
66The [documentation](https://scapy.readthedocs.io/en/latest/) contains more
67advanced use cases, and examples.
68
69Other useful resources:
70
71- [Scapy in 20 minutes](https://github.com/secdev/scapy/blob/master/doc/notebooks/Scapy%20in%2015%20minutes.ipynb)
72- [Interactive tutorial](https://scapy.readthedocs.io/en/latest/usage.html#interactive-tutorial) (part of the documentation)
73- [The quick demo: an interactive session](https://scapy.readthedocs.io/en/latest/introduction.html#quick-demo)
74(some examples may be outdated)
75- [HTTP/2 notebook](https://github.com/secdev/scapy/blob/master/doc/notebooks/HTTP_2_Tuto.ipynb)
76- [TLS notebooks](https://github.com/secdev/scapy/blob/master/doc/notebooks/tls)
77
78## [Installation](https://scapy.readthedocs.io/en/latest/installation.html)
79
80Scapy works without any external Python modules on Linux and BSD like operating
81systems. On Windows, you need to install some mandatory dependencies as
82described in [the
83documentation](http://scapy.readthedocs.io/en/latest/installation.html#windows).
84
85On most systems, using Scapy is as simple as running the following commands:
86
87```bash
88git clone https://github.com/secdev/scapy
89cd scapy
90./run_scapy
91```
92
93To benefit from all Scapy features, such as plotting, you might want to install
94Python modules, such as `matplotlib` or `cryptography`. See the
95[documentation](http://scapy.readthedocs.io/en/latest/installation.html) and
96follow the instructions to install them.
97
98<!-- stop_ppi_description -->
99
100## Contributing
101
102Want to contribute? Great! Please take a few minutes to
103[read this](CONTRIBUTING.md)!
104
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}