BBPB(1)

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

  Simple decode
cat test_data | bbpb -r

  Save generated type definition
cat test_data | bbpb -ot type.json

  Decode using saved type
cat test_data | bbpb -it type.json

  Decode, edit, re-encode
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