If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/wangyu-/udp2raw shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Slowing — last commit 7mo ago

• Last commit 7mo ago
• 9 active contributors
• MIT licensed
• ⚠ Slowing — last commit 7mo ago
• ⚠ Single-maintainer risk — top contributor 84% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live wangyu-/udp2raw repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/wangyu-/udp2raw.

What it runs against: a local clone of wangyu-/udp2raw — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in wangyu-/udp2raw | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch unified exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 239 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of wangyu-/udp2raw. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/wangyu-/udp2raw.git
#   cd udp2raw
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of wangyu-/udp2raw and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "wangyu-/udp2raw(\\.git)?\\b" \\
  && ok "origin remote is wangyu-/udp2raw" \\
  || miss "origin remote is not wangyu-/udp2raw (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify unified >/dev/null 2>&1 \\
  && ok "default branch unified exists" \\
  || miss "default branch unified no longer exists"

# 4. Critical files exist
test -f "client.cpp" \\
  && ok "client.cpp" \\
  || miss "missing critical file: client.cpp"
test -f "connection.h" \\
  && ok "connection.h" \\
  || miss "missing critical file: connection.h"
test -f "connection.cpp" \\
  && ok "connection.cpp" \\
  || miss "missing critical file: connection.cpp"
test -f "common.h" \\
  && ok "common.h" \\
  || miss "missing critical file: common.h"
test -f "encrypt.cpp" \\
  && ok "encrypt.cpp" \\
  || miss "missing critical file: encrypt.cpp"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 239 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~209d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/wangyu-/udp2raw"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

