Pwnagotchi is an A2C-based AI, powered by bettercap and running on a Raspberry Pi Zero W, that learns from its surrounding Wi-Fi environment to maximize crackable WPA key material it captures (either through passive sniffing or by performing de-authentication and association attacks). This material is collected on disk as PCAP files containing any form of handshake supported by hashcat, including full and half WPA handshakes as well as PMKIDs.

It also has an adorable user interface that displays different “moods” depending on what it’s doing and echoes the Tamagotchi digital pets of the 90s. The idea is for its user to take their Pwnagotchi around a city and “feed” it with Wi-Fi handshakes. Pwnagotchi tunes its parameters over time to get better at pwning Wi-Fi things in real-world environments that you expose it to.

To put together your adorable AI buddy, you need to first set up the software on an SD card via flashing the latest release. Download the latest Pwnagotchi release. Then Download and install balenaEtcher. Connect an SD card reader to your PC with the SD card inside. Open balenaEtcher and select the Pwnagotchi Raspbian Lite file you wish to write to the SD card. Select the SD card you wish to write your image to. Review your selections, then click Flash! to begin writing data to the SD card. Wait before removing the SD card as you will need to create one last file on it with the initial configuration.

For the initial configuration, the easiest way is creating a new config.yml YAML file on the boot partition of the SD card. This partition should be easily accessible from your computer regardless of your operating system as it is a simple FAT32 partition. In this process, you might define your Pwnagotchi’s name, a network to whitelist, and the type of display you use. The following is the example initial configuration for a unit with a Pimoroni Inky pHAT display. The grid plug-in signals the unit’s cryptographic identity and optionally reports a list of pwned networks to the PwnGRID.

main:

name: 'pwnagotchi'

plugins:

grid:

enabled: true

exclude:

- 'YourHomeNetworkMaybe'

report: true

whitelist:

- 'YourHomeNetworkMaybe'



ui:

color: 'black'

display: ~

enabled: true

type: 'inky'

Check your config with a YAML validator. During boot, the Pwnagotchi will automatically install this file to /etc/pwnagotchi/config.yml on the Pi and will remove it from the SD card boot partition. Default configuration values that aren’t explicitly set in this file can be viewed in / etc/pwnagotchi/defaults.yml

Because the Inky pHAT used in this build comes fully-assembled, there’s no need to solder anything, so you can just push it down onto the GPIO pins on your Pi Zero WH and get going. Once you have done this then you can eject the SD card from your PC and put it in your Pi. The first time the Pwnagotchi boots it will take some time so wait. This is because the unit needs to generate RSA keys at first boot which will take a few minutes. This process should not be interrupted for the keys not to be corrupted. Once the green LED stops blinking you should see your Pwnagotchi’s face on the eInk display. You can then connect to the Pi via USB. You will hear the “new hardware detected” sound this is the RNDIS gadget being installed.

Next, you will want to be able to connect to your Pwnagotchi from your PC as well as have it share the computer’s network connection. Start by connecting the micro-USB cable to the data port of your Pwnagotchi on the Pi, then connect the other end of that cable to your PC. If your Pwnagotchi has already been booted up at least once before: after a few seconds, you will see a new Ethernet interface on your host computer.

Now right-click the network icon on the bottom right taskbar. Open Network & Internet Settings. Change adapter options. Right-click the Raspberry Pi which will be something like Ethernet 2, go to properties, click Internet Protocol Version 4, and click Properties. Use the following IP address: 10.0.0.1 , subnet mask 255.255.255.0 , gateway 10.0.01, DNS server 1.1.1.1, 8.8.8.8

Close those two windows and go back the network connections window. Right-click the main network connection you use for your computer. Select Properties and the Sharing tab. Tick the box to allow other network users to connect through this computer connection.

If it has a list below that to choose from, choose the Pi’s connection. It may notify you it is changing the IP address of already connected devices, in which case simply re-enter the Pi’s IP address as above and check the gateway address is also set correctly. You should now be able to connect to your unit using SSH either from a Command Prompt or an application like PuTTY:

ssh pi@10.0.0.1 # default password: raspberry

Internet Connection Sharing on Windows can be a bit unstable between reboots. You might need to disable and re-enable Internet Connection Sharing and repeat the above steps periodically.

Putting this into your .bashrc when logged in on the Pwnagotchi will create the pwnlog alias which is a pretty and uncluttered view on the Pwnagotchi logs.

alias pwnlog='tail -f -n300 /var/log/pwn* | sed --unbuffered "s/,[[:digit:]]\{3\}\]//g" | cut -d " " -f 2-'

Putting this into your .bashrc will create the pwnver alias, useful for printing the version of Pwnagotchi currently running.

alias pwnver='python3 -c "import pwnagotchi as p; print(p.version)"'

Pwnagotchi’s face is available at a dedicated web interface located at http://pwnagotchi.local:8080/ if you’ve already connected to the unit via USB and set a static address on the network interface as described above. Change pwnagotchi in the above URL to the new hostname you’ve given your unit.

