marin-m/pbtkUn ensemble d'outils pour la rétro-ingénierie et le fuzzing d'applications basées sur Protobuf
Protobuf est un format de sérialisation développé par Google et utilisé dans un nombre croissant d'applications Android, web, de bureau et autres. Il consiste en un langage pour déclarer des structures de données, qui est ensuite compilé en code ou en un autre type de structure selon l'implémentation cible.
pbtk (Protobuf toolkit) est un ensemble complet de scripts, accessible via une interface graphique unifiée, qui offre deux fonctionnalités principales :
Extraire des structures Protobuf de programmes, les reconvertir en fichiers .proto lisibles, prenant en charge diverses implémentations :
Éditer, rejouer et fuzzer les données envoyées aux endpoints réseau Protobuf, grâce à une interface graphique pratique qui vous permet d'éditer en direct les champs d'un message Protobuf et d'en voir le résultat.
PBTK nécessite Python ≥ 3.5, PySide 6, Python-Protobuf 3, et quelques programmes exécutables (chromium, jad, dex2jar…) pour exécuter les scripts d'extraction.
Les utilisateurs Ubuntu peuvent l'installer avec snap :
$ sudo snap install pbtk
$ pbtk
Les utilisateurs Archlinux peuvent l'installer directement via le paquet :
$ yay -S pbtk-git
$ pbtk
Sur la plupart des autres distributions, vous voudrez l'exécuter directement :
# Pour les dérivés de test Ubuntu/Debian :
$ sudo apt install python3-pip git openjdk-8-jre python3-qtpy-pyside6
# Ensuite, en utilisant UV :
$ sudo snap install --classic astral-uv
$ uv tool install pbtk
$ pbtk
# Ou avec pipx :
$ sudo apt install pipx
$ pipx install pbtk
$ pbtk
Windows est également supporté (avec les mêmes modules requis). Une fois que vous lancez l'interface graphique, elle devrait vous avertir de ce qui vous manque selon ce que vous essayez de faire.
L'interface graphique peut être lancée via le script principal :
pbtk
Les scripts suivants peuvent également être utilisés seuls, sans interface graphique :
pbtk-jar-extract [-h] input_file [output_dir]
pbtk-from-binary [-h] input_file [output_dir]
pbtk-web-extract [-h] input_url [output_dir] # Nécessite une mise à jour pour fonctionner en 2026
Lors de l'installation depuis snap, les commandes exactes diffèrent :
pbtk.jar-extract [-h] input_file [output_dir]
pbtk.from-binary [-h] input_file [output_dir]
pbtk.web-extract [-h] input_url [output_dir]
L'interface graphique peut être lancée via le script principal :
uv sync # Télécharge les dépendances dans le dossier .venv
source .venv/bin/activate # Place les scripts locaux dans $PATH pour la session shell actuelle
uv tool install -e . # Place les scripts locaux dans $PATH en permanence
pbtk
Les scripts suivants peuvent également être utilisés seuls, sans interface graphique :
pbtk-jar-extract [-h] input_file [output_dir]
pbtk-from-binary [-h] input_file [output_dir]
pbtk-web-extract [-h] input_url [output_dir] # Nécessite une mise à jour pour fonctionner en 2026
Disons que vous faites de l'ingénierie inverse d'une application Android. Vous avez exploré un peu l'application avec votre décompilateur préféré, et avez découvert qu'elle transporte du Protobuf en tant que données POST sur HTTPS de manière typique.
Vous ouvrez PBTK et êtes accueilli de manière significative :
La première étape consiste à obtenir vos .protos au format texte. Si vous ciblez une application Android, déposer un APK et attendre devrait faire l'affaire ! (sauf s'il s'agit d'une implémentation vraiment exotique)
Une fois cela fait, vous allez dans ~/.pbtk/protos/<nom de votre APK> (soit via la ligne de commande, soit via le bouton en bas de l'écran d'accueil pour ouvrir votre explorateur de fichiers, comme vous préférez). Tous les .protos de l'application sont bien là.
De retour dans votre décompilateur, vous êtes tombé sur la classe qui construit les données envoyées au point de terminaison HTTPS qui vous intéresse. Elle sérialise le message Protobuf en appelant une classe composée de code généré.
Cette dernière classe devrait correspondre parfaitement à l'intérieur de votre répertoire .protos (par exemple com.foo.bar.a.b correspondra à com/foo/bar/a/b.proto). Quoi qu'il en soit, faire un grep sur son nom devrait vous permettre de la référencer.
C'est super : l'étape suivante consiste à aller à l'étape 2, sélectionner votre .proto d'entrée souhaité, et remplir quelques informations sur votre point de terminaison.
Vous pouvez également fournir un échantillon de données brutes Protobuf, qui ont été envoyées à ce point de terminaison, capturées via mitmproxy ou Wireshark, et que vous collerez sous forme hexadécimale.
L'étape 3 est la partie amusante où l'on clique sur les boutons et voit ce qui se passe ! Vous avez une vue arborescente représentant chaque champ de la structure Protobuf (les champs répétés sont suffixés par "+", les champs obligatoires n'ont pas de cases à cocher).
Survolez simplement un champ pour le mettre au point. Si le champ est de type entier, utilisez la molette de la souris pour incrémenter/décrémenter. Les informations d'énumération apparaissent également au survol.
Voilà ! Vous pouvez déterminer la signification de chaque champ avec cela. Si vous avez extrait des .protos de code minifié, vous pouvez renommer les champs en fonction de ce que vous remarquez qu'ils signifient, en cliquant sur leurs noms.
Bon reverse ! 👌 🎉
PBTK stocke les informations .proto extraites dans ~/.pbtk/protos/ (ou %APPDATA%\pbtk\protos sous Windows).
Vous pouvez déplacer, renommer, éditer ou effacer les données de ce répertoire directement via votre explorateur de fichiers et votre éditeur de texte habituels, c'est la façon attendue de le faire et cela n'interférera pas avec PBTK.
Les points de terminaison basés sur HTTP sont stockés dans ~/.pbtk/endpoints/ sous forme d'objets JSON. Ces objets sont des tableaux de paires d'informations requête/réponse, qui ressemblent à ceci :
[{
"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"
}
}]
PBTK utilise en interne deux types de modules enfichables : les extracteurs et les transports.
Les extracteurs sont définis dans src/pbtk/extractors/*.py. Ils sont définis comme une méthode précédée d'un décorateur, comme ceci :
@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.
Les transports sont définis dans src/pbtk/utils/transports.py. Ils sont définis comme une classe précédée d'un décorateur, comme ceci :
@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)
Les éléments suivants pourraient arriver dans les prochaines versions :
J'ai essayé de faire de mon mieux pour produire un code parfaitement lisible et commenté (sauf pour les parties qui sont essentiellement auto-descriptives, comme la connexion des signaux de l'interface graphique) pour la plupart des modules, afin que vous puissiez contribuer.
pbtk est publié sous la licence GNU GPL (je, par la présente, etc.).
Il n'y a pas de règle formalisée pour la casse du nom du projet, la règle est simplement de suivre votre cœur ❤