Pwnagotchi WiFi Audit Tool Build / Guide

A “pwnagotchi” is a device used for wireless security auditing / hacking that captures the handshakes of any WiFi access points in range of the device. These handshakes can later be cracked. How difficult these are to crack depends on how secure the wireless network is. If the network is set up with the latest encryption standards and an extremely secure password (or is using WPA encryption) it can be nearly/essentially impossible. If the password is a common dictionary word it may crack within seconds.

It’s common and smart security practice for both enterprises and home users to check what kind of networks are operating within range. It’s common to find devices that are “broadcasting” a wireless access point used to share internet but this is often not intended / authorized. It’s also very common to find devices using extremely insecure passwords that will crack in seconds that are authorized to be on the network but need a more secure password. These are basically backdoors into your home / company and they can go for a long time without being caught when this is never checked for.

The “Pwnagotchi” tool automates this process. It will capture anything in range to be easily checked later for extremely insecure hashes (typically using hashcat or there are even online tools to find common hashes which we will cover). This saves a ton of time and can greatly improve your security. Today I’ll cover how to build a pwnagotchi setup as well as the steps to use it. Let’s begin!

Disclaimer

How you configure your pwnagotchi is extremely important and could even get you in legal trouble if you don’t know what you’re doing.

Understand that this is a serious tool and you must observe your local laws and regulations and be extremely careful with it. Only use it on your own networks or networks you are authorized to access/audit. Make sure to double and triple check you configure the tool for the correct mode that you intend to operate it.

Make sure you whitelist any networks in range that should not be audited. I will cover this in our initial configuration where we will create a whitelist.

Hardware Used

Backup Battery

You will notice that my Pi Zero W has a battery. This is called a PiSugar device and I’ve covered it here. This essentially gives me a battery that lasts several hours easily without recharging which is more than enough time to cover a significant amount of distance.

Note: All Pis work

The Pi Zero W specifically is not a requirement (it is recommended and what the original project was developed on/for) but you can alternatively use a Pi 4* or a Pi Zero 2 W* (the prebuilt images work best with the Pi Zero W* but you can use pwnagotchi on any Pi according to the developers).

We are in an absolutely terrible Raspberry Pi shortage at time of writing so you may have to take whatever you can get and that will be totally fine. The Pi 4 even has an advantage that it can audit 5 GHz networks (the Pi Zero W doesn’t do 5 GHz). That may be a consideration for some people. If you need 5 GHz capabilities you should use a Pi 4. The Pi Zero 2 W also does *not* do 5 GHz surprisingly (definitely a missed opportunity in my opinion) so you will want a Pi 4 for that.

I ended up using the Pi 4 in the back of my car where it didn’t matter that it was a little bigger and I use the Pi Zero for on-foot network audits. Different tools for different jobs but they definitely have their place and all work!

The e-ink screen is also optional but it’s *really* cool and it gives you an actual display so you know what it is doing (definitely a much funner experience than seeing nothing or trying to access it remotely).

Alternative Screen Option (official screen of the project):

Overview

To get an idea of the idea and spirit behind the Pwnagotchi project make sure you read their official intro. It’s worth it.

In a nutshell this device will capture WiFi handshakes from any device in range. There are different operating modes where it can be configured to passively collect this information or a more aggressive mode where it will try to communicate with the access points and initiate the handshakes. You can then take these handshakes and use them with a tool like hashcat to attempt to crack them and audit their strength manually or you can utilize Pwnagotchi’s plugins.

The plugins available for Pwnagotchi are extremely powerful. For example one of my favorite ones is the “wpa-sec.py” plugin. It will upload all handshakes to a well-known service called the “Distributed WPA PSK auditor“.

This means that weak handshakes you’ve detected will automatically have their passwords cracked online by this tool and be presented to you in a list. Here is some several year old data that this plugin collected during some audits:

Here you can see exactly why this is useful as a security audit tool. Devices with weak passwords that are commonly used will immediately be revealed by a Pwnagotchi with this plugin running.

