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/go-gost/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.

GO — Healthy across all four use cases

• Last commit 2w ago
• 7 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 90% of recent commits

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

What it runs against: a local clone of go-gost/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 go-gost/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 ≤ 41 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "go-gost/gost(\\.git)?\\b" \\
  && ok "origin remote is go-gost/gost" \\
  || miss "origin remote is not go-gost/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 "cmd/gost/register.go" \\
  && ok "cmd/gost/register.go" \\
  || miss "missing critical file: cmd/gost/register.go"
test -f "cmd/gost/program.go" \\
  && ok "cmd/gost/program.go" \\
  || miss "missing critical file: cmd/gost/program.go"
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"
test -f "gost.yml" \\
  && ok "gost.yml" \\
  || miss "missing critical file: gost.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 41 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~11d)"
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/go-gost/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 tunneling and proxy framework written in Go that supports multiple protocols (SOCKS5, HTTP, Shadowsocks, etc.) chained together for flexible network routing. It handles forward proxying, port forwarding, reverse proxies with intranet penetration, TCP/UDP transparent proxying, DNS resolution/proxying, TUN/TAP devices, and load balancing—all configurable via YAML files and Web APIs. Single binary layout: cmd/gost/main.go is entry point, cmd/gost/register.go handles protocol registration, cmd/gost/program.go manages daemon lifecycle. Core logic outsourced to github.com/go-gost/core (v0.3.3) and github.com/go-gost/x (v0.9.0) packages. Config loaded from gost.yml using YAML. E2E tests under tests/e2e/ with testdata fixtures.

Network engineers and DevOps teams needing flexible tunnel/proxy solutions for internal network penetration, protocol bridging, and cross-network forwarding; developers integrating proxy capabilities into Go applications via the modular core/x packages.

Production-ready: the project has comprehensive feature parity with v2, active CI/CD via GitHub Actions (.github/workflows/buildx.yml, release.yml), Docker support, end-to-end tests (tests/e2e/main_test.go), and multiple companion tools (gostctl GUI, gost-ui WebUI). Large feature set and plugin system indicate stable architecture.

Moderate risk: depends on github.com/go-gost/core and github.com/go-gost/x (external owned packages), deep dependency tree (Gin, Prometheus, Redis, iptables bindings), and networking complexity. Single maintainer community risk typical for open-source tunnel projects; breaking changes possible across major versions.

Active development on v3 branch with plugin system, Web API expansion, and load balancing features. CI pipelines in .github/workflows/ automate multi-platform Docker builds (buildx.yml) and releases (release.yml). Recent additions include parallel selector tests (tests/e2e/parallel_selector_test.go) and nightly trigger workflow.

git clone https://github.com/go-gost/gost.git && cd gost/cmd/gost && go build Or: bash <(curl -fsSL https://github.com/go-gost/gost/raw/master/install.sh) --install Or Docker: docker run --rm gogost/gost -V

Daily commands: make build (inferred from Makefile) or cd cmd/gost && go build -o gost && ./gost -c gost.yml. Docker: docker build -t gost . && docker run -v /path/to/gost.yml:/etc/gost/gost.yml gost

• cmd/gost/main.go — Entry point for the GOST application; initializes the tunnel and loads configuration.
• cmd/gost/register.go — Registers protocol handlers and components; essential for understanding which tunneling protocols are available.
• cmd/gost/program.go — Core program lifecycle management; handles startup, shutdown, and configuration reloading.
• go.mod — Declares critical dependencies on go-gost/core and go-gost/x; defines the module's external API surface.
• gost.yml — Example configuration file demonstrating the YAML schema for listeners, services, and chains.
• tests/e2e/main_test.go — End-to-end test suite; validates tunnel functionality and protocol behavior.
• Dockerfile — Container build definition; shows deployment and runtime environment setup.

• main.go (Entry Point) (Go stdlib, judwhite/go-svc) — Bootstraps the application, loads configuration, and orchestrates the program lifecycle.
  • Failure mode: Panics on bad config or permission errors; logs to stderr and exits with non-zero code.
