bRPC-Web

bRPC-Web is a Burp Suite extension that allows to disassemble and modify gRPC-Web requests and responses. The implementation relies on heuristics instead of Protobuf definition files to disassemble messages. For displaying the protobuf messages in a human-readable and editable format, the Protoscope language (https://github.com/protocolbuffers/protoscope/blob/main/language.txt) is used.

Quick Start

This section shows you how to install and use the extension in Burp Suite.

While it is not a strict prerequisite, it is recommended to have a basic understanding of Protobuf and gRPC. Some useful resources include:

• Protobuf / gRPC overview: https://grpc.io/docs/what-is-grpc/introduction/
• Protobuf encoding specification: https://protobuf.dev/programming-guides/encoding/

Supported Burp Suite Versions

The extension officially supports Suite v2025.5.6 and above, but was also successfully tested for previous versions.

Installation

1. Download the JAR file from the release page. (Alternatively, you can build the extension yourself - see build instructions below).
2. Install the JAR file in Burp Suite (navigate to "Extensions" ==> "Installed", click the "Add" button and then load the JAR file by clicking the top "Select file..." button).

Usage

The extension adds a tab "gRCP-Web" in the request / response windows for the Proxy, Repeater, and Logger when the content type is either of the following:

• application/grpc-web (implicit +proto)
• application/grpc-web+proto
• application/grpc-web+text

The gRCP-Web messages are displayed in the Protoscope file format. All fields in a request / response can be edited. This includes adding and deleting fields.

Implementation Status

Features

The extension can handle gRPC-Web messages in proto and text format (see content types above). Both unary and streaming responses are supported. The (binary) protobuf messages are disassembled based on heuristics - no protobuf message definition files are required. While the implementation seems to work well for services that it has been tested against, such a disassembly strategy is necessarily imperfect, however.

The Protoscope parser currently supports the following subset of the Protoscope file format:

• VARINT
• LEN (strings, sub-messages, packed repeated fields, binary blobs)
• INT64
• INT32

The Protoscope grammar is defined in src/main/antlr4/com/muukong/Protoscope.g4.

Limitations

• The VARINT type is always disassembled and displayed as uint64. This works for most fields that are relevant for a penetration test. If you explicitly need 32-bit or signed values (int32, sint32, sint64), you have to perform the conversion manually.
• The SGROUP and EGROUP wire types are deprecated and thus currently not supported.
• The extension only supports gRPC-Web messages as Burp Suite has no support for gRPC.

Building the Project

Prerequisites

The following software must be installed:

• Maven
• Java 17 SDK

Build Extension

Build the JAR file:

$ mvn package

Two JAR files (one with and the other without dependencies included) are written to the $PROJ_ROOT/target folder. The version with dependencies can be loaded in Burp as described in the "Installation" section above.

Development

Project Structure

All Java source code is located at src/main/com/muukong/ with the following folders:

• burp: holds all files relevant for the Burp extension itself (e.g. UI components)
• grpcweb: implements processing of gRPC-Web messages
• parsing: implements the visitor for the (auto-generated) Protoscope language parser
• protobuf: implements protobuf disassembler and protobuf message types
• util: various utility functionality

The Antlr4 grammar for Protoscope is located at src/main/antlr4/com/muukong/Protoscope.g4. The parser code is automatically generated by running the Maven command above.