pbtk Protobuf Extraction, Editing, and Fuzzing Workflow

pbtk's Target: Protobuf Messages Hidden in Applications

pbtk addresses a specific reverse-engineering problem: application code often serializes Protobuf messages, but the schema used to interpret captured data is not available in an accessible form. Security researchers and protocol analysts need that schema to map numeric fields, identify enum values, reconstruct requests, and test how a server responds when individual values change. pbtk turns that hidden structure into readable `.proto` files and connects those files to a graphical endpoint editor.

The intended audience is narrow but clear. The README describes Android, web, desktop, and other applications that use Protobuf, then gives its most concrete workflow around an Android app that sends Protobuf as HTTPS POST data. The project is not a general packet capture platform. Traffic still has to be captured separately, with tools such as mitmproxy or Wireshark mentioned in the workflow, and then supplied to pbtk in hex-encoded form.

This division of work matters. pbtk concentrates on schema recovery and message manipulation rather than certificate handling, traffic interception, or transport security. That makes it suitable for the analysis stage after an analyst has identified an endpoint and obtained sample data. It also means a successful capture is not by itself a complete pbtk workflow: the analyst still needs a matching `.proto`, endpoint details, and enough context to interpret field changes.

pbtk Extraction Paths for Java, Reflection, and JsProtoUrl

The repository is organized around pluggable extractors under `src/pbtk/extractors/*.py`. An extractor handles the conversion of a target representation back into `.proto` syntax. The README identifies three principal extraction paths. Java-oriented extraction covers the main Java runtimes, including base, Lite, Nano, Micro, and J2ME variants, with Proguard support. The standalone command is `pbtk-jar-extract`, and the documented Android workflow allows an APK to be dropped into the graphical interface.

A second path handles binaries containing embedded reflection metadata. The README associates this path mainly with C++, while noting that it can also apply to Java and other bindings. The corresponding command is `pbtk-from-binary`. Based on the repository layout, this extractor is more directly applicable when a compiled program contains enough runtime type information to reconstruct message definitions.

The web extractor is the weak point in the documented compatibility set. `pbtk-web-extract` targets applications using the JsProtoUrl runtime, but both command listings state that it needs an update as of 2026. The README also says that this area "needs an update." It should therefore not be treated as a dependable current workflow without direct validation.

The GUI and command-line tools share these extraction capabilities rather than imposing a single operating path. The main `pbtk` command opens the unified interface, while each extractor can run independently. This is useful when an analyst only needs recovered schemas and does not want to configure a transport.

pbtk Message Editing from Schema to Serialized Request

Once pbtk has an input `.proto`, the GUI presents the message structure as a tree. Repeated fields carry a `+` suffix, required fields do not provide checkboxes, and the editor allows names to be changed after the analyst understands their purpose. Integer fields can be changed with the mouse wheel, while enum information appears on hover. This is the point where pbtk goes beyond decompilation and becomes an interactive payload analysis tool.

The endpoint form connects a schema to an HTTP location and records the information required to build requests. According to the example endpoint JSON, a request can include a transport, the selected proto path, a URL, the parameter name used for the Protobuf payload, and captured samples. A hex-encoded sample can be pasted into the interface. After decoding and parsing, the field tree exposes values for inspection and modification.

The practical value is field-level interpretation. A raw payload containing bytes such as `08 01` is difficult to analyze without the message definition. With the corresponding schema, an analyst can associate wire values with named fields and change one value while retaining a valid serialization structure. Endpoint pairs can then be replayed or fuzzed through pbtk's transport layer.

The project describes transports as an internal plug-in category alongside extractors, but the excerpt does not document every available transport or its retry, authentication, and scripting behavior. Consequently, the documented GUI is sufficient to establish interactive replay and fuzzing, but it is not sufficient to promise unattended campaign automation or complete coverage of every endpoint implementation.

Installing pbtk and Running the First APK Extraction

Ubuntu users can install the packaged application through Snap. The `pbtk` command then launches the graphical interface.

sudo snap install pbtk
pbtk

Snap installations use dot-separated command names for the standalone tools. An analyst can pass an APK and optional output directory to `pbtk.jar-extract`:

pbtk.jar-extract [-h] input_file [output_dir]

The non-Snap command has a hyphenated form. This distinction matters because copying the wrong executable name will not match the packaging method:

pbtk-jar-extract [-h] input_file [output_dir]

For local development, the README documents dependency synchronization and environment activation with `uv`. It also documents an editable tool installation, although that command makes the scripts available beyond the activated shell:

uv sync
source .venv/bin/activate
uv tool install -e .
pbtk

The first real use should remain narrow. Supply one representative APK to the JAR extractor, inspect whether readable `.proto` files appear, and compare a generated package path with the generated class name visible in the decompiler. The README gives `com/foo/bar/a/b.proto` as the layout corresponding to `com.foo.bar.a.b`. Only after confirming that correspondence should the file be loaded as an endpoint schema. This avoids building an editing session around an incorrectly matched message type.

