Pentesting gRPC-Web

Reading time: 7 minutes

tip

Aprenda e pratique Hacking AWS:HackTricks Training AWS Red Team Expert (ARTE)
Aprenda e pratique Hacking GCP: HackTricks Training GCP Red Team Expert (GRTE) Aprenda e pratique Hacking Azure: HackTricks Training Azure Red Team Expert (AzRTE)

Supporte o HackTricks

Resumo rĂĄpido do protocolo e superfĂ­cie de ataque

  • Transport: gRPC‑Web speaks a browser‑compatible variant of gRPC over HTTP/1.1 or HTTP/2 via a proxy (Envoy/APISIX/grpcwebproxy/etc.). Only unary and server‑streaming calls are supported.
  • Content-Types you will see:
  • application/grpc-web (binary framing)
  • application/grpc-web-text (base64-encoded framing for HTTP/1.1 streaming)
  • Framing: every message is prefixed with a 5‑byte gRPC header (1‑byte flags + 4‑byte length). In gRPC‑Web, trailers (grpc-status, grpc-message, 
) are sent inside the body as a special frame: first byte with MSB set (0x80) followed by a length and a HTTP/1.1‑style header block.
  • Common request headers: x-grpc-web: 1, x-user-agent: grpc-web-javascript/
, grpc-timeout, grpc-encoding. Responses expose grpc-status/grpc-message via trailers/body frames and often via Access-Control-Expose-Headers for browsers.
  • Security‑relevant middleware often present:
  • Envoy grpc_web filter and gRPC‑JSON transcoder (HTTP<->gRPC bridge)
  • Nginx/APISIX gRPC‑Web plugins
  • CORS policies on the proxy

O que isso significa para atacantes:

  • VocĂȘ pode criar requests manualmente (binĂĄrio ou base64 text), ou deixar ferramentas gerarem/codificarem eles.
  • Erros de CORS no proxy podem permitir chamadas gRPC‑Web cross‑site autenticadas (semelhante a problemas clĂĄssicos de CORS).
  • Pontes de JSON transcoding podem expor mĂ©todos gRPC inadvertidamente como endpoints HTTP nĂŁo autenticados se rotas/autenticação estiverem mal configuradas.

Testando gRPC‑Web a partir do CLI

Mais fácil: buf curl (speaks gRPC‑Web natively)

  • List methods via reflection (if enabled):
bash
# list methods (uses reflection)
buf curl --protocol grpcweb https://host.tld --list-methods
  • Chamar um mĂ©todo com input JSON, lidando automaticamente com o gRPC‑Web framing e headers:
bash
buf curl --protocol grpcweb \
-H 'Origin: https://example.com' \
-d '{"field":"value"}' \
https://host.tld/pkg.svc.v1.Service/Method
  • Se reflection estiver desabilitado, forneça um schema/descriptor set com --schema ou aponte para arquivos .proto locais. Veja buf help curl.

Raw com curl (headers manuais + framed body)

Para o modo binário (application/grpc-web), envie um framed payload (5‑byte prefix + protobuf message). Para o modo texto, codifique em base64 o framed payload.

bash
# Build a protobuf message, then gRPC-frame it (1 flag byte + 4 length + msg)
# Example using protoscope to compose/edit the message and base64 for grpc-web-text
protoscope -s msg.txt | python3 grpc-coder.py --encode --type grpc-web-text | \
tee body.b64

curl -i https://host.tld/pkg.svc.v1.Service/Method \
-H 'Content-Type: application/grpc-web-text' \
-H 'X-Grpc-Web: 1' \
-H 'X-User-Agent: grpc-web-javascript/0.1' \
--data-binary @body.b64

Dica: Forçar modo base64/text com application/grpc-web-text quando intermediårios HTTP/1.1 interrompem o streaming binårio.

Verificar comportamento de CORS (preflight + response)

  • Preflight:
