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/v2ray/v2ray-core 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 2w ago
• 11 active contributors
• Distributed ownership (top contributor 36% of recent commits)
• MIT licensed
• CI configured
• Tests present

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

What it runs against: a local clone of v2ray/v2ray-core — 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 v2ray/v2ray-core | 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 | Last commit ≤ 45 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "v2ray/v2ray-core(\\.git)?\\b" \\
  && ok "origin remote is v2ray/v2ray-core" \\
  || miss "origin remote is not v2ray/v2ray-core (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"

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

V2Ray Core is a modular platform for building network proxy applications that bypass geolocation and network restrictions. It provides composable inbound/outbound protocol handlers (SOCKS, HTTP, Shadowsocks, VMess, VLESS), a central dispatcher routing engine, and DNS resolution with DoH support to construct custom proxy chains. The core is a Go daemon exposing gRPC APIs for dynamic control via the Commander app. Monolithic modular structure: app/ contains major services (dispatcher, commander, dns, router). Transport protocols live in transport/ (TCP, UDP, WebSocket, QUIC). Inbound/outbound proxies in proxy/ (socks, http, shadowsocks, vmess, vless, trojan). Shared utilities in common/, net/, and serial/. All proto definitions use protobuf (*.proto → *.pb.go). The entire binary compiles to a single statically-linked executable.

Network engineers, privacy-focused developers, and system administrators building proxy infrastructure who need protocol-agnostic routing, dynamic configuration, and multi-layer obfuscation capabilities without relying on monolithic VPN software.

Production-ready and actively maintained (moved to v2fly org in 2020). Strong CI/CD with GitHub Actions for testing, linting, code analysis, and automated geo-file updates. ~1.4M lines of Go code with comprehensive test coverage (codecov badge present). Recent commits indicate ongoing development and security patching.

Moderate risk: core dependencies (gRPC, QUIC, protobuf) are actively maintained, but the project depends on 16+ Go packages with varying maintenance levels. The codebase is large (1.48M Go lines) making breaking changes harder to track. Migrate to v2fly/v2ray-core happened; this v2ray/v2ray-core repo is legacy—new development occurs at v2fly. No single-maintainer risk visible but ecosystem fragmentation is a concern.

Repository is marked as archived; active development moved to v2fly/v2ray-core. This legacy repo still has workflows for testing (test.yml), linting (.golangci.yml), CodeQL analysis, and geo-file updates (updateGeofile.yml), indicating some maintenance. No active PRs visible in current state, focus is on v2fly fork.

git clone https://github.com/v2ray/v2ray-core.git && cd v2ray-core && go mod download && go build -o v2ray ./main

Daily commands: go run ./main to execute the core daemon. Configure via JSON/Protobuf config file passed as argument. No built-in dev server; this is a daemon. Use 'go test ./...' to run test suite. Makefile or shell scripts in .dev/ may provide convenience targets.

• app/dispatcher/default.go: Core routing engine that dispatches connections to outbound handlers based on inbound protocol and rules
• app/commander/service.go: gRPC service definition for dynamic control of V2Ray daemon (add/remove inbounds, modify routes)
• app/dns/dns.go: DNS resolution with support for DoH, rule-based splitting, and integration with routing engine
• proxy/*/inbound.go: Protocol-specific inbound listeners (SOCKS5, HTTP, Shadowsocks, VMess, VLESS, Trojan) — main entry point for client connections
• transport/*/conn.go: Transport layer implementations (TCP, UDP, WebSocket, QUIC, KCP) that abstract underlying network mechanics
• common/protocol/: Shared protocol utilities and type definitions (User, Account, SecurityPolicy) used across inbound/outbound modules

Inbound protocol handlers: proxy//inbound.go. Outbound routing: app/dispatcher/default.go. New transport: transport//conn.go. DNS resolution: app/dns/dns.go. gRPC services: app/commander/service.go. Always regenerate protos with .dev/protoc/{linux,macos,windows}/protoc after editing *.proto files. Tests co-located as *_test.go files next to implementation.

Protobuf regeneration required: modifying .proto files demands running .dev/protoc//protoc manually—Go code generation is not automatic. Starlark script support for routing rules adds complexity; malformed scripts silently fail. The legacy status (repo archived, dev moved to v2fly) means PRs here may be ignored—new features should target v2fly/v2ray-core. gRPC listener must be explicitly configured in config; disabled by default. Environment variable support minimal; all configuration is file-based JSON/Protobuf.

