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/trojan-gfw/trojan 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 2y ago

• 16 active contributors
• GPL-3.0 licensed
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 79% 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 trojan-gfw/trojan repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/trojan-gfw/trojan.

What it runs against: a local clone of trojan-gfw/trojan — 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 trojan-gfw/trojan | 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 ≤ 655 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "trojan-gfw/trojan(\\.git)?\\b" \\
  && ok "origin remote is trojan-gfw/trojan" \\
  || miss "origin remote is not trojan-gfw/trojan (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 "src/main.cpp" \\
  && ok "src/main.cpp" \\
  || miss "missing critical file: src/main.cpp"
test -f "src/core/service.h" \\
  && ok "src/core/service.h" \\
  || miss "missing critical file: src/core/service.h"
test -f "src/session/session.h" \\
  && ok "src/session/session.h" \\
  || miss "missing critical file: src/session/session.h"
test -f "src/ssl/sslsession.h" \\
  && ok "src/ssl/sslsession.h" \\
  || miss "missing critical file: src/ssl/sslsession.h"
test -f "src/proto/trojanrequest.h" \\
  && ok "src/proto/trojanrequest.h" \\
  || miss "missing critical file: src/proto/trojanrequest.h"

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

Trojan is a C++ TLS-based tunneling proxy that disguises itself as legitimate HTTPS traffic to evade active/passive detection and ISP QoS throttling targeting the Great Firewall of China. It implements multiple protocols layered over TLS (trojanrequest, SOCKS5, UDP packets) to route traffic while remaining cryptographically indistinguishable from standard HTTPS. Modular C++ architecture: src/core/ handles config parsing, logging, authentication, and service lifecycle; src/proto/ implements protocol serialization (Trojan request format, SOCKS5, UDP); src/session/ wraps clientsession.cpp (client-side tunneling) and forwardsession.cpp (server-side forwarding). CMakeLists.txt orchestrates cross-platform builds; examples/ provides sample configs for client/server/forwarding modes.

Network engineers, privacy advocates, and system administrators in censored regions who need to route TCP/UDP traffic through the GFW while maintaining plausible deniability that the connection is ordinary HTTPS traffic. Contributors are typically C++ developers familiar with networking, TLS, and cross-platform compilation.

Production-ready. The project has CI/CD via Azure Pipelines, published Docker images, systemd service files, comprehensive documentation in docs/, and a mature CMake build system supporting Linux/macOS/Windows. The presence of SECURITY.md, CONTRIBUTING.md, and structured GitHub issue templates indicates long-term maintenance discipline.

Low-risk from code structure but politically sensitive: this tool explicitly enables circumventing state-level censorship, which carries legal and operational risks in deployment jurisdictions. Dependency surface is moderate (Boost, OpenSSL, optional libmysqlclient) but OpenSSL version constraints are strict (≥1.1.0). No obvious abandonment signals; lack of granular timestamp data makes recency assessment difficult.

No specific PR or milestone data visible from file list alone. Azure Pipelines and Gitpod config indicate ongoing CI maintenance. The presence of .gitpod.yml suggests recent adoption of cloud-based development workflow. Documentation appears actively maintained (docs/README.md, protocol.md, build.md).

git clone https://github.com/trojan-gfw/trojan.git && cd trojan && mkdir build && cd build && cmake .. && make. On macOS/Linux with Homebrew: brew install cmake boost openssl; follow identical CMake steps. See docs/build.md for platform-specific details.

Daily commands: Server: trojan -c examples/server.json-example (or specify trojan.service for systemd). Client: trojan -c examples/client.json-example. Forward mode: trojan -c examples/forward.json-example. All modes run in foreground by default; fork to background or use systemd. Logs go to stdout/configured path per src/core/log.cpp.

• src/main.cpp — Entry point for the entire application; must understand how the service is initialized and configured.
• src/core/service.h — Core service abstraction managing client/server lifecycle; essential to understand the main event loop and connection handling.
• src/session/session.h — Base session class defining the contract for all connection types; critical for understanding data flow through the proxy.
• src/ssl/sslsession.h — TLS/SSL session wrapper; foundational since Trojan's core purpose is to tunnel traffic over encrypted connections.
• src/proto/trojanrequest.h — Protocol definition for Trojan requests; essential to understand how client commands are parsed and routed.
• src/core/config.h — Configuration parsing and management; required to understand how modes (client/server/forward/NAT) are selected.
• CMakeLists.txt — Build configuration for dependencies (Boost, OpenSSL, MySQL); critical for setting up the development environment.

