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/shadowsocksr-backup/shadowsocksr-csharp 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 7y ago

• 2 active contributors
• GPL-3.0 licensed
• Tests present
• ⚠ Stale — last commit 7y ago
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 99% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No CI workflows 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 shadowsocksr-backup/shadowsocksr-csharp repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/shadowsocksr-backup/shadowsocksr-csharp.

What it runs against: a local clone of shadowsocksr-backup/shadowsocksr-csharp — 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 shadowsocksr-backup/shadowsocksr-csharp | 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 ≤ 2617 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "shadowsocksr-backup/shadowsocksr-csharp(\\.git)?\\b" \\
  && ok "origin remote is shadowsocksr-backup/shadowsocksr-csharp" \\
  || miss "origin remote is not shadowsocksr-backup/shadowsocksr-csharp (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 "shadowsocks-csharp/Controller/ShadowsocksController.cs" \\
  && ok "shadowsocks-csharp/Controller/ShadowsocksController.cs" \\
  || miss "missing critical file: shadowsocks-csharp/Controller/ShadowsocksController.cs"
test -f "shadowsocks-csharp/Controller/Local.cs" \\
  && ok "shadowsocks-csharp/Controller/Local.cs" \\
  || miss "missing critical file: shadowsocks-csharp/Controller/Local.cs"
test -f "shadowsocks-csharp/Encryption/EncryptorFactory.cs" \\
  && ok "shadowsocks-csharp/Encryption/EncryptorFactory.cs" \\
  || miss "missing critical file: shadowsocks-csharp/Encryption/EncryptorFactory.cs"
test -f "shadowsocks-csharp/Controller/HttpProxy.cs" \\
  && ok "shadowsocks-csharp/Controller/HttpProxy.cs" \\
  || miss "missing critical file: shadowsocks-csharp/Controller/HttpProxy.cs"
test -f "shadowsocks-csharp/Encryption/IEncryptor.cs" \\
  && ok "shadowsocks-csharp/Encryption/IEncryptor.cs" \\
  || miss "missing critical file: shadowsocks-csharp/Encryption/IEncryptor.cs"

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

ShadowsocksR for Windows is a C# implementation of the ShadowsocksR proxy protocol, enabling Windows users to route traffic through encrypted SOCKS5/HTTP proxies with support for custom obfuscation and protocol layers. It provides system-wide proxy configuration, PAC (Proxy Auto-Config) file management with GFWList integration, and UDP proxying via SocksCap/ProxyCap. Monolithic C# Windows Forms application (shadowsocks-csharp.sln): core proxy logic likely in root namespace, third-party dependencies bundled directly in shadowsocks-csharp/3rd/ (zxing for QR scanning, opendns for DNS queries, SimpleJson for config parsing), with packaging scripts for release distribution.

Windows users (both .NET 2.0 and 4.0 targets) who need to circumvent network restrictions or use privacy-focused proxying; contributors interested in C# proxy implementations and Windows system proxy integration.

This is a mature but archived backup fork (note 'shadowsocksr-backup' in repo name). The original ShadowsocksR project was actively developed but the ecosystem fragmented; this C# variant targets Windows specifically and appears to have reached feature-complete status circa 2017. No recent commit dates are visible in the file list, suggesting inactive maintenance.

Single-maintainer risk (BreakWa11) with no visible continuous contribution; the 'backup' designation indicates this is not the primary maintained version. Heavy reliance on embedded third-party code (zxing QR code library, opendns library, SimpleJson) with no visible package.json-style dependency management means dependency updates are manual. Last activity date unclear, making security patch status unknown.

No active development visible. Repo is labeled 'backup' and no recent commits, PRs, or issues are shown in the file structure. This appears to be a historical snapshot or archive of the Windows C# port.

Clone the repo and open shadowsocks-csharp.sln in Visual Studio Express 2012 or later (VS2010+ can handle it): git clone https://github.com/shadowsocksr-backup/shadowsocksr-csharp.git && cd shadowsocksr-csharp && devenv shadowsocks-csharp.sln. No NuGet or npm setup required as dependencies are vendored.

Daily commands: Build via Visual Studio (F5 for Debug, or Build > Build Solution). Produces either ShadowsocksR-dotnet4.0.exe or ShadowsocksR-dotnet2.0.exe depending on target framework. Run executable to spawn system tray icon; config persists to local files (likely in AppData or program directory based on typical proxy tool patterns).

