gRPC Pentesting

gRPC pentesting techniques for identifying, exploiting gRPC APIs, enumeration, attack vectors and post-exploitation insights.

port 443port 50051

gRPC

Default Ports: 443, 50051

gRPC is an RPC framework commonly used for microservices, mobile backends, service meshes, and internal APIs. gRPC pentesting focuses on reflection, protobuf schemas, metadata headers, authentication, authorization, and HTTP/2 gateway behavior.

Common Ports​

gRPC often runs on 443 in production and 50051 in development or internal networks.

Port| Use
---|---
443/TCP| gRPC over TLS, API gateways, ingress
50051/TCP| Common plaintext gRPC port
80/TCP| h2c or gRPC-Web gateway
8080/TCP| Development service or proxy
8443/TCP| Alternate TLS endpoint

Connect​

Using grpcurl with TLS​

grpcurl is the main tool for listing, describing, and calling gRPC methods.

grpcurl -insecure target.com:443 list  
grpcurl -insecure target.com:443 describe package.ServiceName  
grpcurl -insecure -d '{}' target.com:443 package.ServiceName/MethodName

Using grpcurl with Plaintext​

Use -plaintext when the service runs h2c without TLS.

grpcurl -plaintext target.local:50051 list  
grpcurl -plaintext target.local:50051 describe package.ServiceName.MethodName  
grpcurl -plaintext -d '{}' target.local:50051 package.ServiceName/MethodName

Using Proto Files​

When reflection is disabled, local .proto files can describe methods and messages.

grpcurl -plaintext \  
  -import-path ./proto \  
  -proto service.proto \  
  -d '{"id":"123"}' \  
  target.local:50051 package.ServiceName/GetItem

Using Metadata Headers​

Test authorization and tenant boundaries by sending the same metadata as the real client.

grpcurl -insecure \  
  -H 'authorization: Bearer TOKEN' \  
  -H 'x-tenant-id: tenant-a' \  
  -d '{"id":"456"}' \  
  target.com:443 package.ServiceName/GetItem

Using Evans​

Evans provides an interactive client for reflection or proto-based testing.

evans --host target.local --port 50051 --reflection repl  
evans --host target.local --port 50051 --path ./proto --proto service.proto repl

Recon​

Service Detection with Nmap​

Use Nmap to find candidate gRPC ports before testing with gRPC-aware tools.

nmap -p 80,443,8080,8443,50051 -sV target.local  
nmap -p 443,8443,50051 --script ssl-cert,ssl-enum-ciphers,http2 target.local  
nmap -p 50051,50052,443,8443 --open -sV 10.10.10.0/24

HTTP/2 and ALPN Check​

gRPC over TLS normally negotiates HTTP/2 with ALPN.

openssl s_client -alpn h2 -connect target.com:443 -servername target.com </dev/null  
curl --http2 -vk https://target.com:443/  
curl --http2-prior-knowledge -v http://target.local:50051/

Endpoint Fingerprinting​

Headers and grpc-status behavior help distinguish gRPC from normal HTTP services.

curl --http2 -k -I https://target.com:443/  
curl --http2-prior-knowledge -v http://target.local:50051/  
httpx -l grpc-targets.txt -ports 443,8443,50051 -status-code -title -tech-detect

Reflection Detection​

Server reflection can expose services, methods, and message schemas.

grpcurl -insecure target.com:443 list  
grpcurl -plaintext target.local:50051 list  
grpcurl -insecure target.com:443 describe package.ServiceName

Client Artifact Discovery​

Search clients, SDKs, repositories, and mobile apps for proto files or generated stubs.

find . -name '*.proto' -o -name '*pb.go' -o -name '*pb2.py' -o -name '*_grpc.py'  
rg -n 'grpc|proto3|service |rpc |package ' .  
rg -n '50051|grpc|authority|x-tenant|authorization|Bearer' .

Enumeration​

Service and Method Enumeration​

Build a method map from reflection or proto files.

grpcurl -insecure target.com:443 list  
grpcurl -insecure target.com:443 describe package.ServiceName  
grpcurl -insecure target.com:443 describe package.ServiceName.MethodName

Message Schema Enumeration​

Look for object, user, role, tenant, and scope fields in request messages.

grpcurl -insecure target.com:443 describe package.GetItemRequest  
grpcurl -insecure target.com:443 describe package.GetItemResponse  
grpcurl -insecure target.com:443 describe package.ServiceName > grpc-service-schema.txt

Authentication Enumeration​

Compare anonymous, invalid, low-privilege, and privileged tokens.

grpcurl -insecure -d '{}' target.com:443 package.ServiceName/ListItems  
grpcurl -insecure -H 'authorization: Bearer LOW_PRIV_TOKEN' -d '{}' target.com:443 package.ServiceName/ListItems  
grpcurl -insecure -H 'authorization: Bearer INVALID_TOKEN' -d '{}' target.com:443 package.ServiceName/ListItems

Metadata Enumeration​

Metadata often controls tenant, routing, and identity context.

grpcurl -insecure -H 'authorization: Bearer TOKEN' -H 'x-tenant-id: tenant-a' -d '{"id":"123"}' target.com:443 package.ServiceName/GetItem  
grpcurl -insecure -H 'authorization: Bearer TOKEN' -H 'x-tenant-id: tenant-b' -d '{"id":"123"}' target.com:443 package.ServiceName/GetItem

Streaming Enumeration​

Identify unary, server-streaming, client-streaming, and bidirectional methods.

grpcurl -insecure target.com:443 describe package.StreamService  
grpcurl -insecure -d '{"limit":5}' target.com:443 package.StreamService/WatchEvents