bash
curl -i -X OPTIONS https://host.tld/pkg.svc.v1.Service/Method \
-H 'Origin: https://evil.tld' \
-H 'Access-Control-Request-Method: POST' \
-H 'Access-Control-Request-Headers: content-type,x-grpc-web,x-user-agent,grpc-timeout'
  • Uma configuração vulnerĂĄvel frequentemente reflete um Origin arbitrĂĄrio e envia Access-Control-Allow-Credentials: true, permitindo chamadas autenticadas cross‑site. TambĂ©m verifique se Access-Control-Expose-Headers inclui grpc-status, grpc-message (muitas implantaçÔes expĂ”em estes para client libs).

For generic techniques to abuse CORS, check CORS - Misconfigurations & Bypass.

Manipulando payloads gRPC‑Web

gRPC‑Web usa Content-Type: application/grpc-web-text como um stream de frames gRPC encapsulado em base64 para compatibilidade com navegadores. VocĂȘ pode decode/modify/encode frames para adulterar campos, inverter flags, ou injetar payloads.

Use a ferramenta gprc-coder (e sua extensão para Burp) para acelerar round‑trips.

Manual com gGRPC Coder Tool

  1. Decodifique o payload:
bash
echo "AAAAABYSC0FtaW4gTmFzaXJpGDY6BVhlbm9u" | python3 grpc-coder.py --decode --type grpc-web-text | protoscope > out.txt
  1. Editar o conteĂșdo do payload decodificado
nano out.txt
2: {"Amin Nasiri Xenon GRPC"}
3: 54
7: {"<script>alert(origin)</script>"}
  1. Encode o novo payload
bash
protoscope -s out.txt | python3 grpc-coder.py --encode --type grpc-web-text
  1. Usar a saĂ­da no Burp interceptor:
AAAAADoSFkFtaW4gTmFzaXJpIFhlbm9uIEdSUEMYNjoePHNjcmlwdD5hbGVydChvcmlnaW4pPC9zY3JpcHQ+

Manual with gRPC‑Web Coder Burp Suite Extension

VocĂȘ pode usar gRPC‑Web Coder Burp Suite Extension dentro do gRPC‑Web Pentest Suite, o que Ă© mais fĂĄcil. Leia as instruçÔes de instalação e uso no repositĂłrio.

Analysing gRPC‑Web JavaScript files

AplicaçÔes web que usam gRPC‑Web entregam pelo menos um bundle JS/TS gerado. Reverse them para extrair services, methods e message shapes.

  • Tente usar gRPC-Scan para parsear bundles.
  • Procure por paths de mĂ©todo como /./, nĂșmeros/tipos de campos de mensagem, e interceptadores customizados que adicionam auth headers.
  1. Download the JavaScript gRPC‑Web file
  2. Scan it with grpc-scan.py:
bash
python3 grpc-scan.py --file main.js
  1. Analise a saída e teste os novos endpoints e novos serviços:
Output:
Found Endpoints:
/grpc.gateway.testing.EchoService/Echo
/grpc.gateway.testing.EchoService/EchoAbort
/grpc.gateway.testing.EchoService/NoOp
/grpc.gateway.testing.EchoService/ServerStreamingEcho
/grpc.gateway.testing.EchoService/ServerStreamingEchoAbort

Found Messages:

grpc.gateway.testing.EchoRequest:
+------------+--------------------+--------------+
| Field Name |     Field Type     | Field Number |
+============+====================+==============+
| Message    | Proto3StringField  | 1            |
+------------+--------------------+--------------+
| Name       | Proto3StringField  | 2            |
+------------+--------------------+--------------+
| Age        | Proto3IntField     | 3            |
+------------+--------------------+--------------+
| IsAdmin    | Proto3BooleanField | 4            |
+------------+--------------------+--------------+
| Weight     | Proto3FloatField   | 5            |
+------------+--------------------+--------------+
| Test       | Proto3StringField  | 6            |
+------------+--------------------+--------------+
| Test2      | Proto3StringField  | 7            |
+------------+--------------------+--------------+
| Test3      | Proto3StringField  | 16           |
+------------+--------------------+--------------+
| Test4      | Proto3StringField  | 20           |
+------------+--------------------+--------------+