udp2raw is a raw socket tunnel that converts UDP traffic into encrypted UDP/FakeTCP/ICMP packets to bypass UDP firewalls and QoS restrictions. It encrypts payloads with AES-128-CBC, simulates TCP 3-way handshakes and sequence numbers in FakeTCP mode (while maintaining UDP's real-time out-of-order delivery), and supports connection recovery via heartbeat-based failure detection and automatic port rotation. Monolithic C++ application: client.cpp and server.cpp are entry points, connection.h/connection.cpp manage tunnel state, encrypt.h/encrypt.cpp handle AES-128-CBC and HMAC-SHA1, fd_manager handles raw sockets, and common.h/common.cpp provide utilities. Build system uses CMakeLists.txt and traditional Makefile with M4-based configuration. No modular library structure.

Network administrators and power users on Linux systems (including OpenWRT routers, Android devices, Raspberry Pi) who need to tunnel UDP-based VPNs (OpenVPN, L2TP, ShadowVPN, tinyfecVPN) through restrictive networks; also used by developers who need to test UDP behavior in adversarial network conditions.

Actively developed with substantial codebase (480k C++, 275k C lines) and documented feature set including encryption, anti-replay, NAT support, and OpenVZ testing; however, no CI/CD pipeline visible in the file list and single primary maintainer (wangyu-) suggests active but potentially bottlenecked development. Production-ready for its intended use cases but monitor for security updates on the encryption layer.

Single maintainer (wangyu-) with no visible CI pipeline or automated testing framework, raw socket manipulation requires root/cap_net_raw (high privilege attack surface), and encryption implementation (AES-128-CBC) predates modern standards like ChaCha20-Poly1305. No package manager dependencies listed (good) but peer-reviewed security audits are not mentioned.

Repository data does not expose recent commit history or open pull requests; based on file list alone, active areas appear to be build system maintenance (CMakeLists.txt, build_guide docs), platform guides (android_guide.md, openvpn_guide.md), and example configuration (example.conf). Documentation has zh-cn Chinese translations suggesting international user base.

git clone https://github.com/wangyu-/udp2raw.git
cd udp2raw
make
# or: cmake . && make
sudo ./udp2raw -s -l 0.0.0.0:4096 -r 127.0.0.1:8080 -k 'your-key' --mode fakeTcp
sudo ./udp2raw -c -l 127.0.0.1:1234 -r 'server-ip:4096' -k 'your-key' --mode fakeTcp

Requires root or CAP_NET_RAW capability; no external dependencies to install.

Daily commands: Server mode: sudo ./udp2raw -s -l 0.0.0.0:4096 -r 127.0.0.1:8080 -k 'password' --mode fakeTcp. Client mode: sudo ./udp2raw -c -l 127.0.0.1:1234 -r server-ip:4096 -k 'password' --mode fakeTcp. See example.conf for full option reference (--cipher, --auth-mode, --anti-replay, --heartbeat, etc.). Verify with tcpdump that packets appear as TCP/ICMP, not raw UDP.

• client.cpp — Main client-side entry point that initializes the tunnel, handles command-line arguments, and orchestrates the UDP-to-raw protocol conversion.
• connection.h — Core abstraction defining the connection state machine and packet processing logic shared between client and server modes.
• connection.cpp — Implements connection lifecycle, packet encapsulation/decapsulation, and protocol state transitions for all tunnel modes.
• common.h — Defines shared data structures, constants, and utility macros used throughout the codebase for protocol handling.
• encrypt.cpp — Implements encryption/decryption engine wrapping AES and PBKDF2, critical for all tunnel traffic security.
• fd_manager.cpp — Manages raw socket creation and lifecycle, essential for raw packet I/O on Linux kernel.
• CMakeLists.txt — Build configuration that ties together libev, AES acceleration libraries, and platform-specific compilation flags.

• Connection State Machine (C++, libev callbacks) — Maintains per-connection state (handshake, established, closed), handles packet sequencing, detects replay attacks
  • Failure mode: Out-of-sync state between client/server leads to packet drops; if sequence validation fails, connection hangs
• Encryption Engine — Encrypts/decrypts tunnel payload, derives

Add support for a new encapsulation protocol (e.g., GRE)

1. Define protocol header struct and constants in common.h with mode enum value (common.h)
2. Implement packet construction and parsing functions in common.cpp (common.cpp)
3. Add protocol dispatch case in connection.cpp's encapsulation/decapsulation logic (connection.cpp)
4. Update fd_manager.cpp to set appropriate socket options (IP_HDRINCL, etc.) for the new protocol (fd_manager.cpp)
5. Add command-line argument handling in client.cpp for the new mode (client.cpp)

Integrate a different encryption algorithm (e.g., ChaCha20)

1. Add cipher enum and wrapper function declarations in encrypt.h (encrypt.h)
2. Implement cipher operations in encrypt.cpp with same interface as AES (encrypt.cpp)
3. Update CMakeLists.txt to link new cryptography library (CMakeLists.txt)
4. Add cipher selection logic in connection.cpp packet processing (connection.cpp)

Add a new command-line option or configuration parameter

1. Define config struct field in common.h (common.h)
2. Parse option in client.cpp argument parser, set default in example.conf (client.cpp)
3. Pass config value through connection initialization in connection.cpp (connection.cpp)
4. Use config value in relevant protocol or I/O logic (fd_manager.cpp or encrypt.cpp) (fd_manager.cpp)

• libev — Efficient, portable event-driven I/O multiplexing across Linux, BSD, and embedded platforms; required for handling concurrent UDP and raw socket events
• Raw sockets (SOCK_RAW) — Only mechanism to send/receive packets with custom IP/TCP/ICMP headers without kernel TCP/UDP stack intervention; essential for protocol spoofing
• AES-NI hardware acceleration — Encryption is bottleneck in tunnel throughput; AES-NI provides 10–50x speedup on modern x86/ARM, critical for acceptable performance
• PBKDF2 key derivation — Derives strong cryptographic keys from user passwords with tunable iteration count; resists brute-force and rainbow-table attacks

• Raw socket approach instead of TUN/TAP device

  • Why: Simpler to implement, fewer kernel dependencies, but requires root or cap_net_raw capability
  • Consequence: Works on resource-constrained systems (phones, routers) but cannot be run as unprivileged user; no per-connection state at OS level

• FakeTCP header spoofing instead of legitimate TCP encapsulation

  • Why: Bypasses UDP-blocking firewalls by impersonating TCP traffic, which is rarely blocked
  • Consequence: May trigger IDS/DPI detection on sophisticated networks; does not establish real TCP connections, so not compatible with TCP window scaling or other TCP semantics

• Synchronous encryption on main event loop instead of async offload

  • Why: Simpler code, avoids thread synchronization overhead
  • Consequence: Encryption latency directly added to packet processing; high packet rates may cause latency spikes unless AES-NI is available

• Client-only binary (no separate server mode binary)

  • Why: Single codebase, reduces maintenance; server mode invoked with different command-line flags
  • Consequence: Deployment assumes same binary deployed on both sides; no separate role optimization

• Does not handle TCP traffic directly—only UDP; for TCP tunneling, requires pairing with a UDP-based VPN (OpenVPN, L2TP, ShadowVPN)
• Does not support Windows or macOS natively—Linux-only (or via separate multiplatform fork); uses Linux-specific raw socket APIs
• Does not implement authentication or key exchange—pre-shared key only; no asymmetric cryptography or certificate validation
• Does not optimize for latency-sensitive applications—adds encryption/decryption overhead; designed for bandwidth-limited scenarios
• Does not include GUI or web dashboard—command-line configuration only

Raw socket operations require root or explicit CAP_NET_RAW Linux capability (sudo not always sufficient on some systems); IP_HDRINCL requires manually constructing full IP headers, which breaks on systems with CSUM_PARTIAL offloading; some ISPs silently drop ICMP tunnels so mode selection is empirical; connection recovery requires matching heartbeat interval across client/server (hardcoded default may desync if clock skew exists); AES-128-CBC is vulnerable to padding oracle attacks—no explicit PKCS7 validation mentioned in encrypt.cpp.

• Raw Socket (SOCK_RAW) and IP_HDRINCL — udp2raw's core mechanism—raw sockets let you craft arbitrary IP/ICMP/TCP headers and bypass kernel UDP stack, but require root and careful header construction to avoid kernel checksum offloading issues.
• FakeTCP: Stateful TCP Simulation without Congestion Control — The tunnel simulates TCP 3-way handshake and seq/ack sequences to fool firewalls into thinking it's legitimate TCP, while internally delivering packets out-of-order in real-time like UDP—understanding this hybrid is key to avoiding TCP-over-TCP problems.
• AES-128-CBC and HMAC-SHA1 for Tunnel Encryption — The cryptographic layer protects tunnel payloads and integrity; CBC mode's IV handling and HMAC padding oracle vulnerabilities are non-obvious pitfalls in the encrypt.cpp implementation.
• Anti-Replay Window with Sliding Window Algorithm — Defends against replay attacks in connectionless UDP tunnels by tracking packet sequence numbers in a fixed-size window; critical for security when encryption mode is chosen.
• Connection Recovery via Heartbeat and Port Rotation — When network changes occur (WiFi handoff, cable replug), the client detects timeout via missed heartbeat packets and rotates to a new UDP port while server correlates old/new flows—this requires stateful connection tracking across port changes.
• Multiplexing Multiple UDP Flows Over Single Raw Tunnel — A single client connection can carry multiple independent UDP conversations (e.g., multiple DNS queries or OpenVPN subflows); the tunnel demultiplexes by source/dest IP:port pairs, reducing handshake overhead.
• CAP_NET_RAW Linux Capability and Privilege Separation — udp2raw typically runs as root for raw socket access, but can be sandboxed with CAP_NET_RAW to reduce attack surface—understanding Linux capabilities is essential for secure deployment on hardened systems.

• wangyu-/tinyfecVPN — Companion project by same author—VPN that works over unreliable networks; commonly used together with udp2raw to tunnel VPN traffic through hostile ISPs.
• clowwindy/shadowsocks — Related UDP tunneling tool for bypassing censorship; provides alternative approach to UDP traffic obfuscation, often compared to udp2raw in network circumvention contexts.
• xtaci/kcptun — KCP-based UDP tunnel with FEC and congestion control; documented in udp2raw doc/ (kcptun_step_by_step.md) as a companion tool for bandwidth optimization.
• wangyu-/udp2raw-multiplatform — Official Windows/macOS port of udp2raw (this repo is Linux-only due to raw socket differences); same codebase adapted for cross-platform raw socket APIs.
• openvpn/openvpn — Primary use case for udp2raw—OpenVPN tunneling over restrictive networks; documented in doc/openvpn_guide.md with step-by-step integration examples.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for encryption module (encrypt.cpp/encrypt.h)

The encrypt.cpp module handles critical cryptographic operations but has no visible test suite. Given that udp2raw tunnels sensitive traffic, comprehensive unit tests for encryption/decryption operations, IV handling, and various cipher modes would improve security assurance and catch regressions. This is especially important for the AES acceleration variants in lib/aes_acc/.

• [ ] Create tests/encrypt_test.cpp with test cases for encrypt.cpp functions
• [ ] Add test cases for all supported cipher modes referenced in encrypt.h
• [ ] Test AES-NI acceleration path vs fallback in lib/aes_acc/aesni.c
• [ ] Add CMake test target to CMakeLists.txt to run encrypt tests
• [ ] Document test execution in doc/build_guide.md

Add GitHub Actions CI workflow for multi-platform builds

The repo supports Linux, Android, OpenWRT, and Raspberry Pi, but there's no CI pipeline visible. A GitHub Actions workflow would catch build breakages across architectures (x86, ARM, ARM64), validate the CMakeLists.txt configuration, and ensure documentation stays current. This is critical for a security-focused tunnel tool.

• [ ] Create .github/workflows/build.yml with matrix strategy for Linux/ARM/ARM64
• [ ] Add build steps for both client.cpp and server.cpp compilation
• [ ] Include static analysis (clang-tidy) using .clang-format config already present
• [ ] Validate CMakeLists.txt syntax and dependency resolution
• [ ] Document CI status badge in README.md

Complete and index platform-specific build documentation with CMake examples

doc/build_guide.md exists but is incomplete (referenced but partially shown). The repo has multiple platform variants (desktop/Android/OpenWRT/RPi) but clear build instructions are scattered. Creating comprehensive, indexed build documentation with concrete CMake commands for each platform would reduce contributor friction and support issues.

• [ ] Expand doc/build_guide.md with explicit CMake build commands for Linux, ARM, and ARM64 targets
• [ ] Add section referencing Android build specifics (currently only doc/android_guide.md exists)
• [ ] Document dependency installation for libssl-dev and other requirements from CMakeLists.txt
• [ ] Add troubleshooting section for common compilation errors
• [ ] Link to platform-specific guides (Android, OpenWRT) from main build_guide.md

• Add unit tests for encrypt.cpp AES-128-CBC and HMAC-SHA1 functions (currently no test/ directory visible; cross-reference test vectors from NIST CAVP test suites).
• Document the FakeTCP seq/ack_seq simulation algorithm in connection.cpp with inline comments and a doc/ diagram (current code logic is difficult to follow for new contributors).
• Implement YAML/TOML config file parsing (example.conf is template-only; allow users to load configs instead of only CLI args) by adding a config_parser.cpp module.

• High · Use of Raw Sockets with Elevated Privileges — client.cpp, connection.cpp, and core networking modules. The application requires root access or CAP_NET_RAW capability to manipulate raw sockets and craft custom network packets (ICMP/FakeTCP/UDP headers). This significantly increases the attack surface and potential for privilege escalation exploits. Any vulnerability in the application could be leveraged to compromise the entire system. Fix: Implement principle of least privilege by dropping unnecessary capabilities after initialization. Use Linux capabilities (setcap) instead of requiring full root. Consider sandboxing with seccomp or AppArmor/SELinux profiles to restrict system calls.
• High · Potential Buffer Overflow in Packet Processing — connection.cpp, common.cpp, encrypt.cpp. The codebase manipulates raw network packets and custom headers without clear bounds checking visible in the file structure. C/C++ packet handling code is particularly vulnerable to buffer overflows when parsing untrusted network data, especially in connection.cpp and common.cpp. Fix: Implement strict input validation and bounds checking for all packet parsing. Use safe C++ constructs (std::array, std::string with size limits). Enable compiler protections (stack canaries, ASLR). Conduct thorough fuzzing of packet processing logic.
• High · Cryptographic Implementation Concerns — encrypt.cpp, lib/aes_acc/, lib/pbkdf2-sha1.cpp, lib/pbkdf2-sha256.cpp. Custom cryptographic implementations in encrypt.cpp with AES acceleration libraries (aes_acc) and pbkdf2 implementations may contain timing attacks, incorrect IV handling, or improper key derivation. The presence of architecture-specific assembly code (x86, ARM, MIPS) increases complexity and potential for cryptographic flaws. Fix: Use established cryptographic libraries (OpenSSL, libsodium) instead of custom implementations. If custom code must be retained, conduct security audits and formal cryptographic analysis. Ensure constant-time operations to prevent timing attacks. Validate IV uniqueness and key derivation parameters.
• High · Hardcoded Configuration and Potential Credential Exposure — example.conf, configuration handling. The presence of example.conf suggests configuration files may contain sensitive parameters. If default credentials, encryption keys, or pre-shared keys are hardcoded or left with weak defaults, they could be easily compromised. Fix: Never store credentials or sensitive keys in configuration files or code. Use environment variables or secure key management systems. Implement secure defaults that require explicit configuration. Document security considerations in build_guide.md.
• Medium · Lack of Input Validation on Network Headers — connection.cpp, common.cpp. The application crafts and parses custom TCP/UDP/ICMP headers. Malformed or malicious packets could bypass validation logic, leading to undefined behavior, DoS, or information disclosure. Fix: Implement comprehensive validation for all custom headers. Verify packet structure, lengths, checksums, and sequence numbers. Implement rate limiting and packet size validation to prevent DoS attacks.
• Medium · Potential Information Disclosure Through Error Messages — client.cpp, server components, fd_manager.cpp. Verbose error handling in security-critical networking code could leak system information, internal state, or cryptographic details to attackers through log messages or responses. Fix: Implement secure logging with sensitive data redaction. Avoid exposing stack traces, memory addresses, or cryptographic state in error messages. Use generic error messages for external-facing responses while logging detailed information only server-side.
• Medium · MD5 Usage for Security-Critical Operations — lib/md5.cpp, lib/md5.h. The codebase includes md5.cpp/md5.h. MD5 is cryptographically broken and should not be used for security purposes like authentication, integrity verification, or key derivation. Fix: Replace MD5 with SHA-256 or SHA-3 for all security-critical operations. If MD5 is used for non-security purposes (checksums), document this clearly. Conduct code review to ensure MD5 isn't used for cryptographic authentication.
• Medium · Incomplete File Structure Visibility — undefined. Critical implementation files for server-side components, authentication, and session management are not visible in the provided file structure, making complete security Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.