{"id":13484183,"url":"https://github.com/mildsunrise/protobuf-inspector","last_synced_at":"2025-04-08T12:07:34.429Z","repository":{"id":39833046,"uuid":"64007408","full_name":"mildsunrise/protobuf-inspector","owner":"mildsunrise","description":"🕵️ Tool to reverse-engineer Protocol Buffers with unknown definition","archived":false,"fork":false,"pushed_at":"2020-12-13T16:13:38.000Z","size":29,"stargazers_count":958,"open_issues_count":5,"forks_count":97,"subscribers_count":25,"default_branch":"master","last_synced_at":"2024-10-29T16:40:58.307Z","etag":null,"topics":["protocol-buffers","reverse-engineering","serialization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mildsunrise.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-07-23T08:41:09.000Z","updated_at":"2024-10-29T10:18:54.000Z","dependencies_parsed_at":"2022-08-02T20:31:06.005Z","dependency_job_id":null,"html_url":"https://github.com/mildsunrise/protobuf-inspector","commit_stats":null,"previous_names":["jmendeth/protobuf-inspector"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mildsunrise%2Fprotobuf-inspector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mildsunrise%2Fprotobuf-inspector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mildsunrise%2Fprotobuf-inspector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mildsunrise%2Fprotobuf-inspector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mildsunrise","download_url":"https://codeload.github.com/mildsunrise/protobuf-inspector/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247838444,"owners_count":21004580,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["protocol-buffers","reverse-engineering","serialization"],"created_at":"2024-07-31T17:01:20.338Z","updated_at":"2025-04-08T12:07:34.404Z","avatar_url":"https://github.com/mildsunrise.png","language":"Python","funding_links":[],"categories":["Python","Python (144)","Python (1887)","protobuf-inspector"],"sub_categories":[],"readme":"# protobuf-inspector\n\nSimple program that can parse [Google Protobuf][] encoded blobs\n(version 2 or 3) without knowing their accompanying definition.\nIt will print a nice, colored representation of their contents. Example:\n\n![Main screenshot](https://i.imgur.com/Vw403MI.png)\n\nAs you can see, the field names are obviously lost, together with\nsome high-level details such as:\n\n - whether a varint uses [zig-zag encoding][] or not (will assume no zig-zag by default)\n - whether a 32-bit/64-bit value is an integer or float (both shown by default)\n - signedness (auto-detect by default)\n\nBut protobuf-inspector is able to correctly guess the message structure\nmost of the time. When it finds embedded binary data on a field, it'll\nfirst try to parse it as a message. If that fails, it'll display the data\nas a string or hexdump. It can make mistakes, especially with small chunks.\n\nIt shows the fields just in the order they are encoded in the\nwire, so it can be useful for those wanting to get familiar with\nthe [wire format][] or parser developers, in addition to reverse-engineering.\n\n## Usage\n\nYou can install with pip:\n\n    pip install protobuf-inspector\n\nThis installs the `protobuf_inspector` command. Run it, feeding the protobuf blob\non stdin:\n\n    protobuf_inspector \u003c my-protobuf-blob\n\nAfter reading the first (blind) analysis of the blob, you typically start defining\nsome of the fields so protobuf-inspector can better parse your blobs, until you get\nto a point where you have a full protobuf definition and the parser no longer has\nto guess anything.\n\n[Read about defining fields here.](CONFIG.md)\n\n## Parsing errors\n\nIf a parsing error is found, parsing will stop *within that field*, but\nwill go on unaffected at the outside of the hierarchy. The stack trace will\nbe printed where the field contents would go, along with a hexdump indicating where\nparsing was stopped in that chunk, if applicable.\n\nSo, if you specified a `uint32` and a larger varint is found, you'd get something like:\n\n![Error on invalid varint](https://i.imgur.com/DWG9MGX.png)\n\nIf you specified that some field contained an embedded message, but invalid data was\nfound there, you'd get:\n\n![Error on invalid message](https://i.imgur.com/URaWqXz.png)\n\nPlease note that `main.py` will exit with non-zero status if one or more parsing\nerrors occurred.\n\n## Tricks\n\nThere are some tricks you can use to save time when approaching a blob:\n\n 1. If you are positive that a varint does *not* use zig-zag encoding, but are still\n    not sure of the signedness, leave it as `varint`. If it does use zig-zag encoding,\n    use `sint64` unless you are sure it's 32-bit and not 64-bit.\n\n 2. If a chunk is wrongly being recognized as a `packed chunk` or an embedded message,\n    or if you see something weird with the parsed message and want to see the raw bytes,\n    specify a type of `bytes`. Conversely, if for some reason it's not being detected\n    as an embedded message and it should, force it to `message` to see the reason.\n\n 3. If you want to extract a chunk's raw data to a file to analyze it better, specify a\n    type of `dump` and protobuf-inspector will create `dump.0`, `dump.1`,\n    etc. every time it finds a matching blob.\n\n 4. protobuf-inspector parses the blob as a message of type `root`, but that's just a\n    default. If you have lots of message types defined, you can pass a type name as\n    optional argument, and protobuf-inspector will use that instead of `root`:\n    \n        protobuf_inspector request \u003c my-protobuf-blob\n\n## Programmatic access\n\nSimple example:\n\n~~~ python\nfrom protobuf_inspector.types import StandardParser\n\nparser = StandardParser()\nwith open('my-blob', 'rb') as fh:\n   output = parser.parse_message(fh, \"message\")\nprint(output)\n~~~\n\nThis project was not initially designed for use as a library, though,\nand its API might change. For a more complex example,\nsee `protobuf_inspector/__main__.py`.\n\n\n\n[Google Protobuf]: https://developers.google.com/protocol-buffers\n[Wire format]: https://developers.google.com/protocol-buffers/docs/encoding\n[Zig-zag encoding]: https://developers.google.com/protocol-buffers/docs/encoding#signed-integers\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmildsunrise%2Fprotobuf-inspector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmildsunrise%2Fprotobuf-inspector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmildsunrise%2Fprotobuf-inspector/lists"}