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