Add a new session type (e.g., HTTP/2 multiplexing session)

1. Create a new session header in src/session/ inheriting from src/session/session.h (src/session/newsession.h)
2. Implement the session logic in newsession.cpp, overriding transfer() and close() methods (src/session/newsession.cpp)
3. Register the session factory in src/core/service.cpp's createSession() or equivalent dispatcher (src/core/service.cpp)
4. Add JSON config field to src/core/config.h and parsing logic in config.cpp to enable the new mode (src/core/config.h)
5. Document the new mode in docs/config.md and provide an example in examples/ (docs/config.md)

Add a new authentication backend (e.g., Redis or LDAP)

1. Extend src/core/authenticator.h with a new auth provider interface (src/core/authenticator.h)
2. Implement the new provider in src/core/authenticator.cpp (e.g., RedisAuthenticator class) (src/core/authenticator.cpp)
3. Add config fields for the new backend in src/core/config.h and parsing in config.cpp (src/core/config.h)
4. Update docs/authenticator.md to explain the new backend and its configuration (docs/authenticator.md)

Add a new command type to the Trojan protocol

1. Update the command enum in src/proto/trojanrequest.h and document the new command ID (src/proto/trojanrequest.h)
2. Extend the parsing logic in src/proto/trojanrequest.cpp to handle the new command (src/proto/trojanrequest.cpp)
3. Update session handling in src/session/serversession.cpp to dispatch the new command (src/session/serversession.cpp)
4. Document the new command in docs/protocol.md with wire format details (docs/protocol.md)

Add support for a new TLS cipher suite or certificate validation logic

1. Modify src/ssl/ssldefaults.cpp to register new cipher suites or validation callbacks (src/ssl/ssldefaults.cpp)
2. Update src/ssl/sslsession.cpp to invoke the new validation in handshake logic (src/ssl/sslsession.cpp)
3. Add config fields in src/core/config.h to control the new TLS behavior (src/core/config.h)
4. Document in docs/config.md under TLS settings (docs/config.md)

• C++ with Boost.Asio — High-performance async I/O for handling thousands of concurrent proxy connections with minimal CPU overhead; required for GFW evasion where detection often includes timing/behavior analysis.
• OpenSSL / TLS 1.3 — Industry-standard encryption ensures traffic is indistinguishable from legitimate HTTPS; TLS 1.3 provides forward secrecy and modern cipher suites resistant to passive monitoring.
• MySQL (optional) — Scalable credential storage for large deployments with dynamic user management; enables rate limiting and audit logging.
• CMake — Cross-platform build system; supports macOS, Linux, Windows, and edge cases like ARM.

• Stateless protocol design (no persistent connection state on server between requests)

  • Why: Simplifies deployment on load-balanced servers and makes detection harder since each packet looks independent.
  • Consequence: Cannot track multi-packet state; requires careful UDP packet fragmentation logic and timeout handling.

• SOCKS5 address format within encrypted payload (not exposed plaintext)

  • Why: Prevents ISPs from detecting destination addresses via packet inspection.
  • Consequence: Client must establish connection before knowing if server will accept it; server auth happens after connection, adding latency.

• Multiple session types

  • Why: undefined
  • Consequence: undefined

TLS cert generation: server requires valid TLS cert/key at startup (examples show paths); self-signed certs work but defeat the 'indistinguishable from HTTPS' premise. Password auth vs MySQL: config must specify one; client password is sent raw in first Trojan request (no salting), so protocol relies on TLS encryption. UDP support: limited; forwardsession may not handle all UDP edge cases. Logging verbosity: compiled-in log level in src/core/log.cpp; no runtime log level toggle visible. Single-threaded main loop: service.cpp likely uses synchronous I/O or thread-per-connection; scale expectations differ from async frameworks.