• Protocol Buffers (protobuf) — V2Ray's entire config serialization, gRPC service definitions, and cross-module data exchange rely on .proto files compiled to Go code; understanding proto schema is essential for modifying config structures
• gRPC — Commander app and all dynamic control APIs use gRPC for client-daemon communication; any feature requiring runtime reconfiguration goes through gRPC service definitions in app/commander/
• Connection Routing / Switching (Dispatcher Pattern) — V2Ray's core value is the dispatcher engine (app/dispatcher/) that examines inbound connection metadata (protocol, source IP, domain, SNI) and routes to appropriate outbound handler—this is the essential routing logic
• SOCKS5 / HTTP Proxy Protocols — proxy/socks/ and proxy/http/ implement standard SOCKS5 and HTTP CONNECT tunneling that clients connect to; understanding these protocols is prerequisite for extending inbound handlers
• VMess Protocol (V2Ray proprietary) — proxy/vmess/ implements V2Ray's custom encrypted tunnel protocol with account/user abstraction; core to understanding V2Ray's security model vs standard proxies
• Transport Multiplexing (TCP, UDP, QUIC, WebSocket) — transport/ abstracts network layer allowing protocols to run over multiple transports; QUIC and WebSocket support enables proxy over restrictive networks (HTTP-only, UDP-blocked)
• DNS Hijacking / Rule-based DNS Splitting — app/dns/ implements conditional DNS resolution (split routing for specific domains) critical for blocking ads, bypassing geolocation, and routing to appropriate outbound proxies based on query domain

• v2fly/v2ray-core — Official maintained fork—this v2ray/v2ray-core is archived; all new development and issues should go to v2fly/v2ray-core
• XTLS/Xray-core — Community fork adding REALITY obfuscation and improved VLESS protocol; shares protocol design with V2Ray but diverges on TLS implementation
• shadowsocks/shadowsocks-ng — Alternative proxy platform focused on Shadowsocks protocol; V2Ray's shadowsocks handler can interoperate but Shadowsocks-ng is simpler single-protocol implementation
• gost/gost — Another Go proxy toolkit with similar protocol modularity (SOCKS, HTTP, Shadowsocks); lighter weight and more minimal than V2Ray
• trojan-gfw/trojan — Trojan protocol specification and reference implementation that V2Ray's proxy/trojan/ handler implements and interoperates with

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 unit tests for app/dispatcher/stats.go

The stats.go file in the dispatcher module lacks corresponding _test.go file (stats_test.go exists but only has minimal coverage based on the pattern). The dispatcher is a critical component for traffic routing and statistics tracking. Adding thorough unit tests would improve reliability and prevent regressions in traffic counting, monitoring, and reporting features that depend on accurate statistics.

• [ ] Review app/dispatcher/stats.go and identify all exported functions and methods
• [ ] Create comprehensive test cases for each statistic tracking function (counters, gauges, histograms)
• [ ] Add edge case tests (concurrent access, overflow conditions, nil receivers)
• [ ] Test integration between stats.go and dispatcher.go to ensure stats are properly recorded during dispatch operations
• [ ] Aim for >80% code coverage for the stats module

Add integration tests for app/dns DNS resolution pipeline

The DNS module has multiple complex components (dnscommon.go, dohdns.go, udpns.go, nameserver.go, hosts.go) with individual tests, but lacks integration tests verifying the complete DNS resolution flow. Given the security-critical nature of DNS in a proxy tool, integration tests covering fallback behavior, caching, DoH vs UDP failover, and hosts file override scenarios would significantly improve confidence.

• [ ] Create app/dns/integration_test.go for end-to-end DNS resolution tests
• [ ] Add test cases for: standard UDP resolution, DoH resolution, hosts file matching, nameserver failover chains
• [ ] Test timeout and error handling across the full pipeline (app/dns/server.go → nameserver.go → udpns.go/dohdns.go)
• [ ] Add concurrent query tests to verify thread-safety and proper DNS caching behavior
• [ ] Include tests for specific scenarios like invalid DNS responses and malformed hosts entries

Add missing unit tests for app/log/command/command.go functionality

The command module (app/log/command/) has a command.go file with corresponding command_test.go, but based on the gRPC service definition in config_grpc.pb.go, the test coverage appears incomplete. The log command service is used for runtime log level adjustment and debugging, making robust testing essential for maintainability and preventing accidental breakage of operator-facing APIs.