• register.go (Component Registration) (go-gost/core, go-gost/x) — Dynamically registers protocol handlers, services, and middleware from go-gost/core and go-gost/x into the runtime.
  • Failure mode: Silent omission of unregistered protocols; undefined protocol names in config fail at listener startup.
• program.go (Lifecycle Management) (Go channels, context, signal handling) — Manages startup sequence, graceful shutdown, configuration reloading, and listener lifecycle.
  • Failure mode: Slow shutdown if connections don't close; configuration reload may drop in-flight tunnels.
• Listener Layer (go-gost/core) (TCP/UDP sockets, protocol handlers) — Accepts incoming connections and dispatches them to service handlers; enforces protocol negotiation.
  • Failure mode: Port bind failures prevent startup; protocol mismatches close connections abruptly.
• Service Layer (go-gost/x) (go-gost/core interfaces, TLS, AEAD ciphers) — Implements protocol-specific tunnel establishment (SOCKS, HTTP, Shadowsocks); routes traffic through forwarding chains.
  • Failure mode: Encryption/decryption errors drop connections; unreachable targets cause tunnel timeouts.
• Forwarding Chain (go-gost/core connector interface) — Chains multiple proxy hops (via go-gost/core chain abstraction); enables multi-level indirection.
  • Failure mode: Chain hop failures cascade; no automatic failover without explicit selector.

• Client → Listener (go-gost/core) — Inbound TCP/UDP connection request

Add Support for a New Tunneling Protocol

1. Implement the protocol handler in go-gost/x (external repo), or if using existing handlers, register it (cmd/gost/register.go)
2. Add protocol configuration examples to the default YAML schema (gost.yml)
3. Create end-to-end tests validating the new protocol's tunnel operations (tests/e2e/main_test.go)
4. Update README with protocol documentation and examples (README.md)

Extend the Configuration System

1. Modify the YAML schema and parsing in gost.yml to support new config fields (gost.yml)
2. Update program.go to load and apply the new configuration fields during startup (cmd/gost/program.go)
3. Add integration tests validating the new configuration is properly parsed and applied (tests/e2e/main_test.go)

Add a New Load-Balancing or Selector Strategy

1. Implement the selector logic (likely in go-gost/core as an abstraction) (cmd/gost/register.go)
2. Add configuration examples for the new selector strategy (gost.yml)
3. Write parallel and concurrent load tests (tests/e2e/parallel_selector_test.go)

• Go 1.25.0 — Compiled language providing high concurrency (goroutines) and low overhead for tunnel proxying; cross-platform compilation simplifies deployment.
• go-gost/core — Provides abstract interfaces for services, handlers, listeners, and protocol chains; decouples registration from implementation.
• go-gost/x — Reference implementations of tunneling protocols (SOCKS, HTTP, Shadowsocks, etc.); modular protocol ecosystem.
• YAML configuration — Human-readable tunnel definition language; supports multi-level forwarding chains and dynamic service binding.
• Docker multi-stage builds — Minimal production images; compiled Go binary requires no runtime dependencies.

• Modular protocol registration via go-gost/x

  • Why: Allows users to pick which protocols to compile in; reduces binary bloat for constrained environments.
  • Consequence: Core logic separated from implementations; requires understanding two repos (core + x) to add protocols.

• YAML configuration over CLI flags

  • Why: Enables complex multi-chain topologies and dynamic reloads without restarting.
  • Consequence: Configuration file is required; less convenient for minimal one-off tunnels compared to pure CLI tools.

• Synchronous tunnel establishment

  • Why: Simpler error reporting and connection lifecycle tracking.
  • Consequence: Connection latency is visible to clients; no pre-warming or connection pooling at the protocol layer.

• Authentication and authorization beyond protocol-level validation (delegated to protocol implementations)
• Encryption of all tunnel traffic (user must select TLS/Shadowsocks-enabled protocols)
• Persistent connection state or recovery after process restart
• Real-time metrics streaming (only Prometheus scrape endpoint)
• Windows service integration beyond basic Windows support (uses judwhite/go-svc but limited)

