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/cyfdecyf/cow 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

• 9 active contributors
• BSD-2-Clause licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 3y ago
• ⚠ Single-maintainer risk — top contributor 85% 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 cyfdecyf/cow repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/cyfdecyf/cow.

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

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-2-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-2-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-2-Clause" \\
  || miss "license drift — was BSD-2-Clause 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 "main.go" \\
  && ok "main.go" \\
  || miss "missing critical file: main.go"
test -f "proxy.go" \\
  && ok "proxy.go" \\
  || miss "missing critical file: proxy.go"
test -f "config.go" \\
  && ok "config.go" \\
  || miss "missing critical file: config.go"
test -f "parent_proxy.go" \\
  && ok "parent_proxy.go" \\
  || miss "missing critical file: parent_proxy.go"
test -f "site_blocked.go" \\
  && ok "site_blocked.go" \\
  || miss "missing critical file: site_blocked.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 1217 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1187d)"
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/cyfdecyf/cow"
  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).

COW (Climb Over the Wall) is an HTTP proxy server written in Go that automatically detects blocked websites and routes them through parent proxies while direct-connecting to accessible sites. It supports SOCKS5, HTTP, Shadowsocks, and COW protocol as secondary proxies, with built-in site classification and PAC generation to minimize latency for unrestricted domains. Monolithic Go binary (~182KB code): core proxy logic in proxy.go/http.go, parent proxy management in parent_proxy.go, site classification in site_blocked.go/site_direct.go/sitestat.go, config parsing in config.go with platform-specific variants (config_unix.go, config_windows.go), authentication in auth.go, and PAC generation in pac.go/pac.js.

Chinese users and IT administrators needing transparent proxy solutions to bypass network restrictions; developers in restricted regions who want automatic fallback proxy behavior without manual per-site configuration.

Moderately mature: at v0.9.8 with active Travis CI, comprehensive config examples (doc/sample-config/rc), unit tests throughout (auth_test.go, config_test.go, http_test.go, etc.), and develop branch workflow established. However, last visible commit date not in metadata suggests potentially stalled—verify recency on GitHub directly before production use.

Single maintainer (cyfdecyf) with no visible dependency management files (no go.mod in file list—likely pre-Go 1.11 or modules not yet committed). Geopolitical sensitivity: codebase explicitly targets bypassing network censorship, which may have legal implications in some jurisdictions. No visible open issue backlog data; review GitHub issues directly.

No recent PR or activity data visible in file metadata; repo appears in maintenance mode. Develop branch explicitly mentioned as accepting PRs, but trunk (master) shows v0.9.8 changelog entry without visible subsequent activity.

Clone: git clone https://github.com/cyfdecyf/cow.git && cd cow. Install: go build (no go.mod indicates pre-modules; may need go get for deps). Run: ./cow (uses ~/.cow/rc config on Linux or rc.txt on Windows). For quick test: ./cow -h to see CLI options.

Daily commands: go build -o cow creates executable. Start proxy: ./cow (Linux/macOS) or cow.exe (Windows). Config lives at ~/.cow/rc (Unix) or rc.txt in COW directory (Windows). Visit http://127.0.0.1:7777/pac for PAC after startup (port configurable via listen = in rc).

• main.go — Entry point that initializes the proxy server, loads configuration, and starts listening for connections—essential for understanding the application lifecycle.
• proxy.go — Core proxy logic handling HTTP requests, response routing, and forwarding decisions—the heart of request processing.
• config.go — Configuration parsing and validation that defines how COW behaves; contributors must understand the config schema and how settings affect routing.
• parent_proxy.go — Manages parent proxy connections (SOCKS5, HTTP, shadowsocks) used for blocked sites—critical for the upstream proxy abstraction.
• site_blocked.go — Detection logic for blocked sites; directly influences which requests use parent proxies—core to COW's intelligent routing.
• http.go — HTTP protocol handling, request/response parsing, and CONNECT tunneling—implements the HTTP proxy specification.
• conn_pool.go — Connection pooling and reuse for efficiency; affects performance and resource management across all proxy operations.

Add support for a new parent proxy type

1. Define the proxy type constant and connection struct in parent_proxy.go, following the ProxyServer interface pattern (parent_proxy.go)
2. Implement the proxy connection logic (dial, auth, request forwarding) in the same file or a dedicated file (e.g., proxy_type.go) (parent_proxy.go)
3. Update config.go to parse the new proxy type from the rc config file (config.go)
4. Add a test case in config_test.go and/or proxy_test.go to validate parsing and basic connectivity (config_test.go)

Improve site blocking detection

1. Review the current detection strategy in site_blocked.go (likely probes and timeout-based heuristics) (site_blocked.go)
2. Add new detection rules or refine existing probes (e.g., add DNS checks, change timeouts) (site_blocked.go)
3. Optionally update site_direct.go to pre-classify additional known-good sites (site_direct.go)
4. Add test cases in sitestat_test.go to ensure detection accuracy for known blocked/direct sites (sitestat_test.go)

Add a new configuration option

