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