• shadowsocks-csharp/Controller/ShadowsocksController.cs — Main controller orchestrating proxy lifecycle, server management, and system integration—entry point for all core operations.
• shadowsocks-csharp/Controller/Local.cs — Local SOCKS5/HTTP proxy server implementation that handles client connections and forwards traffic through shadowsocks tunnel.
• shadowsocks-csharp/Encryption/EncryptorFactory.cs — Factory for creating cipher instances; critical for supporting multiple encryption algorithms used by shadowsocks protocol.
• shadowsocks-csharp/Controller/HttpProxy.cs — HTTP proxy handler that converts HTTP requests to SOCKS5 protocol for tunneling through shadowsocks.
• shadowsocks-csharp/Encryption/IEncryptor.cs — Interface defining encryption contract; all cipher implementations depend on this abstraction.
• shadowsocks-csharp/3rd/SimpleJson.cs — JSON serialization/deserialization for server configuration parsing and API communication.

Add a new encryption cipher

1. Create a new class implementing IEncryptor interface in shadowsocks-csharp/Encryption/ (shadowsocks-csharp/Encryption/IEncryptor.cs)
2. Register cipher in EncryptorFactory.GetEncryptor() method with name mapping (shadowsocks-csharp/Encryption/EncryptorFactory.cs)
3. Implement Encrypt(byte[] data) and Decrypt(byte[] data) methods following IV/salt patterns in IVEncryptor (shadowsocks-csharp/Encryption/IVEncryptor.cs)
4. Call native libcrypto functions via Libcrypto.cs if using C bindings (shadowsocks-csharp/Encryption/Libcrypto.cs)

Add support for a new proxy protocol

1. Create protocol handler class in shadowsocks-csharp/Controller/ (e.g., NewProtocolForwarder.cs) (shadowsocks-csharp/Controller/Socks5Forwarder.cs)
2. Implement request parsing and response generation matching protocol spec (shadowsocks-csharp/Controller/ProxySocket.cs)
3. Register in Local.cs Listener initialization to accept connections on new protocol port (shadowsocks-csharp/Controller/Local.cs)
4. Add protocol constants and route logic in ShadowsocksController configuration switch (shadowsocks-csharp/Controller/ShadowsocksController.cs)

Add a new automatic rule list (blocklist/allowlist)

1. Create rule data file in shadowsocks-csharp/Data/ (e.g., new-rules.txt) (shadowsocks-csharp/Data/cn.txt)
2. Extend GfwListUpdater to fetch and parse new rule format (shadowsocks-csharp/Controller/GfwListUpdater.cs)
3. Update PACServer to include new rules in generated proxy.pac content (shadowsocks-csharp/Controller/PACServer.cs)
4. Register rule selection option in ShadowsocksController and FileManager config (shadowsocks-csharp/Controller/FileManager.cs)

• C# / .NET Framework — Windows desktop application with native Windows Forms UI and system integration (registry, PAC, system proxy APIs)
• Native C cryptography (libcrypto.dll) — Offloads cipher operations (AES, ChaCha20, etc.) to optimized native code for performance; avoids managed cryptography overhead
• Sockets API (System.Net.Sockets) — Low-level TCP/UDP socket control needed for SOCKS5/HTTP proxy tunneling and custom protocol handling
• ZXing QR library — Enables server import/export via QR codes—common pattern in shadowsocks ecosystem for easy configuration sharing
• OpenDNS / Custom DNS — Allows DNS queries independent of system resolver; supports GFW evasion and custom rule evaluation before proxy routing

• Windows-only desktop client (not cross-platform)

  • Why: System proxy integration (PAC, registry, WinHTTP) is platform-specific; deeper integration provides better UX
  • Consequence: No Linux/macOS support; users on other platforms must use command-line or third-party clients

• Native C DLL for encryption instead of pure managed code

  • Why: Performance-critical cipher operations; native code provides ~10–50x speedup on large data volumes
  • Consequence: Adds native dependency (.dll files must ship); complicates cross-platform porting; increases attack surface for DLL injection

• Synchronous blocking socket model in Local.cs

  • Why: Simpler implementation; adequate for per-client thread model; avoids async/await complexity
  • Consequence: One OS thread per connection; does not scale to thousands of concurrent connections; fine for desktop (typical ~5–20 connections)

• GFW list stored as text files in Data/ directory

  • Why: Simple, human-readable, version-controllable; easy to debug and edit manually
  • Consequence: Not optimized for lookup speed; requires linear scan or pre-compilation; scales poorly with millions of rules

• Cross-platform support (Linux, macOS, Android, iOS); this is Windows-only
• VPN protocol support (OpenVPN, WireGuard); shadowsocks-only proxy protocol

