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/windtf/wireproxy 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.

GO — Healthy across the board

• Last commit 2mo ago
• 33+ active contributors
• Distributed ownership (top contributor 30% of recent commits)
• ISC licensed
• CI configured
• Tests present

_{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 windtf/wireproxy repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/windtf/wireproxy.

What it runs against: a local clone of windtf/wireproxy — 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 windtf/wireproxy | Confirms the artifact applies here, not a fork | | 2 | License is still ISC | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 93 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of windtf/wireproxy. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/windtf/wireproxy.git
#   cd wireproxy
#
# 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 windtf/wireproxy and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "cmd/wireproxy/main.go" \\
  && ok "cmd/wireproxy/main.go" \\
  || miss "missing critical file: cmd/wireproxy/main.go"
test -f "config.go" \\
  && ok "config.go" \\
  || miss "missing critical file: config.go"
test -f "wireguard.go" \\
  && ok "wireguard.go" \\
  || miss "missing critical file: wireguard.go"
test -f "http.go" \\
  && ok "http.go" \\
  || miss "missing critical file: http.go"
test -f "routine.go" \\
  && ok "routine.go" \\
  || miss "missing critical file: routine.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 93 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~63d)"
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/windtf/wireproxy"
  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).

wireproxy is a userspace WireGuard client written in Go that exposes a WireGuard VPN connection as a SOCKS5/HTTP proxy or tunnel, eliminating the need for root privileges or dedicated network interfaces. Users configure WireGuard peers via INI config files (Interface and Peer sections), and wireproxy binds a local SOCKS5 proxy that routes traffic through the encrypted tunnel. Flat monolith structure: cmd/wireproxy/main.go is entry point; core logic lives in config.go (INI parsing), wireguard.go (WireGuard connection), http.go & udp_proxy.go (proxy handlers), and routine.go (event loops). Systemd and rc.d/ directories provide OS-level integration templates. No internal packages; everything is root-level or under cmd/.

Users who want to selectively route traffic through a WireGuard peer without system-wide VPN setup—particularly browser users leveraging Firefox container tabs, developers avoiding root permission requirements, and infrastructure teams needing per-application VPN routing without network interface manipulation.

Actively maintained with v1.0.9 released and solid CI/CD (GitHub Actions for build, test, linting, container, and releases). Contains test_config.sh and *_test.go files indicating test coverage. Single maintainer (octeep) with recent commits visible. Production-ready for userspace proxy use cases, though UDP support is still in TODO.

Low-to-moderate risk: small, focused codebase (~47KB Go) with well-scoped dependencies (wireguard, socks5, argparse, landlock). Single maintainer creates continuity risk. No open CVEs visible in go.mod; all deps are established (zx2c4.com/wireguard, things-go/go-socks5). TCP-only in SOCKS5 (UDP in TODO) may limit use cases. Last activity appears recent based on version tagging.

No specific PR or milestone data visible in file list. Latest release is v1.0.9. Codebase is stable; TODO comments indicate future work on UDP support in SOCKS5 and UDP static routing. Sponsor support from IPRoyal suggests ongoing maintenance commitment.

git clone https://github.com/windtf/wireproxy && cd wireproxy && make

Daily commands: make builds the binary. Then: ./wireproxy [-c /path/to/config.conf] or wireproxy -d (daemon mode). Default config paths: /etc/wireproxy/wireproxy.conf or $HOME/.config/wireproxy.conf. Use -n flag for config validation only.

• cmd/wireproxy/main.go — Entry point that initializes the application, parses CLI arguments, and starts the proxy service.
• config.go — Defines configuration parsing logic for WireGuard peer settings and proxy parameters; foundational for all runtime behavior.
• wireguard.go — Core WireGuard client implementation that establishes peer connections and manages the encrypted tunnel.
• http.go — HTTP and SOCKS5 proxy server implementation; exposes the WireGuard tunnel as a usable proxy interface.
• routine.go — Main application loop and goroutine orchestration that coordinates proxy server, WireGuard client, and signal handling.
• udp_proxy.go — UDP traffic proxying logic; handles non-TCP traffic through the WireGuard tunnel.
• go.mod — Declares all Go dependencies including WireGuard, SOCKS5, and security libraries that form the project's foundation.

• config.go – Configuration Parser (go-ini/ini, argparse) — Reads INI-formatted WireGuard config; parses CLI arguments; validates required fields (private key, peer public key, allowed IPs, endpoint).
  • Failure mode: Invalid config → startup panic; missing keys → clear error messages; malformed addresses → parse failures logged to stderr
