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/shadowsocks/shadowsocks-go 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

• 25+ active contributors
• Distributed ownership (top contributor 23% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 6y ago

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

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

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.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 "shadowsocks/proxy.go" \\
  && ok "shadowsocks/proxy.go" \\
  || miss "missing critical file: shadowsocks/proxy.go"
test -f "shadowsocks/encrypt.go" \\
  && ok "shadowsocks/encrypt.go" \\
  || miss "missing critical file: shadowsocks/encrypt.go"
test -f "cmd/shadowsocks-server/server.go" \\
  && ok "cmd/shadowsocks-server/server.go" \\
  || miss "missing critical file: cmd/shadowsocks-server/server.go"
test -f "cmd/shadowsocks-local/local.go" \\
  && ok "cmd/shadowsocks-local/local.go" \\
  || miss "missing critical file: cmd/shadowsocks-local/local.go"
test -f "shadowsocks/config.go" \\
  && ok "shadowsocks/config.go" \\
  || miss "missing critical file: shadowsocks/config.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 2249 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2219d)"
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/shadowsocks/shadowsocks-go"
  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).

shadowsocks-go is a Go port of the Shadowsocks tunnel proxy protocol, enabling clients to bypass firewalls by routing traffic through encrypted socks5 proxies. It implements the Shadowsocks protocol with support for multiple encryption methods (AES-CFB, ChaCha20, RC4-MD5, etc.) and can operate as both client (shadowsocks-local) and server (shadowsocks-server), maintaining protocol compatibility with the original Python/Node.js implementations. Monolithic structure: shadowsocks/ is the core package (encryption, config, networking primitives); cmd/shadowsocks-server/ and cmd/shadowsocks-local/ are thin CLI wrappers around the core; cmd/shadowsocks-httpget/ is a utility tool. Tests live alongside source in _test.go files; sample configs are in sample-config/ and deb/ contains Debian packaging.

Network engineers and users in censored regions who need a lightweight, encrypted tunnel; also Go developers maintaining legacy Shadowsocks infrastructure (though the project explicitly directs new users to the newer go-shadowsocks2).

This project is deprecated and no longer actively maintained — the README explicitly redirects users to go-shadowsocks2. Version 1.2.2 is the last release, Travis CI shows passing builds, but there is no recent commit activity visible. It was production-grade when active but should not be used for new deployments.

High risk for new use: The codebase is explicitly deprecated with an active redirect to a successor project. No current security patches, and cryptographic primitives (RC4, table encryption) are already marked as deprecated/insecure within the code itself. Single-maintainer risk is extreme — this is a personal port that is no longer maintained by the original Shadowsocks team.

