0
# Scapy
1

2
A powerful Python-based interactive packet manipulation program and library designed for network security, research, and testing. Scapy provides comprehensive capabilities for forging, decoding, sending, and capturing network packets across a wide range of protocols, enabling tasks like network scanning, tracerouting, probing, unit testing, security assessments, and network discovery.
3

4
## Package Information
5

6
- **Package Name**: scapy
7
- **Language**: Python
8
- **Installation**: `pip install scapy`
9
- **Version**: 2.6.1
10
- **License**: GPL-2.0-only
11

12
## Core Imports
13

14
```python
15
from scapy.all import *
16
```
17

18
For specific functionality:
19

20
```python
21
from scapy.all import Ether, IP, TCP, UDP, ICMP, ARP
22
from scapy.all import sr, sr1, send, sendp, sniff
23
from scapy.all import rdpcap, wrpcap
24
from scapy.all import conf
25
```
26

27
## Basic Usage
28

29
```python
30
from scapy.all import *
31

32
# Create packets
33
packet = IP(dst="8.8.8.8")/ICMP()
34
ethernet_packet = Ether()/IP(dst="192.168.1.1")/TCP(dport=80)
35

36
# Send packets and receive responses
37
response = sr1(packet, timeout=2)
38
if response:
39
    response.show()
40

41
# Capture packets
42
packets = sniff(count=10, filter="tcp port 80")
43
packets.summary()
44

45
# Read/write pcap files
46
packets = rdpcap("capture.pcap")
47
wrpcap("output.pcap", packets)
48

49
# Create complex protocols
50
dns_query = IP(dst="8.8.8.8")/UDP(dport=53)/DNS(rd=1, qd=DNSQR(qname="example.com"))
51
answer = sr1(dns_query)
52
```
53

54
## Architecture
55

56
Scapy is built around a flexible packet manipulation architecture:
57

58
- **Packet Class**: Universal packet representation supporting layered protocols
59
- **Field System**: Strongly-typed field definitions for protocol structures  
60
- **Layer Binding**: Automatic protocol layer recognition and chaining
61
- **Protocol Layers**: 100+ implemented network protocols from L2 to L7
62
- **Send/Receive Engine**: Cross-platform network I/O with multiple socket types
63
- **Analysis Framework**: Packet lists, filtering, and statistical analysis tools
64

65
This design enables Scapy to handle any network protocol, craft custom packets with precise control, and serve as both an interactive tool and a programmatic library for network security research, testing, and analysis.
66

67
## Capabilities
68

69
### Core Packet System
70

71
Fundamental packet creation, manipulation, and field system. Provides the Packet base class, field types, and core operations for building and dissecting network packets.
72

73
```python { .api }
74
class Packet:
75
    def __init__(self, *args, **kwargs): ...
76
    def show(self): ...
77
    def summary(self) -> str: ...
78
    def build(self) -> bytes: ...
79
    def copy(self): ...
80
    def getlayer(self, layer): ...
81
    def haslayer(self, layer) -> bool: ...
82

83
class Raw(Packet):
84
    def __init__(self, load: bytes = b""): ...
85

86
def bind_layers(lower, upper, **kwargs): ...
87
```
88

89
[Core Packet System](./core-packet-system.md)
90

91
### Protocol Layers
92

93
Comprehensive implementation of network protocols from Layer 2 to Layer 7, including Ethernet, IP, TCP, UDP, wireless protocols, and application-layer protocols.
94

95
```python { .api }
96
class Ether(Packet):
97
    def __init__(self, dst: str = "ff:ff:ff:ff:ff:ff", src: str = None, type: int = None): ...
98

99
class IP(Packet):
100
    def __init__(self, dst: str = "127.0.0.1", src: str = None, ttl: int = 64, **kwargs): ...
101

102
class TCP(Packet):
103
    def __init__(self, sport: int = 20, dport: int = 80, seq: int = 0, 
104
                 ack: int = 0, flags: int = 2, **kwargs): ...
105

106
class UDP(Packet):
107
    def __init__(self, sport: int = 53, dport: int = 53, **kwargs): ...
108

109
class ICMP(Packet):
110
    def __init__(self, type: int = 8, code: int = 0, **kwargs): ...
111

112
class DNS(Packet):
113
    def __init__(self, rd: int = 1, qd: DNSQR = None, **kwargs): ...
114
```
115

