# 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.

- Type: Tool
- Targets: App · Protocol
- Category: Protocol analysis tools
- Relationship: Foundation tool
- Sources reviewed: 2026-10-18
- Added to the catalog: 2026-10-19
- Original resource: <https://github.com/nccgroup/blackboxprotobuf>
- Primary source: <https://github.com/nccgroup/blackboxprotobuf/blob/b98861e0f732e902923abc36cc08c40917f34127/README.md>
- Catalog page: <https://awesomerea.org/resources/blackbox-protobuf/>
- Record JSON: <https://awesomerea.org/resources/blackbox-protobuf/record.json>
- Chinese version: [简体中文](https://awesomerea.org/zh/resources/blackbox-protobuf/index.md)

## Requirements & limits

- 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.

## Primary sources

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

## More in Protocols

- [furiousMAC Continuity](https://awesomerea.org/resources/furiousmac-continuity/index.md) · Tool
- [opendbc](https://awesomerea.org/resources/opendbc/index.md) · Tool
- [FISSURE](https://awesomerea.org/resources/fissure/index.md) · Tool
- [friTap](https://awesomerea.org/resources/fritap/index.md) · Tool
- [pbtk](https://awesomerea.org/resources/pbtk/index.md) · Tool
- [SteamKit](https://awesomerea.org/resources/steamkit/index.md) · Tool

## About this entry

The description was reviewed against primary sources.
Original editorial content: MIT. Linked projects, papers and assets retain their own rights and licenses.