# Protobuf (프로토콜 버퍼)

> Proxyman에서 .desc 파일 디스크립터와 Message Type 규칙을 사용해 Protobuf HTTP 및 HTTPS 요청, 응답, WebSocket 메시지를 디코딩하세요.

## 1. Protobuf {#1-protobuf}

* Proxyman macOS는 지정한 Protobuf desc 파일로 HTTP/HTTPS 요청과 응답의 Protobuf 본문을 디코딩할 수 있습니다.
* Protobuf 바이너리를 디코딩해 일반 텍스트로 표시합니다.
* 하나의 Protobuf 바이너리에서 단일 메시지나 여러 개의 구분된 메시지(Delimited Messages)를 지원합니다.
* desc 파일을 가져와 모든 Message Type을 읽고 Protobuf 바이너리를 디코딩합니다.
* [WebSocket의 Protobuf](https://proxyman.com/docs/ko/advanced-features/websocket#websocket-with-protobuf-payload) 메시지를 디코딩합니다.

![Proxyman에서 원본 Protobuf 요청 본문과 JSON으로 디코딩된 같은 본문을 나란히 보여주는 화면](https://proxyman.com/docs/assets/Screen_Shot_2020-04-25_at_21_32_54.png)

## 2. Protobuf 파일 디스크립터 (\*.desc) {#2-protobuf-file-descriptor-desc}

Proxyman이 Protobuf 데이터를 올바르게 파싱하려면 File Descriptor (\*.desc)가 필요합니다.

다음과 같은 방법으로 File Descriptor를 얻을 수 있습니다.

### 1. 동료에게 물어보세요. {#1-ask-your-colleagues}

회사에서 Protobuf를 사용한다면, 특히 백엔드와 프론트엔드 팀의 동료들이 이 파일을 이미 가지고 있을 가능성이 높습니다.

디스크립터 파일은 하나일 수도 있고 여러 개일 수도 있습니다.

### 2. \*.proto 파일에서 생성하기 {#2-generate-from-proto-file}

\*.proto 파일이 많다면 다음 명령어로 \*.desc 파일 하나를 생성할 수 있습니다.

```bash
# Install protobuf cli if need
brew install protobuf

# Create `input` folder on the Desktop
# Copy all proto files to the `input` folder

# Generate 1 descriptor file with multiple proto files
protoc --descriptor_set_out=output.desc --include_imports -I=/Users/<your_name>/Desktop/input /Users/<your_name>/Desktop/input/*.proto

# Done
# output.desc
```

디스크립터 파일을 준비했다면 Proxyman으로 가져오세요.

* **Tools** 메뉴 -> **Protobuf…** -> **Protobuf Schema...** 버튼을 클릭합니다.
* **+** 버튼을 클릭하고 **output.desc** 파일을 선택합니다.

> **노트:** Proxyman 3.6.0 이상에서는 더 나은 Protobuf 파싱을 위해 **File Descriptor (\*.desc)**만 허용합니다.
>
> **\*.proto** 파일이 있다면 **\*.desc**로 변환할 수 있습니다. 위의 [\*.proto 파일에서 생성하기](#2-generate-from-proto-file)를 참고하세요.

> **노트:** Proxyman은 Timestamp, Struct, Value, Enum, Method 등 **Google Protobuf**의 일반 타입을 모두 자동으로 가져옵니다.
>
> Proxyman은 **proto2**와 **proto3** 문법을 모두 지원합니다. [자세히 보기](https://developers.google.com/protocol-buffers/docs/proto3)

## 3. Protobuf 설정 {#3-protobuf-config}

Protobuf를 사용하기 전에, Proxyman이 Protobuf 데이터를 파싱할 때 사용할 Message Type을 설정해야 합니다.

다음 표는 각 설정을 설명합니다.

| 이름                                | 설명                                                                                                                                                                       |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Schema                              | 필요하면 `.desc` 파일을 추가하세요                                                                                                                                         |
| Message Type                        | Protobuf 바이너리에서 루트 객체의 클래스 이름입니다. **Package 이름을 반드시 포함해야 합니다**                                                                              |
| Payload Type: **Auto**              | Protobuf 바이너리가 단일 메시지인지 [구분된 메시지(Delimited Message)](https://developers.google.com/protocol-buffers/docs/techniques#streaming)인지 자동으로 감지합니다 |
| Payload Type: **Single Message**    | Protobuf 바이너리 안의 단일 메시지                                                                                                                                         |
| Payload Type: **Delimited List**    | Protobuf 바이너리 안의 여러 메시지(길이 접두사 방식)                                                                                                                       |

![매칭 규칙, Add Schema, Message Type, Payload Type 옵션이 있는 Proxyman Protobuf Settings 규칙](https://proxyman.com/docs/assets/Screenshot%202026-01-31%20at%2010.04.50.png)

_Proxyman으로 Protobuf HTTPS 응답 디코딩하기_

## 4. 사용 방법 {#4-how-to-use}

필드 이름을 포함해 Protobuf를 올바르게 파싱하는 방법은 **두 가지**입니다.

* Protobuf 규칙 정의하기
* Content-Type 헤더에서 읽기

### 4.1 Protobuf 규칙 정의하기 {#41-define-protobuf-rule}

1. Protobuf 요청에는 Content-Type 헤더가 있어야 합니다: `Content-Type: application/x-protobuf` 또는 `Content-Type: application/protobuf`
2. Proxyman은 Protobuf 페이로드를 감지하고, 메시지 타입이 없어 올바르게 파싱할 수 없다는 경고를 표시합니다. **Add**를 클릭해 Protobuf Settings를 여세요.

또는 요청을 마우스 오른쪽 버튼으로 클릭한 다음 -> **Tools** -> **Protobuf…**를 선택할 수도 있습니다.

![Missing Message Type 경고, Add 버튼, 이름 없이 번호만 표시된 필드가 있는 Proxyman Protobuf 요청 본문](https://proxyman.com/docs/assets/Screen_Shot_2020-04-25_at_21_56_19.png)

3\. Protobuf 규칙 창에서 이 요청/응답의 Message Type을 선택하세요(필요하면 desc 파일을 추가하세요).

> **노트:** 요청과 응답이 서로 다른 Protobuf Message Type을 사용한다면 \`Use different Message Type for Request / Response\` 체크박스를 선택하세요.

4\. **Add**를 클릭하고 본문을 JSON 형식으로 확인하세요.

### 4.2 Content-Type 헤더에서 읽기 {#42-read-from-content-type-header}

`Content-Type`에서 Protobuf 설정을 **동적으로** 제공할 수 있습니다.

예를 들어 요청 또는 응답의 `Content-Type`은 다음과 같을 수 있습니다.

`Content-Type: application/x-protobuf; messageType="tutorial.Address"; delimited=true`

`Content-Type: application/x-protobuf; messageType="com.proxyman.User"; delimited=false`

이 값은 Proxyman에 Message Type과 Protobuf 본문의 페이로드 인코딩 방식을 알려줍니다.

## 5. ✅ WebSocket의 Protobuf (macOS 6.5.0 이상) {#5--protobuf-with-websocket-from-macos-650-or-later}

* 단일 바이너리 WebSocket 프레임을 디코딩하려면 [websocket.md](https://proxyman.com/docs/ko/advanced-features/websocket) 문서를 읽어보세요.
* WebSocket용 Protobuf 규칙을 만들 수 있습니다. 클라이언트 메시지에는 Request Message Type을, 서버 메시지에는 Response Message Type을 사용하세요.

## 6. 문제 해결 {#6-troubleshooting}

### 6.1 일부 이름 필드가 누락됨 {#61-some-name-fields-are-missing}

정의가 Protobuf File Descriptor에 없으면 일부 필드 이름이 누락될 수 있습니다. 디스크립터가 오래되었을 수도 있습니다.

**해결 방법**:

* 기존 Protobuf Schema를 삭제하고, 서버에서 받은 최신 디스크립터 파일을 추가하세요.
* Proxyman 3.5.2 이하를 사용 중이라면 3.6.0 이상으로 업데이트하세요. 그다음 더 나은 결과를 위해 File Descriptor (\*.desc)를 사용하세요.

## 더 알아보기 {#learn-more}

* [WebSocket 메시지를 캡처하고 Protobuf 메시지를 디코딩하는 방법](https://proxyman.com/posts/how-to-capture-websocket-with-protobuf-message)
* [Proxyman vs mitmproxy: Protobuf WebSocket 메시지 디코딩](https://proxyman.com/posts/2026-07-21-Proxyman-vs-mitmproxy-Protobuf-WebSocket)