Scapy - https://github.com/secdev/scapy¶
packets manipulation in Python
developed by Philippe Biondi, since 2003
- maintained by Gabriel, Guillaume & Pierre, since 2012
native support on Linux, macOS & *BSD
- Solaris & Windows thanks to
libpcap&npcap.dll
- Solaris & Windows thanks to
Python3 compatible since 2018
Stats¶
PyPI downloads
- daily: 15k
- Python3: 80%
GiHub
- stars: 4200
- daily clones: 300
Python versions
- 2.7, 3.4, 3.5, 3.6, 3.7, pypy, pypy3
Installing & Launching Scapy¶
It is as simple as cloning the git repository:
git clone --depth 1 https://github.com/secdev/scapy
cd scapy
sudo ./run_scapy
aSPY//YASa
apyyyyCY//////////YCa |
sY//////YSpcs scpCY//Pp | Welcome to Scapy
ayp ayyyyyyySCP//Pp syY//C | Version 2.4.3
AYAsAYYYYYYYY///Ps cY//S |
pCCCCY//p cSSps y//Y | https://github.com/secdev/scapy
SPPPP///a pP///AC//Y |
A//A cyP////C | Have fun!
p///Ac sC///a |
P////YCpc A//A | We are in France, we say Skappee.
scccccp///pSP///p p//Y | OK? Merci.
sY/////////y caa S//P | -- Sebastien Chabal
cayCyayP//Ya pY/Ya |
sY/PsY////YCc aC//Yp
sc sccaCY//PCypaapyCP//YSs
spCPY//////YPSps
ccaacs
using IPython 7.6.1
>>>Today Tutorial?¶
I will escort you in the discovery of most Scapy features:
- packets manipulation
- interacting with the network
- visualization
- using Scapy as a Python module
- implementing a new protocol
- answering machines
- IPv6 reconnaissance
- X.509 certificates manipulation
- TLS tricks
Slides available at https://guedou.github.io/¶
Packets Manipulation¶
- packets are Python objects
- the
/operator is used to stack packets
In [2]:
packet = IP() / TCP()
Ether() / packet
Out[2]:
- the
ls()function list packets fields
>>> ls(IP, verbose=True)
version : BitField (4 bits) = (4)
ihl : BitField (4 bits) = (None)
tos : XByteField = (0)
len : ShortField = (None)
id : ShortField = (1)
flags : FlagsField (3 bits) = (<Flag 0 ()>)
MF, DF, evil
frag : BitField (13 bits) = (0)
ttl : ByteField = (64)
proto : ByteEnumField = (0)
chksum : XShortField = (None)
src : SourceIPField = (None)
dst : DestIPField = (None)
options : PacketListField = ([])- Scapy selects the correct source IPv4 address, MAC addresses...
In [3]:
p = Ether() / IP(dst="www.secdev.org") / TCP(flags="F")
p.summary()
Out[3]:
- all fields can be easily accessed
In [4]:
print(p.dst) # first layer with a dst field, i.e. Ether
print(p[IP].src) # explicit access to the IP layer src field
# sprintf() supports Scapy own formats strings
print(p.sprintf("%Ether.src% > %Ether.dst%\n%IP.src% > %IP.dst%"))
- a field can store many values
In [5]:
[p for p in IP(ttl=(1, 5)) / ICMP()] # a sequence of values from 1 to 5
Out[5]:
In [6]:
[p for p in IP() / TCP(dport=[22, 80, 443])] # specific values
Out[6]:
Interacting With The Network¶
- the
sr1()function sends a packet and returns a reply - Scapy can match queries and answers
In [7]:
r = sr1(IP(dst="8.8.8.8") / UDP() / DNS(qd=DNSQR()))
r[DNS].an
Out[7]:
- the
srp()function sends a list of frames and returns two variables:ra list of queries and matched answersua list of unanswered packets
In [8]:
r, u = srp(Ether() / IP(dst="8.8.8.8", ttl=(5, 10)) / UDP() / DNS(qd=DNSQR(qname="www.example.com")))
r, u
Out[8]:
In [9]:
# Access the first tuple
print(r[0][0].summary()) # sent packet
print(r[0][1].summary()) # received packet
# Scapy received an ICMP time-exceeded
r[0][1][ICMP]
Out[9]:
- a list of packets can be written to and read from a
PCAPfile
In [10]:
wrpcap("scapy.pcap", r)
pcap_p = rdpcap("scapy.pcap")
pcap_p[0]
Out[10]:
- the
command()method gives the Python statement that will build the same object
In [11]:
pcap_p[0].command()
Out[11]:
- the
sniff()function captures packets
In [12]:
s = sniff(count=2)
s
Out[12]:
In [13]:
sniff(count=2, prn=lambda p: p.summary())
Out[13]:
In [14]:
sniff(offline=IP(dst="8.8.8.8/24") / UDP(), filter="udp and dst host 8.8.8.8")
Out[14]:
- the
lsc()function lists available commands
>>> lsc()
IPID_count : Identify IP id values classes in a list of packets
arpcachepoison : Poison target's cache with (your MAC,victim's IP) couple
arping : Send ARP who-has requests to determine which hosts are up
arpleak : Exploit ARP leak flaws, like NetBSD-SA2017-002.
bind_layers : Bind 2 layers on some specific fields' values.
bridge_and_sniff : Forward traffic between interfaces if1 and if2, sniff and return
chexdump : Build a per byte hexadecimal representation
computeNIGroupAddr : Compute the NI group Address. Can take a FQDN as input parameter
corrupt_bits : Flip a given percentage or number of bits from a string
corrupt_bytes : Corrupt a given percentage or number of bytes from a string
defrag : defrag(plist) -> ([not fragmented], [defragmented],
defragment : defragment(plist) -> plist defragmented as much as possible
dhcp_request : Send a DHCP discover request and return the answer
[..]In [15]:
# Send ARP who-has requests to determine which hosts are up
arping("192.168.42.0/24")
Out[15]:
- the
help()function describes commands behaviors and arguments
>>> help(traceroute)
Help on function traceroute in module scapy.layers.inet:
traceroute(target, dport=80, minttl=1, maxttl=30, sport=<RandShort>, l4=None, filter=None, timeout=2, verbose=None, **kargs)
Instant TCP traceroute
:param target: hostnames or IP addresses
:param dport: TCP destination port (default is 80)
:param minttl: minimum TTL (default is 1)
:param maxttl: maximum TTL (default is 30)
:param sport: TCP source port (default is random)
:param l4: use a Scapy packet instead of TCP
:param filter: BPF filter applied to received packets
:param timeout: time to wait for answers (default is 2s)
:param verbose: detailed output
:return: an TracerouteResult, and a list of unanswered packetsVisualization¶
- with
srloop(), send 100 packets to 8.8.8.8 and 8.8.4.4 - the
multiplot()method can be used to display IP ID values
In [20]:
ans, unans = srloop(IP(dst=["8.8.8.8", "1.1.1.1"]) / ICMP(), inter=.1, timeout=.1, count=80, verbose=False)
In [21]:
%matplotlib inline
ans.multiplot(lambda x, y: (y[IP].src, (y.time, y[IP].id)), plot_xy=True)
Out[21]:
- the
raw()function builds a packet, as sent on the network
In [22]:
pkt = IP() / UDP() / DNS(qd=DNSQR())
repr(raw(pkt))
Out[22]:
This representation being complicated, Scapy can:
- do a
hexdumpof the content
In [23]:
hexdump(pkt)
- dump fields content layer by layer
In [24]:
pkt.show()
- display a pretty representation
In [14]:
pkt.canvas_dump()
Out[14]:
The traceroute() functions calls sr(IP(ttl=(1,15)) and create the TracerouteResult object
In [25]:
ans, unans = traceroute('www.secdev.org', maxttl=15)
In [22]:
%matplotlib inline
ans.world_trace()
Out[22]:
The make_table() method provides a compact results representation, useful for a basic port scanner
In [27]:
targets = ["scanme.nmap.org", "nmap.org"]
ans = sr(IP(dst=targets) / TCP(dport=[22, 80, 443, 31337]), timeout=3, verbose=False)[0]
ans.extend(sr(IP(dst=targets) / UDP() / DNS(qd=DNSQR()), timeout=3, verbose=False)[0])
ans.make_table(lambda x, y: (x[IP].dst,
x.sprintf('%IP.proto%/{TCP:%r,TCP.dport%}{UDP:%r,UDP.dport%}'),
y.sprintf('{TCP:%TCP.flags%}{ICMP:%ICMP.type%}')))
Scapy As a Python Module¶
Scapy can be used to build your own tools like ping6.py:
In [35]:
import argparse
from scapy.all import *
parser = argparse.ArgumentParser(description="A simple ping6")
parser.add_argument("ipv6_host", help="An IPv6 address")
args = parser.parse_args()
print(sr1(IPv6(dst=args.ipv6_host) / ICMPv6EchoRequest(), verbose=0).summary())
sudo python ping6.py www.kame.net
IPv6 / ICMPv6 Echo Reply (id: 0x0 seq: 0x0)
Implementing a New Protocol¶
To add new protocols, create an object:
- that inherits from
Packet - defines fields in the
fields_descvariable
In [36]:
class DNSTCP(Packet):
name = "DNS over TCP"
fields_desc = [ FieldLenField("len", None, fmt="!H", length_of="dns"),
PacketLenField("dns", 0, DNS, length_from=lambda p: p.len)]
# This method tells Scapy to decode the payload with DNSTCP
def guess_payload_class(self, payload):
return DNSTCP
This new protocol can be directly used to build and parse a packet
In [37]:
DNSTCP(raw(DNSTCP(dns=DNS())))
Out[37]:
The StreamSocket object allows Scapy to use a TCP socket
In [38]:
import socket
from scapy.all import *
sck = socket.socket(socket.AF_INET, socket.SOCK_STREAM) # create a TCP socket
sck.connect(("8.8.8.8", 53)) # connect to 8.8.8.8 on 53/TCP
# Create a StreamSocket and define the default class
ssck = StreamSocket(sck)
ssck.basecls = DNSTCP
# Send the DNS query
ssck.sr1(DNSTCP(dns=DNS(qd=DNSQR(qname="www.example.com"))))
Out[38]:
Answering Machines¶
Scapy can wait for a query, then send an answer with the AnsweringMachine object.
Two methods are mandatory:
is_request(): returnsTrueif the packet is the expected querymake_reply(): returns the packet that will be sent by Scapy
Note: in the following example, the Wi-Fi interface must be put in monitor mode
In [ ]:
from scapy.all import *
# Specify the Wi-Fi interface
conf.iface = "mon0"
# Create the Answering Machine
class ProbeRequest_am(AnsweringMachine):
function_name = "pram"
mac = "00:11:22:33:44:55"
def is_request(self, pkt):
return Dot11ProbeReq in pkt
def make_reply(self, req):
rep = RadioTap()
# Note: depending on your Wi-Fi card, you might need something else than RadioTap()
rep /= Dot11(addr1=req.addr2, addr2=self.mac, addr3=self.mac, ID=RandShort(), SC=RandShort())
rep /= Dot11ProbeResp(cap="ESS", timestamp=int(time.time())
rep /= Dot11Elt(ID="SSID", info="Scapy !")
rep /= Dot11Elt(ID="Rates", info='\x82\x84\x0b\x16\x96')
rep /= Dot11Elt(ID="DSset", info=orb(10))
return rep
# Start the answering machine
#ProbeRequest_am()() # uncomment to test
IPv6 Reconnaissance¶
- discover the link IPv6 router using the Router Solicitation message
In [39]:
sr1(IPv6() / ICMPv6ND_RS())
Out[39]:
- probe local nodes and list manufacturers
In [40]:
a,u = sr(IPv6(dst="ff02::1") / ICMPv6EchoRequest(), multi=1, timeout=1)
a.make_table(lambda t: (t[0][IPv6].dst, t[1][IPv6].src, in6_addrtovendor(t[1][IPv6].src)))
X.509 Certificates Manipulation¶
- Scapy can easily parse certificates, and display their contents
In [1]:
load_layer("tls")
cert_blackhat = Cert(pem2der(open("files/blackhat.com.pem", "rb").read())) # assuming you d/l the certificate
cert_blackhat
Out[1]:
- several useful methods help exploring them
In [2]:
print(cert_blackhat.isSelfSigned()) # check if it is self signed
print(cert_blackhat.subject) # display the subject
print(cert_blackhat.remainingDays()) # compute the number of days until expiration
- look for the Subject Alternative Name extension
In [3]:
[e for e in cert_blackhat.tbsCertificate.extensions if e.extnID == "2.5.29.17"]
Out[3]:
- moreover, some cryptographic tricks are also included, like verifying signatures
In [4]:
# Verify issuers signatures
cert_comodo = Cert(pem2der(open("files/comodo.pem", "rb").read())) # assuming you d/l the certificate
print(cert_blackhat.isIssuerCert(cert_comodo)) # check the signature
- or, change the certificate signature
In [5]:
cert_blackhat.tbsCertificate.serialNumber.val = 0x42 # Change a value
private_key = PrivKeyRSA("files/private_key.pem") # Load a private key
new_cert_blackhat = private_key.resignCert(cert_blackhat) # Do a new signature
print(hex(new_cert_blackhat.tbsCertificate.serialNumber.val)) # Print the value
print(private_key.verifyCert(new_cert_blackhat)) # Verify the signature
HTTP & TLS tricks¶
- since Scapy v2.4.3, it is possible to perform HTTP queries
In [6]:
load_layer("http")
req = HTTP() / HTTPRequest(
Accept_Encoding=b'gzip, deflate',
Cache_Control=b'no-cache',
Pragma=b'no-cache',
Connection=b'keep-alive',
Host=b'www.secdev.org',
)
t = TCP_client.tcplink(HTTP, "www.secdev.org", 80)
r = t.sr1(req, timeout=3)
In [66]:
r[HTTPResponse].show()
- sniff TLS traffic
In [11]:
load_layer("tls")
s = sniff(filter="port 443", count=100) # sniff packets on port 443
ch_list = [p for p in s if TLSClientHello in p] # filter Client Hello messages
ch_list[0][TLSClientHello].show() # display the first message
Online Resources¶
Projects That Uses Scapy¶
Wi-Fi & Bluetooth
- Clients deauthentication - https://github.com/DanMcInerney/wifijammer
- Rogue Access Points - https://github.com/wifiphisher/wifiphisher & https://github.com/P0cL4bs/WiFi-Pumpkin
- BT/BLE Attacks - https://redmine.laas.fr/projects/mirage
IPv6
- Windows MITM - https://github.com/fox-it/mitm6
- Assessment framework - https://github.com/aatlasis/Chiron
Audits & Attacks
- KRACK - https://github.com/vanhoefm/krackattacks-scripts
- LLMNR & MDNS poisoner - https://github.com/SpiderLabs/Responder
- 802.1x bypass - https://github.com/Orange-Cyberdefense/fenrir-ocd
- RADIUS - https://github.com/ANSSI-FR/audit-radius