marin-m/pbtkUn set di strumenti per il reverse engineering e il fuzzing di applicazioni basate su Protobuf
# pbtk - Ingegneria inversa di app Protobuf
**[Protobuf](https://developers.google.com/protocol-buffers/) è un formato di serializzazione** sviluppato da Google e utilizzato in un numero crescente di applicazioni Android, web, desktop e altro. Consiste in un **linguaggio per dichiarare strutture dati**, che viene poi compilato in codice o in un altro tipo di struttura a seconda dell'implementazione target.
pbtk (*Protobuf toolkit*) è un set completo di script, accessibile tramite un'interfaccia grafica unificata, che offre due funzionalità principali:
- **Estrarre strutture Protobuf da programmi**, convertendole in file .proto leggibili, supportando diverse implementazioni:
- Tutti i principali runtime Java (base, Lite, Nano, Micro, J2ME), con pieno supporto Proguard, *(2026: funziona ancora bene ma principalmente con APK vecchi)*
- Binari contenenti metadati di reflection incorporati (tipicamente C++, a volte Java e la maggior parte degli altri binding), *(2026: funziona ancora bene)*
- Applicazioni web che utilizzano il runtime JsProtoUrl. *(2026: necessita di un aggiornamento)*
- **Modificare, riprodurre e fare fuzzing dei dati** inviati a endpoint di rete Protobuf, tramite un'interfaccia grafica pratica che permette di modificare in tempo reale i campi di un messaggio Protobuf e visualizzare il risultato.
<img src="https://assets.kitploit.com/production/public/readmes/3051/860b9306c2be49d204ad562b8bf0abdb831e9f1c9852edda265734fe26be1a2b.png" alt="L'interfaccia grafica dell'editor pbtk">
## Installazione
PBTK richiede Python ≥ 3.5, PySide 6, Python-Protobuf 3 e una manciata di programmi eseguibili (chromium, jad, dex2jar...) per eseguire gli script di estrazione.
Gli utenti Ubuntu possono installarlo usando `snap`:
```
$ sudo snap install pbtk
$ pbtk
```
Gli utenti Archlinux possono installare direttamente tramite il [pacchetto](https://aur.archlinux.org/packages/pbtk-git/):
```
$ yay -S pbtk-git
$ pbtk
```
Sulla maggior parte delle altre distribuzioni, conviene eseguirlo direttamente:
```tcl
# For Ubuntu/Debian testing derivates:
$ sudo apt install python3-pip git openjdk-8-jre python3-qtpy-pyside6
# Then, using UV:
$ sudo snap install --classic astral-uv
$ uv tool install pbtk
$ pbtk
# Or using pipx:
$ sudo apt install pipx
$ pipx install pbtk
$ pbtk
```
Anche Windows è supportato (con gli stessi moduli richiesti). Una volta avviata la GUI, ti avviserà su ciò che ti manca in base a ciò che provi a fare.
## Utilizzo da riga di comando (installazione tramite gestore pacchetti)
La GUI può essere avviata tramite lo script principale:
pbtk
I seguenti script possono essere usati anche in modo autonomo, senza GUI:
pbtk-jar-extract [-h] input_file [output_dir]
pbtk-from-binary [-h] input_file [output_dir]
pbtk-web-extract [-h] input_url [output_dir] # Needs update to work as of 2026
Quando installato da `snap`, i comandi esatti differiscono:
pbtk.jar-extract [-h] input_file [output_dir]
pbtk.from-binary [-h] input_file [output_dir]
pbtk.web-extract [-h] input_url [output_dir]
## Utilizzo da riga di comando (locale)
La GUI può essere avviata tramite lo script principale:
```bash
uv sync # Download dependencies to the .venv folder
source .venv/bin/activate # Put the local scripts in $PATH for the current shell session
uv tool install -e . # Put the local scripts in $PATH all time
pbtk
```
I seguenti script possono essere usati anche in modo autonomo, senza GUI:
pbtk-jar-extract [-h] input_file [output_dir]
pbtk-from-binary [-h] input_file [output_dir]
pbtk-web-extract [-h] input_url [output_dir] # Needs update to work as of 2026
## Flusso di lavoro tipico
Supponiamo che tu stia facendo reverse engineering di un'applicazione Android. Hai esplorato un po' l'applicazione con il tuo decompilatore preferito e hai capito che trasporta Protobuf come dati POST su HTTPS in modo tipico.
Apri PBTK e vieni accolto in modo significativo:
Il primo passo è ottenere i tuoi .proto in formato testo. Se stai analizzando un'app Android, trascinare un APK e attendere dovrebbe fare il lavoro magico! (a meno che non si tratti di un'implementazione davvero esotica)
Fatto ciò, vai a `~/.pbtk/protos/<nome del tuo APK>` (tramite riga di comando o il pulsante in fondo alla schermata di benvenuto per aprire il file browser, come preferisci). Tutti i .proto dell'app sono effettivamente qui.
Tornato al tuo decompilatore, ti sei imbattuto nella classe che costruisce i dati inviati all'endpoint HTTPS che ti interessa. Serializza il messaggio Protobuf chiamando una classe composta da codice generato.
Questa classe dovrebbe avere una corrispondenza esatta nella directory dei tuoi .proto (ad esempio `com.foo.bar.a.b` corrisponderà a `com/foo/bar/a/b.proto`). In ogni caso, cercare il suo nome con grep dovrebbe permetterti di farvi riferimento.
Fantastico: il passo successivo è andare al **Passo 2**, selezionare il file .proto desiderato e compilare alcune informazioni sul tuo endpoint.
Puoi anche fornire alcuni dati Protobuf grezzi di esempio, inviati a questo endpoint, catturati tramite mitmproxy o Wireshark, e che incollerai in forma esadecimale.
**Passo 3** è la parte divertente di cliccare pulsanti e vedere cosa succede! Hai una vista ad albero che rappresenta ogni campo nella struttura Protobuf (i campi ripetuti hanno suffisso "+", i campi obbligatori non hanno caselle di controllo).
Basta passare il mouse su un campo per metterlo a fuoco. Se il campo è di tipo intero, usa la rotellina del mouse per incrementarlo/decrementarlo. Le informazioni sull'enumerazione appaiono anche al passaggio del mouse.
Ecco fatto! Puoi determinare il significato di ogni campo con questo. Se hai estratto i .proto da codice minificato, puoi rinominare i campi in base a ciò che noti significano, cliccando sui loro nomi.
Buon reversing! 👌 🎉
## Archiviazione locale dei dati
PBTK archivia le informazioni .proto estratte in `~/.pbtk/protos/` (o `%APPDATA%\pbtk\protos` su Windows).
Puoi spostare, rimuovere, rinominare, modificare o cancellare i dati da questa directory direttamente tramite il tuo normale file browser ed editor di testo, è il modo previsto e non interferirà con PBTK.
Gli endpoint basati su HTTP sono archiviati in `~/.pbtk/endpoints/` come oggetti JSON. Questi oggetti sono array di coppie di informazioni richiesta/risposta, che appaiono così:
```javascript
[{
"request": {
"transport": "pburl",
"proto": "www.google.com/VectorTown.proto",
"url": "https://www.google.com/VectorTown",
"pb_param": "pb",
"samples": [{
"pb": "!....",
"hl": "fr"
}]
},
"response": {
"format": "other"
}
}]
```
## Struttura del codice sorgente
PBTK utilizza internamente due tipi di moduli pluggabili: estrattori e trasporti.
* Un **estrattore** supporta l'estrazione di strutture .proto da un'implementazione o piattaforma Protobuf target.
Gli estrattori sono definiti in `src/pbtk/extractors/*.py`. Sono definiti come un metodo preceduto da un decoratore, in questo modo:
```python
@register_extractor(name = 'my_extractor',
desc = 'Extract Protobuf structures from Foobar code (*.foo, *.bar)',
depends={'binaries': ['foobar-decompiler']})
def my_extractor(path):
# Load contents of the `path` input file and do your stuff...
# Then, yield extracted .protos using a generator:
for i in do_your_extraction_work():
yield proto_name + '.proto', proto_contents
# Other kinds of information can be yield, such as endpoint information or progress to display.
```
* Un **trasporto** supporta un modo per deserializzare, riserializzare e inviare dati Protobuf sulla rete. Ad esempio, il trasporto più comunemente usato sono i dati POST grezzi su HTTP.
I trasporti sono definiti in `src/pbtk/utils/transports.py`. Sono definiti come una classe preceduta da un decoratore, in questo modo:
```python
@register_transport(
name = 'my_transport',
desc = 'Protobuf as raw POST data',
ui_data_form = 'hex strings'
)
class MyTransport():
def __init__(self, pb_param, url):
self.url = url
def serialize_sample(self, sample):
# We got a sample of input data from the user.
# Verify that it is valid in the form described through "ui_data_form" parameter, fail with an exception or return False otherwise.
# Optionally modify this data prior to returning it.
bytes.fromhex(sample)
return sample
def load_sample(self, sample, pb_msg):
# Parse input data into the provided Protobuf object.
pb_msg.ParseFromString(bytes.fromhex(sample))
def perform_request(self, pb_data, tab_data):
# Perform a request using the provided URL and Protobuf object, and optionally other transport-specific side data.
return post(url, pb_data.SerializeToString(), headers=USER_AGENT)
```
## Miglioramenti futuri
I seguenti potrebbero arrivare per le prossime versioni:
* Completare la parte di fuzzing automatico.
* Supporto per l'estrazione di estensioni dal codice Java.
* Supporto per il runtime JSPB (JavaScript principale).
* Se c'è un'altra piattaforma che desideri vedere supportata, apri un issue e la valuterò.
Ho cercato di fare del mio meglio per produrre codice ampiamente leggibile e commentato (tranne per le parti che sono per lo più auto-esplicative, come la connessione dei segnali GUI) per la maggior parte dei moduli, così puoi contribuire.
## Licenza
pbtk è rilasciato sotto licenza [GNU GPL](https://www.gnu.org/licenses/gpl-3.0.html) (Io, qui, ecc.).
Non esiste una regola formalizzata per le maiuscole/minuscole del nome del progetto, la regola è semplicemente seguire il tuo cuore ❤