SANS Penetration Testing

Special Request: Wireless Client Sniffing with Scapy

[Editor comment: Dude! A Scapy article by Josh Wright that can help us stay in scope and follow rules of engagement in a pen test? What's not to like? :) -Ed.]

By Joshua Wright, InGuardians

I participate on the Scapy mailing list, helping out with questions where I am able. Recently, I saw a question that piqued my interest:
"What I'm looking to do is identify the MAC addresses of client devices without actually sniffing any packets containing actual data relating to website content, email content etc. [...] Are there any packets I could look at that would contain the MAC of client devices but not contain any online usage data as outlined?"

If we want to investigate the presence of wireless client devices but want to avoid capturing any data frames, we can focus on management frames. WiFi networks use management frames to establish a connection to the network, disconnect from the network, and more. Three management frames are easily distinguishable as being sent by client devices only:

- Probe Request Frames
- Association Request Frames
- Reassociation Request Frames

Using Scapy, it is easy to write a little Python that checks for the IEEE 802.11 type field to determine if a frame is a management frame, then examine the subtype field to determine if it is one of the three only sent by client devices.

First, we need to put a wireless card interface into monitor mode, as shown:

root@bt:~# airmon-ng start wlan0
Interface Chipset Driver
wlan0 Ralink RT2870/3070 rt2800usb - [phy0]
(monitor mode enabled on mon0)

With the mon0 interface receiving packets in monitor mode, we can run the following Scapy script. I've added a lot of comments in the script to help explain what is happening.

#!/usr/bin/env python
# The previous line ensures that this script is run under the context
# of the Python interpreter. Next, import the Scapy functions:
from scapy.all import *

# Define the interface name that we will be sniffing from, you can
# change this if needed.
interface = "mon0"

# Next, declare a Python list to keep track of client MAC addresses
# that we have already seen so we only print the address once per client.
observedclients = []

# The sniffmgmt() function is called each time Scapy receives a packet
# (we'll tell Scapy to use this function below with the sniff() function).
# The packet that was sniffed is passed as the function argument, "p".
def sniffmgmt(p):

# Define our tuple (an immutable list) of the 3 management frame
# subtypes sent exclusively by clients. I got this list from Wireshark.
stamgmtstypes = (0, 2, 4)

# Make sure the packet has the Scapy Dot11 layer present
if p.haslayer(Dot11):

# Check to make sure this is a management frame (type=0) and that
# the subtype is one of our management frame subtypes indicating a
# a wireless client
if p.type == 0 and p.subtype in stamgmtstypes:

# We only want to print the MAC address of the client if it
# hasn't already been observed. Check our list and if the
# client address isn't present, print the address and then add
# it to our list.
if p.addr2 not in observedclients:
print p.addr2
observedclients.append(p.addr2)

# With the sniffmgmt() function complete, we can invoke the Scapy sniff()
# function, pointing to the monitor mode interface, and telling Scapy to call
# the sniffmgmt() function for each packet received. Easy!
sniff(iface=interface, prn=sniffmgmt)

Next, we simply run the script:

# python client-nodata-enum.py
WARNING: No route found for IPv6 destination :: (no default route?)
88:c6:63:fa:de:d9
00:26:b0:75:ef:f5
00:1f:3a:4f:a2:be
58:1f:aa:ba:77:fe
0c:74:c2:5e:25:11
60:33:4b:f0:43:34
f4:0b:93:04:b5:d9
90:4c:e5:60:61:2e
8c:58:77:90:a0:da
00:21:5c:7e:70:c3
From here, lots of opportunities become available. For example, we could disconnect each client from the network by adding the following line after the print statement:
sendp(RadioTap()/Dot11(type=0,subtype=12,addr1=p.addr2,addr2=p.addr3,addr3=p.addr3)/Dot11Deauth())

We might do this in a penetration test to gently disconnect each user from the network once while capturing the activity to observe the EAP types in use (since clients reconnect automatically, this will typically have little impact to the network, but it's a good idea to ensure your customer is prepared for a potential outage if clients do not reconnect gracefully).

I'm not sure why the original request wanted to obtain a list of client MAC addresses without looking at data frames, but it's a simple task with Scapy. In the Ethical Hacking Wireless SEC617 course, we spend a good amount of time on Scapy with an emphasis on wireless fuzzing, while the Advanced Penetration Testing SEC660 course leverages Scapy for a number of wired-side attack techniques.
You can grab the script in this module, without comments, from my website at http://www.willhackforsushi.com/code/client-nodata-enum.py.
-Josh

10 Comments

Posted April 10, 2013 at 6:41 AM | Permalink | Reply

Wayne

Great article, actually I have been hunting scapy usage on 802.11''but not many useful results. And it seems the scapy official document don't have much content about dot11.
Could you kindly refer me any sources of info about dot11 usage.
Thanks!

Posted April 12, 2013 at 4:58 PM | Permalink | Reply

Josh Wright

The documentation for IEEE 802.11-specific use of Scapy is a little sparse (http://www.secdev.org/projects/scapy/doc/), but Scapy is also self-documenting! From an interactive Scapy shell, you can issue the ls() command to see a list of packet types that are available. For any packet type, add the packet type name inside the parenthesis to see a list of fields you can edit, as in:
ls(Dot11)
This will help you learn what Scapy has to offer, but it doesn't help explain the IEEE 802.11 protocol itself, and sometimes Scapy's packet parameter names are mildly misleading, causing confusion as to what Dot11.FCField actually means. However, we have Wireshark! First, create a simple packet with no parameters, as in:
p=Dot11()
Next, open the packet in Wireshark by running:
wireshark(p)
This first packet won't be terribly interesting, but you can return to Scapy and do this again for any combination of packet types. Try:
p=Dot11(type=0,subtype=4,FCFlags=0xff)
And then:
wireshark(p)
The new packet will look a lot different than the previous one, and you can experiment to see what fields get tweaked by Scapy by using the packet dissector view in Wireshark.
I love it when a plan comes together.

Posted April 12, 2013 at 5:00 PM | Permalink | Reply

Josh Wright

The documentation for IEEE 802.11-specific use of Scapy is a little sparse (http://www.secdev.org/projects/scapy/doc/), but Scapy is also self-documenting! From an interactive Scapy shell, you can issue the ls() command to see a list of packet types that are available. For any packet type, add the packet type name inside the parenthesis to see a list of fields you can edit, as in: ls(Dot11). This will help you learn what Scapy has to offer, but it doesn't help explain the IEEE 802.11 protocol itself, and sometimes Scapy's packet parameter names are mildly misleading, causing confusion as to what Dot11.FCField actually means. However, we have Wireshark! First, create a simple packet with no parameters, as in: p=Dot11(). Next, open the packet in Wireshark by running: wireshark(p). This first packet won't be terribly interesting, but you can return to Scapy and do this again for any combination of packet types. Try: p=Dot11(type=0,subtype=4,FCFlags=0xff). And then: wireshark(p). The new packet will look a lot different than the previous one, and you can experiment to see what fields get tweaked by Scapy by using the packet dissector view in Wireshark. I love it when a plan comes together.

Posted July 17, 2013 at 10:10 PM | Permalink | Reply

Summertime Sadness

This is really great work !
thanks alot for sharing it with us , we want more and more

Posted December 11, 2013 at 9:19 PM | Permalink | Reply

Tim

This is exactly what I'm looking for in my project. Is it also possible to get to know the strength of the incoming signal?

Posted January 23, 2014 at 7:28 AM | Permalink | Reply

Rahul

What I want to do is sniffing data packets containing actual data relating to website content, email content . How can I do that ?? ( I want this for my academic project )

Posted February 22, 2014 at 11:47 AM | Permalink | Reply

Ed Skoudis

Rahul ''" Use Wireshark. It's a great, free sniffer that'll provide the data you need.

Posted March 10, 2014 at 2:34 AM | Permalink | Reply

sec560stud2013

Great article for expanding scapy to do wireless related stuffs! came across this while searching scapy on duckduckgo, need for readings learned from sec560 class i took last nov2k12 in singapore.
Thanks Ed and Josh

Posted March 11, 2014 at 10:47 AM | Permalink | Reply

Ed Skoudis

Thank you, Sec560 stud. Glad you found it useful. Nice name, by the way.

Posted April 21, 2014 at 9:58 AM | Permalink | Reply

pd

Thanks for this. Im teaching myself python and wanted to do exactly this but lack the underlying knowledge of IEEE 802.11.
I imagine whoever asked the question was interested in tracking and or locating individuals using the mac address(s) of their mobile device(s).

Post a Comment






Captcha


* Indicates a required field.