• TLS Fingerprinting Evasion — Trojan's core defense mechanism; understanding why exact byte-for-byte HTTPS imitation defeats statistical detection is crucial to appreciating design decisions in src/proto/ and docs/protocol.md
• SOCKS5 Protocol — Client-to-Trojan communication uses SOCKS5 address encoding (src/proto/socks5address.cpp); essential to understand how client requests are translated into Trojan wire format
• Challenge-Response Authentication — Trojan uses password-based auth without per-session salting (src/core/authenticator.cpp); reliance on TLS for encryption rather than crypto primitives is a design trade-off worth understanding
• Protocol Multiplexing over TLS — src/session/ and src/proto/ implement multiple logical protocols (Trojan request, UDP packets) over a single TLS connection; critical to grasping how bandwidth and connection overhead are managed
• Fallback Host Spoofing — Config allows specifying a legitimate HTTPS host for active probing fallback; understanding why this defeats identification is core to Trojan's security model, visible in docs/config.md and src/core/config.cpp
• Boost.Asio Async I/O — CMakeLists.txt links Boost; src/core/service.cpp likely uses Asio for socket multiplexing and connection handling across multiple clients concurrently
• QoS Throttling Circumvention — Trojan avoids ISP packet inspection throttling by using legitimate TLS; docs/overview.md explains why this is distinct from traditional proxy obfuscation and why protocol design choices matter

• v2ray/v2ray-core — Comparable proxy framework with modular protocol support (VMess, Shadowsocks, SOCKS5) and broader platform reach; major alternative to Trojan for GFW circumvention
• shadowsocks/shadowsocks-rust — Stream cipher-based proxy; older, simpler approach to encrypted tunneling; Trojan improves on it via TLS indistinguishability
• XIU2/CloudflareSpeedTest — Complementary tool for finding fast Cloudflare edge nodes to front Trojan servers, commonly paired in real deployments
• trojan-gfw/trojan-go — Official Go reimplementation of Trojan with additional features (multiplexing, gRPC); native sibling with broader stdlib support
• trojan-gfw/trojan-qt5 — Official Qt5 GUI client for Trojan; reference implementation for client-side UX 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 comprehensive unit tests for src/proto/ protocol parsing

The proto directory contains critical protocol implementations (trojanrequest.cpp, socks5address.cpp, udppacket.cpp) that parse untrusted network data, but there are no dedicated unit tests in the tests/ directory for these modules. This is a security-sensitive area where malformed input could cause crashes or vulnerabilities. Adding unit tests would improve robustness and prevent regressions.

• [ ] Create tests/unit/ directory structure
• [ ] Add test cases for src/proto/trojanrequest.cpp covering valid/invalid request parsing
• [ ] Add test cases for src/proto/socks5address.cpp covering address parsing edge cases
• [ ] Add test cases for src/proto/udppacket.cpp covering packet serialization/deserialization
• [ ] Integrate unit tests into CMakeLists.txt build system
• [ ] Document how to run tests in CONTRIBUTING.md

Add GitHub Actions CI workflow for macOS and Windows builds

Currently azure-pipelines.yml handles CI, but the repo lacks GitHub Actions workflows. With .github/ directory already present and issue templates configured, adding native GitHub Actions for cross-platform builds (macOS, Windows) alongside the existing Azure Pipelines would improve developer experience, provide faster feedback loops, and allow PR authors to validate changes on multiple platforms before merge.

• [ ] Create .github/workflows/build-macos.yml for macOS CMake build and tests
• [ ] Create .github/workflows/build-windows.yml for Windows MSVC build
• [ ] Ensure both workflows run the basic smoke tests from tests/LinuxSmokeTest/
• [ ] Configure workflows to trigger on pull requests and pushes to master
• [ ] Document CI/CD setup and platform-specific build requirements in docs/build.md

Add integration tests for session lifecycle in src/session/

The session directory contains 6 session type implementations (clientsession, serversession, forwardsession, natsession, udpforwardsession) with complex state management and networking logic. Currently only basic smoke tests exist. Adding integration tests that validate session creation, data forwarding, error handling, and cleanup would significantly improve confidence in the core tunneling logic.

• [ ] Create tests/integration/ directory for session tests
• [ ] Add integration test suite for src/session/clientsession.cpp covering connection lifecycle
• [ ] Add integration test suite for src/session/serversession.cpp covering authentication and forwarding
• [ ] Add test cases for UDP forwarding in src/session/udpforwardsession.cpp
• [ ] Add negative test cases for connection timeouts and protocol errors
• [ ] Integrate integration tests into CMakeLists.txt and document in tests/integration/README.md

