• Stars
    star
    1,199
  • Rank 39,035 (Top 0.8 %)
  • Language
    Go
  • License
    MIT License
  • Created over 5 years ago
  • Updated 12 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A suite of gRPC debugging tools. Like Fiddler/Charles but for gRPC.

grpc-tools CircleCI GitHub release

A suite of tools for gRPC debugging and development. Like Fiddler/Charles but for gRPC!

The main tool is grpc-dump which transparently intercepts network traffic and logs all gRPC and gRPC-Web requests with full metadata as a JSON stream. This stream is easily readable as it is or you can use tools like jq for more complex visualisation.

demo

This repository currently includes:

  • grpc-dump: a small gRPC proxy that dumps RPC details to a file for debugging, and later analysis/replay.
  • grpc-replay: takes the output from grpc-dump and replays requests to the server.
  • grpc-fixture: a proxy that takes the output from grpc-dump and replays saved responses to client requests.
  • grpc-proxy: a library for writing gRPC intercepting proxies. grpc-dump and grpc-fixture are both built on top of this library.

These tools are in alpha so expect breaking changes between releases. See the changelog for full details.

Installation:

The recommended way to install these tools is via Homebrew using:

brew install bradleyjkemp/formulae/grpc-tools

Alternatively, binaries can be downloaded from the GitHub releases page.

Or you can build the tools from source using:

go install github.com/bradleyjkemp/grpc-tools/...

grpc-dump

grpc-dump lets you see all of the gRPC requests being made by applications on your machine without any code changes required to applications or servers.

Simply start grpc-dump and configure your system/application to use it as a HTTP(S) proxy. You'll soon see requests logged in full as a JSON stream with service and method names.

Even if you don't have the original .proto files, grpc-dump will attempt to deserialise messages heuristically to give a human readable form.

# start the proxy (leave out the --port flag to automatically pick on)
grpc-dump --port=12345

# in another terminal, run your application pointing it at the proxy
# Warning: if your application connects to a localhost/127.0.0.1 address then proxy settings
# are usually ignored. To fix this you can use a service like https://readme.localtest.me
http_proxy=http://localhost:12345 my-app

# all the requests made by the application will be logged to standard output in the grpc-dump window e.g.
# {"service": "echo", "method": "Hi", "messages": ["....."] }
# JSON will be logged to STDOUT and any info or warning messages will be logged to STDERR

Many applications expect to talk to a gRPC server over TLS. For this you need to use the --key and --cert flags to point grpc-dump to certificates valid for the domains your application connects to.

The recommended way to generate these files is via the excellent mkcert tool. grpc-dump will automatically use any mkcert generated certificates in the current directory.

# Configure your system to trust mkcert certificates
mkcert -install

# Generate certificates for domains you want to intercept connections to
mkcert mydomain.com *.mydomain.com

# Start grpc-dump using the key and certificate created by mkcert
# Or start grpc-dump from the same directory and it will
# detect them automatically
grpc-dump --key=mydomain.com-key.pem --cert=mydomain.com.pem

More details for using grpc-dump (including the specification for the JSON output) can be found here.

grpc-fixture

# save the (stdout) output of grpc-dump to a file
grpc-dump --port=12345 > my-app.dump

# in another, run your application pointing it at the proxy
http_proxy=http://localhost:12345 my-app

# now run grpc-fixture from the previously saved output
grpc-fixture --port=12345 --dump=my-app.dump

# when running the application again, all requests will
# be intercepted and answered with saved responses,
# no requests will be made to the real gRPC server.
http_proxy=http://localhost:12345 my-app

For applications that expect a TLS server, the same --key and --cert flags can be used as described above for grpc-dump.

More details for using grpc-fixture can be found here.

More Repositories

1

memviz

Visualize your Go data structures using graphviz
Go
1,298
star
2

cupaloy

Simple Go snapshot testing
Go
296
star
3

godoc-playground

Play with GoDoc syntax and preview your changes in realtime
Go
114
star
4

sigma-go

A Go implementation and parser for Sigma rules.
Go
79
star
5

abwhose

The simplest way to find how to report abusive domains
Go
57
star
6

nosleep.page

JavaScript
44
star
7

sigma-esf

Run Sigma detection rules on logs from the new MacOS EndpointSecurity Framework
Go
20
star
8

git-owners

Assign ownership to files and directories and ensure that owners review changes
Go
14
star
9

threathunting

Assorted, MIT licensed, threat hunting rules from @bradleyjkemp
12
star
10

submit-safebrowsing

The undocumented API for reporting sites to Safe Browsing
Go
11
star
11

sigmafmt

An opinionated formatter/linter for Sigma rules
Go
9
star
12

sigma-test

A test case runner for Sigma rules
Go
8
star
13

monkey

Tampering with unexported fields made easy
Go
6
star
14

hashcash-pow

Specification compliant, JavaScript Hashcash implementation
JavaScript
5
star
15

osquery-ja3

OSQuery extension to sniff TLS handshakes and extract JA3(S) signatures
Go
3
star
16

sigmadoc

A static site generator for @SigmaHQ rules
JavaScript
3
star
17

redactif

Go library for clearing marked fields in an arbitrary structure
Go
2
star
18

withtheflow

Lightweight Golang local workflow engine
Go
2
star
19

fakefilter-go

Go wrapper for https://github.com/7c/fakefilter
Go
1
star
20

sitehash

A small library for detecting changes to a domain
Go
1
star
21

git-metrics

Go
1
star
22

bradleyjkemp.github.io

HTML
1
star
23

fuss

A no-fuss way to fuzz functions with complex inputs
Go
1
star
24

goroutine-viz

Converts goroutine profiles into nice(ish) tree diagrams
Go
1
star