• wireguard.go – Tunnel Manager (zx2c4.com/wireguard, golang.org/x/net, gvisor (userspace)) — Establishes encrypted peer-to-peer tunnel; handles packet encryption/decryption; manages tun/tap interface (or userspace network stack); routes IP packets through peer.
  • Failure mode: Peer unreachable → connection timeout; crypto mismatch → packet drops; interface setup failure → startup error
• http.go – Proxy Server (things-go/go-socks5, net/http (stdlib)) — Accepts SOCKS5 and HTTP CONNECT client connections; parses connection requests; queues outbound packets to wireguard tunnel; relays responses back to clients.
  • Failure mode: Bind failure on port → startup error; malformed SOCKS request → connection reset; tunnel unavailable → SOCKS error response
• routine.go – Event Loop & Orchestration (Go goroutines, os/signal, landlock/protect) — Main goroutine coordinator; starts proxy server, WireGuard tunnel, and signal handlers; manages lifecycle; applies privilege restrictions on demand.
  • Failure mode: Goroutine panic → crash (no recovery); signal handling issues → SIGKILL fallback required; sandbox apply fails → non-critical error logged

Add support for a new proxy protocol (e.g., HTTP CONNECT)

1. Review the current SOCKS5 implementation and proxy acceptance logic in http.go to understand the interface pattern (http.go)
2. Add protocol-specific handler function alongside the existing SOCKS5 handler in http.go (http.go)
3. Register the new protocol listener in routine.go's main loop where current proxy servers are started (routine.go)
4. Add CLI flag and config struct field in config.go to allow users to enable/disable the new protocol (config.go)
5. Write unit tests following the pattern in config_test.go to validate configuration parsing (config_test.go)

Implement a new WireGuard peer selection strategy (e.g., load balancing across multiple peers)

1. Extend the Config struct in config.go to support multiple peer definitions and selection strategy settings (config.go)
2. Modify wireguard.go to accept a list of peers and implement peer selection/failover logic (wireguard.go)
3. Update routine.go to handle peer switching during runtime and manage multiple WireGuard tunnel instances (routine.go)
4. Add integration tests in config_test.go to verify multi-peer configuration parsing (config_test.go)

Add privilege separation / sandboxing for security hardening

1. Review existing security libraries (landlock, protect) imported in go.mod and current usage in main.go (cmd/wireproxy/main.go)
2. Implement seccomp/landlock rule application in routine.go after WireGuard tunnel is established (routine.go)
3. Add sandbox configuration options to config.go (e.g., filesystem whitelist, syscall restrictions) (config.go)
4. Create privilege-drop utility functions in util.go to handle capability dropping and user switching (util.go)

• Go + WireGuard (zx2c4.com/wireguard) — Pure userspace WireGuard implementation eliminates need for kernel module or root; provides cross-platform portability and isolation from system network interfaces.
• SOCKS5 proxy (things-go/go-socks5) — Industry-standard proxy protocol allowing applications to route traffic through wireproxy without code changes; HTTP support added natively for web clients.
• Landlock + seccomp (landlock-lsm, protect) — Provides privilege separation and sandboxing post-tunnel-establishment; restricts application attack surface after security-critical operations complete.
• INI config format (go-ini/ini) — Compatible with standard WireGuard config file format; reduces user friction by allowing config file reuse across WireGuard tools.

• Userspace WireGuard implementation instead of kernel module

  • Why: Eliminates root requirement, simplifies deployment, improves portability across Linux distributions and non-Linux OS
  • Consequence: Slight throughput penalty (~5-10% overhead) compared to kernel-space implementation; CPU usage higher for high-throughput workloads.

• Single-threaded proxy loop with goroutines for concurrency

  • Why: Go's goroutine model simplifies concurrent connection handling; easier to reason about resource sharing than multi-threaded C approach
  • Consequence: GC pauses may introduce microsecond-scale latency jitter; not suitable for ultra-low-latency gaming/trading applications.

• No built-in authentication/authorization for proxy

  • Why: Assumes wireproxy runs on trusted machine or localhost; keeps code simple and focused on proxying core
  • Consequence: Requires external firewall/network isolation; unsuitable for multi-user systems without additional security layers.

• Separate UDP proxy handler rather than integrated tunneling

  • Why: Allows explicit control over UDP forwarding; enables future per-protocol rate limiting or filtering
  • Consequence: UDP handling code is less optimized than TCP path; adds complexity for features that touch both paths.

• Does not implement full VPN tunnel mode (does not capture all system traffic; only proxied connections)
• Does not provide GUI or web dashboard (CLI/config-file only interface)
• Does not implement authentication or access control (assumes trusted local use or firewall-gated access)
• Not designed for high-throughput data center use (userspace implementation trades throughput for simplicity)