116
[Protocol Layers](./protocol-layers.md)
117

118
### Send/Receive Operations
119

120
Network I/O functions for sending packets, receiving responses, capturing traffic, and managing network communication across different platforms.
121

122
```python { .api }
123
def sr(x, promisc: bool = None, filter: str = None, timeout: float = None, 
124
       inter: float = 0, verbose: int = None, chainCC: bool = False, 
125
       retry: int = 0, multi: bool = False, **kwargs) -> tuple[SndRcvList, PacketList]: ...
126
def sr1(x, promisc: bool = None, filter: str = None, timeout: float = None, 
127
        verbose: int = None, retry: int = 0, **kwargs) -> Packet: ...
128
def send(x, inter: float = 0, loop: int = 0, count: int = None,
129
         verbose: int = None, realtime: bool = None, **kwargs) -> None: ...
130
def sendp(x, inter: float = 0, loop: int = 0, count: int = None,
131
          verbose: int = None, realtime: bool = None, iface: str = None, **kwargs) -> None: ...
132
def sniff(count: int = 0, store: bool = True, prn: callable = None, 
133
          filter: str = None, lfilter: callable = None, timeout: float = None, 
134
          iface: str = None, **kwargs) -> PacketList: ...
135

136
class AsyncSniffer:
137
    def __init__(self, count: int = 0, store: bool = True, prn: callable = None,
138
                 filter: str = None, lfilter: callable = None, **kwargs): ...
139
    def start(self): ...
140
    def stop(self): ...
141
    def join(self, timeout: float = None): ...
142
    @property
143
    def results(self) -> PacketList: ...
144
```
145

146
[Send/Receive Operations](./send-receive.md)
147

148
### Packet Analysis
149

150
Packet collection management, filtering, analysis, and visualization tools for working with captured network traffic and packet sequences.
151

152
```python { .api }
153
class PacketList:
154
    def summary(self) -> None: ...
155
    def show(self) -> None: ...
156
    def filter(self, func) -> PacketList: ...
157
    def plot(self, **kwargs): ...
158
    def conversations(self) -> dict: ...
159

160
class SndRcvList(PacketList):
161
    def make_table(self, **kwargs): ...
162

163
def rdpcap(filename: str, count: int = -1) -> PacketList: ...
164
def wrpcap(filename: str, pkt: PacketList, **kwargs) -> None: ...
165
```
166

167
[Packet Analysis](./packet-analysis.md)
168

169
### Configuration and Utilities
170

171
Global configuration management, utility functions for data conversion, validation, file operations, and platform-specific functionality.
172

173
```python { .api }
174
class Conf:
175
    def configure(self, **kwargs): ...
176

177
# Global configuration object
178
conf: Conf
179

180
def hexdump(x: bytes) -> None: ...
181
def checksum(data: bytes) -> int: ...
182
def get_if_list() -> list[str]: ...
183
def get_if_addr(iff: str) -> str: ...
184
def valid_ip(ip: str) -> bool: ...
185
def valid_mac(mac: str) -> bool: ...
186
```
187

188
[Configuration and Utilities](./config-utilities.md)
189

190
### Automation Framework
191

192
State machine framework for building automated network protocols, responding to network events, and creating interactive network services.
193

194
```python { .api }
195
class Automaton:
196
    def __init__(self): ...
197
    def start(self): ...
198
    def stop(self): ...
199

200
class ATMT:
201
    @staticmethod
202
    def state(name: str): ...
203
    @staticmethod
204
    def action(func): ...
205
    @staticmethod
206
    def receive(func): ...
207
    @staticmethod
208
    def timeout(func, timeout: float): ...
209
```
210

211
[Automation Framework](./automation.md)