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/ginuerzh/gost 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 — Stale — last commit 1y ago

• 35+ active contributors
• MIT licensed
• CI configured
• ⚠ Stale — last commit 1y ago
• ⚠ Concentrated ownership — top contributor handles 55% of recent commits
• ⚠ 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 ginuerzh/gost repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ginuerzh/gost.

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ginuerzh/gost(\\.git)?\\b" \\
  && ok "origin remote is ginuerzh/gost" \\
  || miss "origin remote is not ginuerzh/gost (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "cmd/gost/main.go" \\
  && ok "cmd/gost/main.go" \\
  || miss "missing critical file: cmd/gost/main.go"
test -f "gost.go" \\
  && ok "gost.go" \\
  || miss "missing critical file: gost.go"
test -f "chain.go" \\
  && ok "chain.go" \\
  || miss "missing critical file: chain.go"
test -f "handler.go" \\
  && ok "handler.go" \\
  || miss "missing critical file: handler.go"
test -f "node.go" \\
  && ok "node.go" \\
  || miss "missing critical file: node.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 524 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~494d)"
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/ginuerzh/gost"
  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).

GOST (GO Simple Tunnel) is a lightweight, feature-rich tunneling proxy written in Go that implements multiple protocols (HTTP/HTTPS/HTTP2/SOCKS4/SOCKS5/Shadowsocks) with support for proxy chaining, TLS encryption, and advanced routing. It enables clients to tunnel traffic through multiple sequential proxies, making it ideal for bypassing network restrictions and building multi-hop proxy chains. Monolithic structure with cmd/gost/ as the main CLI entry point (cfg.go, main.go, route.go, peer.go); core tunnel logic in root-level files (auth.go, bypass.go, chain.go, client.go, dns.go); .config/ contains JSON/text configuration examples; examples/ has working demos for benchmarking, forwarding, and UDP tunneling. Tests are colocated (*_test.go files).

Network engineers and security professionals who need to build multi-level proxy chains; system administrators deploying transparent proxies or port forwarding; developers requiring SOCKS5/HTTP proxy servers with TLS negotiation and protocol flexibility; users in restricted network environments needing traffic tunneling through multiple hops.

GOST is actively maintained and production-ready. The codebase is substantial (602KB Go code), has CI/CD workflows (buildx.yml, release.yml), includes Docker support, and is distributed via multiple channels (GitHub releases, Docker Hub, Homebrew, Snap). The presence of comprehensive examples and .config files with sample setups indicates mature usage patterns.

The project is single-maintainer (ginuerzh), which creates maintenance risk if the author becomes unavailable. It depends on 20+ external packages including crypto libraries (golang.org/x/crypto), transport protocols (quic-go, xtaci/kcp-go), and obfuscation tools (obfs4), increasing the attack surface. No visible GitHub Issues or PR activity in the provided data, making it unclear if bugs are actively triaged.

No specific recent activity visible in the file list. The repo appears in stable maintenance mode with CI workflows (buildx.yml for multi-arch Docker builds, release.yml for GitHub releases) but no active PR/issue data provided. The .goreleaser.yaml suggests automated release processes are in place.

Clone the repo and build the CLI: git clone https://github.com/ginuerzh/gost.git && cd gost/cmd/gost && go build. Alternatively, pull the Docker image: docker run --rm ginuerzh/gost -V. Or install via Homebrew: brew install gost.

Daily commands: For development: cd cmd/gost && go build && ./gost -L=:8080 starts an HTTP proxy on port 8080. With forwarding: ./gost -L=:8080 -F=192.168.1.1:8081. Multi-protocol listening: ./gost -L=http2://:443 -L=socks5://:1080 -L=ss://aes-128-cfb:123456@:8338. Docker: docker run --rm -p 8080:8080 ginuerzh/gost -L=:8080.

• cmd/gost/main.go — Entry point that initializes the tunnel, loads configuration, and starts listeners—every contributor must understand the bootstrap flow
• gost.go — Core Dialer and Listener interfaces that define the tunnel abstraction; all protocol implementations extend these
• chain.go — Implements the proxy chain logic allowing multi-hop tunneling; fundamental to the multi-level forwarding feature
• handler.go — Handler interface and implementations that route inbound connections to the appropriate protocol; load-bearing dispatch layer
• node.go — Node struct encapsulates protocol type, address, and authentication; the configuration unit for all tunnel endpoints
• cmd/gost/cfg.go — Configuration parsing from JSON/CLI; critical for understanding how GOST interprets user input
• server.go — Server setup and request handling loop; bridges configuration to active listeners and handlers

