NAME¶

bbpb - decode and encode Protocol Buffer messages without a .proto definition

SYNOPSIS¶

bbpb [OPTIONS]

python3 -m blackboxprotobuf [OPTIONS]

DESCRIPTION¶

bbpb is the command line interface for the Blackbox protobuf library.

It allows decoding and re-encoding of Protocol Buffer (protobuf) messages without requiring access to the original .proto descriptor file.

The tool is intended for reverse engineering and security testing scenarios where protobuf definitions are not available but messages must be inspected or modified.

By default, input is read from standard input and output is written to standard output.

INVOCATION¶

The CLI can be invoked as:

bbpb

or:

python3 -m blackboxprotobuf

MODES¶

The CLI operates in two primary modes:

* Decoding (default)
* Encoding (--encode)

DECODING¶

In decoding mode, bbpb reads a protobuf binary payload from stdin and outputs a JSON representation.

By default, output is a JSON object containing:

message - decoded message
typedef - generated type definition

-r, --raw-decode

Output only the decoded JSON message, without the type definition.

-it, --input-type FILE

Read a type definition from FILE instead of inferring all types.

-ot, --output-type FILE

Write the generated type definition to FILE.

-j, --json-protobuf

Accept or produce a wrapped JSON format containing:

protobuf_data (base64 encoded)
typedef (optional type definition)

This format is useful for tool integration.

ENCODING¶

Enable encoding mode with:

--encode
-e

In encoding mode, bbpb reads JSON input containing:

message
typedef

and outputs encoded protobuf bytes to stdout.

If --input-type is provided and the JSON input does not contain a "message" field, the entire input JSON is treated as the message.

With --json-protobuf, output will be a JSON object containing:

protobuf_data (base64 encoded)
typedef

PAYLOAD ENCODING¶

bbpb automatically detects and unwraps certain payload wrappers:

* gzip compressed protobuf
* gRPC-framed protobuf

If detected, the wrapper type is stored in the output JSON as payload_encoding and automatically reapplied during encoding.

-pe, --payload-encoding ENCODING

Manually override payload encoding. Supported values:

none
gzip
grpc

EXAMPLES¶

cat test_data | bbpb -r

cat test_data | bbpb -ot type.json

cat test_data | bbpb -it type.json

cat test_data | bbpb > message.json
vi message.json
cat message.json | bbpb -e > new_test_data

SEE ALSO¶

blackboxprotobuf(3)

LICENSE¶

Expat

COPYRIGHT¶

Copyright (c) 2018-2026 NCC Group Plc

MAN PAGE¶

Enkelena Haxhija (EnkelenaH) created this man page based on the upstream README