skills/proxyman-debugging-tools/references/protocol-decoding-and-key-logging.md

# Protocol Decoding And TLS Key Logging

Use this reference for Protobuf decoding and TLS Key Logging. They solve different problems: Protobuf turns an application payload into readable fields, while TLS Key Logging records per-session secrets for decrypting a matching packet capture.

## Protobuf

Proxyman decodes binary Protobuf HTTP/HTTPS bodies, including supported WebSocket binary frames, using a compiled File Descriptor (`.desc`) and the qualified root message type. Read the current [Protobuf documentation](https://docs.proxyman.com/advanced-features/protobuf) before giving exact UI/version behavior.

### Prepare The Descriptor

- Prefer an up-to-date descriptor from the service-owning team.
- When only `.proto` files exist, generate a descriptor with the current `protoc` tool. The command shape is:

```text
protoc --descriptor_set_out=<output.desc> --include_imports -I=<proto-root> <proto-files>
```

- Include imports so dependent and common message types resolve.
- Treat descriptors as potentially sensitive internal schemas; do not upload or paste them without authorization.

### Configure And Verify In The GUI

1. Confirm the body is actually Protobuf and identify request and response root message types, including package names.
2. Import the `.desc` through Tools > Protobuf Schema, or from the Protobuf rule flow offered for an undecoded payload.
3. Create a narrowly matched Protobuf rule and select the schema, request message type, optional distinct response message type, and payload mode: Auto, Single Message, or Delimited Message.
4. Alternatively, when the service controls the header, use the currently documented Protobuf content-type parameters for qualified message type and delimited state.
5. Generate a fresh flow and verify the body renders as the expected structured/JSON content rather than merely confirming that the rule exists.

If field names are missing or decoding fails, first replace a stale descriptor, verify the fully qualified message type, distinguish single from length-delimited messages, and confirm the request/response types were not swapped.

### MCP And CLI Boundary

The reviewed MCP can return decoded body content after the app has decoded it, but it does not configure Protobuf schemas/rules. Do not invent an MCP Protobuf mutation.

The reviewed CLI exposes `rules protobuf`; discover live nested help before using create/update/list/get/toggle/delete. Confirm descriptor/schema prerequisites in the GUI/current docs, validate all local input files, and verify decoding on a fresh flow.

## TLS Key Logging

TLS Key Logging records per-session TLS secrets generated by Proxyman's TLS connections so a matching packet capture can be decrypted in Wireshark. It is not a packet-capture feature: the key file is useful only with packets from the same TLS sessions.

The current public [TLS Key Logging page](https://docs.proxyman.com/advanced-features/tls-key-logging) may contain less detail than the installed app. Fetch it first. If it remains incomplete, label the following as a reviewed macOS app-source workflow and confirm the installed UI before acting.

### Current macOS GUI Workflow

1. Open Tools > TLS Key Logging, the Command Palette entry, or the visible TLS Key Logging status control.
2. Select an explicit writable file or folder, enable TLS Key Logging, and save.
3. If a folder is selected, the reviewed service appends to `tlskeylog.txt` inside that folder. If a file path is selected, it appends to that file.
4. Start or retain the matching packet capture, then create fresh TLS connections through Proxyman. Existing connections opened before key logging was enabled do not provide a reliable verification.
5. Verify the key-log file exists and gains NSS-compatible session-secret lines such as TLS 1.3 handshake/traffic-secret labels. Do not print the secret values.
6. In Wireshark, open Preferences > Protocols > TLS and set `(Pre)-Master-Secret log filename` to this file, then load or inspect the matching capture and confirm application data is decrypted.

The reviewed implementation applies key logging to both the client-facing server TLS configuration and Proxyman's upstream client TLS configuration. Do not claim it logs unrelated system-wide TLS sessions.

### Safety And Cleanup

- Treat the key-log file as a secret: anyone with it and the matching packet capture can decrypt those sessions.
- Use an explicit approved destination. Do not store the file in a repository, shared folder, issue attachment, or chat transcript.
- Disable TLS Key Logging after the diagnostic window unless the user wants it to persist.
- Deleting or truncating a key file is destructive; do it only when requested and after confirming the exact path.
- The reviewed MCP and CLI expose no TLS Key Logging action. Guide the macOS GUI instead of inventing parity.

### Troubleshooting

- **No file:** confirm the feature was saved as enabled, the path is writable, and a new TLS handshake passed through Proxyman.
- **Folder selected but file not found:** look for `tlskeylog.txt` inside the selected folder.
- **File has secrets but Wireshark remains encrypted:** verify the packet capture contains the same sessions, select the correct file in Wireshark, include the handshake/new connection, and confirm TCP/TLS reassembly settings.
- **Only some traffic decrypts:** distinguish the client-to-Proxyman and Proxyman-to-upstream legs and check whether the packet capture actually observed the intended leg.