Dual .NET targeting (.NET 2.0 and 4.0 executables) requires careful build configuration to avoid API incompatibilities (e.g., System.Net.ServicePointManager SSL settings differ). WinForms application requires Windows GUI runtime (no headless mode). Third-party libraries are embedded and vendored—no package manager available, so dependency updates require manual code patching. System proxy integration touches Windows registry/WinAPI, which has version-specific behavior on Windows 7 vs Windows 8+. PAC file modifications are written to local disk and broadcast to browsers via Windows API calls—not tested on non-English locale Windows. QR code scanning depends on camera/file input which may fail silently if no camera is available.

• SOCKS5 Protocol — The core transport protocol this proxy implements; understanding SOCKS5 handshake, authentication, and UDP handling is essential to grok how traffic is routed
• System Proxy (PAC / Direct Proxy) — This repo integrates with Windows system proxy settings and PAC files; understanding how WinHTTP reads proxy configs and browser interactions is critical for debugging integration issues
• Reed-Solomon Error Correction — Embedded zxing library uses Reed-Solomon codes to reliably decode QR codes; understanding polynomial-based error correction helps when debugging QR scanning failures
• Stream Cipher + Obfuscation — ShadowsocksR adds obfuscation layers on top of symmetric encryption; the protocol implements stream ciphers (AES, ChaCha20) with custom obfuscation protocols to evade DPI detection
• DNS-over-TCP for GFWList Updates — The opendns/ library implements DNS queries to fetch GFWList (China domain blocklist); understanding DNS wire format and TCP-based DNS is needed to extend domain filtering
• Windows WinForms Application Architecture — This is a .NET WinForms desktop app with system tray integration; understanding WinForms threading model, control lifecycle, and native Windows interop is needed for UI modifications
• GFWList and PAC Rule Matching — The PAC file is auto-updated from GFWList (blocklist of Chinese domains requiring proxy); understanding how domain regex patterns are compiled and evaluated at client-side determines which traffic routes through the proxy

• shadowsocksr/shadowsocksr — The original Python-based ShadowsocksR project that defined the protocol and obfuscation extensions this C# port implements
• shadowsocks/shadowsocks-windows — Official Shadowsocks C# Windows client; architectural sibling using similar WinForms + system proxy integration, useful for comparing protocol handling
• breakwa11/shadowsocks-rss — RSS server variant by the same maintainer (BreakWa11); complements this client for full ShadowsocksR ecosystem
• klzgrad/naiveproxy — Modern alternative to ShadowsocksR using QUIC + obfuscation; useful context for how the proxy landscape evolved post-2017
• Noto/Clash — Contemporary multi-protocol proxy framework (post-Shadowsocks era); demonstrates modern approaches to proxy routing and config management

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 OpenDNS DnsQuery and DnsResponse classes

The shadowsocks-csharp/3rd/opendns directory contains DNS query and response handling code with no corresponding test files. Given that DNS resolution is critical for proxy functionality, adding unit tests for DnsQuery.cs, DnsResponse.cs, and the ResourceRecord classes would improve reliability and catch regressions early. This is a core networking feature that should have test coverage.

• [ ] Create Tests/OpenDnsTests.cs or similar test project structure
• [ ] Add unit tests for DnsQuery.cs query construction and parsing
• [ ] Add unit tests for DnsResponse.cs response parsing for various record types (Address.cs, MX.cs, SOA.cs)
• [ ] Add unit tests for ResourceRecordCollection.cs to verify collection operations
• [ ] Ensure tests cover edge cases like malformed responses and timeout scenarios

Add unit tests for ZXing QR code encoder/decoder in shadowsocks-csharp/3rd/zxing/qrcode

The QR code functionality (encoder/decoder) is bundled but has no visible test coverage. ShadowsocksR uses QR codes for sharing server configurations. Adding tests for Encoder.cs and QRCodeReader.cs would ensure QR code generation and parsing work correctly, preventing configuration sharing failures and improving code maintainability.

• [ ] Create Tests/ZXingQRCodeTests.cs for QR code functionality
• [ ] Add tests for Encoder.cs to verify QR code generation with various data sizes
• [ ] Add tests for QRCodeReader.cs to verify QR code decoding accuracy
• [ ] Add integration tests for round-trip encoding/decoding of sample proxy configs
• [ ] Test edge cases like maximum data capacity and error correction levels (ErrorCorrectionLevel.cs)

Create GitHub Actions workflow for continuous integration and release builds

The repository has an AppVeyor badge but no visible .github/workflows directory for GitHub Actions. Creating a CI workflow would automate building, testing, and potentially signing releases. This is especially important for a security-sensitive tool like ShadowsocksR where build integrity matters. The packaging/upload.sh script suggests automated release processes exist but aren't documented in CI.