Config file must exist at /etc/wireproxy/wireproxy.conf or $HOME/.config/wireproxy.conf unless -c path is specified; startup fails silently otherwise. WireGuard [Interface] private key must be valid base64; invalid keys cause runtime panics (test with -n flag first). SOCKS5 only supports CONNECT; UDP in SOCKS5 is unimplemented (TODO). Landlock sandbox (on supported Linux) may restrict file I/O; check OS capability. Running without -d (daemon) blocks foreground; useful for testing but production needs systemd wrapper (provided in systemd/wireproxy.service).

• SOCKS5 Proxy Protocol (RFC 1928) — wireproxy exposes itself as a SOCKS5 server; understanding negotiation (auth, CONNECT), address formats, and connection lifecycle is essential for debugging proxy behavior and extending protocol support.
• Userspace Network Stack (TUN/TAP simulation) — wireproxy doesn't use kernel TUN interfaces; instead it reads/writes raw packets to the WireGuard userspace device, requiring understanding of packet I/O multiplexing and tunnel semantics.
• WireGuard Peer Configuration & Cryptography — config.go parses [Interface] and [Peer] sections (private keys, public keys, allowed IPs, endpoints); misunderstanding key encoding or CIDR routing breaks connectivity.
• HTTP CONNECT Tunneling — http.go implements HTTP CONNECT method for establishing encrypted tunnels; required for HTTPS through the proxy and browser integration (Firefox containers).
• Linux Landlock LSM (Mandatory Access Control) — wireproxy applies landlock rules for sandboxing; understanding capability restrictions and allow-lists is necessary for hardening deployment and debugging permission errors.
• Go Goroutines & Channel Multiplexing — routine.go uses concurrent goroutines to multiplex WireGuard reads, SOCKS5 listener, and proxy forwarding; race conditions or deadlocks require understanding Go's concurrency model.
• INI Configuration Parsing (go-ini library) — config.go parses INI format matching WireGuard CLI syntax; understanding schema validation, type coercion (addresses, keys, ports), and error recovery is crucial for config debugging.

• zx2c4/wireguard-go — Upstream userspace WireGuard implementation that wireproxy depends on; essential for understanding packet handling and device API.
• artem-russkikh/wireproxy-awg — Fork mentioned in README supporting Amnezia VPN instead of standard WireGuard; shows how to swap encryption backends while keeping proxy architecture.
• things-go/go-socks5 — SOCKS5 protocol library wireproxy vendors; needed to understand proxy negotiation (auth, CONNECT) and compatibility constraints.
• landlock-lsm/go-landlock — Linux sandboxing integration wireproxy uses; relevant for understanding security boundaries and capability restrictions in production.
• shadowsocks/shadowsocks-go — Alternative userspace proxy tunnel (different crypto, similar architecture); useful reference for async proxy patterns and multi-protocol support.

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 config.go parsing and validation

config.go exists but config_test.go is minimal. The codebase parses wireguard configs with go-ini, handles peer settings, and network configuration. A comprehensive test suite would catch regressions in config parsing logic, edge cases in peer address validation, and malformed input handling. This is critical since config mishandling directly impacts VPN connectivity.

• [ ] Expand config_test.go with tests for valid/invalid config file formats
• [ ] Add test cases for edge cases: missing required fields, invalid IP addresses, malformed wireguard keys
• [ ] Add tests for the ini parsing behavior with go-ini/ini v1.67.0
• [ ] Add tests for any custom validation logic in config.go
• [ ] Run tests via existing test.yml workflow to ensure integration

Add integration tests for UDP proxy behavior in udp_proxy.go

udp_proxy.go exists but there's no dedicated test file for it. Given wireproxy's core functionality is proxying traffic through wireguard, UDP proxy correctness is critical. Current test.yml likely only runs basic tests. UDP proxy needs integration tests covering packet forwarding, timeout handling, and connection state management.

• [ ] Create udp_proxy_test.go with integration tests
• [ ] Add tests for UDP packet forwarding through wireguard peers
• [ ] Test timeout and cleanup of idle UDP connections
• [ ] Test concurrent UDP connections to verify no race conditions
• [ ] Consider adding a test mode flag to allow testing without real wireguard setup

Add HTTP proxy feature documentation and tests in http.go

README mentions 'socks5/http proxy' but UseWithVPN.md only covers socks5 setup. http.go exists but lacks test coverage (no http_test.go file). The HTTP proxy capability should have: (1) documented usage examples in README or separate docs, (2) unit tests for HTTP CONNECT tunneling, and (3) tests for proxy header handling.