Add a new proxy protocol (e.g., custom tunnel)

1. Create protocol file (e.g., myproto.go) implementing Dialer, Listener, Connector interfaces from gost.go (myproto.go)
2. Register factory in handler.go's protocol dispatcher; add case clause in handler switch statement (handler.go)
3. Add configuration parsing in cmd/gost/cfg.go to recognize the new protocol string (cmd/gost/cfg.go)
4. Create myproto_test.go with Dial/Listen cycle tests following patterns in socks_test.go (myproto_test.go)
5. Update Node type in node.go if your protocol requires new fields beyond Addr and User (node.go)

Add a new authentication method

1. Add new Authenticator implementation in auth.go following existing SimpleAuth or NoAuth patterns (auth.go)
2. Update handler.go to use the new authenticator in protocol handlers (SOCKS5/HTTP) (handler.go)
3. Add configuration parsing in cmd/gost/cfg.go to recognize auth method in JSON/CLI (cmd/gost/cfg.go)
4. Write test cases in auth_test.go validating auth success and failure paths (auth_test.go)

Add a new advanced feature (filter/obfuscation/routing rule)

1. Create feature file (e.g., myfeature.go) with a struct implementing necessary interfaces (myfeature.go)
2. Integrate into server.go or handler.go request flow; typically add as middleware or during connect phase (server.go)
3. Add config loading logic in cmd/gost/cfg.go for the new feature's parameters (cmd/gost/cfg.go)
4. Write myfeature_test.go tests verifying feature activation and correctness (myfeature_test.go)
5. Update .config/gost.json example to show the new feature in action (.config/gost.json)

• Go 1.22 — Goroutines enable lightweight concurrent tunneling; efficient for many simultaneous proxies without thread overhead
• quic-go, KCP — QUIC and KCP reduce latency for international tunnels and enable UDP-based tunneling where TCP is blocked
• TLS/mTLS (via gosocks5, tls-dissector) — Encrypts tunnel payload and metadata; resists detection and Man-in-the-Middle attacks
• pluggable-transports (PT goptlib) — Integrates Tor pluggable transports for circumvention in censored networks

• Support multiple proxy protocols (SOCKS5, HTTP, SS, SSH) in one binary

  • Why: Maximizes flexibility and backward compatibility; users can run single GOST instance for all use cases
  • Consequence: Increased binary size (~20MB) and complexity in protocol dispatch; harder to audit single-protocol security

• Chain-based multi-hop proxy via sequential Dial calls

  • Why: Simple and composable; each hop is independent; no global connection table
  • Consequence: Each hop introduces round-trip latency; connection pooling difficult; suitable for <100ms per-hop

• Configuration from JSON + CLI args (no YAML/TOML)

  • Why: Minimal dependencies; familiar to Go ecosystem
  • Consequence: No schema validation; users must learn JSON structure; harder to validate before startup

• No authentication database; only simple plaintext/no-auth

  • Why: Reduces scope; suitable for private/controlled environments
  • Consequence: Cannot scale to multi-user deployments; credentials in plaintext in config files

• Does not provide user-level permission/quota management (no rate limiting, bandwidth caps per user)
• Not a load-balancing reverse proxy; designed for outbound tunneling, not inbound service distribution
• Does not implement QUIC 0-RTT or connection migration for mobile clients
• Not a DNS server; acts as DNS client only (resolves names, does not serve)
• Does not support SOCKS v4a forward DNS (limitations in gosocks4 library)
• Does not provide WebUI or REST API for runtime configuration changes (config reload requires binary SIGHUP)

TLS certificate handling: cmd/gost/.ssl/ contains localhost certificates for development; production deployments may need custom cert management. Config file location: Examples in .config/ but actual runtime path may differ based on how main.go is invoked. Protocol scheme complexity: Each -F flag accepts protocol:// prefixes (http, socks5+wss, quic, etc.); incorrect scheme combinations may fail silently. Dependency versions: .goreleaser.yaml and go.mod specify exact versions; updating transitive dependencies (especially crypto libs) requires careful testing due to proxy's security-sensitive nature.

