
Protobuf 기반 앱을 리버스 엔지니어링 및 퍼징하기 위한 도구 세트
Protobuf는 직렬화 형식으로, Google에서 개발했으며 점점 더 많은 Android, 웹, 데스크톱 및 기타 애플리케이션에서 사용되고 있습니다. 이는 데이터 구조를 선언하기 위한 언어로 구성되며, 대상 구현에 따라 코드 또는 다른 종류의 구조로 컴파일됩니다.
pbtk(Protobuf toolkit)는 통합 GUI를 통해 접근할 수 있는 완전한 기능을 갖춘 스크립트 모음으로, 두 가지 주요 기능을 제공합니다:
프로그램에서 Protobuf 구조 추출, 이를 읽을 수 있는 .proto 파일로 다시 변환하며, 다양한 구현을 지원합니다:
데이터 편집, 재전송 및 퍼징 — Protobuf 네트워크 엔드포인트로 전송되는 데이터를 편리한 그래픽 인터페이스를 통해 처리하며, Protobuf 메시지의 필드를 실시간으로 편집하고 결과를 확인할 수 있습니다.
PBTK는 Python ≥ 3.10, GTK 4, Adwaita ≥ 1.8, Python-Protobuf 3, 그리고 추출기 스크립트를 실행하기 위한 몇 가지 실행 프로그램(chromium, jad, dex2jar...)을 필요로 합니다.
Ubuntu 사용자는 snap을 사용하여 설치할 수 있습니다:
$ sudo snap install pbtk
$ pbtk
Archlinux 사용자는 패키지를 통해 직접 설치할 수 있습니다:
$ yay -S pbtk-git
$ pbtk
대부분의 다른 배포판에서는 직접 실행하는 것이 좋습니다:
# For Ubuntu/Debian derivates:
sudo apt install python3-pip git openjdk-8-jre gir1.2-adw-1 \
blueprint-compiler gir1.2-gtk-4.0 gir1.2-soup-3.0 python3-gobject
# 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
Windows도 지원됩니다. pbtk 2.x는 GTK 4 기반으로 동작하지만, pbtk 1.x(마지막 버전은 1.1.5)는 Qt 5 기반으로 동작했습니다.
GUI를 실행하면 수행하려는 작업에 따라 누락된 항목에 대해 경고가 표시됩니다.
GUI는 메인 스크립트를 통해 실행할 수 있습니다:
pbtk
다음 스크립트들은 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] # 2026년 기준으로 작동하려면 업데이트 필요
snap에서 설치한 경우 정확한 명령어가 다릅니다:
pbtk.jar-extract [-h] input_file [output_dir]
pbtk.from-binary [-h] input_file [output_dir]
pbtk.web-extract [-h] input_url [output_dir]
GUI는 메인 스크립트를 통해 실행할 수 있습니다:
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
cp -a .github/hooks/* .git/hooks/ # Needed for contributing to code
pbtk
다음 스크립트들은 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] # 2026년 기준으로 작동하려면 업데이트 필요
Android 애플리케이션을 리버스 엔지니어링하고 있다고 가정해 봅시다. 즐겨 쓰는 디컴파일러로 애플리케이션을 조금 살펴보았고, 이 애플리케이션이 전형적인 방식으로 Protobuf를 HTTPS를 통한 POST 데이터로 전송한다는 것을 알아냈습니다.
PBTK를 열면 의미 있는 방식으로 맞이해 줍니다:

첫 번째 단계는 .proto 파일들을 텍스트 형식으로 가져오는 것입니다. Android 앱을 대상으로 한다면, APK를 넣고 기다리기만 하면 마법 같은 작업이 이루어집니다! (정말 특이한 구현이 아니라면 말이죠)

이 작업이 끝나면 ~/.pbtk/protos/<APK 이름>으로 이동합니다 (명령줄을 통해서든, 환영 화면 하단의 버튼으로 파일 브라우저를 열어서든 원하는 방식으로). 앱의 모든 .proto 파일이 실제로 여기에 있습니다.
디컴파일러로 돌아가 보니, 관심 있는 HTTPS 엔드포인트로 전송되는 데이터를 생성하는 클래스를 발견했습니다. 이 클래스는 생성된 코드로 이루어진 클래스를 호출하여 Protobuf 메시지를 직렬화합니다.

이 후자의 클래스는 .proto 디렉터리 안에서 완벽한 대응 항목을 가질 것입니다 (즉 com.foo.bar.a.b는 com/foo/bar/a/b.proto와 일치합니다). 어느 쪽이든, 그 이름을 grep하면 참조할 수 있을 것입니다.
좋습니다: 다음은 2단계로 넘어가서, 원하는 입력 .proto를 선택하고 엔드포인트에 대한 정보를 몇 가지 채우는 것입니다.

이 엔드포인트로 전송된, mitmproxy나 Wireshark를 통해 캡처한 샘플 원시 Protobuf 데이터를 16진수 인코딩 형태로 붙여넣을 수도 있습니다.
3단계는 버튼을 클릭하고 무슨 일이 일어나는지 지켜보는 재미있는 부분입니다! Protobuf 구조의 모든 필드를 나타내는 트리 뷰가 있습니다 (반복 필드는 "+"가 접미사로 붙고, 필수 필드에는 체크박스가 없습니다).

필드 위에 마우스를 올리면 포커스가 맞춰집니다. 필드가 정수 타입이면 마우스 휠로 값을 증가/감소시킬 수 있습니다. 열거형 정보도 마우스를 올리면 나타납니다.
여기 있습니다! 이것으로 모든 필드의 의미를 파악할 수 있습니다. 축소된 코드에서 .proto를 추출했다면, 필드 이름을 클릭하여 알아낸 의미에 따라 이름을 바꿀 수 있습니다.
즐거운 리버싱 되세요! 👌 🎉
PBTK는 추출된 .proto 정보를 ~/.pbtk/protos/에 저장합니다 (Windows에서는 %APPDATA%\pbtk\protos).
일반 파일 브라우저와 텍스트 편집기를 통해 이 디렉터리에서 직접 데이터를 넣고, 빼고, 이름을 바꾸고, 편집하거나 삭제할 수 있습니다. 이것이 의도된 방식이며 PBTK와 충돌하지 않습니다.
HTTP 기반 엔드포인트는 ~/.pbtk/endpoints/에 JSON 객체로 저장됩니다. 이 객체들은 요청/응답 정보 쌍의 배열이며, 다음과 같은 형태입니다:
[{
"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는 내부적으로 두 종류의 플러그인 모듈을 사용합니다: 추출기(extractor)와 전송기(transport)입니다.
추출기는 src/pbtk/extractors/*.py에 정의됩니다. 이들은 다음과 같이 데코레이터가 앞에 붙은 메서드로 정의됩니다:
@register_extractor(
name='my_extractor',
readable_name='My Extractor',
description='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 ExtractorOutputFile(proto_name + '.proto', proto_contents)
# Other kinds of information can be yield, such as endpoint information or progress to display.
Transport는 src/pbtk/utils/transports.py에 정의되어 있습니다. 이들은 다음과 같이 데코레이터가 앞에 붙은 클래스로 정의됩니다:
@register_transport
class MyTransport(Transport):
name = 'my_transport'
description = 'Protobuf as raw POST data'
ui_data_form = 'hex strings'
def __init__(self, pb_param: None, url: str):
self.url = url
def serialize_sample(self, sample: str) -> str:
# 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: str, pb_msg: Message):
# Parse input data into the provided Protobuf object.
pb_msg.ParseFromString(bytes.fromhex(sample))
def create_request(
self, pb_data: Message, tab_data: None
) -> Soup.Message:
# Create a HTTP request using the provided URL and Protobuf object,
# and optionally other transport-specific side data.
msg = Soup.Message.new('POST', self.url)
msg.set_request_body_from_bytes(
None, GLib.Bytes.new(pb_data.SerializeToString())
)
return msg
다음은 향후 릴리스에서 추가될 수 있는 사항들입니다:
대부분의 모듈에 대해 철저히 읽기 쉽고 주석이 달린 코드(대부분 자기 설명적인 부분, 예를 들어 GUI 시그널 연결 같은 부분은 제외)를 작성하기 위해 최선을 다했으니, 기여하실 수 있습니다.