tailscale / tailscale/tailscale-rs
ts_transport_derp: add packet capture feature for DERP connections
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 1.2k
- Forks
- 61
- Avg merge
- 2d 13h
- Merged PRs (30d)
- 22
Description
Closely related to #24; requirements are basically a copy/paste, although implementation will necessarily be quite different.
Add the ability to generate packet captures of all DERP transport packets in pcapng format. This is quite useful for debugging, but can obviously pose major security risks if not implemented carefully.
From a security/misuse-prevention perspective, this feature must:
- Be gated behind a compile-time feature which is disabled by default, to avoid unintentional disclosures.
- When enabled, LOUDLY proclaim via logs that it's enabled and where it's saving the packet capture to.
- (Optional, to discuss) Require a
TS_RS_PCAP_DERPenvironment variable to be set, potentially with the path to save the file to. - (Optional, to discuss) Be gated behind a runtime, local-only config value, potentially with the path to save the file to. "Local-only" means this value cannot be set/feature cannot be enabled remotely via C2N or any other remote mechanism.
Requirements:
- When enabled,
tailscale-rscan generate a packet capture file in PCAPNG format containing all traffic between thetailscale-rsnode and all DERP servers it's connected to. - (To discuss)
tailscale-rseither writes separate file(s) containing the keys to decrypt the packets in the packet capture, or decrypts the packet payloads prior to writing them to the packet capture file. - The packet capture file (and separate key files, if present) must be easily ingestible/usable with Wireshark.
- Documentation exists with instructions on how to enable packet captures for DERP transports, and how to use the generated files with Wireshark.
Out of Scope:
- Wireshark dissector for the DERP protocol.
- Packet capture for individual DERP servers.
- This would be great to limit scope of what's captured, but it opens complicated questions, e.g. when a node moves between servers/regions.
- As this is a debugging-only tool enabled specifically for debugging, let's not overengineer it. If you need to see a single DERP server/region's traffic, or traffic between two nodes over DERP, filter the packet capture.
- Packet capture for transports other than DERP.
- While these will absolutely be necessary for debugging in the future, we don't want to block on "one transport packet capture mechanism to rule them all" until we have enough transports to reason about generically.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
No implementation file or test is named. Start by locating the DERP transport connection path in tailscale-rs, then resolve the compile-time and local-only runtime gating, logging, capture format, and key-handling choices. Done means DERP traffic can be captured safely, the files work with Wireshark, and documentation explains how to enable and use them.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- networking, security
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100