• Proxy chaining / multi-hop forwarding — Core feature of GOST—understanding how requests traverse sequential proxies (each -F parameter) is essential to using and extending the tool; implemented in chain.go
• SOCKS5 protocol — Primary protocol supported by GOST for client-proxy communication; includes authentication negotiation and TLS extension; critical for understanding client.go and auth.go
• TLS handshake interception / dissection — GOST uses tls-dissector dependency to inspect TLS handshakes without decrypting; enables SNI-based routing and probe-resistance features mentioned in README
• Stream multiplexing (SMUX) — Used via xtaci/smux dependency to run multiple logical connections over a single physical transport; enables efficient resource usage in proxy chains
• QUIC and KCP protocols — Alternative transport layers to TCP used in proxy chains (quic-go, xtaci/kcp-go dependencies); QUIC is zero-RTT capable, KCP is UDP-based with forward error correction—useful for unreliable networks
• Transparent proxy / iptables redirection — GOST supports TCP/UDP transparent proxy mode (mentioned in README, uses go-tproxy dependency); requires understanding of Linux kernel netfilter and how to redirect traffic at system level
• Probe resistance — GOST web proxy includes detection-avoidance for censorship probes; mentioned in README and bypass.go logic; differentiates GOST from naive proxy implementations

• v2ray/v2ray-core — Comparable multi-protocol proxy framework with similar support for HTTP/SOCKS/Shadowsocks and chaining; heavier and more feature-rich alternative
• XX-net/XX-Net — Similar tunneling proxy for circumventing network restrictions; Python-based alternative in the same problem space
• go-gost/gost — The official GOST v3 rewrite; this repo (v2) is the predecessor—v3 uses different architecture and is the current maintained version
• shadowsocks/shadowsocks-go — Shadowsocks implementation that GOST integrates; used as a dependency and reference for SS protocol support
• getlantern/lantern — Similar goal (circumventing censorship) but uses different protocols and decentralized approach; alternative in the user-facing censorship-bypass space

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 DNS resolution and hosts file parsing (dns.go)

The repo has dns.go and hosts.go modules for DNS handling and hosts file parsing, but examining the test files (dns_test.go, hosts_test.go are not visible in the partial file structure). Given the complexity of DNS tunneling features mentioned in .config/dns.txt and .config/hosts.txt, these core modules likely need expanded test coverage for edge cases like malformed entries, concurrent requests, and fallback behavior.

• [ ] Create dns_test.go with tests for DNS query forwarding, caching, and timeout handling
• [ ] Create hosts_test.go with tests for hosts file parsing, IP resolution, and wildcards
• [ ] Add tests for concurrent DNS lookups to verify thread-safety
• [ ] Test edge cases: empty files, malformed entries, IPv6 addresses, FQDN matching

Add unit tests for bypass.go route filtering logic

The bypass.go file controls traffic routing decisions (evidenced by .config/bypass.txt), but bypass_test.go likely has incomplete coverage for the glob pattern matching logic used in .config/bypass.txt. This is critical since incorrect bypass rules could leak traffic or block legitimate connections.

• [ ] Expand bypass_test.go to cover ryanuber/go-glob and gobwas/glob pattern matching
• [ ] Add tests for common bypass patterns (.local, 192.168.., domain.com)
• [ ] Test interaction between bypass rules and proxy chain decisions
• [ ] Add benchmarks for bypass rule matching performance with large rule sets
• [ ] Test case sensitivity and special character handling in patterns

Add integration tests for chain.go proxy chaining across protocol boundaries

The chain.go module implements multi-level proxy forwarding (mentioned in README), but based on the file structure, there's no visible integration test suite testing proxy chains across different protocol combinations (HTTP→SOCKS5→KCP, HTTPS→SSH tunnel, etc.). The repo has examples/ but no automated tests validating chain behavior.

• [ ] Create chain_integration_test.go with end-to-end proxy chain tests
• [ ] Test 2-3 level chains: HTTP→SOCKS5→direct, HTTPS→SSH→KCP→exit
• [ ] Validate protocol negotiation and credential passing through chains
• [ ] Test error handling: broken links, timeout propagation, authentication failures
• [ ] Add tests for bypass rules applied at different chain levels
• [ ] Reference the examples in examples/forward/ and examples/ssh/ for test patterns