• [ ] Create http_test.go with tests for HTTP CONNECT method
• [ ] Add tests for proxy authentication headers if supported
• [ ] Add tests for HTTP proxy error handling (bad requests, closed connections)
• [ ] Document HTTP proxy usage in README.md with example configuration
• [ ] Add example in UseWithVPN.md or create separate HTTP_SETUP.md guide

• Add UDP support to udp_proxy.go: currently stubbed in TODO. Implement UDP packet forwarding via WireGuard device (src/routines.go multiplexes read loop) and expose UDP port in SOCKS5 protocol negotiation (RFC 1928 Section 6).
• Expand config_test.go: test cases for malformed INI (missing [Interface], invalid keys), edge-case CIDR ranges (0.0.0.0/0, ::/0), and peer validation. Currently only basic parsing is tested.
• Document systemd integration in README: Users copy systemd/wireproxy.service but unclear on User= ownership, CapabilityBoundingSet restrictions (affects landlock), and socket activation. Add example with User=nobody and required systemd directives.

• High · Outdated Go Version in Dockerfile — Dockerfile, go.mod. The Dockerfile uses Go 1.26, which is a future/invalid version. This appears to be a typo or misconfiguration. The go.mod file also specifies 'go 1.26.0' which is not a released version. This could lead to unexpected build behavior, missing security patches, and compatibility issues. Current stable Go versions are in the 1.21-1.23 range. Fix: Update Dockerfile to use a stable, released Go version (e.g., 'golang:1.23' or latest stable). Update go.mod to match the actual Go version being used. Review the project's minimum supported Go version policy.
• High · Outdated Wireguard Dependency — go.mod - zx2c4.com/wireguard dependency. The wireguard dependency uses a pinned version from December 2023 (golang.zx2c4.com/wireguard v0.0.0-20231211153847-12269c276173). This is significantly outdated and likely contains known security vulnerabilities. Wireguard receives regular updates with security fixes and protocol improvements. Fix: Update to the latest wireguard version immediately. Run 'go get -u golang.zx2c4.com/wireguard' and test thoroughly. Establish a regular dependency update schedule to track security patches.
• High · Multiple Outdated Cryptographic Dependencies — go.mod - golang.org/x dependencies. Several critical security-related dependencies are outdated: golang.org/x/crypto v0.45.0, golang.org/x/sys v0.40.0, and golang.org/x/net v0.47.0. These foundational packages contain important security fixes and should always be kept current. The discrepancy in version patterns suggests the project hasn't been actively maintained. Fix: Run 'go get -u golang.org/x/crypto golang.org/x/sys golang.org/x/net' to update to latest versions. Run security audit with 'go vet ./...' and 'govulncheck ./...'.
• Medium · Distroless Base Image Without Security Scanning — Dockerfile. While using distroless images (gcr.io/distroless/static-debian11:nonroot) is good security practice, there is no evidence of image scanning in the CI/CD pipeline or supply chain security verification. The image digest is not pinned, allowing for potential base image changes. Fix: Pin the distroless image to a specific digest (e.g., 'gcr.io/distroless/static-debian11:nonroot@sha256:...'). Add image scanning to CI/CD pipeline (Trivy, Grype). Implement container security scanning in the build workflow.
• Medium · Missing SOCKS5 Input Validation in Proxy Handler — http.go, cmd/wireproxy/main.go, things-go/go-socks5 integration. The dependency 'github.com/things-go/go-socks5' handles proxy protocol parsing. Without reviewing the actual main.go and http.go implementations, there's a risk of improper input validation on proxy requests, which could lead to SOCKS5 protocol exploits, header injection, or routing bypasses. Fix: Review SOCKS5 request parsing for proper input validation. Implement strict validation of all proxy headers and addresses. Add fuzzing tests for SOCKS5 protocol handling. Validate all hostnames and IPs against whitelist patterns if applicable.
• Medium · Configuration File Permissions Not Documented — config.go, Dockerfile (VOLUME declaration), README.md. The config file is expected at /etc/wireproxy/config but there is no evidence of documentation or enforcement of secure file permissions. Wireguard configuration files typically contain sensitive peer information and private keys that must be protected with restrictive permissions (0600 or equivalent). Fix: Document required file permissions (0600) for config files in README. Add validation in config.go to check and warn about overly permissive config file permissions. Consider auto-correcting permissions on load if running with appropriate privileges.
• Medium · Potential Hardcoded Secrets in Config Files — undefined. The project loads configuration from files (config.go exists) but the .gitignore file isn't shown in 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.