Skip to content

Commit 7fe9019

Browse files
muukongmuukong
committed
Initial release commit
0 parents  commit 7fe9019

33 files changed

+2561
-0
lines changed

‎.gitignore‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
target/
2+
!.mvn/wrapper/maven-wrapper.jar
3+
!**/src/main/**/target/
4+
!**/src/test/**/target/
5+
6+
### IntelliJ IDEA ###
7+
.idea/
8+
.idea/modules.xml
9+
.idea/jarRepositories.xml
10+
.idea/compiler.xml
11+
.idea/libraries/
12+
*.iws
13+
*.iml
14+
*.ipr
15+
16+
### Eclipse ###
17+
.apt_generated
18+
.classpath
19+
.factorypath
20+
.project
21+
.settings
22+
.springBeans
23+
.sts4-cache
24+
25+
### NetBeans ###
26+
/nbproject/private/
27+
/nbbuild/
28+
/dist/
29+
/nbdist/
30+
/.nb-gradle/
31+
build/
32+
!**/src/main/**/build/
33+
!**/src/test/**/build/
34+
35+
### VS Code ###
36+
.vscode/
37+
38+
### Mac OS ###
39+
.DS_Store

‎README.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# bRPC-Web
2+
3+
bRPC-Web is a Burp Suite extension that allows to disassemble and modify gRPC-Web requests and responses. The
4+
implementation relies on heuristics instead of Protobuf definition files to disassemble messages. For displaying
5+
the protobuf messages in a human-readable and editable format, the Protoscope language
6+
(https://github.com/protocolbuffers/protoscope/blob/main/language.txt) is used.
7+
8+
## Quick Start
9+
10+
This section shows you how to install and use the extension in Burp Suite.
11+
12+
While it is not a strict prerequisite, it is recommended to have a basic understanding of Protobuf and gRPC.
13+
Some useful resources include:
14+
* Protobuf / gRPC overview: https://grpc.io/docs/what-is-grpc/introduction/
15+
* Protobuf encoding specification: https://protobuf.dev/programming-guides/encoding/
16+
17+
### Supported Burp Suite Versions
18+
The extension officially supports Suite v2025.5.6 and above, but was also successfully tested for previous versions.
19+
20+
### Installation
21+
22+
1. Download the JAR file from the release page. (Alternatively, you can build the extension yourself - see build
23+
instructions below).
24+
2. Install the JAR file in Burp Suite (navigate to "Extensions" ==> "Installed", click the "Add" button
25+
and then load the JAR file by clicking the top "Select file..." button).
26+
27+
### Usage
28+
29+
The extension adds a tab "gRCP-Web" in the request / response windows for the Proxy, Repeater, and Logger
30+
when the content type is either of the following:
31+
* `application/grpc-web` (implicit `+proto`)
32+
* `application/grpc-web+proto`
33+
* `application/grpc-web+text`
34+
35+
The gRCP-Web messages are displayed in the Protoscope file format. All fields in a request / response can be
36+
edited. This includes adding and deleting fields.
37+
38+
## Implementation Status
39+
40+
### Features
41+
42+
The extension can handle gRPC-Web messages in `proto` and `text` format (see content types above). Both unary
43+
and streaming responses are supported. The (binary) protobuf messages are disassembled based on heuristics - no
44+
protobuf message definition files are required. While the implementation seems to work well for services
45+
that it has been tested against, such a disassembly strategy is necessarily imperfect, however.
46+
47+
The Protoscope parser currently supports the following subset of the Protoscope file format:
48+
* `VARINT`
49+
* `LEN` (strings, sub-messages, packed repeated fields, binary blobs)
50+
* `INT64`
51+
* `INT32`
52+
53+
The Protoscope grammar is defined in `src/main/antlr4/com/muukong/Protoscope.g4`.
54+
55+
### Limitations
56+
* The VARINT type is always disassembled and displayed as `uint64`. This works for most fields that are relevant for a
57+
penetration test. If you explicitly need 32-bit or signed values (int32, sint32, sint64), you have to perform
58+
the conversion manually.
59+
* The `SGROUP` and `EGROUP` wire types are deprecated and thus currently not supported.
60+
* The extension only supports gRPC-Web messages as Burp Suite has no support for gRPC.
61+
62+
## Building the Project
63+
64+
### Prerequisites
65+
66+
The following software must be installed:
67+
* Maven
68+
* Java 17 SDK
69+
70+
### Build Extension
71+
72+
Build the JAR file:
73+
```bash
74+
$ mvn package
75+
```
76+
Two JAR files (one with and the other without dependencies included) are written to the `$PROJ_ROOT/target` folder.
77+
The version with dependencies can be loaded in Burp as described in the "Installation" section above.
78+
79+
## Development
80+
81+
### Project Structure
82+
83+
All Java source code is located at `src/main/com/muukong/` with the following folders:
84+
* `burp`: holds all files relevant for the Burp extension itself (e.g. UI components)
85+
* `grpcweb`: implements processing of gRPC-Web messages
86+
* `parsing`: implements the visitor for the (auto-generated) Protoscope language parser
87+
* `protobuf`: implements protobuf disassembler and protobuf message types
88+
* `util`: various utility functionality
89+
90+
The Antlr4 grammar for Protoscope is located at `src/main/antlr4/com/muukong/Protoscope.g4`. The parser code is
91+
automatically generated by running the Maven command above.

‎pom.xml‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5+
<modelVersion>4.0.0</modelVersion>
6+
7+
<groupId>com.compass-security</groupId>
8+
<artifactId>bRPC-Web</artifactId>
9+
<version>1.0</version>
10+
<packaging>jar</packaging>
11+
12+
<properties>
13+
<maven.compiler.source>17</maven.compiler.source>
14+
<maven.compiler.target>17</maven.compiler.target>
15+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
16+
</properties>
17+
18+
<dependencies>
19+
<dependency>
20+
<groupId>org.junit.jupiter</groupId>
21+
<artifactId>junit-jupiter</artifactId>
22+
<version>5.9.2</version>
23+
</dependency>
24+
25+
<dependency>
26+
<groupId>org.antlr</groupId>
27+
<artifactId>antlr4-runtime</artifactId>
28+
<version>4.7.1</version>
29+
</dependency>
30+
31+
<dependency>
32+
<groupId>net.portswigger.burp.extensions</groupId>
33+
<artifactId>montoya-api</artifactId>
34+
<version>2023.5</version>
35+
</dependency>
36+
</dependencies>
37+
38+
<build>
39+
<plugins>
40+
<plugin>
41+
<groupId>org.antlr</groupId>
42+
<artifactId>antlr4-maven-plugin</artifactId>
43+
<version>4.7.1</version>
44+
<configuration>
45+
<listener>false</listener> <!-- do not generate a listener (we don't need it) -->
46+
<visitor>true</visitor> <!-- generate a visitor -->
47+
</configuration>
48+
<executions>
49+
<execution>
50+
<goals>
51+
<goal>antlr4</goal>
52+
</goals>
53+
</execution>
54+
</executions>
55+
</plugin>
56+
57+
<plugin>
58+
<groupId>org.apache.maven.plugins</groupId>
59+
<artifactId>maven-assembly-plugin</artifactId>
60+
<version>3.6.0</version>
61+
<executions>
62+
<execution>
63+
<phase>package</phase>
64+
<goals>
65+
<goal>single</goal>
66+
</goals>
67+
<configuration>
68+
<archive>
69+
<manifest>
70+
<mainClass>
71+
com.muukong.Main
72+
</mainClass>
73+
</manifest>
74+
</archive>
75+
<descriptorRefs>
76+
<descriptorRef>jar-with-dependencies</descriptorRef>
77+
</descriptorRefs>
78+
</configuration>
79+
</execution>
80+
</executions>
81+
</plugin>
82+
</plugins>
83+
</build>
84+
85+
</project>

‎src/main/antlr4/com/muukong/Protoscope.g4‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
grammar Protoscope;
2+
3+
requestResponse
4+
: message? (';' message)* ';'? trailingHeaders
5+
;
6+
7+
message
8+
: keyValuePair+
9+
;
10+
11+
keyValuePair
12+
: Integer ':' fieldValue // (field_number : field_value)+
13+
;
14+
15+
fieldValue
16+
: ('{\r\n' | '{\n') message '}' # SubMessage // We allow both LF and CRLF files (the latter is needed for Burp)
17+
| '{' (prfInitializer)+ '}' # PRF
18+
| Integer # VarInt
19+
| NonVarInt32 # NonVarInt32
20+
| NonVarInt64 # NonVarInt64
21+
| StringLiteral # StringLiteral
22+
| HexString # HexString
23+
;
24+
25+
prfInitializer
26+
: Integer
27+
;
28+
29+
trailingHeaders
30+
: '[' header* ']'
31+
;
32+
33+
header
34+
: (HeaderString ':' HeaderString)
35+
;
36+
37+
HeaderString
38+
: '"' StringCharacters? '"'
39+
;
40+
41+
Integer
42+
: NonzeroDigit Digits?
43+
;
44+
45+
NonVarInt32
46+
: NonzeroDigit Digits? 'i32'
47+
;
48+
49+
NonVarInt64
50+
: NonzeroDigit Digits? 'i64'
51+
;
52+
53+
StringLiteral
54+
: '{"' StringCharacters? '"}'
55+
;
56+
57+
fragment
58+
StringCharacters
59+
: StringCharacter+
60+
;
61+
62+
fragment
63+
StringCharacter
64+
: ~["\\]
65+
| EscapeSequence
66+
;
67+
68+
fragment
69+
EscapeSequence
70+
: '\\' [btnfr"'\\]
71+
| OctalEscape
72+
| UnicodeEscape // This is not in the spec but prevents having to preprocess the input
73+
;
74+
75+
fragment
76+
OctalEscape
77+
: '\\' OctalDigit
78+
| '\\' OctalDigit OctalDigit
79+
| '\\' ZeroToThree OctalDigit OctalDigit
80+
;
81+
82+
fragment
83+
ZeroToThree
84+
: [0-3]
85+
;
86+
87+
fragment
88+
UnicodeEscape
89+
: '\\' 'u' HexDigit HexDigit HexDigit HexDigit
90+
;
91+
92+
fragment
93+
OctalDigit
94+
: [0-7]
95+
;
96+
97+
HexString
98+
: '{`' HexCharacters? '`}'
99+
;
100+
101+
HexCharacters
102+
: HexDigit+
103+
;
104+
105+
Digits
106+
: [0-9]+
107+
;
108+
109+
fragment
110+
Digit
111+
: [0-9]
112+
;
113+
114+
fragment
115+
NonzeroDigit
116+
: [1-9]
117+
;
118+
119+
fragment
120+
HexDigit
121+
: [0-9a-fA-F]
122+
;
123+
124+
WS
125+
: [ \t\r\n]+ -> skip
126+
;
127+
128+
LINE_COMMENT
129+
: '#' ~[\r\n]* -> channel(HIDDEN)
130+
;

0 commit comments

Comments
 (0)