1. Protocol registration in register.go must match service chains in YAML config, or handlers silently fail. 2) TUN/TAP and transparent proxy features require root/admin privileges and iptables on Linux. 3) Plugin system (go-gost/plugin v0.2.1) requires .so compilation; cross-platform plugins non-trivial. 4) Config hot-reload via fsnotify.Watcher may miss rapid file changes; restart often safer. 5) Load balancing 'selector' behavior undefined if all upstreams fail (check e2e tests for fallback logic).

• Protocol chaining — Core GOST feature; allows composing multiple proxies (e.g., SOCKS5 → HTTP → Shadowsocks) in series; understanding chain order and protocol compatibility is essential for config
• Selector (load balancing) — GOST uses selector patterns to distribute traffic across multiple upstreams; parallel_selector_test.go tests concurrent routing behavior
• Transparent proxy (iptables redirect) — GOST can intercept kernel-level traffic via iptables (go-iptables v0.5.0); critical for TCP/UDP redirect mode without per-app proxy config
• TUN/TAP virtual interfaces — GOST can create virtual network adapters for system-wide traffic interception; advanced feature requiring kernel-level networking knowledge
• Token bucket rate limiting — Limiter concept in GOST controls bandwidth/RPS; used for traffic shaping in high-load scenarios
• Reverse proxy tunneling (intranet penetration) — GOST can expose internal services via outbound-only tunnels; enables NAT traversal without opening inbound ports
• Plugin architecture — go-gost/plugin (v0.2.1) allows dynamic handler loading at runtime; critical for extending GOST without recompilation

• go-gost/core — Core tunnel engine and interfaces; required dependency that defines Dialer, Listener, Handler abstractions
• go-gost/x — Extended protocol implementations (HTTP, SOCKS5, Shadowsocks); provides builtin handlers registered in register.go
• go-gost/gostctl — Official GUI control panel for GOST; uses Web API endpoints exposed by gost daemon
• go-gost/gost-ui — Official WebUI dashboard; frontend for real-time config and monitoring of running GOST instances
• shadowsocks/shadowsocks-go — Reference Shadowsocks implementation in Go; GOST integrates via go-gost/go-shadowsocks2 (v0.1.2)

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 end-to-end tests for core protocol chains (SOCKS5/HTTP/Shadowsocks)

The repo has a tests/e2e directory with only parallel_selector_test.go. Given that GOST supports multiple protocol chains (SOCKS5, HTTP, Shadowsocks, etc.), there are no visible e2e tests validating multi-protocol chaining—a core feature. This is critical for a tunnel project where protocol compatibility is essential.

• [ ] Create tests/e2e/protocol_chain_test.go with test cases for SOCKS5→HTTP, SOCKS5→Shadowsocks, and HTTP→SOCKS5 chains
• [ ] Add testdata/protocol_chain/ directory with YAML configs for each chain variant (similar to testdata/parallel_selector/server.yaml)
• [ ] Validate request routing and response handling through multi-hop chains in each test
• [ ] Integrate into tests/e2e/Dockerfile to run alongside existing e2e tests

Add CI workflow for cross-platform binary testing (Linux/macOS/Windows)

The .github/workflows directory has buildx.yml (Docker) and release.yml, but no workflow testing actual binary execution on different OS platforms. Given the repo supports TUN/TAP and transparent proxying (platform-specific features), cross-platform testing in CI is necessary to catch OS-specific bugs before release.

• [ ] Create .github/workflows/test-matrix.yml with matrix strategy for ubuntu-latest, macos-latest, windows-latest
• [ ] Build GOST binaries for each platform using cmd/gost/main.go and run basic smoke tests (e.g., gost --version, listener startup)
• [ ] Add platform-specific tests for TUN/TAP (skip on Windows if not applicable, test on Linux/macOS)
• [ ] Ensure tests run before release.yml is triggered (add as dependency in workflow)

Add integration tests for DNS proxy feature with caching validation

The README highlights DNS resolution and DNS proxy as features, but there are no visible tests validating DNS proxy behavior, caching, or fallback resolution. This is a high-value feature that requires validation to ensure reliability.