• Add unit tests for src/proto/trojanrequest.cpp parsing malformed wire frames (invalid address types, truncated payloads) to harden protocol robustness.
• Write docs/troubleshooting.md with common setup errors (TLS cert not found, port 443 permission denied, Boost linkage on macOS) and solutions.
• Implement runtime log-level control via config.json or CLI flag; currently src/core/log.cpp appears to have compile-time only settings.

The Trojan-GFW codebase has moderate security posture with several areas of concern. Critical issues include outdated Alpine

• High · Outdated Alpine Base Image — Dockerfile, line 1. Dockerfile uses Alpine 3.11, which is significantly outdated and no longer receives security updates. Alpine 3.11 reached end-of-life in November 2022. This exposes the container to known vulnerabilities in system libraries. Fix: Update to a currently supported Alpine version (e.g., Alpine 3.18 or later). Regularly update base images as part of maintenance.
• High · Potential SQL Injection via MariaDB Integration — src/core/authenticator.cpp, src/core/authenticator.h, Dockerfile (mariadb-connector-c-dev dependency). The codebase includes MariaDB connector dependencies (mariadb-connector-c-dev) and authenticator modules (authenticator.cpp/h). Without visible input validation or parameterized query usage in the provided snippets, there is risk of SQL injection if database queries are constructed with user input. Fix: Implement parameterized queries/prepared statements for all database operations. Conduct thorough code review of authenticator.cpp for input sanitization and use ORM libraries or prepared statement APIs exclusively.
• Medium · Missing Input Validation in Protocol Handlers — src/proto/trojanrequest.cpp, src/proto/socks5address.cpp, src/proto/udppacket.cpp. Protocol parsing modules (trojanrequest.cpp, socks5address.cpp, udppacket.cpp) handle untrusted network input. Without visible validation logic in file structure, there's risk of buffer overflows, malformed packet handling, or injection attacks. Fix: Implement strict input validation and bounds checking for all network protocol parsers. Add unit tests for malformed packets and edge cases.
• Medium · Configuration File Exposure Risk — Dockerfile (WORKDIR /config, CMD), examples/server.json-example, examples/client.json-example. The application expects config.json to be present in /config workdir. Configuration files may contain sensitive information (certificates, credentials, IP addresses). The default command directly exposes configuration loading without explicit validation. Fix: Implement strict file permission controls (600 or 400) on config.json. Use environment variables or secrets management for sensitive values rather than config files. Document secure configuration practices.
• Medium · TLS/SSL Configuration Not Explicitly Hardened — src/ssl/ssldefaults.cpp, src/ssl/ssldefaults.h, src/ssl/sslsession.cpp. While sslsession.cpp and ssldefaults.cpp exist, the specific TLS version requirements, cipher suites, and certificate validation logic are not visible. Default TLS configurations may be weak. Fix: Enforce TLS 1.2+ with strong cipher suites. Implement certificate pinning for client-server communication. Disable deprecated protocols (SSLv3, TLS 1.0, 1.1).
• Medium · Insufficient Logging and Audit Trail — src/core/log.cpp, src/core/log.h. While log.cpp exists, the actual logging implementation details are not visible. For a proxy/tunnel application handling sensitive data, insufficient logging creates compliance and forensic investigation challenges. Fix: Implement comprehensive audit logging including: authentication attempts, connection metadata, errors, and security-relevant events. Ensure logs do not contain sensitive data (passwords, keys).
• Low · Build Artifact Stripping Could Complicate Debugging — Dockerfile, line 7. Dockerfile uses 'strip -s trojan' which removes debug symbols. While this reduces binary size, it may complicate incident response and security analysis. Fix: Consider maintaining separate debug and release builds. Alternatively, document how to rebuild with symbols if needed for security incidents.
• Low · No HEALTHCHECK Directive in Dockerfile — Dockerfile. Docker container lacks health check definition, making it harder to detect runtime failures or compromised states in orchestrated environments. Fix: Add HEALTHCHECK directive to monitor trojan service availability and responsiveness.

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.