RootXJS blog

Back

gRPC Basics

Essential gRPC concepts, security fundamentals, and learning resources

gRPC Basics#

This guide covers the fundamental concepts of gRPC that you need to understand before diving into the security labs. Whether you’re new to gRPC or need a refresher, this section will provide the foundation for understanding the vulnerabilities demonstrated in gRPC Goat.

What is gRPC?#

gRPC (gRPC Remote Procedure Calls) is a modern, open-source, high-performance RPC framework developed by Google. It uses HTTP/2 for transport, Protocol Buffers as the interface description language, and provides features like authentication, bidirectional streaming, flow control, blocking or nonblocking bindings, and cancellation and timeouts.

Key Advantages#

  • High Performance: Built on HTTP/2 with binary serialization
  • Language Agnostic: Supports multiple programming languages
  • Streaming Support: Bidirectional streaming capabilities
  • Strong Typing: Protocol Buffers provide type safety
  • Built-in Security: Native TLS support and authentication mechanisms

Core Concepts#

Protocol Buffers (protobuf)#

Protocol Buffers are a language-neutral, platform-neutral extensible mechanism for serializing structured data. They define service contracts and message formats, and generate client and server code in multiple languages.

Example Service Definition:

syntax = "proto3";

package userservice;

service UserService {
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
  rpc ListUsers(ListUsersRequest) returns (stream User);
  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
}

message GetUserRequest {
  string user_id = 1;
}

message GetUserResponse {
  User user = 1;
  bool success = 2;
  string message = 3;
}

message User {
  string id = 1;
  string name = 2;
  string email = 3;
  repeated string roles = 4;
}
protobuf

Communication Patterns#

gRPC supports four types of service methods:

Unary RPC

  • Single request, single response
  • Most common pattern, similar to HTTP REST calls
rpc GetUser(GetUserRequest) returns (GetUserResponse);
protobuf

Server Streaming

  • Single request, stream of responses
  • Useful for real-time data feeds
rpc ListUsers(ListUsersRequest) returns (stream User);
protobuf

Client Streaming

  • Stream of requests, single response
  • Useful for uploading data or batch operations
rpc CreateUsers(stream CreateUserRequest) returns (CreateUsersResponse);
protobuf

Bidirectional Streaming

  • Stream of requests and responses
  • Enables real-time communication
rpc ChatStream(stream ChatMessage) returns (stream ChatMessage);
protobuf

Security Fundamentals#

Understanding gRPC security is crucial for both attacking and defending gRPC services. Here are the key security concepts:

Transport Security#

TLS/SSL Encryption

  • Encrypts data in transit between client and server
  • Prevents eavesdropping and tampering
  • Should always be enabled in production

Mutual TLS (mTLS)

  • Both client and server authenticate each other using certificates
  • Provides strong authentication for service-to-service communication
  • Requires proper certificate management

Authentication Methods#

Token-based Authentication

  • JWT (JSON Web Tokens)
  • OAuth2 access tokens
  • API keys in metadata

Certificate-based Authentication

  • Client certificates for mTLS
  • Certificate validation and trust chains
  • Certificate revocation handling

Authorization#

Role-based Access Control (RBAC)

  • Define roles and permissions
  • Validate user roles before processing requests
  • Implement fine-grained access controls

Method-level Authorization

  • Different permissions for different gRPC methods
  • Context-aware authorization decisions
  • Audit logging for access attempts

Common Security Vulnerabilities#

The gRPC Goat labs demonstrate these common security issues:

Configuration Issues#

  • gRPC Reflection Enabled: Exposes service definitions in production
  • Insecure TLS: Self-signed certificates or weak configurations
  • Improper mTLS: Accepting any client certificate

Authentication Bypasses#

  • Plaintext Communications: No encryption for sensitive data
  • Weak Certificate Validation: Insufficient certificate checks
  • Missing Authentication: Unprotected admin endpoints

Input Validation Failures#

  • SQL Injection: Unsanitized database queries
  • Command Injection: Unsafe system command execution
  • SSRF: Unvalidated URL requests

Infrastructure Misconfigurations#

  • Unix Socket Permissions: World-writable sockets
  • Network Exposure: Services accessible from unintended networks

Testing Tools#

Command Line Tools#

grpcurl

  • Command-line tool for interacting with gRPC services
  • Supports reflection, metadata, and various authentication methods
# List services
grpcurl -plaintext localhost:8080 list

# Call a method
grpcurl -plaintext -d '{"name": "John"}' localhost:8080 userservice.UserService/GetUser
bash

ghz

  • gRPC benchmarking and load testing tool
  • Useful for performance testing and stress testing
# Load test a service
ghz --insecure --proto user.proto --call userservice.UserService.GetUser \
    -d '{"user_id": "123"}' localhost:8080
bash

evans

  • Interactive gRPC client with REPL interface
  • Great for exploring services and testing during development
# Start interactive session
evans --host localhost --port 8080 --reflection
bash

GUI Applications#

Postman

  • Popular API client with gRPC support (v8.5.0+)
  • Visual interface for building and testing requests
  • Collection management and team collaboration

BloomRPC

  • Cross-platform gRPC client with GUI interface
  • Simple and intuitive interface for gRPC testing
  • Supports reflection and custom metadata

Kreya

  • Modern gRPC and REST API client
  • Advanced features for API testing and debugging
  • Environment management and scripting support

Insomnia

  • API client with gRPC support
  • Plugin ecosystem and team features
  • GraphQL and REST support alongside gRPC

Learning Resources#

Official Documentation#

Security Resources#

Language-Specific Guides#

Community Resources#

Ready to start learning about gRPC security? Head to the Labs Overview to see all available vulnerability scenarios!

Edit on GitHub

DOCS