Scapy?¶
- packets manipulation in Python
- developed by Philippe Biondi, since 2003
- maintained by Guillaume & Pierre, since 2012
- native support on Linux, Mac OS X, *BSD, & Windows
- on Windows, only
npcap.dllis required
- on Windows, only
- get it at https://github.com/secdev/scapy
- you can star the project !
- documentation at https://scapy.readthedocs.io
What's New Since 2.3.3?¶
core¶
- numerous patches to prepare for Python 3 compatibility
- see guidelines at https://github.com/secdev/scapy/blob/master/CONTRIBUTING.md
- better Windows support: IPv6 now works
- a lot of new unit tests
protocols¶
- new: HTTP/2, EAP-TTLS, TACACS, MQTT,
- updated: SCTP, NTP, PPTP, CDP, BGP, ISIS
- major changes: TLS, X.509
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 4ad7977
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 | To craft a packet, you have to be a
scccccp///pSP///p p//Y | packet, and learn how to swim in
sY/////////y caa S//P | the wires and in the waves.
cayCyayP//Ya pY/Ya | -- Jean-Claude Van Damme
sY/PsY////YCc aC//Yp |
sc sccaCY//PCypaapyCP//YSs
spCPY//////YPSps
ccaacs
>>>Today's 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
- advanced features: automaton, pipes
These slides are available at: https://guedou.github.io/¶
Packets Manipulation¶
- packets are 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) = (0)
MF, DF, evil
frag : BitField (13 bits) = (0)
ttl : ByteField = (64)
proto : ByteEnumField = (0)
chksum : XShortField = (None)
src : SourceIPField (Emph) = (None)
dst : DestIPField (Emph) = (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]:
p = sr1(IP(dst="8.8.8.8")/UDP()/DNS(qd=DNSQR()))
p[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 string 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]:
- 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
bind_layers : Bind 2 layers on some specific fields' values
bridge_and_sniff : Forward traffic between interfaces if1 and if2, sniff and return the
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 : defrag(plist) -> plist defragmented as much as possible
dhcp_request : --
[..]In [14]:
# Send ARP who-has requests to determine which hosts are up
arping("192.168.46.0/24")
Out[14]:
- 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
traceroute(target, [maxttl=30,] [dport=80,] [sport=80,] [verbose=conf.verb]) -> NoneVisualization¶
- 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 [15]:
ans, unans = srloop(IP(dst=["8.8.8.8", "8.8.4.4"])/ICMP(), inter=.1, timeout=.1, count=100, verbose=False)
In [16]:
%matplotlib inline
ans.multiplot(lambda (x, y): (y[IP].src, (y.time, y[IP].id)), plot_xy=True)
Out[16]:
- the
str()function builds a packet, as sent on the network
In [17]:
pkt = IP() / UDP() / DNS(qd=DNSQR())
repr(str(pkt))
Out[17]:
This representation being complicated, Scapy can:
- do a
hexdumpof the content
In [18]:
hexdump(pkt)
- dump fields content layer by layer
In [19]:
pkt.show()
- display a pretty representation
In [20]:
pkt.canvas_dump()
Out[20]:
The traceroute() functions calls sr(IP(ttl=(1,15)) and create the object TracerouteResult
In [21]:
ans, unans = traceroute('www.secdev.org', maxttl=15)
Different methods can be used to display the results, like world_trace() that uses the GeoIP module from MaxMind
In [22]:
ans.world_trace()
Out[22]:
The make_table() method provides a compact results representation, useful for a basic port scanner
In [23]:
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 [ ]:
from scapy.all import *
import argparse
parser = argparse.ArgumentParser(description="A simple ping6")
parser.add_argument("ipv6_address", help="An IPv6 address")
args = parser.parse_args()
print sr1(IPv6(dst=args.ipv6_address)/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 [24]:
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 [25]:
DNSTCP(str(DNSTCP(dns=DNS())))
Out[25]:
The StreamSocket object allows Scapy to use a TCP socket
In [26]:
import socket
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[26]:
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 [ ]:
# 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=time.time())
rep /= Dot11Elt(ID="SSID",info="Scapy !")
rep /= Dot11Elt(ID="Rates",info='\x82\x84\x0b\x16\x96')
rep /= Dot11Elt(ID="DSset",info=chr(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 [28]:
sr1(IPv6()/ICMPv6ND_RS())
- probe local nodes and list manufacturers
In [29]:
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 [27]:
load_layer("tls")
cert_github = Cert(pem2der(open("files/github.com.pem").read())) # assuming you d/l the certificate
cert_github
Out[27]:
- several useful methods help exploring them
In [30]:
print cert_github.isSelfSigned() # check if it is self signed
print cert_github.subject # display the subject
print cert_github.remainingDays() # compute the number of days until expiration
- moreover, some cryptographic tricks are also included, like verifying signatures:
In [31]:
# Verify issuers signatures
cert_digicert = Cert(pem2der(open("files/digicert_sha2.pem").read())) # assuming you d/l the certificate
print cert_github.isIssuerCert(cert_digicert) # check the signature
- or, change the certificate signature:
In [32]:
cert_github.tbsCertificate.serialNumber.val = 0x42 # Change a value
private_key = PrivKeyRSA("files/private_key.pem") # Load a private key
new_cert_github = private_key.resignCert(cert_github) # Do a new signature
print hex(new_cert_github.tbsCertificate.serialNumber.val) # Print the value
print private_key.verifyCert(new_cert_github) # Verify the signature
TLS tricks¶
- sniff TLS traffic
In [34]:
load_layer("tls")
s = sniff(filter="port 443", count=10) # 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
Advanced Features¶
- automaton: ease the creation of state machines with decorators
- pipes can be used for advanced manipulations: forwarding between interfaces, on the fly modifications, ...
- the nfqueue Python module could be used to perform simple MitM