marin-m/pbtkUm conjunto de ferramentas para engenharia reversa e fuzzing de aplicativos baseados em Protobuf
Protobuf é um formato de serialização desenvolvido pelo Google e usado em um número crescente de aplicativos Android, web, desktop e outros. Consiste em uma linguagem para declarar estruturas de dados, que é então compilada para código ou outro tipo de estrutura, dependendo da implementação alvo.
pbtk (Protobuf toolkit) é um conjunto completo de scripts, acessível através de uma GUI unificada, que fornece duas funcionalidades principais:
Extrair estruturas Protobuf de programas, convertendo-as de volta para arquivos .proto legíveis, suportando várias implementações:
Editar, repetir e fazer fuzzing de dados enviados para endpoints de rede Protobuf, através de uma interface gráfica prática que permite editar ao vivo os campos de uma mensagem Protobuf e visualizar o resultado.
O PBTK requer Python ≥ 3.5, PySide 6, Python-Protobuf 3 e alguns programas executáveis (chromium, jad, dex2jar...) para executar os scripts de extração.
Usuários Ubuntu podem instalá-lo usando snap:
$ sudo snap install pbtk
$ pbtk
Usuários Archlinux podem instalar diretamente através do pacote:
$ yay -S pbtk-git
$ pbtk
Na maioria das outras distribuições, você vai querer executá-lo diretamente:
# Para derivados Ubuntu/Debian em teste:
$ sudo apt install python3-pip git openjdk-8-jre python3-qtpy-pyside6
# Em seguida, usando UV:
$ sudo snap install --classic astral-uv
$ uv tool install pbtk
$ pbtk
# Ou usando pipx:
$ sudo apt install pipx
$ pipx install pbtk
$ pbtk
O Windows também é suportado (com os mesmos módulos necessários). Depois de executar a GUI, ela deve avisar sobre o que está faltando, dependendo do que você tentar fazer.
A GUI pode ser iniciada através do script principal:
pbtk
Os seguintes scripts também podem ser usados de forma autônoma, sem 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] # Precisa de atualização para funcionar a partir de 2026
Quando instalado via snap, os comandos exatos diferem:
pbtk.jar-extract [-h] input_file [output_dir]
pbtk.from-binary [-h] input_file [output_dir]
pbtk.web-extract [-h] input_url [output_dir]
A GUI pode ser iniciada através do script principal:
uv sync # Baixar dependências para a pasta .venv
source .venv/bin/activate # Colocar os scripts locais no $PATH para a sessão atual do shell
uv tool install -e . # Colocar os scripts locais no $PATH permanentemente
pbtk
Os seguintes scripts também podem ser usados de forma autônoma, sem 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] # Precisa de atualização para funcionar a partir de 2026
Digamos que você está fazendo engenharia reversa de um aplicativo Android. Você explorou um pouco o aplicativo com seu descompilador favorito e descobriu que ele transporta Protobuf como dados POST via HTTPS de forma típica.
Você abre o PBTK e é recebido de forma significativa:
O primeiro passo é obter seus .protos em formato de texto. Se você está mirando um aplicativo Android, soltar um APK e esperar deve fazer o trabalho mágico! (a menos que seja uma implementação realmente exótica)
Feito isso, você vai para ~/.pbtk/protos/<nome do seu APK> (através da linha de comando ou do botão na parte inferior da tela de boas-vindas para abrir o navegador de arquivos, da forma que preferir). Todos os .protos do aplicativo estão aqui.
De volta ao seu descompilador, você se deparou com a classe que constrói os dados enviados para o endpoint HTTPS que lhe interessa. Ela serializa a mensagem Protobuf chamando uma classe feita de código gerado.
Esta última classe deve ter uma correspondência perfeita dentro do seu diretório .protos (isto é, com.foo.bar.a.b corresponderá a com/foo/bar/a/b.proto). De qualquer forma, pesquisar seu nome deve permitir referenciá-la.
Isso é ótimo: a próxima coisa é ir para a Etapa 2, selecionar o arquivo .proto de entrada desejado e preencher algumas informações sobre seu endpoint.
Você também pode fornecer alguns dados Protobuf brutos de exemplo, que foram enviados para este endpoint, capturados através do mitmproxy ou Wireshark, e que você colará em formato hex.
Etapa 3 é sobre a parte divertida de clicar em botões e ver o que acontece! Você tem uma visualização em árvore representando cada campo na estrutura Protobuf (campos repetidos são sufixados por "+", campos obrigatórios não têm caixas de seleção).
Apenas passe o mouse sobre um campo para focá-lo. Se o campo for do tipo inteiro, use a roda do mouse para incrementar/decrementar. Informações sobre enum aparecem também ao passar o mouse.
Aqui está! Você pode determinar o significado de cada campo com isso. Se você extraiu .protos de código minificado, pode renomear campos de acordo com o que você percebe que eles significam, clicando em seus nomes.
Feliz engenharia reversa! 👌 🎉
O PBTK armazena informações de .proto extraídas em ~/.pbtk/protos/ (ou %APPDATA%\pbtk\protos no Windows).
Você pode mover para dentro, mover para fora, renomear, editar ou apagar dados deste diretório diretamente através do seu navegador de arquivos e editor de texto comuns, é a forma esperada de fazer isso e não interferirá com o PBTK.
Endpoints baseados em HTTP são armazenados em ~/.pbtk/endpoints/ como objetos JSON. Esses objetos são arrays de pares de informações de requisição/resposta, que se parecem com isso:
[{
"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"
}
}]
O PBTK usa internamente dois tipos de módulos plugáveis: extratores e transportes.
Os extratores são definidos em src/pbtk/extractors/*.py. Eles são definidos como um método precedido por um decorador, assim: