Skip to content

Xyl0se/Pwnagotchi-new-guerilla-guide

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

12 Commits
.gitignore
.gitignore
 
 
README.md
README.md
 
 
original_notes
original_notes
 
 

Repository files navigation

Pwnagotchi-new-guerilla-guide

Updated version of panoptyks 2022 guerilla guide

Table of Contents

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 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.

1. Flash the current image

1.1 Download

1.2 write the image to a micro sd card with RPI Imager

RPI Imager

(for details see pwnagotchi.org)

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.

  1. connect RP0W data port to pc (Micro-USB to USB A)
  2. wait for the device to boot up for the first time (20+ Minutes)
  3. Check Device Manager for COM-Port - as described here
  4. If Windows didn't install the Raspberry PI as an "Ethernet Gadget", download the driver from RNDIS
  6. Unpack the CAB
  7. In Device Manager select the COM-Device and update the driver with the one from the CAB
  8. 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 [email protected]

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)

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.

3 Upload initial config.toml

  1. Prepare your config.toml according to the official guide.
  2. connect through ftp and upload your config.toml to /etc/pwnagotchi/
  3. 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 [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.

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.

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

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/pwnagotchi/config.toml

fs.memory.enabled = true
fs.memory.mounts.log.enabled = true
fs.memory.mounts.data.enabled = true

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:

  1. copy the plugin_name.py file to your folder (e.g. /etc/pwnagotchi/custom-plugins/)
  2. 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

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

About

Updated version of panoptyks 2022 guerilla guide

Resources

Readme
Activity

Stars

272 stars

Watchers

15 watching

Forks

24 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 4