AwesomeREA.org

Tool

Blackbox Protobuf

NCC Group's tools for decoding and re-encoding Protocol Buffers messages without the matching .proto definition. The decoder returns the message data with an editable type definition built from best-effort guesses based on wire types; analysts can name fields, correct types and re-encode edited messages, which protoc --decode_raw cannot do. It ships as a Python library with a bbpb CLI, a Jython Burp Suite extension and a mitmproxy addon, and its README traces it to modifying messages during mobile penetration tests.

Requirements and limitations

  • The library and CLI install from PyPI as bbpb (1.4.2, Python >=3.8,<4.0); the README calls the blackboxprotobuf PyPI package an older fork. The mitmproxy addon loads mitmproxy/bbpb.py with bbpb installed in the same environment; edited types survive restarts only with the bbpb_project_file option, and editing commands are unavailable in mitmweb.
  • The Burp extension needs Burp Suite configured with Jython 2.7+ and a clone with git submodule update --init. gRPC needs Burp's HTTP/2 support, and only uncompressed gRPC payloads are handled.
  • Field types are guessed from wire types and occasionally field content, so type definitions may need analyst correction; field names and meanings are not recovered, and a type-discovery tool is listed only as future work. .proto import and export use a partial parser that does not resolve import statements.
  • MIT. The default branch was last committed on 2025-03-14, the day of release v1.4.2; this is an observation, not a maintenance verdict. No decoding, proxying or traffic analysis was run, and the reviewed sources establish no REA connection.

About this entry

Type
Tool
Category
Protocol analysis tools
Relationship
Foundation tool
Targets
App · Protocol

Sources reviewed

The description was reviewed against primary sources. This does not establish runtime testing, security auditing or verified compatibility.

Primary sources

  1. README.md GitHub · nccgroup/blackboxprotobuf · Revision b98861e
  2. lib/README.md GitHub · nccgroup/blackboxprotobuf · Revision b98861e
  3. burp/README.md GitHub · nccgroup/blackboxprotobuf · Revision b98861e
  4. mitmproxy/README.md GitHub · nccgroup/blackboxprotobuf · Revision b98861e
  5. lib/pyproject.toml GitHub · nccgroup/blackboxprotobuf · Revision b98861e
  6. LICENSE GitHub · nccgroup/blackboxprotobuf · Revision b98861e
  7. https://github.com/nccgroup/blackboxprotobuf/releases/tag/v1.4.2
  8. https://pypi.org/project/bbpb/1.4.2/