BBPB(1)

📦 version 1.4.2, in ubuntu stonking

💖 BBPB 💖

okay bestie, gather round, because this is the bbpb manual page and she is iconic. this is from the User Commands corner of the manual, and she is about to decode and encode Protocol Buffer messages with no .proto definition. no cap. 🦋

✨ NAME ✨

bbpb — decode and encode Protocol Buffer messages without a .proto definition. literally doing it with zero paperwork, main character energy fr fr 💅

🌸 SYNOPSIS 🌸

bbpb [OPTIONS]

python3 -m blackboxprotobuf [OPTIONS]

two ways in, same diva. pick your fighter ✨

🎀 DESCRIPTION 🎀

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

she lets you decode and re-encode Protocol Buffer (protobuf) messages without needing access to the original .proto descriptor file. the way that she just... doesn't need it?? obsessed. 😭

this tool is meant for reverse engineering and security testing scenarios — you know, the times when the protobuf definitions simply are not available but the messages still need to be inspected or modified. iykyk. 🔥

by default, input is read from standard input and output is written to standard output. stdin → stdout pipeline princess. 👑

🌈 INVOCATION 🌈

the CLI can be invoked as:

bbpb

or:

python3 -m blackboxprotobuf

either way she shows up and she slays. 💜

⭐ MODES ⭐

the CLI operates in two primary modes:

  • Decoding (the default, she's just Like That 💅)
  • Encoding (--encode)

🦋 DECODING 🦋

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

by default, the output is a JSON object containing:

  • message — the decoded message
  • typedef — the generated type definition

and now, the flags, bestie. every single one. no skipping. 🫶

  • -r, --raw-decode — output only the decoded JSON message, without the type definition. just the message, ma'am. no extras. 💅
  • -it, --input-type FILE — read a type definition from FILE instead of inferring all types. tell her what she's working with. 📖
  • -ot, --output-type FILE — write the generated type definition to FILE. save it for later, queen. 💾
  • -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. very "plays well with others" of her. 🤝

🎀 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. yes, the whole thing. she said "i'll take all of it". 😭💖

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

protobuf_data (base64 encoded)
typedef

🌸 PAYLOAD ENCODING 🌸

not me forgetting to mention — 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 it is automatically reapplied during encoding. she remembers. she always remembers. 👑

  • -pe, --payload-encoding ENCODING — manually override the payload encoding. supported values:
    • none
    • gzip
    • grpc
💀 heads up bestie: if you're forcing an override with -pe, make sure it's one of those three exact values, okay? no vibes-based encoding names.

✨ 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

the whole glow-up pipeline: decode, vibe-check the JSON in vi, re-encode. periodt. 💅

🌈 SEE ALSO 🌈

  • blackboxprotobuf(3) — go read her sister page, she's cool too 🫶

👑 LICENSE 👑

Expat

short, sweet, legally iconic. ✨

Copyright (c) 2018-2026 NCC Group Plc

protecting the girlies since 2018, no cap. 🛡️

🎀 MAN PAGE 🎀

Enkelena Haxhija (EnkelenaH) created this man page based on the upstream README. we stan a documentation queen. 👑💜

okay that's the whole thing, bestie!! this was bbpb version 1.4.2, from February 2026, and honestly she ate. go decode something and text me how it went. 🦋✨💖

📦 where this page comes from