The success rate is not incredibly high (this page had more than some of my other pages which would only have 2-3 revealed passwords per page) but as you can see it’s more than high enough (alarmingly high for residential points especially) to be worth configuring this plugin and checking your network with it for weak links that an attacker will find just as easily if this automated tool is able to collect and crack them that easily with no human intervention.

If networks are following appropriate password length and complexity requirements and not using common dictionary words this tool will *not* be able to crack them. That is normal and what you should see. It’s incredibly useful though for revealing devices setup with inappropriate / default credentials in the environment (usually unauthorized or misconfigured, or more commonly these days the device is setting up access points by default without explicitly being turned on).

There are many more plugins available. The official Pwnagotchi plugins list and documentation is available here.

Build Instructions

Download Location

The precompiled image can be downloaded here from the official Pwnagotchi GitHub releases page.

Write Image

Write this image to your SD card (or SSD) you are going to use with the Pi as you would normally.

Once the image has finished writing eject it from your SD card writer and then plug it back in. We need to create some configuration files before we boot up the pwnagotchi.

Creating config.toml

If you followed the instructions in the previous section you should have ejected your SD card after writing the image and then plugged it back in. You should now see the “boot” volume. This is where we are going to create a new file right in the root / base of the “boot” volume named:

config.toml

This is the main configuration file that controls the pwnagotchi. Let’s start with the basics (from the official documentation):

main.name = "pwnagotchi"
main.lang = "en"
main.whitelist = [
  "YourHomeNetworkMaybe"
]

ui.web.enabled = true
ui.web.address = "0.0.0.0"
ui.web.username = "changeme"
ui.web.password = "changeme"
ui.web.port = 8080

main.plugins.webcfg.enabled = true

main.plugins.grid.enabled = true
main.plugins.grid.report = true
main.plugins.grid.exclude = [
  "YourHomeNetworkMaybe"
]

ui.display.enabled = true
ui.display.type = "inky"
ui.display.color = "black"

Here we are giving the device a name and we can whitelist any networks we don’t want the Pwnagotchi to test. We are also going to select our screen type here. The example uses the type of “inky” and the display color of “black”. If you don’t have a display you can leave the last 2 lines out. Use ‘waveshare_2’ for the alternative Wavescreen recommendation. Additional options are here.

The middle section enables the ‘pwngrid’ plugin (enabled by default unless we explicitly disable it even if you don’t include the section in the file, you need to set enabled and report to false) which helps map access points you’ve discovered. Obviously this is not appropriate data to share sometimes so you can disable this here by setting both enabled and report to false if you do not want this functionality.

We can change the language if your native language is not English. This is done with the “main.lang” parameter on the second line of my example.

Watch out for settings not sticking when using the preconfigured config.toml method (especially the display). More on this in the next section.

Important config.toml Note

I and others have found that the Pwnagotchi does not always seem to pick up all these settings (particularly when trying to configure the screen).

If you find that your screen isn’t functioning then it’s likely that your config.toml settings aren’t being picked up. If you are experiencing this then the best way to solve it is to manually edit your /etc/pwnagotchi/config.toml file.

There are two ways to do this. The easiest way is using a Linux-based PC. If you can put the SD card into that PC it will be able to see the “root” partition. Other operating systems will not be able to see it. On Linux you can simply navigate to /etc/pwnagotchi/config.toml and edit it with a normal text editor.

The second method is to log into the Pi using the default credentials (pi/raspberry) either via SSH or using a monitor and keyboard. Once you are in you will again simply edit the file /etc/pwnagotchi/config.toml. Make sure that your display type is correct and that the display is enabled in /etc/pwnagotchi/config.toml.

Enabling WPA-SEC

If you want to enable WPA-SEC like I am using in the guide first register for a free account at wpa-sec.stanev.org.

Once you’ve registered and signed in you will see an API key in the top right of your screen. Add this section to config.toml (be very careful with spacing):