1. Add the option field to the Config struct in config.go and document its purpose in a comment (config.go)
2. Add parsing logic in the parseConfig() function to read the option from the rc file (config.go)
3. Use the new config option in the relevant proxy or site classification logic (e.g., proxy.go or site_blocked.go) (proxy.go)
4. Add a test case in config_test.go to validate parsing of the new option (config_test.go)

Optimize connection pooling or timeout handling

1. Analyze current pool strategy in conn_pool.go and measure bottlenecks with stat.go metrics (conn_pool.go)
2. Adjust pool size limits, eviction policies, or timeout thresholds in conn_pool.go (conn_pool.go)
3. Optionally refine timeout calculation in estimate_timeout.go based on collected statistics (estimate_timeout.go)
4. Add benchmark tests in conn_pool_test.go to measure performance improvements (conn_pool_test.go)

1. Config file path differs by OS: ~/.cow/rc (Unix) vs. rc.txt in exe directory (Windows)—easy to misplace config. 2) Requires manual 'blocked' and 'direct' files for per-site overrides (no separate subdirectory; files live in same dir as config). 3) PAC URL must be explicitly configured or discovered from listen address—browsers don't auto-detect. 4) Timeout learning (estimate_timeout.go) requires traffic baseline; first blocked-site detection may fail and require manual retry. 5) No built-in HTTPS certificate pinning—vulnerable to MITM by ISP proxies that intercept CONNECT. 6) Shadowsocks and COW parent protocols require matching cipher/auth on both ends—typos silently fail.

• PAC (Proxy Auto-Config) Script Generation — COW dynamically generates PAC files (pac.go, pac.js) to tell browsers which sites bypass the proxy—critical for performance, as direct sites avoid proxy overhead
• Transparent Proxy / Intercept Proxy — COW acts as a man-in-the-middle (listening on 127.0.0.1:7777) that decides per-request whether to use direct or parent proxy—requires understanding TCP/IP layer interception vs. SOCKS forwarding
• CONNECT Tunneling (HTTP CONNECT Method) — COW must handle HTTPS via CONNECT tunneling in http.go—browser sends 'CONNECT host:443' and COW either tunnels directly or through parent proxy
• Connection Pooling with Timeout Heuristics — conn_pool.go + estimate_timeout.go manage reusable connections and learn per-site timeouts—blocked sites timeout differently than direct sites, enabling automatic detection
• Shadowsocks Protocol (AEAD Cipher Streams) — COW supports Shadowsocks as parent proxy; requires understanding streaming cipher modes (aes-128-cfb, aes-256-gcm) and how COW wraps SS clients
• Site Classification / Bloom Filter Optimization — sitestat.go + site_blocked.go use domain blacklist + runtime stats to classify sites—early blocking decisions (site_blocked.go) save connection attempts on known-blocked domains
• SOCKS5 Protocol Implementation — COW both accepts SOCKS5 clients (for client-side tool integration) and connects via SOCKS5 parent proxies—requires stateful protocol parsing in proxy.go

• shadowsocks/shadowsocks-go — COW uses Shadowsocks as one secondary proxy option; this is the Go implementation of the SS protocol COW wraps
• clowwindy/goproxy — Go proxy library that inspired COW's automatic site detection approach—similar problem of smart routing without user configuration
• golang/net — Go standard library network package—COW relies entirely on stdlib HTTP/SOCKS5 rather than external proxy libs
• v2fly/v2ray-core — Modern successor ecosystem for proxy routing; users may migrate from COW to V2Ray for more granular rule-based routing
• getlantern/lantern — Alternative circumvention tool with different philosophy (P2P fallback); addresses same user need with different architecture

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 test coverage for site_blocked.go and site_direct.go

These files manage critical functionality for detecting blocked/direct sites but lack corresponding _test.go files. Given the proxy's core feature is automatic site classification, testing the site detection logic is essential. This would catch regressions in blocking detection and PAC generation.

• [ ] Create site_blocked_test.go with tests for site blocking detection logic
• [ ] Create site_direct_test.go with tests for direct site classification
• [ ] Add test cases for edge cases: domain variations, internationalized domains, subdomains
• [ ] Verify interaction between site_blocked.go and sitestat.go (already has tests)
• [ ] Test the data structures in site_blocked.go and site_direct.go for correctness

Add unit tests for parent_proxy.go and proxy configuration loading

parent_proxy.go handles multi-proxy failover and load balancing (per README), which is critical infrastructure, but has no _test.go file. Combined with config.go's complexity (platform-specific variants: config_unix.go, config_windows.go), comprehensive testing would prevent proxy routing failures.

• [ ] Create parent_proxy_test.go to test proxy selection, failover, and load balancing logic
• [ ] Add tests for proxy parsing and validation in config.go
• [ ] Test SOCKS5, HTTP, shadowsocks, and cow-protocol proxy parsing (mentioned in README)
• [ ] Test multi-proxy scenarios with failure simulation
• [ ] Ensure config_unix.go and config_windows.go platform-specific logic is covered

Migrate from Travis CI to GitHub Actions with Go module support

.travis.yml exists but Go modules and modern CI practices have evolved since this project's active period. GitHub Actions provides better integration, caching, and matrix testing across Go versions and OS platforms (already evident in main_unix.go/main_windows.go split). This improves contributor experience and catches issues earlier.

