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/netchx/netch 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 the board

• Last commit 4d ago
• 11 active contributors
• Distributed ownership (top contributor 40% of recent commits)
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

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

What it runs against: a local clone of netchx/netch — 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 netchx/netch | 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 main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 34 days ago | Catches sudden abandonment since generation |

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

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

# 4. Critical files exist
test -f "Netch/Program.cs" \\
  && ok "Netch/Program.cs" \\
  || miss "missing critical file: Netch/Program.cs"
test -f "Netch/Controllers/MainController.cs" \\
  && ok "Netch/Controllers/MainController.cs" \\
  || miss "missing critical file: Netch/Controllers/MainController.cs"
test -f "Netch/Models/Server.cs" \\
  && ok "Netch/Models/Server.cs" \\
  || miss "missing critical file: Netch/Models/Server.cs"
test -f "Netch/Interfaces/IController.cs" \\
  && ok "Netch/Interfaces/IController.cs" \\
  || miss "missing critical file: Netch/Interfaces/IController.cs"
test -f "Netch/Models/Modes/Mode.cs" \\
  && ok "Netch/Models/Modes/Mode.cs" \\
  || miss "missing critical file: Netch/Models/Modes/Mode.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 34 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~4d)"
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/netchx/netch"
  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).

Netch is a Windows proxy client that intercepts and routes traffic through multiple protocols (Shadowsocks, Trojan, VMess, VLESS, WireGuard, SOCKS5) using kernel-level drivers (Netfilter, WinTUN, WinPcap/Npcap). It supports process-specific routing, LAN sharing, and virtual adapter modes, currently in v2.0 development after clearing v1.0 codebase. Monolithic C# WinForms desktop app: Controllers/ handles protocol/driver abstraction (MainController, NFController, TUNController, DNSController), Forms/ contains all UI (MainForm, SettingForm, ServerForm, subscription/mode editors), Models inferred from protocol enums, with native C/C++ shims for driver communication. .github/workflows orchestrate builds.

Windows users in regions with network restrictions who need transparent proxy routing for specific applications or system-wide traffic, and developers maintaining proxy protocol implementations or network interception tools.

The project is actively under major reconstruction — the README explicitly states v1.0 code was cleared for v2.0 preparation, indicating a breaking redesign in progress. CI/CD is present (.github/workflows/build.yml, release.yml), but the current state is pre-release. Approach production use cautiously until v2.0 stabilizes.

High risk: (1) v2.0 is mid-rewrite with v1.0 fully cleared, so documentation and backward compatibility are uncertain; (2) depends on low-level Windows drivers (Netfilter, WinTUN, WinPcap) requiring admin rights and OS version specificity; (3) heavy C# + C++ hybrid codebase (336KB C#, 68KB C++) increases surface for native interop bugs; (4) no visible test directory in top 60 files suggests weak test coverage.

Active v2.0 refactor with codebase wipe. Build and release automation pipelines are in place (.github/workflows/), indicating ongoing CI setup. Dependabot monitoring enabled. No commit history visible, but issue templates translated to Chinese (bug_report.zh-CN.yml, feature_request.zh-CN.yml) suggest international user base growth.

git clone https://github.com/netchx/netch.git
cd netch
# Open Netch.sln in Visual Studio (requires .NET 6.0 x64)
# Build: dotnet build Netch.sln
# Run: dotnet run --project Netch/Netch.csproj
# (Requires elevated/admin privileges for driver access)

Daily commands:

cd netch
dotnet build Netch.sln -c Release
# Then launch Netch/bin/Release/Netch.exe (requires admin)
# Or: dotnet run --project Netch/Netch.csproj --configuration Release

• Netch/Program.cs — Entry point for the application; all contributors must understand how the app bootstraps and initializes.
• Netch/Controllers/MainController.cs — Core orchestration logic for proxy lifecycle (start/stop/status); essential for understanding control flow.
• Netch/Models/Server.cs — Base model for proxy server abstraction; foundational for all protocol implementations.
• Netch/Interfaces/IController.cs — Interface contract for all controllers; defines the fundamental abstraction layer for extensibility.
• Netch/Models/Modes/Mode.cs — Base class for proxy modes (ProcessMode, TunMode, ShareMode); critical for understanding mode architecture.
• Netch/Global.cs — Global state and settings management; essential for understanding application-wide configuration.
• Netch/Forms/MainForm.cs — Main UI form and user interactions; entry point for UI layer developers.

