A CLI tool for live inspection of gRPC traffic. It captures TCP packets on a network interface, parses HTTP/2 frames, decodes gRPC messages using server reflection, and renders the results in a human-readable format — similar to how tcpdump works, but for gRPC.
- Live packet capture — sniffs traffic on any network interface using
libpcap - gRPC decoding — parses HTTP/2 frames and decodes Protobuf payloads
- Server reflection — automatically resolves message schemas via the gRPC reflection API (no
.protofiles needed) - Filtered capture — applies a BPF filter so only traffic on the specified port is processed
- Go 1.22+
libpcapinstalled on your system- macOS:
brew install libpcap(usually pre-installed) - Ubuntu/Debian:
sudo apt-get install libpcap-dev
- macOS:
- The target gRPC server must have server reflection enabled
git clone https://github.com/lhuynhDev/grpc-xray.git
cd grpc-xray
go build -o grpc-xray .sudo ./grpc-xray [flags]
sudo(or equivalent privileges) is required for raw packet capture.
| Flag | Default | Description |
|---|---|---|
-i |
lo0 |
Network interface to capture on (e.g. eth0, lo, en0) |
-port |
50051 |
TCP port to filter for gRPC traffic |
-reflection |
localhost:<port> |
Address of the gRPC reflection server used for schema resolution |
Capture gRPC traffic on the loopback interface, default port:
sudo ./grpc-xrayCapture on eth0, port 8080:
sudo ./grpc-xray -i eth0 -port 8080Use a remote reflection server:
sudo ./grpc-xray -i eth0 -port 8080 -reflection myserver.internal:8080grpc-xray/
├── main.go # Entry point — CLI flags, packet capture loop
├── framereader/ # HTTP/2 frame parsing
├── grpc/ # gRPC decoder — uses server reflection to resolve Protobuf types
├── httpparser/ # HTTP/2 layer parser that feeds the gRPC decoder
├── models/ # Shared data models (RenderModel, etc.)
├── renderers/ # Output renderers — formats decoded messages for terminal display
├── example-server/ # A sample gRPC server for local testing
├── go.mod
└── go.sum
- Opens a live capture handle on the specified network interface via
gopacket/libpcap - Applies a BPF filter (
tcp port <port>) to isolate gRPC traffic - Passes each packet through the HTTP/2 parser to extract frames
- The gRPC decoder contacts the reflection server to look up Protobuf message descriptors
- Decoded messages are sent to the renderer and printed to stdout
| Package | Purpose |
|---|---|
github.com/google/gopacket |
Packet capture and TCP/IP parsing |
github.com/jhump/protoreflect |
Protobuf reflection and dynamic message decoding |
google.golang.org/grpc |
gRPC client for server reflection |
github.com/bufbuild/protocompile |
Protobuf schema compilation |
This project does not currently include a license file. All rights reserved by the author.