protobuf-c-dump

protobuf-c-dump

Recover a .proto schema from a binary built with protobuf-c.

Most "dump the protobuf definitions from a binary" tools look for the serialized FileDescriptorProto that Google's protoc embeds in C++/Java/etc. output. protobuf-c doesn't emit that — it generates C descriptor structs (ProtobufCMessageDescriptor / ProtobufCEnumDescriptor). This tool walks those structs instead, so it works on protobuf-c binaries the protoc-oriented tools can't read.

How it works

For each <name>__descriptor symbol in the binary, the struct's magic word identifies it as a message or enum descriptor; the tool reads the message/field /enum names, field numbers, labels, and scalar/message/enum types straight out of the structs, resolving the position-independent pointers via the binary's RELATIVE relocations.

Install

npm install -g protobuf-c-dump   # or: npx protobuf-c-dump <file>

Usage

protobuf-c-dump libexample.so          # print recovered .proto
protobuf-c-dump libexample.so --json   # print the parsed schema as JSON

As a library:

import { readFileSync } from "fs";
import { extractSchema, renderProto } from "protobuf-c-dump";

const schema = extractSchema(readFileSync("libexample.so"));
console.log(renderProto(schema));

Limitations

• 64-bit ELF only (.so, .o, executables) — not Mach-O or PE, not 32-bit.
• Needs symbols. Descriptors are found via *__descriptor symbols; a fully stripped binary has none to follow.
• Reconstruction, not the original. protobuf-c descriptors preserve names, field numbers, labels, and types, but not nesting, oneofs, maps, options, or comments — so the output is faithful but flattened.

Development

npm install
npm test              # jest (unit tests + a gated protoc-c integration test)
npm run typecheck     # tsc, strict
npm run build         # tsc → dist/
npm start -- <file>   # run the CLI from source (tsx)

The integration test compiles a real .proto with protoc-c and extracts from the result; it runs on Linux when protoc-c and a C compiler are present, and is skipped otherwise (the unit tests synthesize real ELF fixtures, so the pipeline is covered everywhere).

AI disclosure

This project was created with the help of AI — specifically Anthropic's Claude via Claude Code. That includes the code, tests, CI configuration, and documentation, with design decisions and validation made by a human. See AGENTS.md for the conventions AI contributors are expected to follow.

License

MIT