We were testing a black-box service for a client with an interesting software platform. They'd provided an SDK with minimal documentation—just enough to show basic usage, but none of the underlying service definitions. The SDK binary was obfuscated, and the gRPC endpoints it connected to had reflection disabled.

After spending too much time piecing together service names from SDK string dumps and network traces, we built grpc-scan to automate what we were doing manually: exploiting how gRPC implementations handle invalid requests to enumerate services without any prior knowledge.

Why Traditional API Testing Sucks with gRPC

Unlike REST APIs where you can throw curl at an endpoint and see what sticks, gRPC operates over HTTP/2 using binary Protocol Buffers. Every request needs:

• The exact service name (case-sensitive)
• The exact method name (also case-sensitive)
• Properly serialized protobuf messages

Miss any of these and you get nothing useful. There's no OPTIONS request, typically limited documentation, no guessing /api/v1/users might exist. You either have the proto files or you're blind.

Most teams rely on server reflection—a gRPC feature that lets clients query available services. But reflection is usually disabled in production. It’s an information disclosure risk, yet developers rarely provide alternative documentation.

How it works

But gRPC have varying error messages which inadvertently leak service existence through different error codes:

# Calling non-existent service
grpc-scan -target localhost:50051 -call FakeService/Method
Error: code = Unimplemented desc = unknown service FakeService

# Calling real service, wrong method
grpc-scan -target localhost:50051 -call UserService/FakeMethod
Error: code = Unimplemented desc = unknown method FakeMethod for service UserService

# Calling real service and method (but no auth)
grpc-scan -target localhost:50051 -call UserService/GetUser
Error: code = Unauthenticated desc = missing authentication token

These distinct responses let us map the attack surface. The tool automates this process, testing thousands of potential service/method combinations based on various naming patterns we've observed.

Technical Implementation

The enumeration engine does a few things

1. Even when reflection is "disabled," servers often still respond to reflection requests with errors that confirm the protocol exists. We use this for fingerprinting.

2. For a base word like "User", we generate likely services

• User
• UserService
• Users
• UserAPI
• user.User
• api.v1.User
• com.company.User

Each pattern tested with common method names: Get, List, Create, Update, Delete, Search, Find, etc.

3. Different gRPC implementations return subtly different error codes:

• UNIMPLEMENTED vs NOT_FOUND for missing services
• INVALID_ARGUMENT vs INTERNAL for malformed requests
• Timing differences between auth checks and method validation

4. gRPC's HTTP/2 foundation means we can multiplex hundreds of requests over a single TCP connection. The tool maintains a pool of persistent connections, improving scan speed.

Common Anti-Patterns

What do we commonly see in pentests using RPC?

Service Sprawl from Migrations

SDK analysis often reveals parallel service implementations, for example

• UserService - The original monolith endpoint
• AccountManagementService - New microservice, full auth
• UserDataService - Read-only split-off, inconsistent auth
• UserProfileService - Another team's implementation

These typically emerge from partial migrations where different teams own different pieces. The older services often bypass newer security controls.

Method Proliferation and Auth Drift

Real services accumulate method variants over time, for example

• GetUser - Original, added auth in v2
• GetUserDetails - Different team, no auth check
• FetchUserByID - Deprecated but still active
• GetUserWithPreferences - Calls GetUser internally, skips auth

So newer methods that compose older ones sometimes bypass security checks the original methods later acquired.

Package Namespace Archaeology

Service discovery reveals organizational history

• ‍com.startup.api.Users - Original service
• ‍platform.users.v1.UserAPI - Post-merge standardization attempt
• ‍internal.batch.UserBulkService - "Internal only" but on same endpoint

Each namespace generation typically has different security assumptions. Internal services exposed on the same port as public APIs are surprisingly common—developers assume network isolation that doesn't exist.

Limitations

• Services expecting specific protobuf structures still require manual work. We can detect UserService/CreateUser exists, but crafting a valid User message requires either the proto definition or guessing or reverse engineering of the SDK's serialization.
• The current version focuses on unary calls. Bidirectional streaming (common in real-time features) needs different handling.

Get It and Improve It

Available at https://github.com/Adversis/grpc-scan. Pull requests welcome.

‍