• [ ] Review app/log/command/config_grpc.pb.go service definition to identify all gRPC methods
• [ ] Examine app/log/command/command_test.go to identify untested code paths
• [ ] Add unit tests for gRPC service methods: QueryStats, SetLogLevel, RestartLogger (if applicable)
• [ ] Add tests for error conditions: invalid log levels, non-existent loggers, concurrent command execution
• [ ] Test the integration between command service and the log.go module to verify state changes propagate correctly

• Add unit tests for app/dispatcher/stats.go—currently stats_test.go exists but coverage appears incomplete for concurrent access patterns and race conditions in the statsManager.
• Document the Starlark routing rule DSL with concrete examples in a new docs/ directory, as go.starlark.net integration is mentioned in go.mod but examples are absent from the file list.
• Implement missing protocol handler for Shadowsocks 2022 cipher (XChaCha20) in proxy/shadowsocks/—current implementation supports older ciphers but AEAD 2022 spec is not referenced.

• High · Outdated Go Dependencies with Known Vulnerabilities — go.mod - All dependencies. The go.mod file specifies Go 1.15 and multiple dependencies from 2020 that likely contain known CVEs. Notable outdated packages include: golang.org/x/crypto (Oct 2020), golang.org/x/net (Oct 2020), golang.org/x/sys (Oct 2020), google.golang.org/grpc (Aug 2020), and lucas-clemente/quic-go (Aug 2020). These versions predate critical security patches for TLS, cryptographic operations, and network handling. Fix: Update all dependencies to their latest stable versions. Particularly prioritize: golang.org/x/crypto, golang.org/x/net, golang.org/x/sys, google.golang.org/grpc, and google.golang.org/protobuf. Run 'go get -u ./...' and test thoroughly.
• High · Expired GPG Key for Security Contact — SECURITY.md - GPG Public Key Block. The SECURITY.md file lists a GPG public key (E2E35E27914FB007C0D4B6DDB117BA3BE8B494A7) that expired on 2022-01-02. This key is used for vulnerability reporting and is no longer valid. Users cannot securely encrypt vulnerability reports to the security contact. Fix: Update the GPG public key immediately with a new key that has current validity dates. Announce the key transition prominently and allow a grace period for reports with the old key.
• High · Untrusted Binary Execution in Docker Build — Dockerfile - Line: RUN git clone --progress https://github.com/v2fly/v2ray-core.git. The Dockerfile clones the entire repository directly from GitHub without verifying commit signatures or releases: 'git clone --progress https://github.com/v2fly/v2ray-core.git'. Combined with the expired GPG key, there is no cryptographic verification of the source code being built. Fix: Implement git commit signature verification in the Dockerfile. Use 'git clone' with '--verify-signatures' flag or checkout a signed release tag. Implement a multi-stage build with explicit version pinning.
• Medium · Unverified Third-Party Package: xiaokangwang/VSign — go.mod - github.com/xiaokangwang/VSign dependency. The dependency 'github.com/xiaokangwang/VSign v0.0.0-20200828155424-dc1c86b73fbf' is a third-party cryptographic signing package from an individual developer. The pseudo-version indicates it's pinned to a commit rather than a release. Little community audit trail exists for this critical cryptographic component. Fix: Audit the VSign package source code thoroughly. Consider switching to well-established, community-reviewed cryptographic libraries. If VSign is essential, request a formal release version and security audit.
• Medium · Unverified Third-Party Package: xtls/go — go.mod - github.com/xtls/go dependency. The dependency 'github.com/xtls/go v0.0.0-20201007031018-d42c13c57942' is pinned to a commit rather than a release version. This appears to be a custom TLS implementation, which is a sensitive cryptographic component that should have formal versioning and community review. Fix: Verify the xtls/go package is actively maintained. Upgrade to a tagged release version if available. Conduct a security audit of custom TLS modifications before using in production.
• Medium · Missing Build Reproducibility — Dockerfile - codename=$(git describe --abbrev=0 --tags). The Dockerfile uses 'git describe --abbrev=0 --tags' to determine the build version dynamically, but doesn't pin the exact commit SHA. This prevents build reproducibility and makes it difficult to audit exactly which code was compiled. Fix: Pin builds to specific commit SHAs or release tags. Add build metadata (timestamps, commit SHAs) to binaries for auditability. Use a reproducible build process with locked dependencies.
• Medium · Insufficient Docker Image Hardening — undefined. The final Docker image uses Alpine Linux with minimal hardening. It runs as root without explicit USER directive, and ca-certificates installation 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.