The username and password for the Pwnagotchi web UI are both “changeme” by default. You should change these by ensuring the webcfg plug-in is enabled, then clicking on it and browsing to the UI web section, changing the username and password then saving to automatically update the config.yml.

You can also view bettercap’s web UI in your browser at http://pwnagotchi.local/ whenever your Pwnagotchi is in MANU mode with the default username and password both being pwnagotchi.

While the Pwnagotchi does support tri-colour eInk displays like those from Waveshare and Pimoroni, with options to enter black or red in the UI configuration; it seems that colours aren’t displayed currently, limiting your Pwnagotchi’s face to being in black and white. If you want your little buddy to maybe stand-out, the most UI customisation you can currently do is to invert the colour scheme manually. Change row 19 and 20 in /usr/local/lib/python3.7/dist-packages/pwnagotchi/ui/view.py :

WHITE = 0x00

BLACK = 0xff

Next, you may want to connect your Pwnagotchi to your Android phone. Ensure Bluetooth tethering is turned on, on your phone, under “Settings: Connections: Mobile Hotspot and Tethering”. Then enable Bluetooth discovery scan on the phone. Find your MAC address for your phone, at Settings -> About Phone -> Status. Now SSH into the Pwnagotchi and run the following commands:

$ sudo bluetoothctl

$ scan on

......

[CHG] Device B4:D3:FF:C3:DB:8F

We care about B4:D3:FF:C3:DB:8F which should be the MAC address of your phone. Add the following to config.yml either directly or via the webcfg plug-in:

main:

plugins:

bt-tether:

enabled: true

devices:

android-phone:

enabled: true

mac: B4:D3:FF:C3:DB:8F # mac of your phone

ip: '192.168.44.44' # ip from which your pwnagotchi should be reachable on your phone

netmask: 24

interval: 1 # check every x minutes for device

scantime: 15

priority: 99

max_tries: 0

search_order: 1

share_internet: true

Back at the command prompt on the Pwnagotchi, you need to test pairing. Have your phone Bluetooth settings open because it will be asked there also.

$ sudo bluetoothctl

pair B4:D3:FF:C3:DB:8F

...(pair) yes/no

$ yes

# here your phone will ask if you want to pair with some code ... say yes on phone and yes in terminal

$ trust B4:D3:FF:C3:DB:8F

Restart the Pwnagotchi:

$ sudo reboot

Keep the screen on in Settings > Connections > Bluetooth because some vendors, notably Samsung and Motorola, prevent the scan and pair of the device outside this screen even for a trusted device. You should get a notification on your phone that the Pwnagotchi is connected and the Pwnagotchi’s eInk display should show BT C at the top.

Automated auditing of downloaded WPA material can be done with the Distributed WPA PSK auditor, which is a distributed network of volunteers running a cracking service for free in the interest of promoting better security. You upload the handshake files and it will be tested against several dictionaries. The Statistics page shows that about 15.5% of submitted networks are successfully cracked.

This can be done by enabling the wpa-sec plug-in on the Pwnagotchi via its configuration, either directly yourself to config.yml or again via the webcfg plug-in, and adding the key that the WPA-SEC website provides to this configuration. Cracked keys will be automatically downloaded and can be located in the file wpa-sec.cracked.potfile in the /root/handshakes/ directory where PCAP files are also located.

Another service that attempts to recover passwords, obtained legally such as for pentesting or audit, is Online Hash Crack. They use cloud computing clusters to perform a huge amount of calculations. Just upload your hashes or files to the website and wait for the results. This can be automated by enabling the onlinehashcrack plugin in the configuration with the email address registered with the Online Hash Crack website.

The net-pos Pwnagotchi plug-in saves a JSON file with the access points with more signal whenever a handshake is captured. It can be enabled in the Pwnagotchi configuration file. When internet is available the files are converted in geo-locations using the Mozilla Location Service, and a file with latitude and longitude data is created.

The webgpsmap plug-in, when enabled via the configuration file, shows existing position data stored in your handshakes directory. The plugin does the following: search for PCAP files in your handshakes directory, for every found PCAP file it looks for a file with latitude and longitude data inside and shows this position on the map.

If also a .cracked file with a plaintext password inside exists, it reads the content and shows the position as green instead of red and the password inside the infobox of the position. You can view it at http://pwnagotchi.local:8080/plugins/webgpsmap

There are several options for cases including Pwnagotchi-specific 3D printed models. My choice is the Pibow Pi Zero W case. If you use this, a couple of important things, you should do before starting to assemble your Pibow case. The first is to make sure the micro-SD card with the Pwnagotchi on it is in your Pi Zero. If you don’t do that now, then you’ll have to disassemble the case again to fit it. You will then need to take off the Inky pHAT. You can then follow the instructions below to assemble it.

You can then just pop the Inky pHAT back onto the Pi and plug it into a portable power pack. I use the Primo Powerbank 2200 mAh. Your adorable Pwnagotchi AI buddy is now fully assembled and ready to be used for auditing & pentesting your Wi-Fi networks.