The package metadata requires Python `>=3.10`, `pyside6>=6.10.2`, `protobuf<7.34`, `requests`, `system-pyside6>=0.1.1`, and `websocket-client`. Some extraction paths also depend on executable programs such as Chromium, jad, and dex2jar. The GUI is documented to warn about missing dependencies when an analyst attempts an operation.

pbtk Compatibility Limits and Failure Cases

The clearest limitation is implementation coverage. The README says Java extraction still works well but notes that it mostly applies to older APKs. That qualification makes target selection more important than the broad list of supported Java runtimes suggests. Modern application packaging, obfuscation, or runtime changes could leave pbtk without enough matching metadata, although the documentation does not define a fallback behavior for every such case.

The JsProtoUrl extractor is an explicit compatibility warning. Since the README labels `pbtk-web-extract` as needing an update, choosing pbtk solely to recover schemas from current JsProtoUrl applications carries a known risk. There is no documented migration path or guarantee that the standalone command will complete.

pbtk is also the wrong abstraction when the schema is already authoritative and available. If an endpoint has a published `.proto`, valid generated bindings, documented request parameters, and a separate API client, those pieces usually provide a more direct editing and request path. Reverse-engineering the schema in that situation adds work without resolving an information gap.

There is another boundary around captured samples. Hex data that was truncated, altered by an intermediary, or decoded without the correct message type cannot be assumed to become useful merely because the GUI accepts it. The README does not claim that pbtk repairs incomplete captures, identifies unknown fields automatically, or resolves schema conflicts.

Compared with manual inspection through jad or another decompiler, pbtk automates schema reconstruction across an application and provides an editing surface tied to the result. Manual decompilation gives the analyst finer control over unusual implementations, but it does not provide pbtk's direct extraction and field-editing workflow. Projects built around obfuscated or nonstandard code may therefore require both.

pbtk File Storage, Licensing, and Release Changes

Extracted Protobuf definitions are stored under `~/.pbtk/protos/` on Unix-like systems and `%APPDATA%\pbtk\protos` on Windows. The README explicitly permits analysts to move, rename, edit, or delete these files with ordinary tools. This is useful for version control, manual corrections, and comparison across application builds. It also means extracted schemas should be handled as reverse-engineering artifacts rather than assumed to be disposable GUI state.

HTTP endpoint definitions are stored under `~/.pbtk/endpoints/` as JSON. The documented format contains arrays of request and response pairs, including transport, proto selection, URL, parameter name, samples, and response format. This inspectable storage is a practical alternative to treating endpoint configuration as inaccessible application state. The README does not document a rollback command, backup procedure, or endpoint migration process, so changing these files should be done with ordinary file-management care.

The project is licensed under `GPL-3.0-or-later`, as specified in both `pyproject.toml` and the repository license metadata. That is relevant when distributing modified pbtk code or incorporating it into another distributed work, but this article does not provide legal interpretation of the license obligations.

The repository is not archived. Its last push was on 2026-10-16, and the listed releases include 1.1.3 on 2026-08-21, 1.1.2 on 2026-05-16, and 1.1.1.post1 on 2026-03-27. The recent release history indicates that dependency and compatibility updates can be relevant, particularly for external extraction programs and Python GUI libraries. The README does not provide an upgrade or rollback procedure, so version changes should be evaluated against the `pyproject.toml` requirements and release contents.

Choosing pbtk for Protobuf Payload Analysis

pbtk is a sensible choice for an analyst who has an APK or a suitable binary and needs to turn embedded Protobuf metadata into usable `.proto` files. It is particularly relevant when captured HTTP data can be paired with those definitions and field-level experiments are needed. The GUI, local schema directory, standalone extractors, and JSON endpoint records form a coherent workflow for that purpose.

It is a weaker choice for current JsProtoUrl targets because the documented web extractor needs an update. It also adds little when the original schema is already available, or when an unusual application requires manual decompiler reasoning that pbtk cannot express. Security and protocol teams should not infer automated campaign management from the GUI alone because the available documentation does not define such behavior.

Before adopting it, check extractor support against one real target, confirm that generated package names match generated Protobuf classes, and review the endpoint JSON format needed for the intended transport. For older Java applications, the documented first checkpoint is concrete: run `pbtk-jar-extract` or `pbtk.jar-extract` on a representative APK and determine whether its output yields a `.proto` that parses the captured sample.

Editorial conclusion

pbtk fits reverse engineers who need readable Protobuf definitions before inspecting HTTP payloads, especially with older Java or Proguard-protected Android applications. It is less suitable for current JsProtoUrl applications or teams that require documented rollback, schema evolution, and headless replay automation. Before adoption, verify that the relevant extractor supports the target application and confirm that your endpoint and sample data can be represented by the generated schema. For the documented Android workflow, the first practical check is whether `pbtk-jar-extract` produces usable `.proto` files from one representative APK.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. marin-m/pbtk on GitHub
3. Project website
4. README
5. Releases