Add a new proxy protocol (e.g., new server type)

1. Create a new server class inheriting from Server.cs in Models/ (Netch/Models/Server.cs)
2. Implement IServerController to define startup/shutdown logic for the protocol (Netch/Interfaces/IServerController.cs)
3. Register the new type in the JSON converter's type discriminator (Netch/JsonConverter/ServerConverterWithTypeDiscriminator.cs)
4. Add a ServerForm or configuration UI in Forms/ to expose protocol-specific settings (Netch/Forms/ServerForm.cs)
5. Update MainController.cs to instantiate the new controller when the server type is selected (Netch/Controllers/MainController.cs)

Add a new proxy mode (traffic interception method)

1. Create a new mode class inheriting from Mode.cs in Models/Modes/ (Netch/Models/Modes/Mode.cs)
2. Implement IModeController to define Start/Stop/Reload for the mode (Netch/Interfaces/IModeController.cs)
3. Register the new mode type in the JSON converter's type discriminator (Netch/JsonConverter/ModeConverterWithTypeDiscriminator.cs)
4. Create a mode editor form in Forms/ModeForms/ for user configuration (see ProcessForm.cs as example) (Netch/Forms/ModeForms/ProcessForm.cs)
5. Update MainController to instantiate and manage the new mode controller (Netch/Controllers/MainController.cs)

Add a new settings option or configuration field

1. Add the property to Setting.cs in Models/Settings/ (Netch/Models/Settings/Setting.cs)
2. Add UI controls to SettingForm.cs to allow user configuration (Netch/Forms/SettingForm.cs)
3. Bind the UI control to the Setting property via data binding (Netch/Forms/SettingForm.Designer.cs)
4. If needed, use the setting in the appropriate controller (MainController.cs or mode-specific controller) (Netch/Controllers/MainController.cs)

Add a new traffic routing rule or bypass list

1. Extend the mode model (e.g., ProcessMode.cs) to include rule definitions (Netch/Models/Modes/ProcessMode/ProcessMode.cs)
2. Update the mode editor form (e.g., ProcessForm.cs) to display and edit rules (Netch/Forms/ModeForms/ProcessForm.cs)
3. Implement rule parsing/evaluation in the mode controller (e.g., NFController.cs) (Netch/Controllers/NFController.cs)
4. Use RouteHelper.cs or Redirector.cs interop to apply rules at the kernel level (Netch/Interops/RouteHelper.cs)

Admin requirement: All driver modes (ProcessMode, TunMode, ShareMode) require Windows administrator privileges — app will silently fail without it. Driver versions: WinTUN/WinPcap/Npcap versions must match .NET 6.0 x64 ABI expectations; x86 binaries or mismatched driver versions cause crashes. DNS port conflicts: DNSController assumes port 53 is free; VPNs or other DNS services will block startup. .NET 6.0 mandatory: Project targets net6.0-windows only — older .NET Framework or .NET Core versions will not load. No offline mode: Protocol parsing may require live internet for subscription updates (SubscriptionForm.cs) — test offline first.

• Transparent Proxy / Network Interception — Core feature of ProcessMode and TunMode — understanding how kernel drivers intercept packets before the OS network stack processes them is essential to Netch's entire value proposition
• Netfilter (Linux iptables equivalent on Windows) — NFController.cs implements Windows-side traffic filtering and redirection using Netfilter driver — you must understand packet filtering rules to debug process routing
• Virtual Network Adapter / TUN (Tunnel Interface) — TunMode creates a synthetic network interface via WinTUN to capture all traffic — architectural foundation for system-wide proxying without per-process config
• DNS Spoofing / DNS Hijacking — DNSController intercepts DNS queries to prevent leaks and redirect them through the proxy — critical for GFW circumvention (DNS is often the weakest point)
• SOCKS Protocol (SOCKS5) — SOCKS5 is the common wire protocol Netch clients speak to backends; understanding SOCKS5 framing (handshake, auth, relay) is prerequisite for adding custom protocol handlers
• WinPcap / Npcap (Packet Capture Library) — Used by ShareMode (PcapController.cs inferred) to sniff and redirect LAN traffic — requires understanding of raw socket programming and packet assembly
• UDP Full Cone NAT — Netch advertises UDP NAT FullCone support as a feature — requires understanding of NAT traversal and connection-less protocol routing through proxy intermediaries

• v2ray/v2ray-core — Reference implementation for VMess/VLESS protocol parsing and routing — Netch wraps these as protocol backends
• shadowsocks/shadowsocks-windows — Alternative Shadowsocks-only Windows proxy client with similar driver integration patterns (Netfilter, TUN) — architectural inspiration
• trojan-gfw/trojan — Core Trojan protocol reference — Netch implements Trojan as one of its supported proxying protocols
• wireguard/wireguard-windows — WireGuard official Windows client — Netch integrates WireGuard alongside other protocols; shares TUN driver architecture
• nmap/npcap — WinPcap/Npcap successor used by Netch's ShareMode for packet capture and LAN-based proxying

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 Controllers (DNSController, TUNController, NFController)

The Controllers directory contains critical proxy logic (DNSController.cs, TUNController.cs, NFController.cs, MainController.cs) but there are no visible test files in the repo. Given this is a 2.0 rewrite in preparation, adding comprehensive unit tests for controller initialization, state transitions, and error handling would improve reliability and make future refactoring safer.

• [ ] Create Netch.Tests project in Netch.sln
• [ ] Write unit tests for DNSController lifecycle (Start/Stop/Restart)
• [ ] Write unit tests for TUNController with mock WinTUN driver interactions
• [ ] Write unit tests for NFController (Netfilter) process interception logic
• [ ] Add test for MainController orchestration of sub-controllers
• [ ] Configure GitHub Actions workflow (.github/workflows/test.yml) to run on PR

Complete and document the Mode system architecture (ProcessMode, ShareMode, TunMode)

The README shows three modes (ProcessMode, ShareMode, TunMode) but the description for TunMode is incomplete ('Use WinTUN driver to creat...'). Additionally, ModeForms exist but there's no architecture documentation explaining how modes relate to controllers and server types. Add detailed docs with examples.

• [ ] Complete the TunMode description in README.md with full feature list
• [ ] Create docs/MODES.md explaining ProcessMode (Netfilter), ShareMode (WinPcap/Npcap), and TunMode (WinTUN) architectures
• [ ] Document how IModeController interface (Netch/Interfaces/IModeController.cs) maps modes to controllers
• [ ] Add code examples showing mode selection flow from MainForm.cs to controller instantiation
• [ ] Document the relationship between ModeEditorUtils.cs and mode configuration persistence

Add GitHub Actions workflow for dependency vulnerability scanning and Go module updates

The repo has Go dependencies (aiodns module with golang.org/x/net, golang.org/x/sys) that are pinned to outdated versions (2021). There's a dependabot.yml but no active workflow for Go module scanning. Add automated checks to detect vulnerabilities and enable automated PRs for safe updates.

• [ ] Review current .github/dependabot.yml and ensure Go ecosystem is enabled
• [ ] Create .github/workflows/go-security.yml using github.com/securego/gosec to scan Go code
• [ ] Add nancy vulnerability check step for Go dependencies in the workflow
• [ ] Create .github/workflows/go-updates.yml to check for outdated Go modules and create update PRs
• [ ] Document in CONTRIBUTING.md how Go dependencies are managed and tested

• Add unit tests for DNSController.cs: File exists but no test directory visible; add xUnit tests for DNS hijacking edge cases (IPv6, EDNS, port conflicts) to prevent silent DNS leaks.
• Document driver installation steps in README: Currently minimal; contributors should add platform-specific WinTUN/WinPcap setup instructions with version requirements and troubleshooting (drivers are common failure point).
• Implement missing mode validation in MainController.cs: Add pre-flight checks (admin rights, driver availability, port binding) with user-facing error messages instead of silent failures — especially critical for v2.0 UX.

• High · Outdated Go Dependencies with Known Vulnerabilities — Dependencies/aiodns/go.mod. The aiodns module uses golang.org/x/net v0.0.0-20210226172049-e18ecbb05110 and golang.org/x/sys v0.0.0-20210303074136-134d130e1a04, which are from early 2021. These versions contain known security vulnerabilities including CVE-2021-21239 (x/net) and CVE-2021-25736 (x/sys). These are indirect dependencies for DNS operations and could be exploited for denial of service or other attacks. Fix: Update golang.org/x/net and golang.org/x/sys to their latest stable versions. Run 'go get -u golang.org/x/net golang.org/x/sys' and rebuild the aiodns module.
• High · Outdated DNS Library Dependency — Dependencies/aiodns/go.mod. The miekg/dns library v1.1.43 is from 2021 and may contain known vulnerabilities. DNS libraries are critical components as they handle untrusted network input and are frequently targeted for attacks. Fix: Update github.com/miekg/dns to the latest stable version (currently 1.1.50+). This ensures security patches for DNS protocol handling are applied.
• Medium · Potential Insecure Deserialization in JSON Converters — Netch/JsonConverter/ModeConverterWithTypeDiscriminator.cs, Netch/JsonConverter/ServerConverterWithTypeDiscriminator.cs. Custom JSON converters with type discriminators (ModeConverterWithTypeDiscriminator.cs, ServerConverterWithTypeDiscriminator.cs) are present. These can be vulnerable to insecure deserialization attacks if they accept untrusted input without proper validation, particularly when loading modes or server configurations from external sources. Fix: Review the JSON converter implementations to ensure: (1) Type discriminators are whitelisted, not dynamically resolved, (2) Input validation is performed on all deserialized objects, (3) Consider using JsonSerializerOptions with restricted type handling.
• Medium · Potential Privilege Escalation via Driver Loading — Netch/Controllers/TUNController.cs, Netch/Controllers/PcapController.cs, Netch/Controllers/NFController.cs, Netch/Interops/tun2socks.cs. Multiple driver-related controllers (TUNController, PcapController, NFController) suggest the application loads and interacts with system drivers. This is a Windows proxy client that appears to use kernel-level drivers (WinTUN, Netfilter, WinPcap/Npcap). Improper driver loading, verification, or path handling could lead to privilege escalation. Fix: Verify that: (1) Drivers are loaded from protected system paths only, not from user-writable directories, (2) Driver signatures are validated before loading, (3) No DLL injection vulnerabilities exist in interop code, (4) Consider requiring administrator confirmation before driver operations.
• Medium · Potential Network Interception and Man-in-the-Middle Risks — Netch/Controllers/UpdateChecker.cs, Netch/Forms/SubscriptionForm.cs, Netch/Models/GitHubRelease/. As a proxy client handling network traffic, the application may be vulnerable to MITM attacks if proxy certificates are not properly validated or if the proxy connection itself is not secured. UpdateChecker and SubscriptionForm suggest remote updates/configurations are downloaded. Fix: Ensure: (1) All remote downloads use HTTPS with certificate pinning, (2) GitHub API calls validate TLS certificates, (3) Subscription configurations are downloaded securely, (4) Digital signatures verify downloaded content integrity, (5) No downgrade attacks are possible.
• Medium · Potential Code Injection via Route/Process Configuration — Netch/Forms/ModeForms/RouteForm.cs, Netch/Forms/ModeForms/ProcessForm.cs, Netch/Interops/RouteHelper.cs. RouteForm.cs and ProcessForm.cs allow users to define routes and process rules. If these are not properly validated, they could be used to inject malicious commands or configurations, especially if they interact with system commands. Fix: Implement strict input validation and sanitization for: (1

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.