• [ ] Create tests/e2e/dns_proxy_test.go with tests for DNS query forwarding, response caching, and multiple resolver fallback
• [ ] Add testdata/dns_proxy/ directory with server.yaml config demonstrating DNS listener setup and resolver chain
• [ ] Test cache hit/miss scenarios and verify TTL handling in responses
• [ ] Validate upstream resolver failover (if configured with multiple resolvers in go-gost/x)

• Add comprehensive unit tests for cmd/gost/register.go protocol handler registration; currently only e2e tests exist in tests/e2e/, so unit coverage of handler binding is missing.
• Document YAML schema for gost.yml with JSON Schema or OpenAPI spec; many config fields are self-evident but nested listeners/chains/plugins lack formal schema.
• Add missing error handling examples to tests/e2e/utils.go helper functions; currently test utils lack panic recovery, making test failures hard to debug.

• High · Outdated Go Version in Dockerfile — Dockerfile, line 3. The Dockerfile specifies golang:1.26-alpine3.23, which appears to be a future/unreleased version. This could indicate either a typo (should be 1.25 or similar) or use of an untested Go version. Using unreleased or incorrect language versions can introduce unexpected vulnerabilities and compatibility issues. Fix: Update to a stable, currently-supported Go version (1.23 or later). Verify the correct version against official Go releases at golang.org. Consider using a specific patch version (e.g., golang:1.23.4-alpine3.23) rather than minor versions.
• Medium · Permissive Binary Compression Error Handling — Dockerfile, lines 9 and 19. The Dockerfile uses '|| echo "upx not found"' and '|| true' to suppress UPX compression failures silently. This can mask build errors and result in uncompressed binaries being deployed unknowingly, potentially affecting intended binary size and performance characteristics. Fix: Either ensure UPX is available and handle failures explicitly, or remove the silent fallback. If binary compression is optional, document this clearly. Use explicit error handling: 'upx --best gost || (echo "Warning: UPX compression failed" && exit 1)'.
• Medium · Outdated Alpine Base Image — Dockerfile, line 21. Alpine 3.23 may have known vulnerabilities. The image tag should be regularly updated to include security patches. No image digest pinning is used, allowing tag mutations. Fix: Pin to specific Alpine patch versions using SHA256 digest: 'FROM alpine:3.23@sha256:...' and regularly scan for and apply security updates. Use tools like Trivy or Grype to identify CVEs in base images.
• Medium · Missing Security Headers and Best Practices in Container — Dockerfile (general configuration). The Docker image is configured to run with default permissions. The Dockerfile does not explicitly run as a non-root user, which is a security best practice. This increases the blast radius if the application is compromised. Fix: Add a non-root user and switch to it before running the application: 'RUN addgroup -S appgroup && adduser -S appuser -G appgroup' and 'USER appuser'. This limits privilege escalation risks.
• Medium · Dependency Version Pinning Issues — go.mod (all dependencies). The go.mod file uses github.com/go-gost/core v0.3.3 and github.com/go-gost/x v0.9.0 without explicit security audit records visible. Several transitive dependencies are indirect and may have untracked vulnerabilities. Fix: Run 'go list -json -m all | nancy' or use 'govulncheck ./...' to identify known vulnerabilities. Maintain an updated dependency tree and regularly audit with 'go mod tidy' and 'go mod verify'. Consider using 'go mod graph' to visualize dependency chains.
• Low · Incomplete Dependency List in Analysis — go.sum (truncated). The provided go.sum output is truncated ('github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 // indi'), making it impossible to verify all transitive dependency versions and checksums. Fix: Review the complete go.sum file to ensure all dependencies have valid checksums. Verify no unused or suspicious dependencies are present.
• Low · No Runtime Security Policies Defined — Dockerfile and deployment configuration. The Dockerfile and configuration lack explicit security policies such as seccomp profiles, AppArmor policies, or SELinux configurations for container runtime hardening. Fix: Define and apply seccomp profiles and AppArmor/SELinux policies appropriate for the tunnel application. Example: Use Docker security options like '--security-opt=no-new-privileges:true'.
• Low · Missing HEALTHCHECK Directive — Dockerfile. The Dockerfile does not include a HEALTHCHECK instruction, making it difficult to detect container failures and unhealthy states in orchestration systems. Fix: Add a HEALTHCHECK directive to validate the tunnel is

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.