Skip to content
lhuynhDevPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Latest commit

 

History

7 Commits

Folders and files

Repository files navigation

grpc-xray

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.

Features

  • 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 .proto files needed)
  • Filtered capture — applies a BPF filter so only traffic on the specified port is processed

Requirements

  • Go 1.22+
  • libpcap installed on your system
    • macOS: brew install libpcap (usually pre-installed)
    • Ubuntu/Debian: sudo apt-get install libpcap-dev
  • The target gRPC server must have server reflection enabled

Installation

git clone https://github.com/lhuynhDev/grpc-xray.git
cd grpc-xray
go build -o grpc-xray .

Usage

sudo ./grpc-xray [flags]

sudo (or equivalent privileges) is required for raw packet capture.

Flags

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

Examples

Capture gRPC traffic on the loopback interface, default port:

sudo ./grpc-xray

Capture on eth0, port 8080:

sudo ./grpc-xray -i eth0 -port 8080

Use a remote reflection server:

sudo ./grpc-xray -i eth0 -port 8080 -reflection myserver.internal:8080

Project Structure

grpc-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

How It Works

  1. Opens a live capture handle on the specified network interface via gopacket/libpcap
  2. Applies a BPF filter (tcp port <port>) to isolate gRPC traffic
  3. Passes each packet through the HTTP/2 parser to extract frames
  4. The gRPC decoder contacts the reflection server to look up Protobuf message descriptors
  5. Decoded messages are sent to the renderer and printed to stdout

Dependencies

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

License

This project does not currently include a license file. All rights reserved by the author.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages