Congratulations on the purchase of your Pwnagotchi.
I have put this device together for you and tested to make sure it is operating as expected.
Pwnagotchi is an A2C-based “AI” powered by bettercap and running on a Raspberry Pi Zero W 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 handshake supported by hashcat, including full and half WPA handshakes as well as PMKIDs.
Learn more about the project and how it started on the author’s blog.
- 1 SanDisk 32gb Ultra microSDHC UHS-I Memory Card with Pwnagotchi 1.5.3 installed
- 1 Pwnagotchi assembled in a 3D printed case
On the sd card is a fresh install of pwnagotchi 1.5.3 with a basic pwnagotchi configuration file and the kernel driver for the real time clock.
The Pwnagotchi you recieved has been assembled and tested to make sure everything is in proper working condition. The sd card has been configured with the basic information needed to setup the device, but due to the nature of the Pwnagotchi software, some steps need to be performed and setup to complete the setup of the pwnagotchi. I choose to setup the device as the Pwnagotchi generates a unique hash key on first startup.
I have added the following for setting up the hardware as a few modification need to be made for this specific setup.
For the real time clock I have added the kernel driver for the DS3231 by opening /boot/config.txt, and on the laxst line added dtoverlay=i2c-rtc,ds3231
I have also added a basic config.toml for the pwnagotchi to enable the display and UPS-lite. After the first boot you will find your config file located at /etc/pwnagotchi/config.toml:
main.name = ""
main.whitelist = []
main.plugins.grid.enabled = true
main.plugins.grid.report = true
main.plugins.grid.exclude = []
main.plugins.ups_lite.enabled = true
ui.display.enabled = true
ui.display.rotation = 0
ui.display.type = "waveshare_2"
ui.display.color = "black"
ui.web.enabled = true
ui.web.address = "0.0.0.0"
ui.web.username = "changeme"
ui.web.password = "changeme"
ui.web.origin = ""
ui.web.port = 8080
ui.web.on_frame = ""I suggest referring to /etc/pwnagotchi/default.toml for other default settings
Before you inset the sd card in the Pwnagotchi, I recommend setting the name for the device. Insert the SD card in your computer and open config.toml with a text editor. The file should look like this:
main.name = ""
main.whitelist = []
main.plugins.grid.enabled = true
main.plugins.grid.report = true
main.plugins.grid.exclude = []
main.plugins.ups_lite.enabled = true
ui.display.enabled = true
ui.display.rotation = 0
ui.display.type = "waveshare_2"
ui.display.color = "black"
ui.web.enabled = true
ui.web.address = "0.0.0.0"
ui.web.username = "changeme"
ui.web.password = "changeme"
ui.web.origin = ""
ui.web.port = 8080
ui.web.on_frame = ""update main.name = "" with your name main.name = "YOUR DEVICE NAME HERE".
update main.whitelist = [] and main.plugins.grid.exclude = [] with any networks you would like to exclude from deauth and reporting to the grid
update ui.web.username = "changeme" and ui.web.password = "changeme" with a unique username and password to prevent web access to your device should someone gain access to it.
refer to defuaults.toml for other settings
Once you are satisified with the configuration file, eject the SD card from the computer before removing it, then insert it into the SD card port on the Pwnagotchi. Connect the Pwnagotchi to power using a MicroUSB cord and connect it to the UPS-lite port on the Pwnagotchi. Last switch the power switch to the on position and open your bag of snacks and sit back and wait. The Pwnagbotchi's first boot can take a few minutes, it needs to generate a unique key.
The Pwnagotchi codebase comes with USB ethernet preconfigured. to ssh into the pi follow the steps outlined in https://pwnagotchi.ai/configuration/#connecting-to-pi0w-with-microusb-cable-on-linux-host
DEV NOTE: These are directions for the recommended hardware, a Pi0w - and connecting to it from a Linux based host via a Micro-USB through the data port. This was written while connecting to a Pi0w with a Data Capable MicroUSB to a Macbook Pro late 2012 running Ubuntu 19.04. It will also work on Lenovo's running Ubuntu 19.04 and 19.10. We can not guarantee these specific directions work on any other OS. Pre-Face
- If you have any wired interfaces on your host PC, you will need to remove them from Network Manager so we can be sure you have everything set correctly, on the correct interface.
- If you are using Wi-Fi on your host computer, you need to be certain that your routers IP address scheme is not in the
10.0.0.1/24range. If it is, you should turn Wi-Fi off initially to best troubleshoot your connectivity issues, then change the interface IP scheme on your Pi once you can ssh to it. - These settings are only verified to work on, 1. a Pi0w, with a 2. MicroUSB data capable cable, 3. the newest released image found on our Github which at the time of writing is v1.3.0.  Steps to complete on your host (the pc that you are connecting the Pi to)
-
First, type ifconfig to check and take note of the names of your current interfaces, and what is now recognized as an adapter on your system. Take note of the Mac Addresses that you see in this output.
-
Starting with a clean slate in your Network Manager (remove all wired interface profiles that you have on your Network Manager,) plug your unpowered Pi0w into your computer through the data port seen in the picture shown above .
-
Wait until your Pi boots into Manu mode. Once you see the breakdown that Pwnagotchi does when in MANU mode, type ifconfig again on your host machine and look for a new interface that was not there during Step 1. (Take EXTRA note of the new interfaces mac address, I will be referencing this mac address on multiple occasions as Step 3.)
- If you have never booted your Pwnagotchi before: it will take a few minutes to boot up &/or become visible or responsive. DO NOT INTERRUPT YOUR PWNAGOTCHI DURING THIS PROCESS. That extra time it takes to boot the first time you turn your Pwnagotchi on? It’s because it is generating its RSA keys; if you interrupt this process, the generated keys may be corrupted!
-
On Network Manager on your PC/Host, (if there are no interfaces automatically added, you can attempt to add a new interface by selecting the mac address noted in Step 3 for the interface profile) select Settings > IPv4 and then change from automatic to manual, then for your address, you’ll need to configure it with a static IP address and then press apply in the top right:
- IP:
10.0.0.1 - Netmask:
255.255.255.0 - DNS (If Required):
1.1.1.1(or whatever)
- IP:
-
Back in your terminal, type
ifconfigand look for the interface that you found in Step 3, and that you edited the settings for in Step 4. If you see the following on the second line of the interface that matches the mac address from Step 3, you should now be able to enterping 10.0.0.2and receive a response from your pi.inet 10.0.0.1 netmask 255.255.255.0 broadcast 10.0.0.255 -
Congratulations! You should now be able to connect to your unit using SSH:
ssh pi@10.0.0.2 # default password: raspberry
TIP: you may need to use the linux_connection_share.sh script before your PC will allow you to ssh to your Pi. Host connection sharing
DEV NOTE: if you have some issues, either you are using the wrong cord, or your Operating System is missing required drivers, or something mostly out of our control. We can't help everyone with their networking, sorry
The default password is raspberry; you should change it as soon as you log in for the first time by issuing the passwd command and selecting a new and more complex passphrase.
If you want to login directly without entering a password (recommended and necessary for certain packaged scripts to work, like backup.sh for instance!), copy your SSH public key to the unit’s authorized keys:
ssh-copy-id -i ~/.ssh/id_rsa.pub pi@10.0.0.2
Want to be able to update your Pwnagotchi and access things from the internet on it? Sure you do!
- Connect to the Pwnagotchi unit via usb0 (A.K.A., using the data port).
- Run the appropriate connection sharing script to bring the interface up on your end and share internet connectivity from another interface: OS Script Location Link Linux scripts/linux_connection_share.sh link Mac OS X scripts/macos_connection_share.sh link Windows scripts/win_connection_share.ps1 link
If you want to upload your handshakes while walking, want to use your smartphone as a display or simply shutdown your pwnagotchi gracefully, you can use the bt-tether-plugin. Make sure to explicitly enable Bluetooth Tethering on your Phone (usually in Settings -> Hotspot or similar) before pairing. Otherwise your Pwnagotchi will pair with your phone but you won't be able to create a Personal Area Network (PAN) even if you enable it after. Now in pwnagotchi’s config.toml add the following:
main.plugins.bt-tether.enabled = false
main.plugins.bt-tether.devices.android-phone.enabled = false # the name of this entry is android-phone
main.plugins.bt-tether.devices.android-phone.search_order = 1 # in which order the devices should
## be searched. E.g. this is #1
main.plugins.bt-tether.devices.android-phone.mac = "" # you need to put your phones
## bt-mac here (settings > status)
main.plugins.bt-tether.devices.android-phone.ip = "192.168.44.44" # this is the static ip of your pwnagotchi
## adjust this to your phones pan-network
## (run "ifconfig bt-pan" on your phone)
## if you feel lucky,
## try: 192.168.44.44 (Android) or
## 172.20.10.6 (iOS)
## 44 is just an example, you can choose
## between 2-254 (if netmask is 24)
main.plugins.bt-tether.devices.android-phone.netmask = 24 # netmask of the PAN
main.plugins.bt-tether.devices.android-phone.interval = 1 # in minues, how often should
## the device be searched
main.plugins.bt-tether.devices.android-phone.scantime = 10 # in seconds, how long should be searched
## on each interval
main.plugins.bt-tether.devices.android-phone.max_tries = 10 # how many times it should try to find the
## phone (0 = endless)
main.plugins.bt-tether.devices.android-phone.share_internet = false # set to true if you want to have
## internet via bluetooth
main.plugins.bt-tether.devices.android-phone.priority = 1 # the device with the highest
## priority wins (1 = highest)
main.plugins.bt-tether.devices.ios-phone.enabled = false # next device...
main.plugins.bt-tether.devices.ios-phone.search_order = 2The legacy configuration (without the devices key) is still supported, but should be converted as soon as possible.
Your pwnagotchi will indicate the status via a little BT symbol at the top of the screen. The status codes are:
- C Connected: This means the connection to the device has been established.
- NF Not found: This means the connection to the device could not be established (probably because it could not be found).
- PE Pairing Error: This error occurs on a pairing problem.
- BE Bnep Error: This error occurs, when the NAP could not be created.
- AE Address Error: The IP could not be assigned to the NAP interface. If you want to fix these problems, the first step should be to start pwnagotchi with --debug and check the log file (/var/log/pwnagotchi.log) for related debug messages.
Some users had problems with the auto pairing feature of the plugin (in old versions). If your pwnagotchi should not make an effort to connect to your bluetooth device after a few minutes, there is a chance that this can be fixed by doing the pairing manually. To do this, put your phone in discoverable mode. On your pwnagotchi, run sudo bluetoothctl and once in the bluetooth-shell, type scan on. That will scan the environment for nearby bluetooth devices. Pick the mac of your phone and type pair and trust . In short time (maybe not immediately) you will be prompted on the phone to allow connection from your pwnagotchi hostname.
As you may know, sdcards have a limited count of write cycles and can break from time to time. A good way to prevent this is to minimize the writes to sdcard. Pwnagotchi has the ability to mount certain directories into memory and only write it back to the sdcard after a certain interval. To activate this functionality, you have to change your config to:
fs.memory.enabled = true
fs.memory.mounts.log.enabled = true
fs.memory.mounts.data.enabled = trueThe full configuration of a mount looks like this:
fs.memory.mounts.log.enabled = true # switch
fs.memory.mounts.log.mount = "/var/log" # which directory to map into memory
fs.memory.mounts.log.size = "50M" # max size to put into memory
fs.memory.mounts.log.sync = 60 # interval in seconds to sync back onto disk
fs.memory.mounts.log.zram = true # use zram for compression (recommended)
fs.memory.mounts.log.rsync = true # use rsync to copy only the difference (recommended)You can execute these two commands and then each time you connect the pwnagotchi to your computer, the interface will be ready and configured:
export RDNIS=' g_ether.host_addr='$(dmesg | awk '/: HOST MAC/{print $NF}')' g_ether.dev_addr='$(dmesg | awk '/: MAC/{print $NF}')
sudo sed -i '$ s/$/ \'"$RDNIS"'/' /boot/cmdline.txt
Putting this into your .bash_aliases will create the pwnlog alias which is a pretty and uncluttered view on the pwnagotchi logs.
alias pwnlog='tail -f -n300 /var/log/pwn*.log | 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)"'