Pwnagotchi-new-guerilla-guide
Updated version of panoptyks 2022 guerilla guide
Preface
This work is based on the guerrila guide to installing pwnagotchi [1.5.5/2022]. For reference see this reddit post and pastebin of panoptyk.
Since panoptyks original writeup some things have changed and I ran into several problems while setting up my pwnagotchi for the first time. Some bugs are still unresolved, see Section known bugs.
However, the normal installation guide from the official website is still valid by and large, so this document will mostly provide details regarding deviations/addons to the standard installation procedure.
The specific hardware I myself have been using for my build is this:
- Raspberry Pi Zero WH (RP0W)
- Waveshare 2.13 V3
- PiSugar 2 (2 LED-version)
- Samsung Evo 32GB micro SD
I will do my best to reference and credit every source, please add sources where missing and/or drop me a hint. Majority of this document has been created in 2023-04, things are moving fast and surely another year later there will be other stuff broken, and other fixes available.
Not every section from the original guide has been used in this document, the omitted text can be found in the file original_notes.
1. Flash the current image
1.1 Download
1.2 write the image to a micro sd card with balena etcher
(for details see pwnagotchi.ai)
2. Basic Connectivity (SSH, FTP, Connection Sharing)
2.1 Connect to PC
Because I am running Windows 11 as a daily driver, this section will cover only Windows. For establishing a connection on Linux or MacOS refer to the official guide.
- connect RP0W data port to pc (Micro-USB to USB A)
- wait for the device to boot up for the first time (20+ Minutes)
- Check Device Manager for COM-Port - as described here
- If Windows didn't install the RP0W as an "Ethernet Gadget", download the corresponding driver on Windows Update
- Unpack the CAB
- In Device Manager select the COM-Device and update the driver with the one from the CAB
- make sure to check in Network Devices for the Interface and configure TCP/IP v4 to use 10.0.0.01 as its IP-address, 255.255.255.0 as Subnet and 10.0.0.1 as Gateway.
2.1 SSH-connection
Open PowerShell as Administrator
ssh pi@10.0.0.2
default password is raspberry, it is generally recommended to immediately change it:
passwd
if you get the WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!
, go to C:\Users\{user}\.ssh
, open known_hosts
and comment out (#) every line; save
connect again with pi (ssh pi@10.0.0.2
); confirm/authorize (yes in terminal)
2.2 establish ftp support
this is optional, but makes installation way easier (imho). On Windows, I use WinSCP, ymmv.
First, enable password login for root (unsafe, should be disabled again after setup has finished).
passwd #change pi's password
sudo su
passwd root #change root's password
Then, enable SFTP support by executing
sudo nano /etc/ssh/sshd_config
uncomment and change the line #PermitRootLogin prohibit-password
to PermitRootLogin yes
then restart ssh by executing:
service ssh restart
login via FTP using:
host: 10.0.0.2
username: root
password: *password*
port: 22
2.3 solve DNS issues
sudo nano /etc/resolv.conf
change the entry behind nameserver "127.0.0.1" to "8.8.8.8".
Warning this is only temporary and will be overwritten on each reboot. There are several different fixes for this, see this thread. Short summary:
- adding dns-nameservers 8.8.8.8 under the gateway line in /etc/network/interfaces.d/usb0-cfg
- add: "server=8.8.8.8@usb0" to /etc/dnsmasq.conf
- systemctl disable dnsmasq
- sudo chattr +i /etc/resolv.conf makes file immutable (make sure beforehand there is 8.8.8.8 or 1.1.1.1 insted of 127.0.0.0)
2.4 Internet connection sharing for win10/11
The official script is named "win_connection_share.ps1" and can be copied via ftp from /usr/local/src/pwnagotchi/scripts once connected.
Execute this in Powershell:
1.) .\win_connection_share.ps1 -SetPwnagotchiSubnet
2.) # Reboot Windows
3.) .\win_connection_share.ps1 -EnableInternetConnectionSharing
if applicable: enable mobilehotspot on pc and turn off power saving mode for your hotspot or your wireless interface.
2.5 Connecting more than one pwnagotchi to a pc
- Configure the usb0 file on the new pwnagotchi to connect:
nano /etc/network/interfaces.d/usb0-cfg
- Modify this file:
allow-hotplug usb0
iface usb0 inet static
address 10.0.0.2
netmask 255.255.255.0
network 10.0.0.0
broadcast 10.0.0.255
gateway 10.0.0.1
metric 20
- With the ip of your choice:
allow-hotplug usb0
iface usb0 inet static
address 192.168.1.2
netmask 255.255.255.0
network 192.168.1.0
broadcast 192.168.1.255
gateway 192.168.1.1
metric 20
-
Reboot.
-
Configure your network connection with the new ip, and you can now connect more than one pwnagotchi to your pc.
3 Upload initial config.toml
- Prepare your config.toml according to the official guide.
- connect through ftp and upload your config.toml to /etc/pwnagotchi/
- make directory /etc/pwnagotchi/custom-plugins for custom plugins to add to that directory later.
4 Enable Bluetooth connection
4.1 change BT settings in stock/default config
This is going to be dependent on your Bluetooth device, but necessary to enable internet access when connected to your Bluetooth device (do it if you didn't already supply your premade/working config in the previous step)
change following options:
- change this to iPhone, because that's my config
main.plugins.bt-tether.enabled = true
main.plugins.bt-tether.devices.android-phone.enabled = true
main.plugins.bt-tether.devices.android-phone.search_order = 1
main.plugins.bt-tether.devices.android-phone.mac = "CH:AN:GE:ME:HE:RE" #phone: settings-> about device -> status "bluetooth address"
main.plugins.bt-tether.devices.android-phone.ip = "192.168.44.44"
main.plugins.bt-tether.devices.android-phone.netmask = 24
main.plugins.bt-tether.devices.android-phone.interval = 1
main.plugins.bt-tether.devices.android-phone.scantime = 10
main.plugins.bt-tether.devices.android-phone.max_tries = 0
main.plugins.bt-tether.devices.android-phone.share_internet = true
main.plugins.bt-tether.devices.android-phone.priority = 1
then reboot pwnagotchi, either via ssh --> sudo reboot now
or through the web UI in your browser.
4.2 pair pwnagotchi with phone (IMPORTANT!)
make sure BT and BT tethering are activated on your phone. keep phone unlocked, pair phone.
If for some reason pwnagotchi stops connecting to your phone after some time, or wont connect at all, try this:
# RP0W data port <--> pc
ssh pi@10.0.0.2
sudo su
bluetoothctl
scan on
discoverable on
paired-devices # copy device adress
untrust *device adress* #run this command a few times
remove *device adress* #run this command a few times
paired-devices #make sure list is empty, if not- run previous command until it is empty
pair *device adress* #*In short time (maybe not immediately) you will be prompted on the phone to allow connection from your pwnagotchi hostname- pair*
trust *device adress*
exit
after that, open cmd window with ssh session(!), and
ping google.com
if you cant ping, see section 2.3 for fixing the dns issues.
5 Add support for Waveshare 2.13" V3 Rev 2.1 e-Ink-display
It is necessary to replace the 6 files updated/added in this pull-request to add support for the V3. Apparently the V2 is no longer produced. In case your display doesn`t work out-of-the-box, it is worth it to try this solution first.
hint: see if there is a "V3"-sticker on the back of the display.
update: you can use this bash script to automate the process.
5.1 Waveshare 2.13" V4
As of April 2024, apparently there also exists a V4 of the display. See this pull-request for further details.
6 Install additional packages
Now that the internet connection has been established, it's time to install some additional packages for added functionality.
6.1 aircrack-ng
Install this to make the aircrackonly plugin work.
cd ~
sudo apt-get install aircrack-ng -y
if you're using default config & airackonly plugin, dont forget to add this to config:
main.plugins.aircrackonly.enabled = true
main.plugins.aircrackonly.face = "(>.<)"
6.2 hcxtools
Hcxtools are a requirement if you want to be able to make use of the hashie.py plugin, which can convert .pcap-files to crackable hashes.
As of april 2023, hcxtools uses libssl3 as default. This Library is currently not supported by the Kali repositories which come preloaded with the pwnagotchi. Therefore it is necessary to install the last supported release, Version 6.2.7.
cd ~
mkdir hcxtools
# install the required dependencies
apt-get install libcurl4-openssl-dev libssl-dev zlib1g-dev
pay attention to sudo rm -r hcxtools before, in case you tried to build the unsupported version before.
cd hcxtools
wget https://github.com/ZerBea/hcxtools/archive/refs/tags/6.2.7.zip
unzip 6.2.7.zip
- find out how to unzip all files in place instead of creating the 6.2.7 subfolder
Connect via sftp to move the files to the hcxtools folder.
make
sudo make install
make takes a while (mine took over 30 min) but should build and install successfully.
6.3 pySerial
pySerial is a required dependency, if you want to use the unofficialgps plugin.
sudo pip3 install pySerial
7 change passwords
7.1 bettercap
sudo nano /etc/pwnagotchi/config.toml
sudo nano /usr/local/share/bettercap/caplets/pwnagotchi-auto.cap
sudo nano /usr/local/share/bettercap/caplets/pwnagotchi-manual.cap
7.2 webui
sudo nano /etc/pwnagotchi/config.toml
# look for the lines
ui.web.enabled = true
ui.web.address = "0.0.0.0"
ui.web.username = "your_login_user"
ui.web.password = "your_password"
ui.web.origin = ""
ui.web.port = 8080
ui.web.on_frame = ""
8 Fix broken AI
In release 1.5.5 the AI won't start by itself. The expected behaviour for Pwnagorchi would be to start in AUTO mode and switch to AI as soon as the Neural network has been loaded.
armv6
wget https://www.piwheels.org/simple/numpy/numpy-1.21.4-cp37-cp37m-linux_armv6l.whl#sha256=826319c22f05d7b50c3637af5563234edbb02f5634a08d314d21ef00271a32fe
sudo pip3 install https://www.piwheels.org/simple/numpy/numpy-1.21.4-cp37-cp37m-linux_armv6l.whl
armv7
https://www.piwheels.org/simple/numpy/numpy-1.21.4-cp37-cp37m-linux_armv7l.whl#sha256=826319c22f05d7b50c3637af5563234edbb02f5634a08d314d21ef00271a32fe
https://www.piwheels.org/simple/numpy/numpy-1.21.4-cp37-cp37m-linux_armv7l.whl
if pwnagotchi still doesnt switch to AI after ~45min
sudo apt-get remove python-opencv
sudo apt-get install python-opencv
9 Pisugar 2 Setup
Install Pisugar Power Manager and Pisugar2 plugin. The Power Manager will set up its own neat web service which allows to configure the function of the button and see some stats about your battery.
# Go to the home directory
cd ~
# Install PiSugar Power Manager
curl http://cdn.pisugar.com/release/Pisugar-power-manager.sh | sudo bash
# Download the plugin and support library
git clone https://github.com/PiSugar/pisugar2py.git
git clone https://github.com/PiSugar/pwnagotchi-pisugar2-plugin.git
# This installs the pisugar2 package into your python library
sudo ln -s ~/pisugar2py/ /usr/local/lib/python3.7/dist-packages/pisugar2
# Installs the user-plugin
sudo ln -s ~/pwnagotchi-pisugar2-plugin/pisugar2.py /etc/pwnagotchi/custom-plugins/pisugar2.py
10 Some useful modifications
10.1 Set up aliases
add the followng lines to .bashrc (for pi and root separately), make sure there are no white spaces at the end!
nano ~/.bashrc
# AND/OR
sudo nano /root/.bashrc
# add these lines to the end
alias pwnlog='tail -f -n300 /var/log/pwn*.log | sed --unbuffered "s/,[[:digit:]]\{3\}\]//g" | cut -d " " -f 2-'
alias pwnver='python3 -c "import pwnagotchi as p; print(p.version)"'
#reload bash
source ~/.bashrc
10.2 Add "SD card protection" by enabling write cache
sudo nano /etc/config.toml
fs.memory.enabled = true
fs.memory.mounts.log.enabled = true
fs.memory.mounts.data.enabled = true
10.3 ATGM336H GPS Module on a Raspberry Pi zero 2
Connections:
GPS ----> RPI02w
VCC ----> 5V
GND ----> GND
TX ----> RX GPIO 15
RX ----> TX GPIO 14
PPS ----> PWM GPIO 18
Configure the serial connection:
sudo raspi-config
Disable serial terminal.
Enabled hardware serial.
Install dependencies:
sudo apt-get install gpsd gpsd-clients
Set the baud rate to 9600:
sudo stty -F /dev/serial0 raw 9600 cs8 clocal -cstopb
Config gpsd to uses the correct serial device:
sudo nano /etc/default/gpsd
Look for:
DEVICES=""
and change it to:
DEVICES="/dev/serial0"
Reboot
Verify with:
gpsmon 127.0.0.1:2947
gpsmon /dev/serial0
cgps 127.0.0.1:2947
cgps /dev/serial0
Configure it inside /etc/pwnagotchi/config.toml
:
main.plugins.gps.enabled = true
main.plugins.gps.speed = 9600
main.plugins.gps.device = "/dev/serial0"
11 Install additional plugins
11.1 Install procedure
For custom plugins to work, you have to add the path to your folder in the config.toml
. I have added these two lines:
main.custom_plugins = "/etc/pwnagotchi/custom-plugins/"
main.custom_plugin_repos = [ "https://github.com/evilsocket/pwnagotchi-plugins-contrib/archive/master.zip",]
depending on where you put your custom-plugins folder in step 3, the procedure onwards is simple:
- copy the plugin_name.py file to your folder (e.g. /etc/pwnagotchi/custom-plugins/)
- add the required settings to the config.toml file. The minimum addition looks like this:
main.plugins.plugin_name.enabled = true
There are several community-developed plugins available, my pwnagotchi has the exp-Plugin by Gaelic Thunder , among others installed.
11.2 Example 1 - Install exp plugin
download the plugin.py file from Github.
copy/move plugin file to /etc/pwnagotchi/custom-plugins
.
add the following lines to config.toml
:
main.plugins.exp.enabled = true
main.plugins.exp.lvl_x_coord = 0
main.plugins.exp.lvl_y_coord = 93
main.plugins.exp.exp_x_coord = 38
main.plugins.exp.exp_y_coord = 93
main.plugins.exp.bar_symbols_count = 12
11.3 Example 2 - Install hashie plugin
download hashie.py from official git.
copy hashie.py to custom-plugins (see above).
add line in config.toml:
main.plugins.hashie.enabled = true
12 Housekeeping
12.1 update small pwnagotchi face (result from Waveshare 3 files)
source: https://www.reddit.com/r/pwnagotchi/comments/u4q18m/how_to_fix_the_small_face_issue_with_waveshare_v3/ change face size in ..pwnagotchi/ui/hw/waveshare3.py, Line 13
13 Additional Tips & Tricks
13.1 default folder locations
folder | location |
---|---|
default plugins directory | /usr/local/lib/python3.7/dist-packages/pwnagotchi/plugins/default/ |
custom plugins directory | /etc/pwnagotchi/custom-plugins/ |
config directory | /etc/pwnagotchi/ |
neural network | /root/brain.nn |
information about nn | /root/brain.json |
Logs | /var/log/pwnagotchi.log |
Memory | /root/peers/ |
handshakes | /root/handshakes/ |
13.2 example for a display layout
https://www.reddit.com/r/pwnagotchi/comments/pn6ztt/pwnagotcha_running_custom_scripts_including_exp/
13.3 other plugins/fixes
-
change pwnagotchi at /usr/local/bin (home_base epoch cycling fix) evilsocket/pwnagotchi#1003
-
change webgpsmap.html /usr/local/lib/python3.7/dist-packages/pwnagotchi/plugins/default for custom made ver
-
change watchdog /usr/local/lib/python3.7/dist-packages/pwnagotchi/plugins/default to v1.0.0 https://github.com/dadav/pwnagotchi-custom-plugins/blob/master/watchdog.py
-
change paw-gps to 1.0.1 evilsocket/pwnagotchi#1054
-
change clock.py 1.0.3 ##changes allow you to customise the displayed time format by editing config.toml, e.g. switching from 12 to 24 hours clock format, or adding seconds https://github.com/evilsocket/pwnagotchi-plugins-contrib/pull/29/files
-
change hashie.py 1.0.3 ##newer than https://github.com/PwnPeter/pwnagotchi-plugins hashie 1.0.3 //it migh be slower than pwnpeter's version//do more tests// https://github.com/evilsocket/pwnagotchi-plugins-contrib/pull/36/files
-
display_version.py 1.0.0 https://github.com/evilsocket/pwnagotchi-plugins-contrib/pull/35/files
-
wpa-sec-list 1.0.0 ##List cracked passwords from wpa-sec https://github.com/evilsocket/pwnagotchi-plugins-contrib/pull/34/files
-
HandshakesDL 0.2.2 ##Download handshake captures from web-ui [newer than handshakes 1.0.3 https://github.com/PwnPeter/pwnagotchi-plugins] https://github.com/evilsocket/pwnagotchi-plugins-contrib/pull/27/files
-
aircrack-ng 2.0.0. https://github.com/dadav/pwnagotchi-custom-plugins/blob/master/aircrackonly.py
-
webcfg update? https://github.com/dadav/pwnagotchi/blob/master/pwnagotchi/plugins/default/webcfg.py
-
home_base 1.0.0 & away_base 1.0.0 https://github.com/troystauffer/home_base plus this fix evilsocket/pwnagotchi#1003
-
unoficialGPS 1.0.0 https://github.com/evilsocket/pwnagotchi-plugins-contrib/pull/22/files
-
auto_update.py 2.0.0 https://github.com/dadav/pwnagotchi-custom-plugins/blob/master/auto_backup.py update it with this: evilsocket/pwnagotchi-plugins-contrib#30
-
exp 1.0.5 https://github.com/GaelicThunder/Experience-Plugin-Pwnagotchi
-
onlinehashcrack 2.1.5 https://github.com/dadav/pwnagotchi-custom-plugins/blob/master/onlinehashcrack.py
-
wpa-sec.py 3.0.2 https://github.com/dadav/pwnagotchi-custom-plugins/blob/master/wpa-sec.py
-
screen_refresh 2.0.0 https://github.com/dadav/pwnagotchi-custom-plugins/blob/master/screen_refresh.py
-
wpa-sec2 #It will only do a check and make .gps.cracked files from the downloaded .cracked.potfile after it downloads from wpa-sec xenDE/pwnagotchi-tools#1
#yml config for it below. NOTE! i didnt test this plugin yet, you need to translate it to toml before you put it in a config
wpa-sec2:
enabled: false
api_key: ''
api_url: "https://wpa-sec.stanev.org"
download_results: true
-
banthex.py a clone of wpa-sec2 https://github.com/V0r-T3x/pwnagotchi_plugins/blob/main/plugins/banthex.py
-
watchdog.py 1.0.0 https://github.com/dadav/pwnagotchi-custom-plugins/blob/master/watchdog.py
-
paw-gps.py 1.0.1 evilsocket/pwnagotchi#1054
-
Fancygotchi, a complete theme manager for pwnagotchi https://github.com/V0r-T3x/fancygotchi
-
crack_house.py 1.0.0 a plugin to show the nearest cracked AP (based on display_password, act like it if no cracked network at proximity) https://github.com/V0r-T3x/pwnagotchi_plugins/blob/main/plugins/crack_house.py
-
fix_region.py 1.0 a plugin to unlock the channel 12 or 13 in certain world region https://github.com/V0r-T3x/pwnagotchi_plugins/blob/main/plugins/fix_region.py
14 known bugs
- bettercap not showing any signals
- activation of onlinehashcrack or wpa-sec plugin leads to pwnagotchi not starting up
To Do
- add to preface the used hardware, including revisions
- explain details of Windows Connection Script and Ethernet Settings
- copy all content from original guide over to this document
- add references and links to jump around in this document
- clean up