• [ ] Create .github/workflows/test.yml to replace .travis.yml with Go test matrix (Go 1.15+)
• [ ] Add cross-platform matrix: runs-on: [ubuntu-latest, macos-latest, windows-latest]
• [ ] Include build verification for both unix and windows variants (proxy_unix.go, proxy_windows.go)
• [ ] Add golangci-lint or go vet step for code quality checks
• [ ] Test the build.sh script validation in script/build.sh within the workflow
• [ ] Keep .travis.yml but add deprecation notice pointing to Actions workflow

• Add unit tests for conn_pool.go—file exists but has no conn_pool_test.go counterpart; implement connection pooling edge cases (eviction, timeout, reuse).
• Document platform-specific setup in README: create separate Getting Started sections for Windows exe taskbar integration (cow-taskbar.exe, cow-hide.exe) vs. Linux init.d script vs. macOS plist—currently scattered across doc/init.d and doc/osx.
• Implement missing proxy type validation in config.go—currently accepts proxy URLs without strong validation; add tests for malformed proxy strings (bad cipher names for Shadowsocks, missing credentials, invalid protocols).

• High · Potential Unvalidated HTTP Proxy Forwarding — proxy.go, http.go, parent_proxy.go. As an HTTP proxy server that forwards requests to parent proxies (HTTP, SOCKS5, shadowsocks), there is risk of request smuggling, header injection, or unvalidated forwarding of client requests. The proxy.go and http.go files likely handle request parsing and forwarding, which could be vulnerable if not properly validating and sanitizing requests before forwarding. Fix: Implement strict HTTP request validation, sanitize headers before forwarding, implement request smuggling protections (RFC 7230 compliance), validate Content-Length and Transfer-Encoding headers, and use well-tested HTTP libraries with security patches.
• High · Automatic Proxy Detection Logic Bypass — site_blocked.go, site_direct.go, sitestat.go. The automatic detection of blocked sites (site_blocked.go) and direct sites (site_direct.go) could be exploited through DNS spoofing, timing attacks, or logic flaws to force sites through unintended proxy paths. An attacker could manipulate the detection mechanism to route sensitive traffic incorrectly. Fix: Implement cryptographic verification of site blocking status, use secure DNS with DNSSEC validation, add rate limiting on detection mechanisms, implement logging/alerting for unusual detection patterns, and consider whitelisting critical sites rather than auto-detection.
• High · Hardcoded Configuration and Potential Credential Exposure — auth.go, config.go, doc/sample-config/rc, doc/sample-config/rc-en. Configuration files (doc/sample-config/rc, doc/sample-config/rc-en) and auth.go suggest authentication handling. If credentials or sensitive proxy configurations are stored in plaintext config files or hardcoded in code, they could be exposed in backups, version control, or log files. Fix: Never hardcode credentials; use secure configuration management (environment variables, encrypted config files). Implement proper credential storage with encryption at rest. Review auth.go for secure password handling (use bcrypt/argon2, not plaintext). Remove sample configs from version control or ensure they contain no real credentials.
• Medium · Unencrypted Proxy Communication — proxy.go, http.go, parent_proxy.go, ssh.go. The proxy supports multiple parent proxy protocols (HTTP, SOCKS5, shadowsocks). Communication between COW and parent proxies, and potentially between clients and COW if using HTTP (not HTTPS), transmits data unencrypted, exposing traffic inspection and man-in-the-middle attacks. Fix: Enforce TLS/HTTPS for client connections to COW. For parent proxy communication, use encrypted protocols (HTTPS, SOCKS5 with TLS). Implement certificate pinning for critical parent proxies. Add support for secure proxy protocols like HTTP/2 over TLS.
• Medium · Missing Input Validation on PAC Generation — pac.go, pac.js. pac.go and pac.js generate Proxy Auto-Config files dynamically. If user-controlled input (hostnames, proxy configurations) is not properly sanitized before JavaScript generation, it could lead to JavaScript injection attacks affecting clients using the PAC file. Fix: Implement strict input validation and output encoding for all variables inserted into pac.js. Use a templating engine that auto-escapes JavaScript contexts. Validate hostnames against RFC specifications. Consider delivering PAC with proper Content-Type and security headers.
• Medium · Unvalidated Parent Proxy Configuration — config.go, config_test.go, parent_proxy.go. Configuration parsing in config.go may not properly validate parent proxy URLs/addresses. Malformed or malicious proxy configurations could cause denial of service, connection leaks, or unexpected behavior. Fix: Implement strict validation of parent proxy configurations including URL parsing, port range validation (1-65535), and protocol verification. Add configuration schema validation. Implement timeout and connection pool limits to prevent resource exhaustion.
• Medium · Inadequate Logging of Security Events — log.go, auth.go, sitestat.go. While log.go exists, the codebase may not implement comprehensive security event logging (failed auth attempts, unusual proxy routing, errors in detection logic), making incident detection and forensics difficult. Fix: Implement detailed security event logging including authentication attempts, proxy route decisions, detection mechanism anomalies

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.