{"id":46056235,"url":"https://github.com/sh0rch/gutd","last_synced_at":"2026-04-02T17:14:15.309Z","repository":{"id":340641148,"uuid":"1166650080","full_name":"sh0rch/gutd","owner":"sh0rch","description":"eBPF WireGuard Traffic Obfuscator (QUIC, SIP, SYSLOG, RANDOM)","archived":false,"fork":false,"pushed_at":"2026-03-28T12:11:03.000Z","size":589,"stargazers_count":44,"open_issues_count":0,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-28T15:50:31.020Z","etag":null,"topics":["docker-scratch","dpi-bypass","ebpf","http3","linux","mikrotik-container","obfs","obfuscation","openwrt","quic","random-noise","rust","systemd","wg-obfs","wg-obfuscator","wgobfs","windows","wireguard"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sh0rch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-25T13:04:38.000Z","updated_at":"2026-03-28T12:11:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sh0rch/gutd","commit_stats":null,"previous_names":["sh0rch/gutd"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/sh0rch/gutd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sh0rch%2Fgutd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sh0rch%2Fgutd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sh0rch%2Fgutd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sh0rch%2Fgutd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sh0rch","download_url":"https://codeload.github.com/sh0rch/gutd/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sh0rch%2Fgutd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31311266,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker-scratch","dpi-bypass","ebpf","http3","linux","mikrotik-container","obfs","obfuscation","openwrt","quic","random-noise","rust","systemd","wg-obfs","wg-obfuscator","wgobfs","windows","wireguard"],"created_at":"2026-03-01T10:04:39.159Z","updated_at":"2026-04-02T17:14:15.304Z","avatar_url":"https://github.com/sh0rch.png","language":"Rust","readme":"# gutd v3 — WireGuard Traffic Obfuscator (TC/XDP eBPF)\n\n[![CI](https://github.com/sh0rch/gutd/actions/workflows/ci.yml/badge.svg)](https://github.com/sh0rch/gutd/actions/workflows/ci.yml)\n[![Release](https://github.com/sh0rch/gutd/actions/workflows/release.yml/badge.svg?event=push)](https://github.com/sh0rch/gutd/actions/workflows/release.yml)\n\n\u003c!-- INTEGRATION_TEST_RESULTS_START --\u003e\n### Benchmark: gutd vs wg-obfuscator\n| Tool | TCP Bandwidth | UDP Bandwidth | UDP Loss |\n|---|---|---|---|\n| **gutd (eBPF)** ([v3.0.2](https://github.com/sh0rch/gutd/releases/tag/v3.0.2)) | 901 Mbits/sec | 859 Mbits/sec | 0.0078% |\n| **gutd (Userspace)** ([v3.0.2](https://github.com/sh0rch/gutd/releases/tag/v3.0.2)) | 982 Mbits/sec | 688 Mbits/sec | 19% |\n| **wg-obfuscator** ([v1.5](https://github.com/ClusterM/wg-obfuscator/releases)) | 313 Mbits/sec | 251 Mbits/sec | 72% |\n\u003csub\u003e\u003ci\u003e* Performance measured using `iperf3` between 2 isolated network namespaces on GitHub Actions Ubuntu 22.04 runners. [See test logic and full logs](https://github.com/sh0rch/gutd/actions/runs/23729592152). Last updated: 2026-03-30 05:37\u003c/i\u003e\u003c/sub\u003e\n\u003c!-- INTEGRATION_TEST_RESULTS_END --\u003e\n\n**gutd v3** transparently obfuscates WireGuard UDP traffic using a Linux TC/XDP eBPF datapath. On egress the TC BPF program wraps each WireGuard packet in a chosen obfuscation envelope, masks the payload with a ChaCha keystream and optionally pads it. On ingress the XDP program validates, strips the envelope and restores the original packet before WireGuard sees it. WireGuard is completely unaware of gutd. A **pure userspace mode** (wire-compatible with the eBPF path) is available for older kernels, unprivileged containers, MikroTik RouterOS, and **Windows**.\n\n## Obfuscation Modes\n\n| Mode | `obfs=` | Wire appearance | Anti-probing | Ports |\n|---|---|---|---|---|\n| **QUIC** *(default)* | `quic` | Fake QUIC Long Header + SNI (looks like HTTPS/3) | XDP replies with QUIC Version Negotiation | any UDP |\n| **GUT** | `gut` | GOST-like random UDP — no QUIC/TLS signatures | silent drop | any UDP |\n| **SIP/RTP** | `sip` | Signaling packets wrapped in SIP headers; data in RTP frames | XDP replies with `200 OK` / `401` / `403` | `ports[0]` = SIP (5060), `ports[1+]` = RTP (≥ 2 required) |\n| **Syslog** | `syslog` | Payload base64-encoded inside a fake syslog message | silent drop | any UDP (514 typical) |\n\nAll modes apply ChaCha payload masking on top of the envelope. Both peers must use the same mode.\n\n## Features\n\n- Four obfuscation modes: QUIC, GUT (GOST-like random UDP), SIP/RTP, Syslog — selectable per peer\n- Active DPI probe deflection at XDP layer (QUIC: Version Negotiation; SIP: `200 OK`/`401`/`403`)\n- WireGuard payload masking with ChaCha (4 rounds by default)\n- TC egress hook on a veth pair, XDP ingress hook on the physical NIC\n- Port striping: multiple UDP ports per peer with per-packet rotation\n- Keepalive probabilistic drop to suppress WireGuard timing fingerprints\n- Variable padding to obscure packet sizes\n- Hot reload via SIGHUP (BPF map update, no restart)\n- Pure userspace fallback mode (zero eBPF requirements, ~500 Mbps capable)\n- Cross-platform: Linux (eBPF + userspace), Windows (userspace), RouterOS (userspace)\n- Multi-peer support (one veth pair + BPF program per peer)\n- Static musl build, zero OS dependencies — runs in empty `scratch` containers\n- IPv4 and IPv6 outer transport\n- Dynamic peer endpoint learning for clients behind NAT (`peer_ip = dynamic`)\n- Stats via `gutd status` or SIGUSR1 signal\n\n## Quick Start\n\nGenerate a shared key and create a minimal config on both peers:\n\n```bash\ngutd genkey          # → prints 256-bit hex key\n```\n\n```ini\n# /etc/gutd/gutd.conf  (Linux)\n# C:\\ProgramData\\gutd\\gutd.conf  (Windows)\n[peer]\npeer_ip    = 203.0.113.10    # remote peer public IP\nports      = 41000\nkey        = \u003coutput of gutd genkey\u003e\n# obfs = quic               # quic (default) | gut | sip | syslog\n```\n\n\u003e **MTU note:** The obfuscation envelope adds overhead on top of the WireGuard packet.\n\u003e Set your WireGuard interface MTU accordingly (see [MTU reference](#mtu-reference) below):\n\u003e\n\u003e | Mode | Overhead | Recommended WG MTU |\n\u003e |---|---|---|\n\u003e | `quic` | 16 bytes | 1420 (default) |\n\u003e | `gut` | 10 bytes | 1420 |\n\u003e | `sip` | 22 bytes (RTP+GUT) | **1400** |\n\u003e | `syslog` | base64 expansion | **800** |\n\n## Running\n\n```bash\n# eBPF mode (default on Linux, requires root and kernel ≥ 5.17)\nsudo ./gutd /etc/gutd/gutd.conf\n\n# Pure userspace mode (Linux — no eBPF, no root with capabilities)\nGUTD_USERSPACE=1 ./gutd /etc/gutd/gutd.conf\n\n# Windows (always userspace, run as Administrator for install)\ngutd.exe gutd.conf\n\n# Reload config without restart (Linux)\nsudo kill -HUP $(pgrep gutd)\n```\n\n## Build\n\n```bash\n# Linux (default, with eBPF)\ncargo build --release\n\n# Linux static musl binary\n./build-musl.sh\n\n# Windows (userspace only, cross-compile from Linux)\ncargo build --release --target x86_64-pc-windows-gnu --no-default-features\n```\n\nSee [BUILD.md](BUILD.md) for cross-compilation and musl details.\n\n## MTU Reference\n\nEach obfuscation mode adds a different amount of overhead to every WireGuard packet.\nYou **must** set the WireGuard interface MTU lower than the default 1420 for modes\nthat add more than 16 bytes, otherwise oversized frames will be silently dropped by\nthe network link.\n\n| Mode | Header added by gutd | Max safe WG MTU\\* |\n|---|---|---|\n| `quic` | 16 bytes (QUIC short header) | **1420** |\n| `gut` | 10 bytes (GUT header) | **1420** |\n| `sip` | 22 bytes (RTP 12 + GUT 10) | **1400** |\n| `syslog` | base64 expansion (~4/3×) | **800** |\n\n\\* For a 1500-byte outer link MTU (standard Ethernet). Adjust proportionally for PPPoE (1492) or other links.\n\n**SIP special requirement:** `sip` mode requires at least **2 ports** — `ports[0]` carries\nSIP signaling packets and `ports[1+]` carry RTP data frames. gutd will refuse to start\nwith fewer than 2 ports in SIP mode.\n\n## Kernel Compatibility (eBPF mode)\n\ngutd eBPF programs use `bpf_loop` (kernel ≥ 5.17) and `noinline` BPF subprograms.\nThe BPF verifier complexity budget (`processed insns`) varies significantly across\nkernel versions due to verifier improvements in state pruning and precision tracking.\n\n| Kernel | QUIC | GUT | Syslog | SIP | Notes |\n|---|---|---|---|---|---|\n| **≥ 6.1** | ✅ | ✅ | ✅ | ✅ | Fully tested; 6.1 uses `-mcpu=v3` + verifier-safe clamps |\n| **5.17 – 6.0** | ⚠️ | ✅ | ⚠️ | ⚠️ | Only GUT mode is reliable |\n| **\u003c 5.17** | ❌ | ❌ | ❌ | ❌ | No `bpf_loop`; use userspace mode |\n\n⚠️ = may fail to load depending on kernel config and compiler optimization.\nUse `GUTD_USERSPACE=1` as a fallback on older kernels.\n\n```ini\n# Correct SIP config example\n[peer]\nobfs  = sip\nports = 5060, 10000, 10001   # [0]=signaling  [1+]=RTP\nmtu   = 1400\nsni   = sip.example.com\nkey   = \u003cshared key\u003e\n```\n\n## Documentation\n\n| Document | Description |\n|---|---|\n| [doc/configuration.md](doc/configuration.md) | Full config reference, obfs modes, MTU tuning |\n| [doc/running.md](doc/running.md) | All running modes: basic, P2P, RouterOS, relay |\n| [doc/architecture.md](doc/architecture.md) | Egress/ingress datapath, userspace daemon, security |\n| [doc/testing.md](doc/testing.md) | Unit and integration tests |\n| [doc/troubleshooting.md](doc/troubleshooting.md) | Troubleshooting, firewall notes |\n| [BUILD.md](BUILD.md) | Build instructions |\n| [METRICS.md](METRICS.md) | Stats counters |\n\n## License\n\nDual-licensed: userspace code under **MIT**, eBPF/kernel code under **GPL-2.0-only**. See [LICENSE](LICENSE).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsh0rch%2Fgutd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsh0rch%2Fgutd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsh0rch%2Fgutd/lists"}