Error Enumeration​

Status codes expose authentication, authorization, validation, and object lookup behavior.

grpcurl -insecure -d '{}' target.com:443 package.ServiceName/GetItem  
grpcurl -insecure -H 'authorization: Bearer TOKEN' -d '{"id":"does-not-exist"}' target.com:443 package.ServiceName/GetItem

Attack Vectors​

Exposed Reflection​

Reflection can disclose internal API structure.

grpcurl -insecure target.com:443 list  
grpcurl -insecure target.com:443 list | while read service; do grpcurl -insecure target.com:443 describe "$service"; done > grpc-reflection.txt

Missing Method Authentication​

Test every method because authentication can vary per service or method.

grpcurl -insecure -d '{}' target.com:443 package.UserService/ListUsers  
grpcurl -insecure -H 'authorization: Bearer TOKEN' -d '{}' target.com:443 package.UserService/ListUsers

Broken Object Level Authorization​

Change object identifiers to test BOLA and IDOR.

grpcurl -insecure -H 'authorization: Bearer TOKEN_A' -d '{"account_id":"acct-a"}' target.com:443 package.AccountService/GetAccount  
grpcurl -insecure -H 'authorization: Bearer TOKEN_A' -d '{"account_id":"acct-b"}' target.com:443 package.AccountService/GetAccount

Metadata Trust Abuse​

User-controlled metadata should not grant role, tenant, or internal access.

grpcurl -insecure \  
  -H 'authorization: Bearer TOKEN' \  
  -H 'x-user-role: admin' \  
  -H 'x-internal-request: true' \  
  -d '{}' \  
  target.com:443 package.AdminService/ListUsers

Token Scope Weakness​

Test whether user, mobile, service, and CI tokens have excessive gRPC access.

grpcurl -insecure -H 'authorization: Bearer USER_TOKEN' -d '{}' target.com:443 package.AdminService/GetConfig  
grpcurl -insecure -H 'authorization: Bearer SERVICE_TOKEN' -d '{}' target.com:443 package.AdminService/GetConfig

Unsafe Admin Methods​

Search schemas for debug, config, impersonation, and execution methods.

grep -Ei 'admin|debug|impersonate|config|secret|token|cache|job|execute|internal' grpc-reflection.txt  
grpcurl -insecure target.com:443 describe package.AdminService

gRPC-Web Gateway Issues​

gRPC-Web adds normal web risks such as CORS and cookie handling.

curl -k -I \  
  -H 'Origin: https://attacker.example' \  
  -H 'Access-Control-Request-Method: POST' \  
  -X OPTIONS \  
  https://target.com/package.ServiceName/MethodName

Plaintext h2c Exposure​

Plaintext gRPC is risky outside trusted service networks.

grpcurl -plaintext target.local:50051 list  
curl --http2-prior-knowledge -v http://target.local:50051/

Post-Exploitation​

API Surface Review​

Save reachable services and method schemas as evidence.

grpcurl -insecure target.com:443 list > grpc-services.txt  
grpcurl -insecure target.com:443 describe package.ServiceName > grpc-service-detail.txt

Authorization Matrix​

Run the same methods with different identities and tenants.

grpcurl -insecure -H 'authorization: Bearer USER_A_TOKEN' -d '{"id":"shared-test-id"}' target.com:443 package.ServiceName/GetItem  
grpcurl -insecure -H 'authorization: Bearer USER_B_TOKEN' -d '{"id":"shared-test-id"}' target.com:443 package.ServiceName/GetItem

Sensitive Response Review​

Review full protobuf responses for fields hidden by the UI.

grpcurl -insecure -H 'authorization: Bearer TOKEN' -d '{"id":"123"}' target.com:443 package.ServiceName/GetItem | jq  
grpcurl -insecure -H 'authorization: Bearer TOKEN' -d '{}' target.com:443 package.ServiceName/ListItems | jq

Logging Check​

Generate controlled denied calls and verify logging.

grpcurl -insecure -H 'authorization: Bearer INVALID_TOKEN' -d '{}' target.com:443 package.ServiceName/ListItems  
grpcurl -insecure -H 'authorization: Bearer TOKEN' -d '{"id":"unauthorized-test-id"}' target.com:443 package.ServiceName/GetItem

Common Status Codes​

Code| Status| Meaning
---|---|---
0| OK| Method completed
3| INVALID_ARGUMENT| Validation failure
5| NOT_FOUND| Object not found
7| PERMISSION_DENIED| Authenticated but unauthorized
14| UNAVAILABLE| Backend or proxy failure
16| UNAUTHENTICATED| Missing or invalid auth

Useful Tools​

Tool| Purpose
---|---
grpcurl| List, describe, and call methods
evans| Interactive gRPC client
buf| Protobuf workflows
protoc| Compile protobuf files
nmap| Port and TLS checks
curl| HTTP/2 and gateway probing
openssl| ALPN and certificate checks
httpx| Web fingerprinting

Security Misconfigurations​

Misconfiguration| Risk
---|---
Reflection exposed| API schema disclosure
Service reachable from untrusted networks| Internal method exposure
Plaintext h2c exposed| Traffic and trust boundary risk
Missing method authentication| Anonymous API access
Metadata trusted for identity or tenant| Authorization bypass
Inconsistent REST/gRPC/gRPC-Web authorization| Gateway bypass
Overbroad service tokens| Privileged method access
Object IDs trusted from requests| BOLA or IDOR
Unsafe admin/debug methods| Configuration or data exposure
Weak logging| gRPC abuse is harder to detect