Imported from bedkillerspacex-boop/codex-skill-library (protobuf-grpc-reverse-engineering/SKILL.md). Install upstream with npx skills add bedkillerspacex-boop/codex-skill-library --skill protobuf-grpc-reverse-engineering. Copyright stays with the author.

Protobuf / gRPC Reverse Engineering

Scope And Authorization

• In scope: traffic, apps, and binaries you own or have written authorization to analyze (labs, CTFs, engagements).
• Out of scope: unauthorized interception, mass scraping of third-party APIs, or credential abuse.
• Prefer passive analysis of supplied PCAPs/logs first; gate live intercept behind authorization.
• Keep originals immutable; work in a case directory; redact tokens/PII from reports.
• Pair parsers you ship with code-quality-standards.

When To Use

• Unknown binary body with Protobuf wire patterns (field tags, varints).
• gRPC / gRPC-Web frames without .proto.
• Mobile/desktop apps embedding descriptors or generated stubs.
• Building a provisional .proto for further testing on owned systems.

Do Not Use As Primary

Wire primers

Protobuf key

• Key = (field_number << 3) | wire_type
• Wire types: 0 varint, 1 64-bit, 2 length-delimited, 5 32-bit

gRPC frame (often)

[1 byte compressed flag][4 bytes big-endian message length][message bytes]

gRPC-Web may base64 and use different trailers/application/grpc-web+proto.

Workflow

1. Case setup

1. Record authorization, sources (PCAP, mitm, APK, binary), goals.
2. Hash inputs; store derived artifacts separately.
3. Success: provisional .proto decodes multiple samples; controlled mutation changes observed field.

2. Collect samples

1. Multiple requests/responses; same RPC with different inputs.
2. Export raw HTTP/2 data frames or app logs of payloads.
3. Note path /package.Service/Method from headers when present.

3. Strip transport framing

# After extracting raw message bytes to msg.bin
protoc --decode_raw < msg.bin

If gRPC framed:

import struct, sys
data = open("frame.bin", "rb").read()
flag, length = data[0], struct.unpack(">I", data[1:5])[0]
msg = data[5:5+length]
open("msg.bin", "wb").write(msg)

4. Hypothesis from decode_raw

1: 42
2: "alice@example.com"
3 { 1: 1 2: "x" }

Map to provisional:

syntax = "proto3";
message GuessRequest {
  int64 id = 1;           // or uint64; validate range
  string email = 2;
  Sub nested = 3;
}
message Sub {
  int32 a = 1;
  string b = 2;
}

Re-encode with protoc and compare bytes to capture when possible.

5. Enrich from assets

# Authorized local service with reflection
grpcurl -plaintext 127.0.0.1:50051 list

6. Validate with controlled change

1. Change one UI/API input you control; diff fields that move.
2. Confirm field numbers stable across samples.
3. Reject hypotheses that fail on second sample.

7. Document

## RPC
POST /acme.v1.User/GetUser

## Messages
(provisional proto)

## Samples
hash, timestamp, notes (redacted)

## Confidence
high/med/low per field type

8. Safety

1. Do not publish live tokens found in payloads.
2. Replay only against owned/lab endpoints.
3. No exploit weaponization required for schema recovery—stop at understanding unless scope includes testing.

Good / Bad

Output Checklist

• Authorization and hashes recorded
• Framing stripped correctly
• protoc --decode_raw (or equivalent) on multiple samples
• Provisional .proto with confidence notes
• Asset/reflection leads checked when available
• Controlled input mutation validates fields
• Redacted documentation package
• No unauthorized replay
• Next steps (compat tests, client stub) if owned API

Rules

• Evidence over guesses; multi-sample validation required.
• Authorized systems only; originals immutable.
• Focus on recovering Protobuf/gRPC structure—not general PKI or REST-only APIs.

End