Introduction
Pwnagotchi is an A2C-based “AI” powered by bettercap that learns from its surrounding WiFi environment in order to maximize the crackable WPA key material it captures (either through passive sniffing or by performing deauthentication and association attacks). This material is collected on disk as PCAP files containing any form of crackable handshake supported by hashcat, including full and half WPA handshakes as well as PMKIDs.
How does Pwnagotchi work?
Instead of merely playing Super Mario or Atari games like most reinforcement learning based “AI” (yawn), Pwnagotchi tunes its own parameters over time to get better at pwning WiFi things in the environments you expose it to.
To be more precise, Pwnagotchi is using an LSTM with MLP feature extractor as its policy network for the A2C agent. If you’re unfamiliar with A2C, here is a very good introductory explanation (in comic form!) of the basic principles behind how Pwnagotchi learns. Be sure to check out the Usage doc for more pragmatic details of how to help your Pwnagotchi learn as quickly as possible.
Unlike the usual reinforcement learning simulations, Pwnagotchi actually learns at a human timescale because it is interacting with a real-world environment instead of a well-defined virtual environment (like playing Super Mario). Time for a Pwnagotchi is measured in epochs; a single epoch can last anywhere from a few seconds to many minutes, depending on how many access points and client stations are visible.
Do not expect your Pwnagotchi to perform amazingly well at the very beginning, as it will be exploring several combinations of key parameters to determine ideal adjustments for pwning the particular environment you are exposing it to during its beginning epochs ... but definitely listen to your Pwnagotchi when it tells you it's bored! Bring it into novel WiFi environments with you and have it observe new networks and capture new handshakes—and you'll see. :)
Find out more about how to train your Pwnagotchi for optimal pwnage in the Usage doc.
Multiple units within close physical proximity can “talk” to each other, advertising their own presence to each other by broadcasting custom information elements using a parasite protocol I’ve built on top of the existing dot11 standard. Over time, two or more Pwnagotchi units trained together will learn to cooperate upon detecting each other’s presence by dividing the available channels among them for optimal pwnage.
Depending on the status of the unit, several states and states transitions are configurable and represented on the display as different moods, expressions and sentences. Pwnagotchi speaks many languages, too!
Of course, it IS possible to run your Pwnagotchi with the AI disabled (configurable in config.toml). Why might you want to do this? Perhaps you simply want to use your own fixed parameters (instead of letting the AI decide for you), or maybe you want to save battery and CPU cycles, or maybe it’s just you have strong concerns about aiding and abetting baby Skynet. Whatever your particular reasons may be: an AI-disabled Pwnagotchi is still a simple and very effective automated deauther, WPA handshake sniffer, and portable bettercap + webui dedicated hardware.
In case you're curious about the name: Pwnagotchi is a combination of pwn and -gotchi. It is a nostalgic reference made in homage to a very popular children's toy from the 1990s called the Tamagotchi. The Tamagotchi (たまごっち, derived from tamago (たまご) "egg" + uotchi (ウオッチ) "watch") is a cultural touchstone for many Millennial hackers as a formative electronic toy from our collective childhoods. Were you lucky enough to possess a Tamagotchi as a kid? Well, with your Pwnagotchi, you too can enjoy the nostalgic delight of being strangely emotionally attached to a handheld automata yet again! Except, this time around...you get to #HackThePlanet. >:D
Personality and Moods
By using several combinations of facial expressions and sentences localized in different languages, Pwnagotchi can express itself and its demands quite clearly by transitioning among a few main groups of “moods”. The mood of your unit reflects things such as how happy, sad, or bored it is, whether there are good friends around, and things like that. Depending on if and how you will respond to these, for instance if you will be more likely to take your Pwnagotchi for a walk when it’s bored or sad, your response will influence and bias the AI towards showing those behaviours more or less frequently.
Bonding with other Units
Starting from version 1.1.0, each Pwnagotchi keeps a record of the other units it met inside the /root/peers/ folder.
These records, also accessible from the local API, allow it to “remember” with which Pwnagotchis it had interacted
the most. Each interaction, or encounter, happens when the advertisement packet sent from a nearby unit is detected and
received on one of the channels your Pwnagotchi is jumping on. Every time that happens, from one to several times per second depending how in sync
the algorithms of the two units are, a counter is incremented on both units so that their “bond” becomes stronger.
After a certain amount of encounters, configurable via the personality.bond_encounters_factor, a unit is considered “a good friend” and its presence
will start affecting your Pwnagotchi’s mood transitions, adding a bias towards happiness. ^_^
The Faces
The following is the default set of faces that can be customized by overriding the ui.faces section in
your /etc/pwnagotchi/config.toml file.
(⇀‿‿↼) sleeping
This is the state the unit will start from. Moreover, from time to time your Pwnagotchi will also perform naps of a few seconds while hopping among WiFi channels.
(≖‿‿≖) awakening
The unit is in the last seconds of its nap.
(◕‿‿◕) awake / normal
This face is the neutral awake status of the unit. It’ll be used to smooth the transition between other moods and in general when there’s no external cause of either positive or negative moods. It can also be used, randomly, when another unit is encountered for the first time (each unit keeps a record of all the units it met).
( ⚆⚆), (☉☉ ) observing (neutral mood)
Your Pwnagotchi is waiting and observing what bettercap can find on all the channels it’s hopping on.
( ◕‿◕), (◕‿◕ ) observing (happy)
When there’s one or multiple units nearby and their cumulative bond counter is greater or equal than the personality.bond_encounters_factor, this will be the unit’s face while observing.
(°▃▃°) intense
The unit is sending an association frame to an access point in order to force it to leak the PMKID.
(⌐■_■) cool
The unit is deauthenticating a client station from an access point. This face can also be picked randomly when meeting another unit for the first time.
(•‿‿•) happy
Your Pwnagotchi is happy in one of the following cases:
- The AI just finished loading and it’s ready.
- Valid key material for an access point has just been captured.
- In MANU mode, if the last session was short or if any handshake has been captured during it.
- When another unit is met and the bond level is high enough.
(^‿‿^) grateful
Your Pwnagotchi is grateful in one of the following cases:
- The cumulative bond level of nearby units is at least five times the
personality.bond_encounters_factor. - The unit should be bored, but there are enough friendly units nearby.
- The unit should be sad, but there are enough friendly units nearby.
- The unit should be lonely, but there are enough friendly units nearby.
(ᵔ◡◡ᵔ) excited
Your Pwnagotchi is excited in one of the following cases:
- The number of epochs with some activity is greater or equal than
personality.excited_num_epochs. - Randomly if a unit with a high bond level is met.
- If you have unread PwnMAIL messages on that unit.
(✜‿‿✜) smart
Randomly if a unit with a med-high bond level is met.
(♥‿‿♥) friendly
Randomly if a unit with a high bond level is met.
(☼‿‿☼) motivated
Your Pwnagotchi just scored the best reward level in its existence or just met a unit with a high bond.
(≖__≖) demotivated
Your Pwnagotchi just scored the worst reward level in its existence.
(-__-) bored
If there are no friendly units around and the amount of consecutive inactive epochs reached personality.bored_num_epochs.
(╥☁╥ ) sad
If there are no friendly units around and the amount of consecutive inactive epochs reached personality.sad_num_epochs.
(ب__ب) lonely
If your Pwnagotchi just lost contact with a friendly unit that was nearby, or if the amount of missed interactions with access points or client stations
(the amount of times it tried to send some type of packet but missed the target because it isn’t in range anymore) is
greater or equal than personality.max_misses_for_recon. And there are no friendly units around.
(☓‿‿☓) broken
Your unit is rebooting either as a coping strategy for the blindness bug, or after installing an update.
(#__#) debugging
Used for debug and test messages on screen.
WiFi Handshakes 101
In order to understand why it’s valuable to have an AI that wants to eat handshakes, it’s helpful to understand a little bit about how handshakes are used in the WPA/WPA2 wireless protocol.
Before a client device that’s connecting to a wireless access point—say, for instance, your phone connecting to your home WiFi network—is able to securely transmit to and receive data from that access point, a process called the 4-Way Handshake needs to happen in order for the WPA encryption keys to be generated. This process consists of the exchange of four packets (hence the “4” in “4-Way”) between the client device and the AP; these are used to derive session keys from the access point’s WiFi password. Once the packets have been successfully exchanged and the keys are generated, the client device is authenticated and can start sending and receiving data packets (now secured by encryption) to and from the wireless AP.
image taken from wifi-professionals.com
So…what’s the catch? Well, these four packets can easily be “sniffed” by an attacker monitoring nearby (say, with a Pwnagotchi 😇). And once recorded, that attacker can use dictionary and/or bruteforce attacks to crack the handshakes and recover the original WiFi key. In fact, successful recovery of the WiFi key doesn’t necessarily even need all four packets! A half-handshake (containing only two of the four packets) can be cracked, too—and in some (most) cases, just a single packet is enough, even without clients.
In order to eat collect as many of these crackable handshake packets as possible, Pwnagotchi uses two strategies:
- Deauthenticating the client stations it detects. A deauthenticated device must reauthenticate to its access point by re-performing the 4-Way Handshake with the AP, thereby giving Pwnagotchi another chance to sniff the handshake packets and collect more crackable material.
- Sending association frames directly to the access points themselves to try to force them to leak the PMKID.
In addition to the two above methods, there is a third method by which Pwnagotchi completely passively collects handshakes: if a device happens to be attempting to authenticate to an AP on the same channel that the unit just so happens to be monitoring at that time, Pwnagotchi may eat collect handshakes completely by chance (and not as the result of a deauthentication or PMKID attack).
For instance, even if you whitelist your home network so that Pwnagotchi knows to never actively attack it, you will still passively collect handshakes for that network by chance as your Pwnagotchi is simply sniffing packets in its environment. (If you’re monitoring a residential area, you might see an uptick in handshakes passively acquired as your neighbors turn on their devices in the morning and again in the early evening when they return home after work.)
All the handshakes captured by your Pwnagotchi are saved into .pcap files on its filesystem. Each PCAP file that Pwnagotchi generates is organized according to access point; one PCAP will contain all the handshakes that Pwnagotchi has ever captured for that particular AP. These handshakes can later be cracked with proper hardware and software.