main.plugins.wpa-sec.enabled = true
main.plugins.wpa-sec.api_key = "XXXXXXXXXXXXX"
main.plugins.wpa-sec.api_url = "https://wpa-sec.stanev.org"
main.plugins.wpa-sec.download_results = true
main.plugins.wpa-sec.whitelist = [
 "YourNetworkMaybe"
]

Additional Configuration

You should absolutely read the official “Configuration” documentation from pwnagotchi.ai. It’s very comprehensive and gets into the gritty details of everything you can do!

Usage

Once the Pwnagotchi boots up you will start seeing activity from both the Pi Zero W’s activity indicator lights as well as the attached display (if you have one).

The device is automated. If you did all of your initial configuration in the previous section then you’re ready to start gathering handshakes! The top right of the screen will have your uptime, the bottom left shows how many networks it has seen vs. how many it was able to successfully capture handshakes for (those are considered “pwned” in the display’s stats.

Simply move around the area you are auditing until you’ve collected all of the data you need.

There is so much more that the Pwnagotchi can do. It has a built in bettercap interface for example which is extremely powerful. My goal isn’t to cover every single thing it can do but to show you how to get started with it / the main capabilities. Definitely make sure you read the official Pwnagotchi usage guide here!

Retrieving Captured Handshakes

This is the most tricky part of using the pwnagotchi. There are several ways to connect to your pwnagotchi to download the handshakes. These are located in the folder:

/root/handshakes

You can use gadget mode. This requires you to connect your Pi Zero to your PC with a data cable. This will put it in a special mode where you can connect and download files from the device. You can also share your internet connection with the device in this mode. To use this mode make sure to see the official “Connect to your Pwnagotchi” documentation where they cover how to configure this on Mac, Windows, and Linux individually (too long to repeat here).

If you connect an Ethernet adapter you can simply SSH into the device normally.

My personal favorite mode since I use Linux on my main desktop PC is I can simply just take the SD card out of the Pi and put it in my PC. If you are on a Linux based PC you will be able to see the “root” partition and simply browse to /root/handshakes in your file explorer window. This won’t work on Windows as Windows will only see the “boot” partition.

Conclusion

I’ve been using this tool for years and have been kind of surprised more people haven’t caught onto how useful this is. Combined with the plugins I outlined this device will immediately detect devices on your property / networks / wherever that are broadcasting wireless networks with extremely weak credentials. You can then investigate the source and take the appropriate measures to secure them.

This is completely automated and portable. While it’s possible to do these kind of audits on a laptop or other device you’d be hard pressed to find setups that make it as easy as a Raspberry Pi Zero running this software makes it. Add the plugin capabilities and it rivals (and often outperforms) even expensive commercially available setups designed to do exactly this same thing.

I suspect it’s never got the recognition it deserves partially because it’s presented to be fun with the different faces and moods of the Pwnagotchi and seems more like a toy to people (probably because the faces and some of the other fun parts in the project are inspired by the Tomagotchi digital pets from the 90’s, and yes I had one as did almost every kid on the street I grew up on when that fad hit).

The faces more represent whether the AI is getting enough “mental stimulation”. If it’s showing sad and angry faces it’s just letting you know there’s nothing more for it to really do here and it’s time to move on. There’s a bit more to it than that and if you want more details then the official “How does Pwnagotchi work?” is a good resource and explains every face and some of the algorithms driving them.

It’s definitely not a toy. It’s an extremely powerful tool and I encourage anyone responsible for securing networks to try running a tool like this at your location and see what comes up. It’s not going to be the things you are thinking about (or probably even realize are there) and that is the point.

I bet you will be surprised what it finds and it’s better to be surprised by your own audit than by a breach!

Additional Resources

Another very awesome wireless tool is the HackRF + PortaPack Upgrade: Upgrading HackRF One to PortaPack H2

For strategies on how to get reasonably priced Pis check out my Raspberry Pi Shortage Survival Guide

If you want to learn how to use a SSD with your Pi check out my Best Storage Adapters and SSDs to use with the Pi article