Updated version of panoptyks 2022 guerilla guide
- Pwnagotchi-new-guerilla-guide
- Preface
- 1. Flash the current image
- 2. Basic Connectivity (SSH, FTP, Connection Sharing)
- 3 Upload initial config.toml
- 4 Enable Bluetooth connection
- 5 Add support for Waveshare 2.13" V3 Rev 2.1 e-Ink-display
- 6 Install additional packages
- 7 change passwords
- 8 Fix broken AI
- 9 Pisugar 2 Setup
- 10 Some useful modifications
- 11 Install additional plugins
- 12 Housekeeping
- 13 Additional Tips & Tricks
- 14 known bugs
- To Do
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 outdated now please use https://pwnagotchi.org/, 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
- BUT
- You can now also use the Pizero2w , RPI3, RPI4, and RPI5
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.
- RPI Imager)
- [pwnagotchi Image]
- PizeroW Look for the armhf Image to flash
- Pizero2 and above Look for the arm64 Image to flash
RPI Imager
(for details see pwnagotchi.org)
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 Raspberry PI as an "Ethernet Gadget", download the driver from RNDIS
- 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.
Open PowerShell as Administrator
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 [email protected]
); confirm/authorize (yes in terminal)
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
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)
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.
- 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.
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.
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 [email protected]
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.
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.
As of April 2024, apparently there also exists a V4 of the display. See this pull-request for further details.
Now that the internet connection has been established, it's time to install some additional packages for added functionality.
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 = "(>.<)"
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.
pySerial is a required dependency, if you want to use the unofficialgps plugin.
sudo pip3 install pySerial
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
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 = ""
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.
sudo pip3 install -v --upgrade numpy
it taaaaakes a while, it really does. go clean your room, garage, neighbour's garage and fix your life in the meantime (2h?)
if you get a timeout error try:
sudo pip3 install --default-timeout=100 -v --upgrade numpy
if pwnagotchi still doesnt switch to AI after ~45min
sudo apt-get remove python-opencv
sudo apt-get install python-opencv
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 https://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
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
sudo nano /etc/pwnagotchi/config.toml
fs.memory.enabled = true
fs.memory.mounts.log.enabled = true
fs.memory.mounts.data.enabled = true
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.
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
download hashie.py from official git.
copy hashie.py to custom-plugins (see above).
add line in config.toml:
main.plugins.hashie.enabled = true
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
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/ |
https://www.reddit.com/r/pwnagotchi/comments/pn6ztt/pwnagotcha_running_custom_scripts_including_exp/
-
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
-
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
- bettercap not showing any signals
- activation of onlinehashcrack or wpa-sec plugin leads to pwnagotchi not starting up
- 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