scifijunkie/pwnagotchi
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: moved docs to www.pwnagotchi.ai repo

Browse Source
This commit is contained in:
Simone Margaritelli 2019-10-07 18:25:59 +02:00
parent 52af839131
commit 7f880698a4
10 changed files with 1 additions and 837 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
README.md
View File

@ -36,15 +36,7 @@ For hackers to learn reinforcement learning, WiFi networking, and have an excuse
**IMPORTANT NOTE:** If you'd like to alphatest Pwnagotchi and are trying to get yours up and running while the project is still very unstable, please understand that the documentation here may not reflect what is currently implemented. If you have questions, ask the community of alphatesters in the [official Pwnagotchi Slack](https://pwnagotchi.herokuapp.com). The Pwnagotchi dev team is entirely focused on the v1.0 release and will NOT be providing support for alphatesters trying to get their Pwnagotchis working in the meantime. All technical support during this period of development is being provided by your fellow alphatesters in the Slack (thanks, everybody! :heart:).
---
- [About the Project](https://github.com/evilsocket/pwnagotchi/blob/master/docs/about.md)
- [How to Install](https://github.com/evilsocket/pwnagotchi/blob/master/docs/install.md)
- [Configuration](https://github.com/evilsocket/pwnagotchi/blob/master/docs/configure.md)
- [Usage](https://github.com/evilsocket/pwnagotchi/blob/master/docs/usage.md)
- [Plugins](https://github.com/evilsocket/pwnagotchi/blob/master/docs/plugins.md)
- [Development](https://github.com/evilsocket/pwnagotchi/blob/master/docs/dev.md)
- [FAQ](https://github.com/evilsocket/pwnagotchi/blob/master/docs/faq.md)
- [Community Hacks](https://github.com/evilsocket/pwnagotchi/blob/master/docs/hacks.md)
https://www.pwnagotchi.ai
## Links

44
docs/about.md
View File

@ -1,44 +0,0 @@
# About the Project
[Pwnagotchi](https://twitter.com/pwnagotchi) is an [A2C](https://hackernoon.com/intuitive-rl-intro-to-advantage-actor-critic-a2c-4ff545978752)-based "AI" leveraging [bettercap](https://www.bettercap.org/) that learns from its surrounding WiFi environment in order to maximize the WPA key material it captures (either passively, or by performing deauthentication and association attacks). This material is collected as PCAP files containing any form of handshake supported by [hashcat](https://hashcat.net/hashcat/), including [PMKIDs](https://www.evilsocket.net/2019/02/13/Pwning-WiFi-networks-with-bettercap-and-the-PMKID-client-less-attack/),
full and half WPA handshakes.
![handshake](https://i.imgur.com/pdA4vCZ.png)
Instead of merely playing [Super Mario or Atari games](https://becominghuman.ai/getting-mario-back-into-the-gym-setting-up-super-mario-bros-in-openais-gym-8e39a96c1e41?gi=c4b66c3d5ced) like most reinforcement learning based "AI" *(yawn)*, Pwnagotchi tunes [its own parameters](https://github.com/evilsocket/pwnagotchi/blob/master/sdcard/rootfs/root/pwnagotchi/config.yml#L54) over time to **get better at pwning WiFi things** in the environments you expose it to.
**Keep in mind:** Unlike the usual RL simulations, Pwnagotchi actually learns over time. Time for a Pwnagotchi is measured in epochs; a single epoch can last from a few seconds to 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](https://hackernoon.com/intuitive-rl-intro-to-advantage-actor-critic-a2c-4ff545978752) several combinations of [key parameters](https://github.com/evilsocket/pwnagotchi/blob/master/docs/usage.md#training-the-ai) 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. :)
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 units trained together will learn to cooperate upon detecting each other's presence by dividing the available channels among them for optimal pwnage.
![peers](https://i.imgur.com/Ywr5aqx.png)
[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](https://github.com/evilsocket/pwnagotchi/blob/master/docs/configure.md#configuration), too!
Of course, it is possible to run your Pwnagotchi with the AI disabled (configurable in `config.yml`). 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](https://www.bettercap.org/) + [webui](https://github.com/evilsocket/pwnagotchi/blob/master/docs/usage.md#bettercaps-web-ui) dedicated hardware.
## 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 are successfully exchanged and the keys have been generated, the client device is authenticated and can start sending and receiving data packets to and from the wireless AP that are secured by encryption.
<p align="center">
<img src="https://i.imgur.com/nI8IE6a.png"/>
<br/>
<small>image taken from <a target="_blank" href="https://www.wifi-professionals.com/2019/01/4-way-handshake">wifi-professionals.com</a></small>
</p>
So...what's the catch? Well, these four packets can easily be "sniffed" by an attacker monitoring nearby (say, with a Pwnagotchi :innocent:). And once recorded, that attacker can use [dictionary and/or bruteforce attacks](https://hashcat.net/wiki/doku.php?id=cracking_wpawpa2) 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](https://hashcat.net/forum/thread-7717-post-41447.html), *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.
- **Send association frames directly to the access points themselves**
to try to force them to [leak the PMKID](https://www.evilsocket.net/2019/02/13/Pwning-WiFi-networks-with-bettercap-and-the-PMKID-client-less-attack/).
All the handshakes captured this way are saved into `.pcap` files on Pwnagotchi's 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](https://hashcat.net/wiki/doku.php?id=cracking_wpawpa2).
## License
`pwnagotchi` is made with ♥ by [@evilsocket](https://twitter.com/evilsocket) and the [amazing dev team](https://github.com/evilsocket/pwnagotchi/graphs/contributors). It's released under the GPL3 license.

126
docs/configure.md
View File

@ -1,126 +0,0 @@
# Configuration
Once you've [written the image file onto the SD card](https://github.com/evilsocket/pwnagotchi/blob/master/docs/install.md#flashing-an-image), there're a few steps you'll have to follow in order to configure your new Pwnagotchi properly.
## Connect to your Pwnagotchi
1. First, start with connecting the USB cable to the data port of the Raspberry Pi and the RPi to your computer.
2. After a few seconds, the board will boot and you will see a new Ethernet interface on your host computer.
3. You'll need to configure it with a static IP address:
- IP: `10.0.0.1`
- Netmask: `255.255.255.0`
- Gateway: `10.0.0.1`
- DNS (if required): `8.8.8.8` (or whatever)
4. If everything's been configured properly, you will now be able to `ping` both `10.0.0.2` or `pwnagotchi.local`
* If you have already customized the hostname of your Pwnagotchi, `pwnagotchi.local` won't work. Instead, try *your unit's hostname* + `.local`.
5. **Congratulations!** You can now connect to your unit using SSH:
```bash
ssh pi@10.0.0.2
```
##### About your SSH connection
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!), copy your SSH public key to the unit's authorized keys:
```bash
ssh-copy-id -i ~/.ssh/id_rsa.pub pi@10.0.0.2
```
## Give your Pwnagotchi a name
You can now set a new name for your unit by [changing the hostname](https://geek-university.com/raspberry-pi/change-raspberry-pis-hostname/)!
Open the `/etc/pwnagotchi/config.yml` file (either via SSH or by directly editing the SD card contents from a computer) that will override the [default configuration](https://github.com/evilsocket/pwnagotchi/blob/master/pwnagotchi/defaults.yml) with your custom values.
## Choose your Pwnagotchi's language
Pwnagotchi displays its UI in English by default, but it can speak several other languages! If you're fine with English, you don't need to do anything special.
But if you want, you can change `main.lang` to one of the supported languages:
- **English** *(default)*
- German
- Dutch
- Greek
- Macedonian
- Italian
- French
- Russian
- Swedish
## PwnGRID
By default the `grid` [plugin](https://github.com/evilsocket/pwnagotchi/blob/master/docs/plugins.md) is **only partially** enabled, this means that whenever the unit will detect internet connectivity in manual mode, it'll signal its
presence to the PwnGRID server without sending any data other than:
- The cryptographic identity of the unit, generated at first boot and used for authentication.
- The output of the `uname -a` command on the unit used to determine the type of hardware.
It is possible to fully opt-in and also enable the unit to send basic information about the pwned networks. None of the captured cryptographic material is sent to this server,
just the minimum information to enroll the unit in the database and know how many networks it "conquered" so far, namely:
- The list of networks that the unit collected handshakes of, made of their `BSSID` and `ESSID`.
Other than for easy unit identification and debugging, this data is collected in order to build drankings, scoreboards and regional statistics. **Like Pokèmon Go, but for WiFi!**
In order to fully opt-in, you can put this in your `/etc/pwnagotchi/config.yml` file:
```yaml
main:
plugins:
grid:
enabled: true
report: true # full-opt in
```
Even if fully opted-in, you can still disable reporting for specific networks, for instance if you don't want your home network to be in the system:
```yaml
main:
plugins:
grid:
enabled: true
report: true
exclude:
- MyHomeNetwork
- de:ad:be:ef:de:ad # both ESSIDs and BSSIDs are supported
```
If instead you prefer to completely opt-out by also disabling signaling:
```yaml
main:
plugins:
grid:
enabled: false # full opt-out
report: false
```
## Display Selection
**Set the type of display you want to use via `ui.display.type`.**
If your display does not work after changing this setting, you might need to completely remove power from the Raspberry Pi and make a clean boot.
**You can configure the refresh interval of the display via `ui.fps`.** We recommend using a slow refresh rate to avoid shortening the lifetime of your e-ink display. The default value is `0`, which will *only* refresh when changes are made to the screen.
## Host Connection Share
Want to be able to update your Pwnagotchi and access things from the internet on it? *Sure you do!*
1. Connect to the Pwnagotchi unit via `usb0` (A.K.A., using the data port).
2. Run the appropriate connection sharing script to bring the interface up on your end and share internet connectivity from another interface:
OS | Script Location
------|---------------------------
Linux | `scripts/linux_connection_share.sh`
Mac OS X | `scripts/macos_connection_share.sh`
Windows | `scripts/win_connection_share.ps1`
## Troubleshooting
##### If your network connection keeps flapping on your device connecting to your Pwnagotchi.
* Check if `usb0` (or equivalent) device is being controlled by NetworkManager.
* You can check this via `nmcli dev status`.

60
docs/dev.md
View File

@ -1,60 +0,0 @@
# Software
- Raspbian + [nexmon patches](https://re4son-kernel.com/re4son-pi-kernel/) for monitor mode, or any Linux with a monitor mode enabled interface (if you tune config.yml).
**Do not try with Kali on the Raspberry Pi 0 W, it is compiled without hardware floating point support and TensorFlow is simply not available for it, use Raspbian.**
## Creating an Image
You can use the `scripts/create_sibling.sh` script to create an - ready to flash - rasbian image with pwnagotchi.
```shell
usage: ./scripts/create_sibling.sh [OPTIONS]
Options:
-n <name> # Name of the pwnagotchi (default: pwnagotchi)
-i <file> # Provide the path of an already downloaded raspbian image
-o <file> # Name of the img-file (default: pwnagotchi.img)
-s <size> # Size which should be added to second partition (in Gigabyte) (default: 4)
-v <version> # Version of raspbian (Supported: latest; default: latest)
-p # Only run provisioning (assumes the image is already mounted)
-d # Only run dependencies checks
-h # Show this help
```
#### Known Issues
`GLib-ERROR **: 20:50:46.361: getauxval () failed: No such file or directory`
- Affected DEB & Versions: QEMU <= 2.11
- Fix: Upgrade QEMU to >= 3.1
- Bug Link: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=923289
## Adding a Language
If you want to add a language use the `language.sh` script. If you want to add for example the language **italian** you would type:
```shell
./scripts/language.sh add it
# Now make your changes to the file
# sdcard/rootfs/root/pwnagotchi/scripts/pwnagotchi/locale/it/LC_MESSAGES/voice.po
./scripts/language.sh compile it
# DONE
```
If you changed the `voice.py`- File, the translations need an update. Do it like this:
```shell
./scripts/language.sh update it
# Now make your changes to the file (changed lines are marked with "fuzzy")
# sdcard/rootfs/root/pwnagotchi/scripts/pwnagotchi/locale/it/LC_MESSAGES/voice.po
./scripts/language.sh compile it
# DONE
```
Now you can use the `preview.py`-script to preview the changes:
```shell
./scripts/preview.py --lang it --display ws1 ws2 inky --output preview.png
# Now open preview.png
```

208
docs/faq.md
View File

@ -1,208 +0,0 @@
# FAQ
<!-- IF YOU CHANGE ANY CHARACTERS IN AN FAQ QUESTION, YOU MUST ALSO CHANGE THE TABLE OF CONTENTS ENTRY &&&AND&&& THE ANCHOR LINK TEXT, OR ELSE THE LINKS WILL BREAK. -->
[**What can Pwnagotchi actually do?**](#what-can-pwnagotchi-actually-do)
* [Why does Pwnagotchi eat handshakes?](#why-does-pwnagotchi-eat-handshakes)
* [What kinds of handshakes does Pwnagotchi eat?](#what-kinds-of-handshakes-does-pwnagotchi-eat)
* [Does Pwnagotchi support both 2.4 GHz and 5.0 GHz?](#does-pwnagotchi-support-both-24-ghz-and-50-ghz)
* [Just how politely *does* Pwnagotchi deauth?](#just-how-politely-does-pwnagotchi-deauth)
* [Hey, I want to learn more about how Pwnagotchi actually works.](#hey-i-want-to-learn-more-about-how-pwnagotchi-actually-works)
* [How is Pwnagotchi using bettercap?](#how-is-pwnagotchi-using-bettercap)
* [What happens if I run a Pwnagotchi without the AI enabled?](#what-happens-if-i-run-a-pwnagotchi-without-the-ai-enabled)
* [How easy is it to hack Pwnagotchi to add additional functionality?](#how-easy-is-it-to-hack-pwnagotchi-to-add-additional-functionality)
[**Building Your Pwnagotchi**](#building-your-pwnagotchi)
* [What hardware do I need to create my very own Pwnagotchi?](#what-hardware-do-i-need-to-create-my-very-own-pwnagotchi)
* [Is there any way to see my Pwnagotchi's face even if I don't have a display?](#is-there-any-way-to-see-my-pwnagotchis-face-even-if-i-dont-have-a-display)
* [How do I attach the screen to the Raspberry Pi?](#how-do-i-attach-the-screen-to-the-raspberry-pi)
* [I love my new Pwnagotchi, but it kinda looks like a bomb. Where can I find a decent case?](#i-love-my-new-pwnagotchi-but-it-kinda-looks-like-a-bomb-where-can-i-find-a-decent-case)
* [Why does everybody use e-ink screens for their Pwnagotchis?](#why-does-everybody-use-e-ink-screens-for-their-pwnagotchis)
* [How do I connect to my Pwnagotchi?](#how-do-i-connect-to-my-pwnagotchi)
[**Customizing Your Pwnagotchi**](#customizing-your-pwnagotchi)
* [How do I change my Pwnagotchi's name?](#how-do-i-change-my-pwnagotchis-name)
* [I want to change the faces. What do I hack?](#i-want-to-change-the-faces-what-do-i-hack)
* [I want my Pwnagotchi to speak a different language. Can it?](#i-want-my-pwnagotchi-to-speak-a-different-language-can-it)
* [I have a great idea for something cool I wish Pwnagotchi could do!](#i-have-a-great-idea-for-something-cool-i-wish-pwnagotchi-could-do)
* [Are there any unofficial community "hacks" for further customizing my Pwnagotchi?](#are-there-any-unofficial-community-hacks-for-further-customizing-my-pwnagotchi)
[**Getting to Know Your Pwnagotchi**](#getting-to-know-your-pwnagotchi)
* [What does everything on the screen mean?](#what-does-everything-on-the-screen-mean)
* [How do I whitelist my home network so Pwnagotchi stops pwning me?](#how-do-i-whitelist-my-home-network-so-pwnagotchi-stops-pwning-me)
* [What is MANU mode? What is AUTO mode?](#what-is-manu-mode-what-is-auto-mode)
* [Why does the AI take 30 minutes to load?](#why-does-the-ai-take-30-minutes-to-load)
* [What is Pwnagotchi doing while it's waiting for the AI to load?](#what-is-pwnagotchi-doing-while-its-waiting-for-the-ai-to-load)
* [How do I know when the AI is running?](#how-do-i-know-when-the-ai-is-running)
* [Where does Pwnagotchi store all the handshakes it's eaten?](#where-does-pwnagotchi-store-all-the-handshakes-its-eaten)
* [What happens when my Pwnagotchi meets another Pwnagotchi?](#what-happens-when-my-pwnagotchi-meets-another-pwnagotchi)
[**Caring for Your Pwnagotchi**](#caring-for-your-pwnagotchi)
* [What do all my Pwnagotchi's faces mean?](#what-do-all-my-pwnagotchis-faces-mean)
* [How do I feed my Pwnagotchi?](#how-do-i-feed-my-pwnagotchi)
* [Oh no, my Pwnagotchi is sad and bored! How do I entertain it?!](#oh-no-my-pwnagotchi-is-sad-and-bored-how-do-i-entertain-it)
* [How do I update my Pwnagotchi?](#how-do-i-update-my-pwnagotchi)
* [I'm extremely emotionally-attached to my Pwnagotchi. How can I back up its brain?](#im-extremely-emotionally-attached-to-my-pwnagotchi-how-can-i-back-up-its-brain)
* [How do I turn off my Pwnagotchi?](#how-do-i-turn-off-my-pwnagotchi)
* [Uh. So. What do I do with all these handshakes my Pwnagotchi has been eating?](#uh-so-what-do-i-do-with-all-these-handshakes-my-pwnagotchi-has-been-eating)
[**Known Quirks**](#known-quirks)
* [My Pwnagotchi's log timestamps seem...unreliable. Huh?](#my-pwnagotchis-log-timestamps-seemunreliable-huh)
* [Help! My Pwnagotchi's SD card got corrupted. What gives?](#help-my-pwnagotchis-sd-card-got-corrupted-what-gives)
---
## **What can Pwnagotchi actually do?**
### Why does Pwnagotchi eat handshakes?
lorem ipsum dolor sit amet
---
### What kinds of handshakes does Pwnagotchi eat?
lorem ipsum dolor sit amet
---
### Does Pwnagotchi support both 2.4 GHz and 5.0 GHz?
lorem ipsum dolor sit amet
---
### Just how politely *does* Pwnagotchi deauth?
lorem ipsum dolor sit amet
---
### Hey, I want to learn more about how Pwnagotchi actually works.
lorem ipsum dolor sit amet
---
### How is Pwnagotchi using bettercap?
lorem ipsum dolor sit amet
---
### What happens if I run a Pwnagotchi without the AI enabled?
lorem ipsum dolor sit amet
---
### How easy is it to hack Pwnagotchi to add additional functionality?
lorem ipsum dolor sit amet
---
## **Building Your Pwnagotchi**
### What hardware do I need to create my very own Pwnagotchi?
lorem ipsum dolor sit amet
---
### Is there any way to see my Pwnagotchi's face even if I don't have a display?
lorem ipsum dolor sit amet
---
### How do I attach the screen to the Raspberry Pi?
lorem ipsum dolor sit amet
---
### I love my new Pwnagotchi, but it kinda looks like a bomb. Where can I find a decent case?
lorem ipsum dolor sit amet
---
### Why does everybody use e-ink screens for their Pwnagotchis?
lorem ipsum dolor sit amet
---
### How do I connect to my Pwnagotchi?
lorem ipsum dolor sit amet
---------------------------------------------------------------------------------------------------------------
## **Customizing Your Pwnagotchi**
### How do I change my Pwnagotchi's name?
lorem ipsum dolor sit amet
---
### I want to change the faces. What do I hack?
lorem ipsum dolor sit amet
---
### I want my Pwnagotchi to speak a different language. Can it?
lorem ipsum dolor sit amet
---
### I have a great idea for something cool I wish Pwnagotchi could do!
lorem ipsum dolor sit amet
---
### Are there any unofficial community "hacks" for further customizing my Pwnagotchi?
lorem ipsum dolor sit amet
---------------------------------------------------------------------------------------------------------------
## **Getting to Know Your Pwnagotchi**
### What does everything on the screen mean?
lorem ipsum dolor sit amet
---
### How do I whitelist my home network so Pwnagotchi stops pwning me?
lorem ipsum dolor sit amet
---
### What is MANU mode? What is AUTO mode?
lorem ipsum dolor sit amet
---
### Why does the AI take 30 minutes to load?
lorem ipsum dolor sit amet
---
### What is Pwnagotchi doing while it's waiting for the AI to load?
lorem ipsum dolor sit amet
---
### How do I know when the AI is running?
lorem ipsum dolor sit amet
---
### Where does Pwnagotchi store all the handshakes it's eaten?
lorem ipsum dolor sit amet
---
### What happens when my Pwnagotchi meets another Pwnagotchi?
lorem ipsum dolor sit amet
---------------------------------------------------------------------------------------------------------------
## **Caring for Your Pwnagotchi**
### What do all my Pwnagotchi's faces mean?
lorem ipsum dolor sit amet
---
### How do I feed my Pwnagotchi?
lorem ipsum dolor sit amet
---
### Oh no, my Pwnagotchi is sad and bored! How do I entertain it?!
lorem ipsum dolor sit amet
---
### How do I update my Pwnagotchi?
lorem ipsum dolor sit amet
---
### I'm extremely emotionally-attached to my Pwnagotchi. How can I back up its brain?
lorem ipsum dolor sit amet
---
### How do I turn off my Pwnagotchi?
lorem ipsum dolor sit amet
---
### Uh. So. What do I do with all these handshakes my Pwnagotchi has been eating?
lorem ipsum dolor sit amet
---------------------------------------------------------------------------------------------------------------
## **Known Quirks**
### My Pwnagotchi's log timestamps seem...unreliable. Huh?
lorem ipsum dolor sit amet
---
### Help! My Pwnagotchi's SD card got corrupted. What gives?
lorem ipsum dolor sit amet

102
docs/hacks.md
View File

@ -1,102 +0,0 @@
# Unofficial Hacks
---
**IMPORTANT DISCLAIMER:** The information provided on this page is NOT officially supported by the Pwnagotchi development team. These are unofficial "hacks" that users have worked out while customizing their units and decided to document for anybody else who might want to do something similar.
- **Please do NOT open issues if you cannot get something described in this document to work.**
- It (almost) goes without saying, but obviously: **we are NOT responsible if you break your hardware by following any instructions documented here. Use this information at your own risk.**
---
If you test one of these hacks yourself and it still works, it's extra nice if you update the **Last Tested On** table and note any minor adjustments you may have had to make to the instructions to make it work with your particular Pwnagotchi setup. :heart:
## Screens
### Waveshare 3.5" SPI TFT screen
Last tested on | Pwnagotchi version | Working? | Reference
---------------|--------------------|----------|-----------|
2019 October 3 | Unknown | :white_check_mark: | ([link](https://github.com/evilsocket/pwnagotchi/issues/124#issue-502346040))
Some of this guide will work with other framebuffer-based displays.
- First: SSH into your Pwnagotchi, and give it some internet!
- Don't forget to check your default gateway and `apt-get update`.
- Follow the guide here: [www.waveshare.com/wiki/3.5inch_RPi_LCD_(A)#Method_1._Driver_installation](https://www.waveshare.com/wiki/3.5inch_RPi_LCD_(A)#Method_1._Driver_installation)
- At the step with `./LCD35-show`, add `lite` to the command prompt (e.g., `./LCD35-show lite`).
- Reboot.
- As root, make three symlinks:
- `cd ~`
- `ln -s pwnagotchi.png pwnagotchi_1.png`
- `ln -s pwnagotchi.png pwnagotchi_2.png`
- `ln -s pwnagotchi.png pwnagotchi_3.png`
- `apt install fbi`
- Change display type to `inky` in `config.yml`
- Add `modules-load=dwc2,g_ether` to your kernel command line (`/boot/cmdline.txt`) or it will break!
- Also must add `dtoverlay=dwc2` to the bottom of (`/boot/config.txt`)
- Edit `/etc/rc.local` and add: `fbi -T 1 -a -noverbose -t 15 -cachemem 0 /root/pwnagotchi_1.png /root/pwnagotchi_2.png /root/pwnagotchi_3.png &`
- Reboot.
And you should be good!
---
### Pwnagotchi face via Bluetooth
Last tested on | Pwnagotchi version | Working? | Reference
---------------|--------------------|----------|-----------|
2019 October 6 | Unknown | :white_check_mark: | on Android
2019 October 6 | Unknown | :white_check_mark: | on iPad iOS 9.3.5
A way to view your Pwnagotchi's ~~face~~ UI wirelessly via Bluetooth on a separate device. Refresh rate is the same as the e-ink display (every few seconds). This is NOT Bluetooth tethering; this is only Bluetooth as a server on pi side; you connect the Bluetooth and get a DHCP IP address and that's it. This hack cannot leverage the data connection.
Contributed by Systemic in the Slack.
##### 1. First Step
- Comment out the Bluetooth disable line from `/boot/config.txt` : `#dtoverlay=pi3-disable-bt`
- Change `/root/pwnagotchi/config.yml` to have `0.0.0.0` instead of `10.0.0.2` to listen as well on Bluetooth.
- Then launch the following commands:
##### 2. Install required packages.
```sudo apt-get install bluez bluez-tools bridge-utils dnsmasq```
##### 3. Configure Bluetooth and start it.
```sudo modprobe bnep
sudo brctl addbr pan0
sudo brctl setfd pan0 0
sudo brctl stp pan0 off
sudo ifconfig pan0 172.26.0.1 netmask 255.255.255.0
sudo ip link set pan0 up
```
```cat <<- EOF > /tmp/dnsmasq_bt.conf```
```bind-interfaces
port=0
interface=pan0
listen-address=172.26.0.1
dhcp-range=172.26.0.2,172.26.0.100,255.255.255.0,5m
dhcp-leasefile=/tmp/dnsmasq_bt.leases
dhcp-authoritative
log-dhcp
```
```EOF```
```sudo dnsmasq -C /tmp/dnsmasq_bt.conf
sudo bt-agent -c NoInputNoOutput&
sudo bt-adapter -a hci0 --set Discoverable 1
sudo bt-adapter -a hci0 --set DiscoverableTimeout 0
sudo bt-adapter -a hci0 --set Pairable 1
sudo bt-adapter -a hci0 --set PairableTimeout 0
sudo bt-network -a hci0 -s nap pan0 &
```
##### 4. Finally: on your phone, you have to disable all existing interfaces:
- Shutdown WiFi.
- Shutdown mobile data.
- Connect to the newly available Bluetooth device (which has the name of your Pwnagotchi).
- Once connected, you can test: `http://172.26.0.1:8080`
- You can also install bettercap's UI (`sudo bettercap` then `ui.update`)
- You'll need to change the http caplets to change `127.0.0.1` to `0.0.0.0`.
- You can connect to the shell with a terminal emulator ...
Happy tweaking.

23
docs/index.md
View File

@ -1,23 +0,0 @@
# Documentation
- [About the Project](https://github.com/evilsocket/pwnagotchi/blob/master/docs/about.md)
- [How to Install](https://github.com/evilsocket/pwnagotchi/blob/master/docs/install.md)
- [Configuration](https://github.com/evilsocket/pwnagotchi/blob/master/docs/configure.md)
- [Usage](https://github.com/evilsocket/pwnagotchi/blob/master/docs/usage.md)
- [Plugins](https://github.com/evilsocket/pwnagotchi/blob/master/docs/plugins.md)
- [Development](https://github.com/evilsocket/pwnagotchi/blob/master/docs/dev.md)
- [FAQ](https://github.com/evilsocket/pwnagotchi/blob/master/docs/faq.md)
- [Community Hacks](https://github.com/evilsocket/pwnagotchi/blob/master/docs/hacks.md)
## Links
&nbsp; | Official Links
---------|-------
Slack | [pwnagotchi.slack.com](https://pwnagotchi.herokuapp.com)
Twitter | [@pwnagotchi](https://twitter.com/pwnagotchi)
Subreddit | [r/pwnagotchi](https://www.reddit.com/r/pwnagotchi/)
Website | [pwnagotchi.ai](https://pwnagotchi.ai/)
## License
`pwnagotchi` is made with ♥ by [@evilsocket](https://twitter.com/evilsocket) and the [amazing dev team](https://github.com/evilsocket/pwnagotchi/graphs/contributors). It's released under the GPL3 license.

60
docs/install.md
View File

@ -1,60 +0,0 @@
# Installation
The project has been developed to run on a Raspberry Pi 0 W configured as an [USB Ethernet gadget](https://learn.adafruit.com/turning-your-raspberry-pi-zero-into-a-usb-gadget/ethernet-gadget) device in order to connect to it via USB. However, given the proper configuration tweaks, any GNU/Linux computer with a WiFi interface that supports monitor mode could be used.
**An important note about the AI:** a network trained with a specific WiFi interface will ONLY work with another interface if it supports the *exact same* WiFi channels of the first one. For instance, you CANNOT use a neural network trained on a Raspberry Pi Zero W (that only supports 2.4Ghz channels) with a 5Ghz antenna; you will need to train one from scratch for those channels.
## Required Hardware
- [Raspberry Pi Zero W](https://www.raspberrypi.org/products/raspberry-pi-zero-w/).†
- A micro SD card, 8GB recommended, **preferably of good quality and speed**.
- A decent power bank (with 1500 mAh you get ~2 hours with AI on).
- One of the supported displays (optional).
† Many users have gotten Pwnagotchi running on other types of Raspberry Pi, but the RPi0W is the "vanilla" hardware config for Pwnagotchi.
### Display
The display is an optional component as the UI is also rendered via a web interface available via the USB cable. If you connect to `usb0` (by using the data port on the unit) and point your browser to the web ui (see `config.yml`), your unit can work in "headless mode".
If, instead, you want to fully enjoy walking around and literally looking at your unit's face, the supported display models are:
- [Waveshare eInk Display (both V1 and V2)](https://www.waveshare.com/2.13inch-e-paper-hat.htm)
- [Product comparison](https://www.waveshare.com/4.3inch-e-paper.htm) (scroll down to `Selection Guide`)
- [GitHub](https://github.com/waveshare/e-Paper/tree/master/RaspberryPi%26JetsonNano/python)
- [Pimoroni Inky pHAT](https://shop.pimoroni.com/products/inky-phat)
- [Product page](https://shop.pimoroni.com/products/inky-phat)
- [GitHub](https://github.com/pimoroni/inky)
- [PaPiRus eInk Screen](https://uk.pi-supply.com/products/papirus-zero-epaper-screen-phat-pi-zero)
Needless to say, we are always happy to receive pull requests adding support for new models.
**One thing to note:** Not all displays are created equally! TFT displays, for example, work similar to an HDMI display, and they are NOT supported. Currently, all the officially-supported displays are I2C displays. If you are still interested in using unsupported displays, you may be able to find a community-submitted hack in the [Screens](https://github.com/evilsocket/pwnagotchi/blob/master/docs/hacks.md#screens) section of the [Hacks](https://github.com/evilsocket/pwnagotchi/blob/master/docs/hacks.md) page. We are not responsible for anything you break by trying to use any display that is not officially supported by the development team!
#### Color vs. Black & White displays
Some of the supported displays support both **Black & White** and **Colored** versions. One common question whether there are meaningful differences between the two. There are:
- Color displays have a much slower refresh rate. In some cases, it can take up to 15 seconds; if slow refresh rates are something that you want to avoid, we recommend you use B&W displays.
- The 3-color 2.13" Waveshare displays have a slightly smaller pixel layout (104x212) compared to their B&W counterparts (122x250).
#### Recommendations
- Avoid the Waveshare eInk **3-color** display. The refresh time is 15 seconds.
- Avoid the Pimoroni Inky pHAT **v1.** They're discontinued due to a faulty hardware part source used in manufacturing that resulted in high failure rates.
- Many users seem to prefer the Inky pHATs. There are two primary reasons:
- The Inkys feature better documentation and SDK support.
- Many Waveshare resellers do not disclose the version of the Waveshare boards they are selling (v1 vs v2), and the type they are selling can be fairly unclear (i.e., Waveshare 2.13 vs 2.13 B vs. 2.13C, and so on.)
## Flashing an Image
The easiest way to create a new Pwnagotchi is downloading the latest stable image from [our release page](https://github.com/evilsocket/pwnagotchi/releases) and write it to your SD card. You will need to use an image writing tool to install the image you have downloaded on your SD card.
[balenaEtcher](https://www.balena.io/etcher/) is a graphical SD card writing tool that works on Mac OS, Linux and Windows, and is the easiest option for most users. balenaEtcher also supports writing images directly from the zip file, without any unzipping required. To write your image with balenaEtcher:
- Download the latest [Pwnagotchi .img file](https://github.com/evilsocket/pwnagotchi/releases).
- Download [balenaEtcher](https://www.balena.io/etcher/) and install it.
- Connect an SD card reader with the SD card inside.
- Open balenaEtcher and select from your hard drive the Raspberry Pi .img or .zip file you wish to write to the SD card.
- Select the SD card you wish to write your image to.
- Review your selections and click 'Flash!' to begin writing data to the SD card.
Your SD card is now ready for the first boot!

56
docs/plugins.md
View File

@ -1,56 +0,0 @@
# Plugins
Pwnagotchi has a simple plugins system that you can use to customize your unit and its behaviour. You can place your plugins anywhere
as python files and then edit the `config.yml` file (`main.plugins` value) to point to their containing folder. Check the [plugins folder](https://github.com/evilsocket/pwnagotchi/tree/master/sdcard/rootfs/root/pwnagotchi/scripts/pwnagotchi/plugins/default/) for a list of default plugins and all the callbacks that you can define for your own customizations.
Here's as an example the GPS plugin:
```python
__author__ = 'evilsocket@gmail.com'
__version__ = '1.0.0'
__name__ = 'gps'
__license__ = 'GPL3'
__description__ = 'Save GPS coordinates whenever an handshake is captured.'
__enabled__ = True # set to false if you just don't use GPS
import core
import json
import os
device = '/dev/ttyUSB0'
speed = 19200
running = False
def on_loaded():
logging.info("GPS plugin loaded for %s" % device)
def on_ready(agent):
global running
if os.path.exists(device):
logging.info("enabling GPS bettercap's module for %s" % device)
try:
agent.run('gps off')
except:
pass
agent.run('set gps.device %s' % device)
agent.run('set gps.speed %d' % speed)
agent.run('gps on')
running = True
else:
logging.info("no GPS detected")
def on_handshake(agent, filename, access_point, client_station):
if running:
info = agent.session()
gps = info['gps']
gps_filename = filename.replace('.pcap', '.gps.json')
logging.info("saving GPS to %s (%s)" % (gps_filename, gps))
with open(gps_filename, 'w+t') as fp:
json.dump(gps, fp)
```

149
docs/usage.md
View File

@ -1,149 +0,0 @@
# Usage
## User Interface
The UI is available either via display if installed, or via http://pwnagotchi.local:8080/ if you connect to the unit via `usb0` and set a static address on the network interface (change `pwnagotchi` with the hostname of your unit).
![ui](https://i.imgur.com/c7xh4hN.png)
* **CH**: Current channel the unit is operating on or `*` when hopping on all channels.
* **APS**: Number of access points on the current channel and total visible access points.
* **UP**: Time since the unit has been activated.
* **PWND**: Number of handshakes captured in this session and number of unique networks we own at least one handshake of, from the beginning.
* **MODE**:
* **AUTO:** This indicates that the Pwnagotchi algorithm is running in AUTOMATIC mode, with AI disabled (or still loading); it disappears once the AI dependencies have been bootstrapped and the neural network has finished loading.
* **MANU:** This appears when the unit is running in MANUAL mode.
* **FRIEND:** If another unit is nearby, its presence will be indicated here. If more than one unit is nearby, only one—whichever has the stronger signal strength—will be displayed.
## Training the AI
At its core Pwnagotchi is a very simple creature: we could summarize its main algorithm as:
```python
# main loop
while True:
# ask bettercap for all visible access points and their clients
aps = get_all_visible_access_points()
# loop each AP
for ap in aps:
# send an association frame in order to grab the PMKID
send_assoc(ap)
# loop each client station of the AP
for client in ap.clients:
# deauthenticate the client to get its half or full handshake
deauthenticate(client)
wait_for_loot()
```
Despite its simplicity, this logic is controlled by several parameters that regulate the wait times, the timeouts, on which channels to hop and so on.
From `config.yml`:
```yaml
personality:
# advertise our presence
advertise: true
# perform a deauthentication attack to client stations in order to get full or half handshakes
deauth: true
# send association frames to APs in order to get the PMKID
associate: true
# list of channels to recon on, or empty for all channels
channels: []
# minimum WiFi signal strength in dBm
min_rssi: -200
# number of seconds for wifi.ap.ttl
ap_ttl: 120
# number of seconds for wifi.sta.ttl
sta_ttl: 300
# time in seconds to wait during channel recon
recon_time: 30
# number of inactive epochs after which recon_time gets multiplied by recon_inactive_multiplier
max_inactive_scale: 2
# if more than max_inactive_scale epochs are inactive, recon_time *= recon_inactive_multiplier
recon_inactive_multiplier: 2
# time in seconds to wait during channel hopping if activity has been performed
hop_recon_time: 10
# time in seconds to wait during channel hopping if no activity has been performed
min_recon_time: 5
# maximum amount of deauths/associations per BSSID per session
max_interactions: 3
# maximum amount of misses before considering the data stale and triggering a new recon
max_misses_for_recon: 5
# number of active epochs that triggers the excited state
excited_num_epochs: 10
# number of inactive epochs that triggers the bored state
bored_num_epochs: 15
# number of inactive epochs that triggers the sad state
sad_num_epochs: 25
```
There is no optimal set of parameters for every situation: when the unit is moving (during a walk for instance) smaller timeouts and RSSI thresholds might be preferred in order to quickly remove routers that are not in range anymore, while when stationary in high density areas (like an office) other parameters might be better. The role of the AI is to observe what's going on at the WiFi level, and adjust those parameters in order to maximize the cumulative reward of that loop / epoch.
## Reward Function
After each iteration of the main loop (an `epoch`), the reward, a score that represents how well the parameters performed, is computed as (an excerpt from `pwnagotchi/ai/reward.py`):
```python
# state contains the information of the last epoch
# epoch_n is the number of the last epoch
tot_epochs = epoch_n + 1e-20 # 1e-20 is added to avoid a division by 0
tot_interactions = max(state['num_deauths'] + state['num_associations'], state['num_handshakes']) + 1e-20
tot_channels = wifi.NumChannels
# ideally, for each interaction we would have an handshake
h = state['num_handshakes'] / tot_interactions
# small positive rewards the more active epochs we have
a = .2 * (state['active_for_epochs'] / tot_epochs)
# make sure we keep hopping on the widest channel spectrum
c = .1 * (state['num_hops'] / tot_channels)
# small negative reward if we don't see aps for a while
b = -.3 * (state['blind_for_epochs'] / tot_epochs)
# small negative reward if we interact with things that are not in range anymore
m = -.3 * (state['missed_interactions'] / tot_interactions)
# small negative reward for inactive epochs
i = -.2 * (state['inactive_for_epochs'] / tot_epochs)
reward = h + a + c + b + i + m
```
By maximizing this reward value, the AI learns over time to find the set of parameters that better perform with the current environmental conditions.
## BetterCAP's Web UI
Moreover, given that the unit is running bettercap with API and Web UI, you'll be able to use the unit as a WiFi penetration testing portable station by accessing `http://pwnagotchi.local/`.
![webui](https://raw.githubusercontent.com/bettercap/media/master/ui-events.png)
## Update your Pwnagotchi
You can use the `scripts/update_pwnagotchi.sh` script to update to the most recent version of pwnagotchi.
```shell
usage: ./update_pwnagitchi.sh [OPTIONS]
Options:
-v # Version to update to, can be a branch or commit. (default: master)
-u # Url to clone from. (default: https://github.com/evilsocket/pwnagotchi)
-m # Mode to restart to. (Supported: auto manual; default: auto)
-b # Backup the current pwnagotchi config.
-r # Restore the current pwnagotchi config. -b will be enabled.
-h # Shows this help. Shows this help.
```
## Backup your Pwnagotchi
You can use the `scripts/backup.sh` script to backup the important files of your unit.
```shell
usage: ./scripts/backup.sh HOSTNAME backup.zip
```
## Random Info
* **On a rpi0w, it'll take approximately 30 minutes to load the AI**.
* `/var/log/pwnagotchi.log` is your friend.
* if connected to a laptop via usb data port, with internet connectivity shared, magic things will happen.
* checkout the `ui.video` section of the `config.yml` - if you don't want to use a display, you can connect to it with the browser and a cable.
* If you get `[FAILED] Failed to start Remount Root and Kernel File Systems.` while booting pwnagotchi, make sure the `PARTUUID`s for `rootfs` and `boot` partitions are the same in `/etc/fstab`. Use `sudo blkid` to find those values when you are using `create_sibling.sh`.