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/snail007/goproxy 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 8mo ago

• Last commit 8mo ago
• GPL-3.0 licensed
• ⚠ Slowing — last commit 8mo ago
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ 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 snail007/goproxy repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/snail007/goproxy.

What it runs against: a local clone of snail007/goproxy — 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 snail007/goproxy | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | 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 ≤ 279 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 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 "config.go" \\
  && ok "config.go" \\
  || miss "missing critical file: config.go"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "VERSION" \\
  && ok "VERSION" \\
  || miss "missing critical file: VERSION"
test -f "CHANGELOG" \\
  && ok "CHANGELOG" \\
  || miss "missing critical file: CHANGELOG"
test -f "docker/Dockerfile" \\
  && ok "docker/Dockerfile" \\
  || miss "missing critical file: docker/Dockerfile"

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

GoProxy is a high-performance proxy server written in Go that supports HTTP(S), SOCKS5, WebSocket, TCP, UDP, and SSH tunneling with advanced features like chain-style proxies, TLS encryption, NAT penetration, port forwarding, and traffic control. It solves the problem of needing a single unified proxy solution that handles multiple protocols, load balancing, and internal network access from external networks. Monolithic single-package structure with config.go as the configuration entry point, direct/ subdirectory likely containing core proxy logic, and doc/ containing architecture diagrams and protocol examples (http-1.png, socks-2.png, tcp-1.png show reference topologies). Protocol handlers appear modular but colocated in main package. Docker/ subdirectory provides containerization support with pre-built certificates.

Network administrators and DevOps engineers who need to expose internal services behind NAT/firewalls, set up encrypted proxy chains for security, or route multiple protocol types (HTTP/SOCKS5/TCP/UDP) through a single configurable server. Also used by individuals in restricted network environments requiring protocol conversion and anti-censorship proxying.

Production-ready and actively maintained. The project has significant GitHub presence (evidenced by 77KB of Go code, 4.8KB of shell scripts, Docker support, and a VERSION file indicating versioning discipline). The presence of CHANGELOG, comprehensive documentation in /doc and /docs directories, and multiple platform editions (Desktop, Android Server/Global) indicates mature development. However, single-maintainer risk exists (snail007 appears as primary author).

Low external dependency risk—only kingpin.v2 for CLI parsing and golang.org/x/time for standard library support, indicating minimal supply chain exposure. Main risk is maintainer concentration (appears community-driven but snail007-centric). No visible CI/CD pipeline configuration (no GitHub Actions, Travis, or Jenkins files in listing). Last activity status unclear from file timestamps, but existence of Docker setup and multiple platform variants suggests ongoing development.

Unable to determine from static file listing alone—no recent commits, open PRs, or milestones visible. The presence of CHANGELOG and VERSION file suggests versioning is tracked, but activity status requires checking GitHub API or recent git history. Desktop edition (proxy_admin_free) and Android editions suggest active ecosystem expansion beyond core server.

git clone https://github.com/snail007/goproxy.git
cd goproxy
go build -o proxy
./proxy --help

Then consult doc/ for protocol-specific examples (http-1.png, socks-2.png) or GOPROXY Manual at https://snail007.goproxyauth.com/goproxy/manual/ for configuration syntax.

Daily commands:

go build -o proxy .
./proxy --help  # Display available proxy modes
./proxy http -p :8080  # Start HTTP proxy on port 8080
./proxy socks5 -p :1080  # Start SOCKS5 proxy on port 1080
./proxy tcp -p :9090 --target targethost:targetport  # TCP port forwarding

See README.md and doc/ directory for protocol-specific flags and chain-proxy examples.

• config.go — Central configuration parsing and initialization—every proxy mode and feature flag flows through here; essential for understanding how command-line arguments map to runtime behavior
• README.md — Entry point for understanding the proxy's full capability matrix (HTTP, SOCKS5, TCP, UDP, KCP, SSH, TLS); required to grasp the feature scope and supported deployment patterns
• VERSION — Version management and release tracking; critical for ensuring contributors align with current release cycle and deprecation policies
• CHANGELOG — Historical record of features, breaking changes, and bug fixes; vital for understanding how the codebase has evolved and what patterns are legacy vs. current best practice
• docker/Dockerfile — Container build definition showing runtime dependencies, binary compilation, and deployment topology; essential for contributors working on cross-platform deployments
• docs/manual/manual.md — Comprehensive operational guide documenting all proxy modes, protocol chains, and configuration examples; required reading to understand real-world usage patterns and architectural constraints
• .gitignore — Defines what is excluded from version control and build artifacts; helps contributors avoid committing secrets, binaries, or platform-specific files