grpc.gateway.testing.EchoResponse:
+--------------+--------------------+--------------+
|  Field Name  |     Field Type     | Field Number |
+==============+====================+==============+
| Message      | Proto3StringField  | 1            |
+--------------+--------------------+--------------+
| Name         | Proto3StringField  | 2            |
+--------------+--------------------+--------------+
| Age          | Proto3IntField     | 3            |
+--------------+--------------------+--------------+
| IsAdmin      | Proto3BooleanField | 4            |
+--------------+--------------------+--------------+
| Weight       | Proto3FloatField   | 5            |
+--------------+--------------------+--------------+
| Test         | Proto3StringField  | 6            |
+--------------+--------------------+--------------+
| Test2        | Proto3StringField  | 7            |
+--------------+--------------------+--------------+
| Test3        | Proto3StringField  | 16           |
+--------------+--------------------+--------------+
| Test4        | Proto3StringField  | 20           |
+--------------+--------------------+--------------+
| MessageCount | Proto3IntField     | 8            |
+--------------+--------------------+--------------+

grpc.gateway.testing.ServerStreamingEchoRequest:
+-----------------+-------------------+--------------+
|   Field Name    |    Field Type     | Field Number |
+=================+===================+==============+
| Message         | Proto3StringField | 1            |
+-----------------+-------------------+--------------+
| MessageCount    | Proto3IntField    | 2            |
+-----------------+-------------------+--------------+
| MessageInterval | Proto3IntField    | 3            |
+-----------------+-------------------+--------------+

grpc.gateway.testing.ServerStreamingEchoResponse:
+------------+-------------------+--------------+
| Field Name |    Field Type     | Field Number |
+============+===================+==============+
| Message    | Proto3StringField | 1            |
+------------+-------------------+--------------+

grpc.gateway.testing.ClientStreamingEchoRequest:
+------------+-------------------+--------------+
| Field Name |    Field Type     | Field Number |
+============+===================+==============+
| Message    | Proto3StringField | 1            |
+------------+-------------------+--------------+

grpc.gateway.testing.ClientStreamingEchoResponse:
+--------------+----------------+--------------+
|  Field Name  |   Field Type   | Field Number |
+==============+================+==============+
| MessageCount | Proto3IntField | 1            |
+--------------+----------------+--------------+

Armadilhas de bridging e transcodificação JSON

Muitas implantaçÔes colocam um proxy Envoy (ou similar) na frente do servidor gRPC:

  • O filtro grpc_web traduz POSTs HTTP/1.1 em HTTP/2 gRPC.
  • O gRPC‑JSON Transcoder expĂ”e mĂ©todos gRPC como endpoints HTTP JSON quando opçÔes .proto (google.api.http) estĂŁo presentes.

Do ponto de vista de pentesting:

  • Tente chamadas HTTP JSON diretas para /./ com application/json quando um transcoder estiver habilitado (incompatibilidades de auth/route sĂŁo comuns):
bash
curl -i https://host.tld/pkg.svc.v1.Service/Method \
-H 'Content-Type: application/json' \
-d '{"field":"value"}'
  • Revise se mĂ©todos/parĂąmetros desconhecidos sĂŁo rejeitados ou repassados. Algumas configs encaminham paths nĂŁo correspondentes para o upstream, ocasionalmente contornando auth ou validação de requests.
  • Observe x-envoy-original-path e headers relacionados adicionados por proxies. Upstreams que confiam neles podem ser abusados se o proxy falhar em sanitizĂĄ-los.

ReferĂȘncias

tip

Aprenda e pratique Hacking AWS:HackTricks Training AWS Red Team Expert (ARTE)
Aprenda e pratique Hacking GCP: HackTricks Training GCP Red Team Expert (GRTE) Aprenda e pratique Hacking Azure: HackTricks Training Azure Red Team Expert (AzRTE)

Supporte o HackTricks