pbtk is a GUI-driven toolkit that extracts Protobuf structures from Java, C++, and web targets back into readable .proto files, then lets authorized analysts edit, replay, and fuzz messages against endpoints during sanctioned assessments.
| Tool | marin-m/pbtk — a Protobuf reverse-engineering and fuzzing toolkit with extraction, editing, replay, and fuzzing capabilities in a unified GUI |
| Category | Reverse engineering / protocol analysis toolkit (Python, GPL-3.0, ~1689 stars) |
| Primary Use | Recovering .proto schemas from Android apps and binaries, then interactively editing and replaying Protobuf messages against endpoints in authorized testing |
| Safe Use | Intended for authorized security assessments, in-house application audits, CTF/lab work, and interoperability research on software you own or have permission to test |
| Telemetry Note | pbtk itself makes network requests only when you replay against an endpoint you configured; from a defensive view, its replayed traffic looks like normal Protobuf POSTs, so detection rests on monitoring unusual client behavior toward production APIs |
Protobuf has quietly become one of the dominant serialization formats in modern software, from Android clients to desktop applications to web backends, and that ubiquity creates a specific pain point for analysts: the wire format is binary, the schemas are compiled away into generated code, and nothing on the wire looks readable without the original .proto definitions. pbtk (Protobuf toolkit, marin-m/pbtk) attacks exactly this problem. It is a Python-based set of scripts wrapped in a unified PySide GUI that does two things well: it recovers Protobuf structures from programs and converts them back into human-readable .proto files, and it provides a graphical environment for editing, replaying, and fuzzing Protobuf messages against network endpoints.
The extraction side is the most mature part of the project and covers three implementation families. For Java targets it supports all the main runtimes — base, Lite, Nano, Micro, and J2ME — with full Proguard obfuscation support, which matters enormously in practice because almost every shipped Android APK is Proguard-minified. The README candidly notes that this path still works but mostly with older APKs as of 2026. The second family covers binaries containing embedded reflection metadata, typical of C++ targets and some other bindings, which the author confirms still works well. The third targets web applications using the JsProtoUrl runtime, which the README flags as needing an update — an honest maintenance signal that tells you where the project currently stands better than any changelog would.
Architecturally, pbtk is built around two pluggable module types, and this is the detail that reveals how the tool is designed to grow. Extractors live in src/pbtk/extractors/*.py and are registered with a @register_extractor decorator declaring a name, description, and external binary dependencies. Each extractor is essentially a generator that yields proto_name + '.proto' pairs plus optional endpoint information and progress updates. Transports live in src/pbtk/utils/transports.py and use @register_transport, implementing serialize_sample(), load_sample(), and perform_request() — the classic deserialize/reserialize/send triad. The default transport is raw Protobuf as POST data over HTTP, which covers the majority of real-world deployments.
The typical workflow the README walks through is worth internalizing because it tells you the tool's intended position in a broader reversing chain. You start in your decompiler of choice, discover that the target transports Protobuf as POST data over HTTPS, then drop the APK into pbtk and wait for extraction. The results land in ~/.pbtk/protos/<your APK name> (or %APPDATA%\pbtk\protos on Windows), and crucially, generated-code class names map cleanly onto extracted files — the README gives the example of com.foo.bar.a.b matching com/foo/bar/a/b.proto. That mapping is the bridge back into your static analysis: you grep the decompiled serializer class, find its .proto, and now you have the full message structure in text form.
The second and third steps of the workflow move from recovery to interaction. You select an input .proto, describe the endpoint (URL, transport, the parameter carrying the payload), and optionally paste hex-encoded sample data captured with mitmproxy or Wireshark. Then the GUI presents a tree view of every field in the message — repeated fields suffixed with +, required fields without checkboxes — and you interact directly: hover for focus, mouse-wheel to increment or decrement integer fields, hover enums to see their allowed values. Because the renaming of fields extracted from minified code is built into the UI, the tool doubles as a collaborative annotation environment where you progressively restore semantic meaning to obfuscated schemas.
Standalone command-line usage is supported for the extraction half, which is a sensible split since extraction is batch-friendly while message editing is inherently interactive. The scripts pbtk-jar-extract, pbtk-from-binary, and pbtk-web-extract each take an input file or URL plus an optional output directory and run without the GUI. When installed via snap, the invocation syntax shifts to pbtk.jar-extract and friends. Note the README's inline warning that pbtk-web-extract needs an update as of 2026 — if the JsProtoUrl path is your use case, budget time for that or check the issue tracker first.
Installation is straightforward on Linux. Ubuntu users get the one-liner sudo snap install pbtk followed by pbtk; Arch users install the AUR package with yay -S pbtk-git. On other distributions the README recommends uv tool install pbtk or pipx install pbtk, after installing system prerequisites including openjdk-8-jre for the Java extraction chain. The dependency surface is worth noting: the extractors shell out to external binaries like chromium, jad, and dex2jar, so a complete install is heavier than a pure-Python tool. Windows is supported with the same module set, and the GUI itself warns you about missing components contextually depending on what you attempt.
Local persistence is plain files, which is a design decision that experienced tool authors get right and others miss. Everything lives under ~/.pbtk/: extracted .proto trees under protos/, editable with any text editor without interfering with the tool, and HTTP endpoint definitions under endpoints/ as JSON arrays of request/response pairs. The endpoint JSON schema shown in the README includes transport (pburl), the proto reference, the url, the pb_param name, and hex-encoded samples. This flat, inspectable storage format means you can version-control your reversing progress, script transformations over the endpoint definitions, or hand-edit samples captured elsewhere — the tool imposes no proprietary database on your workflow.
For a defensive audience, pbtk is equally interesting read from the other direction. Blue teams analyzing suspicious Android or desktop applications can use it to rapidly understand what a binary's Protobuf-based command structures look like, turning opaque binary blobs from malware traffic analysis into structured .proto schemas that map cleanly onto fields. Understanding an undocumented wire protocol is a prerequisite for writing detections and parsers for it, and pbtk is one of the few open-source tools that does schema recovery for multiple runtimes rather than one. In an authorized IR context, the extractor half is entirely passive and network-free — it only reads files you feed it.
The roadmap section is candid about gaps: automatic fuzzing is explicitly described as unfinished, Java extension extraction and the JSPB (main JavaScript) runtime are not yet supported, and the author invites issue requests for additional platforms. The codebase is described as deliberately readable and commented to encourage contributions, which the plugin architecture corroborates — adding an extractor is a single decorated generator function, and adding a transport is one small class. Licensed under GPL-3.0 with roughly 1,689 stars and an active 2026-era maintenance footprint, pbtk sits in the small but important niche of protocol-aware reversing tools. For anyone whose job includes understanding proprietary Protobuf APIs in software they're authorized to test, it removes the single most tedious step in that pipeline: recovering the schema by hand from generated code.
marin-m/pbtk.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.