Add a new proxy protocol mode (e.g., new transport type)

1. Define new protocol flags and options in config.go (e.g., ProtoXYZ, PortXYZ, etc.) (config.go)
2. Create protocol implementation file in root or dedicated package (follow naming pattern: protocol_xyz.go or xyz/handler.go) ([New protocol implementation directory or file])
3. Register the protocol handler in the main initialization logic (referenced from config.go) (config.go)
4. Add usage examples and protocol-specific configuration to docs/manual/manual.md (docs/manual/manual.md)
5. Document the new mode in README.md feature list (README.md)

Add a new filtering rule type (blacklist/whitelist feature)

1. Define new filter rule format and parsing logic in blocked file or a new filtering module (blocked)
2. Add configuration options for the filter in config.go (e.g., --filter-file, --filter-mode) (config.go)
3. Integrate filter checks into the proxy request routing logic (in core proxy handlers) ([Protocol handler that enforces filtering])
4. Add rule format documentation and examples to docs/manual/manual.md (docs/manual/manual.md)

Add a new Docker deployment variant or regional configuration

1. Create a new region-specific timezone or environment file (e.g., docker/Beijing) following the Shanghai pattern (docker/Shanghai)
2. Update docker/build.sh to include the new variant in the build matrix (docker/build.sh)
3. Add a new Dockerfile stage or variant if different dependencies are needed (docker/Dockerfile)
4. Document the new deployment variant in docs/manual/manual.md (docs/manual/manual.md)

Add a new authentication or API endpoint

1. Define API authentication configuration options in config.go (e.g., --api-auth-url, --api-key-file) (config.go)
2. Implement authentication/authorization logic in a new auth module or extend existing protocol handlers ([New auth module or protocol handler])
3. Integrate auth checks into request pipeline for protected proxy modes ([Protocol handler or middleware])
4. Document API authentication flows and examples in docs/manual/manual.md (docs/manual/manual.md)

• Go 1.16+ — High concurrency, low memory overhead, static binary compilation for cross-platform deployment; essential for a high-performance proxy server handling thousands of concurrent connections
• kingpin CLI framework (alecthomas/kingpin.v2) — Declarative command-line argument parsing with automatic help generation; reduces boilerplate for complex multi-protocol configuration
• golang.org/x/time (rate limiting) — Standard library rate-limiting primitives for traffic shaping, bandwidth throttling, and connection pooling features
• Docker containerization — Enables reproducible deployment across heterogeneous infrastructure; simplifies regional TZ/CA bundle management via build variants
• Hugo static site generator (docs/) — Low-overhead documentation hosting; supports multi-language content (English, Simplified Chinese) without server-side rendering

• Single monolithic binary vs. modular plugin architecture

  • Why: Simpler deployment and version management; easier for users to set up and troubleshoot without dependency hell
  • Consequence: Harder to extend with third-party protocols without rebuilding; all features linked into every binary even if unused

• File-based configuration (config.go) + CLI flags vs. configuration server

  • Why: Eliminates runtime dependency on external services; fast startup; supports GitOps-style version control
  • Consequence: Harder to dynamically update rules without restart; no real-time policy changes without orchestration wrapper

• Support for chain-style proxies (parent proxies) over native protocol implementation only

  • Why: Enables integration with existing infrastructure and multi-hop tunneling; reduces code duplication for proxy-to-proxy communication
  • Consequence: Additional latency overhead in chain mode; more complex error handling and timeout logic across hops

• Blacklist/whitelist-based filtering (blocked file) vs. AI/ML-based content inspection

  • Why: Deterministic, transparent, and fast; no false positives from statistical models
  • Consequence: Requires manual rule maintenance and regex expertise; cannot detect novel/obfuscated malicious content

• Real-time dynamic configuration reload without restart (implies monolithic architecture with file-based config)
• Web UI dashboard for live traffic monitoring or rule management (purely CLI/config-file driven)
• Native support for proprietary enterprise proxy protocols (focus is open standards: HTTP, SOCKS5, TCP, UDP, WebSocket, SSH, KCP)
• End-to-end encryption between GoProxy instances without explicit TLS configuration (TLS is opt-in, not transparent)
• Automatic certificate generation and renewal (relies on user providing certs or external CA management)
• High-availability clustering or distributed state (single-instance design; clustering delegated to load balancer/orchestration layer)

