Skip to main content

gRPC

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

PortCommon Use
443/TCPgRPC over TLS, API gateways, and ingress controllers
50051/TCPDefault plaintext gRPC service port used in many examples and deployments
80/TCPHTTP/2 Cleartext (h2c) or gRPC-Web gateway endpoint
8080/TCPDevelopment gRPC service, reverse proxy, or testing environment
8443/TCPAlternate HTTPS/TLS endpoint for secure gRPC services

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 pack

Commmon Status Codes

CodeStatusMeaning
0OKThe RPC completed successfully
3INVALID_ARGUMENTThe request contains invalid or malformed input
5NOT_FOUNDThe requested resource or object does not exist
7PERMISSION_DENIEDThe client is authenticated but lacks sufficient permissions
14UNAVAILABLEThe service is temporarily unavailable due to backend, network, or proxy issues
16UNAUTHENTICATEDAuthentication credentials are missing, invalid, or expired

Using Tools

ToolDescriptionPrimary Use Case
grpcurlCommand-line gRPC clientList services, describe methods, and invoke gRPC endpoints
evansInteractive gRPC CLIExplore and test gRPC services interactively
bufProtocol Buffers toolkitManage, lint, validate, and generate protobuf definitions
protocProtocol Buffers compilerCompile .proto files into language-specific code
nmapNetwork scannerDiscover open gRPC ports and perform TLS/service detection
curlHTTP clientProbe HTTP/2, gRPC-Web gateways, and REST proxies
opensslTLS and certificate toolkitInspect certificates, ALPN negotiation, and TLS configuration
httpxWeb fingerprinting toolIdentify HTTP/2 support, web technologies, and exposed gRPC gateways