Nothing — this is a deprecated, archived project. The last activity points users to go-shadowsocks2 (https://github.com/shadowsocks/go-shadowsocks2). No active PRs, issues, or development.

# Clone the repo (for historical/learning reasons only)
git clone https://github.com/shadowsocks/shadowsocks-go.git
cd shadowsocks-go

# Build client and server
go build -o shadowsocks-local ./cmd/shadowsocks-local
go build -o shadowsocks-server ./cmd/shadowsocks-server

# Run with config
./shadowsocks-local -c config.json
./shadowsocks-server -c config.json

Daily commands:

# Server (requires config.json with server_port, password, method)
./shadowsocks-server

# Client (requires config.json with server, server_port, local_port, password, method)
./shadowsocks-local
# Then configure browser SOCKS5 proxy to 127.0.0.1:local_port

• shadowsocks/proxy.go — Core proxy connection handling and request routing logic that implements the shadowsocks protocol—every network interaction flows through here.
• shadowsocks/encrypt.go — Encryption/decryption implementation using various ciphers; security-critical for the entire tunnel abstraction.
• cmd/shadowsocks-server/server.go — Entry point for the server binary that initializes listeners, config parsing, and main event loop.
• cmd/shadowsocks-local/local.go — Entry point for the client binary that sets up local SOCKS/HTTP proxy listeners and upstream connections.
• shadowsocks/config.go — Configuration parsing and server/client setup—required to understand how settings flow into the runtime.
• shadowsocks/conn.go — Low-level connection wrapper managing protocol framing, cipher state, and I/O operations.
• shadowsocks/udp.go — UDP relay implementation for non-TCP traffic, a distinct protocol path from the main TCP proxy.

• shadowsocks-local (client) — Listens on localhost SOCKS port, accepts client requests, establishes

Add a new cipher algorithm

1. Define the cipher struct and parameters in shadowsocks/encrypt.go (NewCipher function) (shadowsocks/encrypt.go)
2. Implement encryption/decryption methods following the Cipher interface (Encrypt/Decrypt methods) (shadowsocks/encrypt.go)
3. Register the cipher name in the cipherMap and add key derivation logic (shadowsocks/encrypt.go)
4. Add unit tests for the new cipher in shadowsocks/encrypt_test.go (shadowsocks/encrypt_test.go)

Add multi-server failover logic to the client

1. Modify the server selection logic in cmd/shadowsocks-local/local.go to iterate through configured servers on connection failure (cmd/shadowsocks-local/local.go)
2. Update the connection retry logic in shadowsocks/proxy.go to fall back to next server on error (shadowsocks/proxy.go)
3. Add server health status tracking (optional) in shadowsocks/config.go (shadowsocks/config.go)

Add a new authentication or obfuscation layer

1. Create a new file (e.g., shadowsocks/obfuscate.go) with obfuscation logic separate from encryption (shadowsocks/obfuscate.go)
2. Integrate the obfuscation into the Conn Read/Write methods in shadowsocks/conn.go after/before cipher operations (shadowsocks/conn.go)
3. Add config parsing for the obfuscation method in shadowsocks/config.go (shadowsocks/config.go)
4. Add comprehensive tests in shadowsocks/conn_test.go to verify obfuscation does not break protocol (shadowsocks/conn_test.go)

• Go language — Goroutines enable concurrent connection handling without heavyweight threads; single binary deployment simplifies distribution; cross-platform compilation reduces build complexity.
• SOCKS5 protocol on client side — Standard proxy protocol supported by most applications (browsers, curl, etc.); avoids need for custom client libraries.
• Stream cipher (RC4, AES-CFB) instead of block cipher — Avoids padding overhead on packet streams; lower latency and computational cost for real-time proxy use.
• Leaky bucket buffer pool (leakybuf.go) — Reduces GC pressure for high-volume concurrent connections by reusing allocated buffers.

• Stateless, per-connection encryption without session resumption

  • Why: Simpler implementation; no server-side state management required
  • Consequence: Each new connection must re-negotiate encryption; higher CPU cost on reconnect

• Multi-server failover in client, ordered by config

  • Why: Client-side load distribution without coordinator; simple failover on first server failure
  • Consequence: No true load balancing; all traffic goes to first server until it fails; no health checks

• Synchronous UDP relay (blocking per packet)

  • Why: Simpler implementation than async event loop
  • Consequence: UDP throughput and latency worse than TCP under high packet rate

• No protocol versioning or capability negotiation

  • Why: Lighter protocol overhead; simpler server/client compatibility model
  • Consequence: Requires explicit version alignment in docs; harder to add new features backward-compatibly

• Not a real-time audio/video relay—designed for general TCP traffic tunneling.
• Does not provide authentication or per-user access control—relies on shared password/cipher.
• Does not handle DNS queries natively—applications must resolve names locally or via tunnel.
• Not intended for Windows as a primary platform—no native service installation (deprecated).
• Does not support TLS/HTTPS on the tunnel itself—relies on application-level encryption.

Cgo disabled by default: go build must not have cgo enabled (README warns about DNS lookup thread explosion). Config format is strict JSON: trailing commas will fail silently. IV/salt handling: each connection reads IV from first N bytes (N depends on cipher block size), wrong size breaks decryption. Multi-server mode on client: servers are tried in order per README 0.6.2 note, not round-robin. Deprecated encryption: RC4 and table methods are marked insecure in code but still functional — avoid in production. No graceful shutdown: sends data until socket closes, doesn't flush pending buffers.

• CFB mode (Cipher Feedback) — Shadowsocks-go defaults to AES-128-CFB for encryption — understanding stream cipher modes vs block ciphers is essential to grasp why CFB turns AES into a stream cipher and why IV handling matters
• EVP_BytesToKey key derivation — Both server and client must derive the same cipher key+IV from password using this OpenSSL-compatible function — implemented in config.go but not clearly documented, critical for interop
• SOCKS5 protocol — Shadowsocks-local acts as a SOCKS5 server accepting client connections — understanding SOCKS5 handshake (addr parsing, auth negotiation) is needed to modify client-side code
• Leaky bucket / buffer pool — leakybuf.go implements a memory pool to reduce GC pressure — understanding this pattern is important for optimizing concurrent proxy relays handling thousands of connections
• IV (Initialization Vector) per-connection — Each encrypted connection starts with a random IV prepended to ciphertext — critical security practice to prevent plaintext recovery; conn.go reads this, must be understood for protocol correctness
• Goroutine-per-connection concurrency model — Both server and local client spawn a goroutine per accepted TCP connection — understanding Go's lightweight threading and potential resource limits is crucial when debugging high-connection scenarios
• Shadowsocks protocol framing — The wire format (address + port + payload, all encrypted) is non-standard — conn.go implements address parsing and framing; modifying relay behavior requires deep understanding of this format

• shadowsocks/go-shadowsocks2 — Official successor to this project — actively maintained, modernized Go implementation with cleaner API
• clowwindy/shadowsocks — Original Python Shadowsocks implementation — this Go port maintains protocol compatibility with it
• shadowsocks/shadowsocks-libev — C library implementation of Shadowsocks — lightweight alternative with wider language bindings
• v2ray/v2ray-core — Modern proxy framework supporting Shadowsocks protocol among many others — used by users who need more features than vanilla Shadowsocks
• shadowsocks/ShadowsocksR — Shadowsocks fork with additional obfuscation features — historical alternative branch for evasion-focused users

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 UDP relay tests for shadowsocks/udprelay.go

The repo has shadowsocks/udprelay.go and shadowsocks/udp.go but no corresponding test files (no udprelay_test.go or udp_test.go). UDP is a critical protocol for shadowsocks performance. Adding unit tests would catch regressions in relay logic, connection handling, and edge cases like timeout scenarios.

• [ ] Create shadowsocks/udprelay_test.go with tests for UDP packet relay logic
• [ ] Create shadowsocks/udp_test.go with tests for UDP connection pooling and cleanup
• [ ] Test edge cases: malformed packets, timeout handling, concurrent connections
• [ ] Ensure tests run in CI via .travis.yml (already present but may need UDP test additions)

Add integration tests for multi-server client configurations in cmd/shadowsocks-local/

The repo has sample configs for multi-server scenarios (sample-config/client-multi-server.json and testdata/deprecated-client-multi-server.json), but no integration tests validating that the local client correctly distributes traffic across multiple servers or handles server failover. This is a core feature gap.

• [ ] Create cmd/shadowsocks-local/local_integration_test.go
• [ ] Add test cases for: parsing multi-server config, connecting to first available server, fallback to next server on failure
• [ ] Reference sample-config/client-multi-server.json for test configurations
• [ ] Integrate test execution into script/test.sh

Add platform-specific build/test targets to Makefile and CI for Windows compatibility

The repo has script/win32build.bat and script/shadowsocks.exe but the Makefile lacks explicit Windows build targets, and .travis.yml only tests on Linux/macOS. This creates a risk where Windows builds silently break. Adding cross-platform build validation ensures the Windows port stays functional.

• [ ] Update Makefile with explicit windows-386 and windows-amd64 build targets using GOOS=windows GOARCH=<arch>
• [ ] Add AppVeyor or GitHub Actions CI workflow (e.g., .github/workflows/windows-build.yml) to test Windows builds on every PR
• [ ] Verify script/win32build.bat references match the Makefile targets
• [ ] Test that cmd/shadowsocks-server/server.go and cmd/shadowsocks-local/local.go compile without cgo on Windows

• Add comprehensive tests for shadowsocks/udprelay.go — currently no udprelay_test.go exists, leaving UDP relay untested despite being part of the protocol spec
• Document the IV/salt derivation process in code comments — conn.go reads raw bytes from stream but the EVP_BytesToKey algorithm is not explained; would help future maintainers
• Create a MIGRATION.md guide explaining how to upgrade from shadowsocks-go to go-shadowsocks2 — config format and CLI flags likely differ but no migration docs exist

This codebase presents significant security concerns primarily due to its deprecated status and lack of active maintenance. The project explicitly recommends migration to go-shadowsocks2 and will not receive security updates. While no obvious code-level vulnerabilities are evident from the static analysis, the use of deprecated dependencies, outdated build infrastructure, and lack of ongoing security audits makes this unsuitable for production use. The implementation of cryptographic functions in unmaintained code is particularly concerning. Organizations should migrate to the actively maintained alternative immediately.

• High · Deprecated Project - No Active Maintenance — README.md, Repository Status. The repository is explicitly marked as deprecated in the README with a recommendation to use 'go-shadowsocks2' instead. This means the codebase is no longer actively maintained and will not receive security updates or patches for newly discovered vulnerabilities. Fix: Migrate to the actively maintained shadowsocks/go-shadowsocks2 repository. Do not use this deprecated version in production environments.
• High · Cryptographic Implementation in Legacy Codebase — shadowsocks/encrypt.go. The project implements cryptographic functions (shadowsocks/encrypt.go, shadowsocks/encrypt_test.go) in a deprecated codebase that is no longer audited or maintained. Cryptographic implementations require continuous scrutiny for security vulnerabilities and best practices. Fix: Migrate to go-shadowsocks2 which has more recent cryptographic implementations. If staying with this version, conduct a thorough security audit of encryption routines.
• Medium · Potential Information Disclosure via Sample Configuration — sample-config/, deb/etc/shadowsocks/. Sample configuration files (sample-config/client-multi-server.json, sample-config/server-multi-port.json, deb/etc/shadowsocks/config.json) may contain sensitive defaults or example credentials that could be accidentally committed or exposed. Fix: Ensure all sample configuration files do not contain real credentials or sensitive data. Use placeholder values only. Add clear warnings in README about not using sample configs in production.
• Medium · Hardcoded Configuration and Testdata — config.json, shadowsocks/testdata/. The repository contains configuration files and testdata (config.json, shadowsocks/testdata/) that may be used in ways that expose configuration management issues. Deprecated projects often have stale or insecure defaults. Fix: Review all default configurations for security best practices. Use environment variables for sensitive configuration instead of files. Ensure testdata does not contain real credentials.
• Medium · Outdated Build and Deployment Scripts — script/, .travis.yml. Build scripts (script/build.sh, script/createdeb.sh, script/win32build.bat) and CI configuration (.travis.yml) are part of a deprecated project and may use outdated build tools, Go versions, or security practices. Fix: If this project must be used, verify that build scripts use current Go versions and security practices. Consider moving to modern CI/CD platforms with automated security scanning.
• Low · No Visible Input Validation Documentation — shadowsocks/config.go, shadowsocks/proxy.go. While no obvious SQL injection or XSS vulnerabilities are present (as this is a proxy tool, not a web application), the absence of documented input validation and sanitization practices in a networking tool handling untrusted data is concerning. Fix: Document and review input validation for configuration parsing and network packet handling. Ensure all external inputs are properly validated and sanitized.
• Low · No Visible Security Headers or Best Practices Documentation — README.md, Documentation. The codebase lacks visible documentation regarding security best practices, threat models, or security considerations for users deploying this tool. Fix: Add a SECURITY.md file documenting security practices, known limitations, and deployment recommendations. Note that this is a deprecated project.

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.