1. Dual language documentation: English and Chinese READMEs have different resource links and installation sources—use README_ZH.md for Chinese-specific releases. 2. Chain-proxy complexity: The 'chain-style proxies' feature requires specific flag ordering and encryption key exchange; see doc/ diagrams before attempting multi-hop setups. 3. KCP support: Requires golang.org/x/time and may need UDP firewall rules; not documented in main README snippets. 4. API authentication: Mentioned in description but no visible auth handler in root config.go—likely in a module not shown in file listing. 5. Port forwarding semantics: TCP/UDP forwarding flags (--target, port mapping) require careful reading of protocol-specific docs in /doc directory.

• Chain-style Proxies (Proxy Chaining) — Core differentiator of goproxy—allows N-level cascading proxies with encryption between hops; critical for multi-network penetration and security architecture
• SOCKS5 Protocol (RFC 1928) — One of four main protocols supported; required to understand client negotiation, authentication, and UDP association handling in goproxy's proxy modes
• TLS Certificate Pinning & Encrypted Transport — Goproxy uses 'underlying tls high-intensity encryption' for inter-proxy communication; essential for securing chain-proxy links against MITM
• NAT Traversal & Port Forwarding — Goproxy supports 'nat forwarding in different lan' and TCP/UDP port forwarding; core use case for exposing internal services; requires understanding of port mapping and UDP hole punching
• Token Bucket Rate Limiting — Goproxy implements speed limiting and connection limiting via golang.org/x/time; understanding token bucket is necessary to tune traffic control thresholds
• KCP Protocol (Reliable UDP) — Goproxy supports KCP as alternative to TCP for better latency in lossy networks; rare feature requiring understanding of congestion control over UDP
• WebSocket Protocol Proxying — Goproxy can proxy WebSocket connections; requires understanding HTTP upgrade mechanism and frame-level proxying vs. byte-level proxying

• v2ray/v2ray-core — Alternative proxy/tunnel server supporting multiple protocols (Socks, HTTP, etc.) with similar chaining and encryption features; direct competitor in the same space
• elazul/clash — Popular lightweight proxy tool with SOCKS5/HTTP support; similar use case for local proxying and protocol conversion, smaller scope but simpler deployment
• snail007/proxy_admin_free — Official web UI dashboard for goproxy (referenced in README); companion repo that provides management console for this server
• snail007/goproxy-sdk — Official SDK for programmatically controlling goproxy; enables embedding goproxy as a library in other Go applications
• shadowsocks/shadowsocks-go — Classic SOCKS5 + encryption proxy in Go; shares similar threat model (censorship circumvention) but narrower protocol scope than goproxy

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 comprehensive unit tests for config.go parsing and validation

The config.go file appears to be central to the proxy configuration system, but there are no visible test files in the repository structure. Given the complexity of supporting multiple proxy types (HTTP, HTTPS, SOCKS5, TCP, UDP, WebSocket, KCP, SSH), comprehensive tests for configuration parsing, validation, and edge cases would prevent regressions and improve maintainability.

• [ ] Create config_test.go with test cases for valid/invalid proxy type configurations
• [ ] Add tests for chain-style proxy configuration parsing
• [ ] Add tests for authentication and TLS certificate configuration paths
• [ ] Add tests for port forwarding and NAT configuration scenarios
• [ ] Add benchmark tests for configuration parsing performance

Create GitHub Actions CI/CD workflow for multi-platform builds and releases

The README indicates support for cross-platform deployment (Linux, Windows, macOS) and Docker, but there's no visible GitHub Actions workflow file. A comprehensive CI pipeline would automate testing across platforms, build Docker images, and create releases with pre-built binaries for each supported OS/architecture.

• [ ] Create .github/workflows/test.yml for running tests on push/PR across Go 1.16+ versions
• [ ] Create .github/workflows/build.yml to build binaries for linux/amd64, linux/arm64, windows/amd64, darwin/amd64, darwin/arm64
• [ ] Create .github/workflows/docker.yml to build and push Docker images to Docker Hub/GHCR on release
• [ ] Add workflow to automatically update VERSION file and create GitHub releases with built artifacts
• [ ] Add cross-compilation tests to verify KCP and SSH forwarding features compile correctly on all platforms

Add integration tests for proxy chain and protocol bridging scenarios

The repository supports complex features like chain-style proxies and multiple protocol combinations (HTTP→SOCKS5→SSH, TCP→TLS→KCP, etc.), but no visible integration test suite. Adding scenario-based tests would ensure these features work correctly and prevent breaking changes.