• Add integration tests for chain.go covering multi-hop proxy scenarios (currently only *_test.go files exist but test coverage for proxy chaining logic is not visible); this would validate the core multi-forward feature.
• Document the .config/ example files with inline comments explaining each protocol option (http2, socks5+wss, quic, kcp, ss, etc.) and corresponding real-world use cases—currently they are bare configuration files.
• Add prometheus metrics or structured logging hooks to client.go and chain.go to help operators monitor proxy performance (latency, connection counts, protocol distribution)—useful for production deployments mentioned in the README.

• High · Hardcoded SSL/TLS Certificates and Keys in Repository — cmd/gost/.ssl/localhost.key, cmd/gost/.ssl/rootCA.key, cmd/gost/.ssl/localhost.crt, cmd/gost/.ssl/rootCA.crt. The repository contains hardcoded SSL/TLS certificates and private keys in cmd/gost/.ssl/ directory (localhost.key, rootCA.key, localhost.crt, rootCA.crt). These should never be committed to version control as they can be used to impersonate the service or decrypt communications. Fix: Remove all private keys and certificates from the repository. Move them to .gitignore. Generate fresh certificates at deployment time or use a secure secrets management system. Rotate all exposed certificates immediately if this is a production key.
• High · Potential Hardcoded Secrets in Configuration Files — .config/secrets.txt. The .config/secrets.txt file is present in the repository structure, which suggests sensitive credentials may be stored in plaintext or committed to version control. This violates security best practices for secret management. Fix: Remove secrets.txt from version control. Use environment variables, secure vaults (HashiCorp Vault, AWS Secrets Manager), or .gitignore for sensitive configuration. Audit git history for any exposed credentials.
• Medium · Outdated and Potentially Vulnerable Dependencies — go.mod - Multiple dependencies. Several dependencies use old or pinned versions with potential security vulnerabilities: golang.org/x/crypto v0.24.0 (consider updating to latest), golang.org/x/net v0.26.0. Additionally, some dependencies like shadowsocks-go (v0.0.0-20200409064450-3e585ff90601) appear to be unmaintained with old timestamps. Fix: Run 'go mod tidy' and update all dependencies to their latest stable versions. Perform regular security audits using 'go list -u -m all' and tools like Nancy or Snyk to identify vulnerable dependencies.
• Medium · Missing Input Validation and Injection Risk — dns.go, http.go, handler.go, auth.go. The codebase includes DNS proxy (dns.go), HTTP proxy (http.go), and SOCKS protocol handlers without obvious input validation. Potential for DNS injection, HTTP header injection, or protocol smuggling attacks if user input isn't properly validated. Fix: Implement strict input validation for all proxy protocols. Validate and sanitize DNS queries, HTTP headers, and authentication data. Use established libraries for protocol parsing rather than custom implementations.
• Medium · Insecure Docker Configuration — Dockerfile. The Dockerfile runs the application with minimal security hardening. It uses Alpine Linux (good) but doesn't implement non-root user execution, read-only filesystems, or resource limits. The application has network-facing services that could be exploited. Fix: Create a non-root user for running gost. Add 'USER nobody' or similar. Use 'RUN chmod 755 /bin/gost'. Consider adding --security-opt options in docker-compose or Kubernetes manifests. Implement resource limits and read-only root filesystem where possible.
• Medium · Exposed Port Configuration Risk — cmd/gost/cfg.go, cmd/gost/main.go, node.go. The application supports multiple proxy protocols (HTTP, HTTPS, SOCKS4, SOCKS5, KCP, QUIC) on multiple ports. No documentation visible on secure default port configurations or TLS enforcement by default. Fix: Enforce TLS/encryption for all protocols by default where applicable. Provide clear security documentation on port selection and protocol recommendations. Implement rate limiting and connection limits to prevent abuse.
• Medium · Potential Man-in-the-Middle (MITM) Risk in Chain Configuration — chain.go, relay.go. The proxy chain feature (chain.go) allows multi-hop proxying without obvious certificate pinning or authentication validation between hops. This could allow MITM attacks on chained connections. Fix: Implement certificate pinning for TLS connections in proxy chains. Add mutual TLS authentication between chain hops. Validate peer certificates and implement hostname verification.
• Low · Missing Security Headers in HTTP Proxy — undefined. The HTTP proxy implementation (http 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.