• [ ] Create .github/workflows/build.yml to build shadowsocks-csharp.sln on push/PR
• [ ] Add .NET Framework or .NET build steps appropriate for the project's target framework
• [ ] Add step to run any unit tests created (from other PRs) and fail build on test failures
• [ ] Create .github/workflows/release.yml to handle tagged releases with packaging via 7-Zip
• [ ] Document the build and release process in README.md with build status badge

• Add unit tests for SimpleJson.cs—the vendored JSON parser has no visible test coverage; writing integration tests for config serialization/deserialization would catch regressions.
• Document the exact DNS query flow in opendns/ library with inline comments—DnsQuery.cs and DnsResponse.cs lack explanation of wire format parsing, making it hard for new contributors to extend DNS features.
• Create a PROTOCOL.md file explaining the ShadowsocksR protocol extensions (obfuscation, protocol variants) that this C# implementation supports—the README focuses on UI usage, not protocol-level changes from vanilla Shadowsocks.

• High · Bundled Third-Party Libraries Without Version Management — shadowsocks-csharp/3rd/ directory. The codebase includes bundled third-party libraries (SimpleJson.cs, zxing QR code library, opendns DNS library) directly in the source tree. These are embedded dependencies that may contain known vulnerabilities and cannot be easily updated via package managers. No evidence of version tracking or dependency management is visible. Fix: Migrate to proper NuGet package management. Use package managers to track versions and receive security updates. Maintain a dependencies file (packages.config or .csproj) with pinned versions.
• High · Proxy Implementation Without Input Validation — shadowsocks-csharp/Controller/HttpProxy.cs, shadowsocks-csharp/Controller/Socks5Forwarder.cs, shadowsocks-csharp/Controller/ProxySocket.cs. Multiple proxy-related files (HttpProxy.cs, Socks5Forwarder.cs, ProxySocket.cs) handle network data without clearly visible input validation. Proxy applications are common targets for injection attacks and protocol exploitation. Fix: Implement strict input validation for all network data. Validate protocol headers, request sizes, and payload formats. Use safe parsing libraries. Implement request/response filtering.
• High · DNS Resolution Without Security Verification — shadowsocks-csharp/3rd/opendns/. Custom DNS query implementation (opendns module) is bundled and may not include DNSSEC validation or protection against DNS spoofing attacks. This is critical for a proxy application. Fix: Implement DNSSEC validation. Use system DNS APIs with security features enabled. Validate DNS responses. Consider using established DNS libraries with security audits.
• Medium · HTTP Proxy Port Forwarding Without HTTPS — shadowsocks-csharp/Controller/HttpPortForwarder.cs, shadowsocks-csharp/Controller/HttpProxyRunner.cs. HttpPortForwarder.cs and HttpProxyRunner.cs suggest HTTP-based proxying which may transmit credentials and sensitive data in plaintext. The architecture appears to support legacy HTTP proxy protocol. Fix: Enforce HTTPS/TLS for all proxy communications. Implement certificate pinning. Use secure protocols exclusively. Add warnings about unencrypted proxy usage.
• Medium · API Server Without Visible Authentication — shadowsocks-csharp/Controller/APIServer.cs. APIServer.cs is present but no visible authentication mechanism or API key validation is evident from the file structure. This could allow unauthorized access to proxy controls. Fix: Implement strong authentication (API keys, OAuth2, or mutual TLS). Validate all API requests. Implement rate limiting. Use CORS headers appropriately. Log all API access.
• Medium · Auto-Startup Functionality Without Permission Verification — shadowsocks-csharp/Controller/AutoStartup.cs. AutoStartup.cs suggests the application can auto-start, potentially with elevated privileges. No visible permission checks or user consent mechanisms. Fix: Implement explicit user consent before enabling auto-startup. Request elevated privileges only when necessary. Log privilege escalation. Allow users to easily disable auto-startup.
• Medium · QR Code Decoding Without Validation — shadowsocks-csharp/3rd/zxing/qrcode/. Bundled zxing library for QR code decoding. QR codes can contain malicious data. No visible sanitization of decoded content before use in configuration. Fix: Validate and sanitize all decoded QR code data. Implement whitelist validation for configuration parameters. Display decoded content to user before applying. Limit QR code complexity.
• Medium · GFW List Update Mechanism Without Integrity Verification — shadowsocks-csharp/Controller/GfwListUpdater.cs. GfwListUpdater.cs handles updating filtering rules from remote sources. No visible signature verification or checksum validation of downloaded lists. Fix: Implement cryptographic signature verification for downloaded lists. Use HTTPS with certificate pinning. Validate list format and content. Maintain changelog of updates.
• Medium · Logging System Without Sensitive Data — undefined. undefined 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.