• [ ] Create integration_test.go with test fixtures for spinning up proxy chains
• [ ] Add tests for HTTP→SOCKS5→HTTP proxy chains with actual traffic flow
• [ ] Add tests for TCP port forwarding through SSH tunnels with data integrity verification
• [ ] Add tests for protocol bridging (e.g., SOCKS5 client → HTTP proxy backend)
• [ ] Add tests for traffic limiting and connection limiting features with concurrent clients
• [ ] Add tests for blacklist/whitelist filtering across different proxy types

• Add integration tests for SOCKS5 protocol handler: No visible test files in listing despite complex protocol handling in root package. Write tests for socks5 connection establishment, authentication flow, and UDP association (mentioned in README but untested in visible structure).
• Document API authentication mechanism with examples: README mentions 'API authentication' but config.go and visible structure don't show implementation. Create doc/API_AUTH.md with working curl examples for basic-auth, token, or custom auth methods.
• Add GitHub Actions CI/CD pipeline for multi-platform builds: No CI config visible (no .github/workflows/, travis.yml, or similar). Create .github/workflows/build.yml to test on Linux/macOS/Windows and auto-publish Docker images to registry on tag.

The GoProxy codebase has significant security concerns primarily stemming from severely outdated dependencies and Go version (from 2021). The complexity of implementing multiple network proxy protocols introduces substantial attack surface. While the project structure appears organized, critical dependency updates are urgently needed. The proxy's nature as a network intermediary handling various protocols requires rigorous security testing and input validation. Immediate actions: upgrade Go to 1.21+, update all dependencies, and conduct comprehensive security audits given the sensitive nature of proxy software.

• High · Outdated Go Version — go.mod (go 1.16). The project targets Go 1.16, which reached end-of-life in September 2021. This version lacks important security patches and bug fixes. Modern Go versions include critical security improvements for cryptography, networking, and runtime vulnerabilities. Fix: Upgrade to Go 1.21 or later. Update go.mod to reflect the latest stable Go version and rebuild all dependencies.
• High · Outdated Dependencies — go.mod (all dependencies). The go.mod file contains very old dependencies with timestamps from 2021. These packages likely contain known security vulnerabilities that have been patched in newer versions. Specifically: gopkg.in/alecthomas/kingpin.v2 (2.2.6) and golang.org/x/time are significantly outdated. Fix: Run 'go get -u ./...' to update all dependencies to their latest versions. Review the changelog for each dependency for breaking changes.
• Medium · Potential Configuration Exposure Risk — config.go, blocked (files). The presence of 'config.go' and 'blocked' files suggests configuration-driven behavior. Without seeing the contents, there's risk that sensitive configuration (API keys, authentication tokens, TLS certificates) could be exposed through config files committed to version control. Fix: Ensure sensitive configuration is never committed to version control. Use environment variables, external config servers, or secure vaults for secrets. Add secrets patterns to .gitignore.
• Medium · Proxy Server Attack Surface — Entire codebase (core proxy logic). GoProxy implements multiple protocol proxies (HTTP, HTTPS, SOCKS5, TCP, UDP, WebSocket). Complex proxy implementations with multiple protocol handlers increase the attack surface for injection attacks, request smuggling, protocol confusion attacks, and memory safety issues. Fix: Implement comprehensive input validation and sanitization for all proxy protocols. Conduct regular security audits and penetration testing. Use fuzzing to test protocol parsing. Implement rate limiting and request filtering.
• Medium · Missing Security Headers Configuration — HTTP proxy implementation (not visible in partial structure). As an HTTP proxy that likely handles client requests, there's no visible evidence of security headers (CSP, X-Frame-Options, X-Content-Type-Options, etc.) being enforced by default. Fix: Implement configurable security headers for HTTP responses. Add options for HSTS, Content-Security-Policy, and other protective headers in the proxy configuration.
• Low · Indirect Dependency Vulnerabilities — go.mod (indirect dependencies). The project has indirect dependencies (alecthomas/template and alecthomas/units marked as indirect and indirect) from 2019-2021. These may contain transitive vulnerabilities. Fix: Run 'go mod tidy' and 'go mod verify'. Use 'go list -u -m all' to identify available updates. Consider using tools like 'nancy' or 'trivy' for continuous vulnerability scanning.
• Low · Docker Build Configuration — docker/Dockerfile. A Dockerfile exists but without visibility into its contents, it's impossible to verify if it follows security best practices such as using minimal base images, avoiding running as root, or multi-stage builds. Fix: Review Dockerfile for: using specific base image versions (not 'latest'), implementing multi-stage builds, running as non-root user, minimizing layer size, and scanning with tools like 'trivy' or 'grype'.

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.