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/ehang-io/nps 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
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 70% of recent commits
• ⚠ 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 ehang-io/nps repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ehang-io/nps.

What it runs against: a local clone of ehang-io/nps — 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 ehang-io/nps | 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 ≤ 739 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ehang-io/nps(\\.git)?\\b" \\
  && ok "origin remote is ehang-io/nps" \\
  || miss "origin remote is not ehang-io/nps (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 "cmd/nps/nps.go" \\
  && ok "cmd/nps/nps.go" \\
  || miss "missing critical file: cmd/nps/nps.go"
test -f "cmd/npc/npc.go" \\
  && ok "cmd/npc/npc.go" \\
  || miss "missing critical file: cmd/npc/npc.go"
test -f "lib/config/config.go" \\
  && ok "lib/config/config.go" \\
  || miss "missing critical file: lib/config/config.go"
test -f "bridge/bridge.go" \\
  && ok "bridge/bridge.go" \\
  || miss "missing critical file: bridge/bridge.go"
test -f "client/client.go" \\
  && ok "client/client.go" \\
  || miss "missing critical file: client/client.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 739 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~709d)"
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/ehang-io/nps"
  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).

NPS is a lightweight, high-performance intranet penetration proxy server written in Go that tunnels TCP, UDP, SOCKS5, HTTP(S), and KCP traffic through firewalls and NATs. It provides secure internal network access with a powerful web management dashboard, enabling remote access to internal services, databases, SSH, RDP, and DNS resolution from outside the network. Monolithic structure: cmd/nps/ and cmd/npc/ contain server and client entry points respectively; client/ (client.go, control.go, local.go, register.go) handles tunnel establishment; server/ (inferred) handles routing; conf/ holds JSON configs for clients, hosts, tasks, and certificates; web UI assets in web/ (inferred); Makefile orchestrates builds including Android cross-compilation (build.android.sh, build.assets.sh).

Network administrators, DevOps engineers, and IT teams who need to expose internal services (databases, web apps, SSH) securely over the internet without public IPs, and developers debugging payment APIs or accessing staging environments from restricted networks.

Actively maintained and production-ready: 7.3k+ GitHub stars, written in Go 1.15+, includes CI/CD via GitHub Actions (release.yml), comprehensive documentation in docs/, and supports multiple platforms (Linux, Windows, macOS, Synology). Regular releases visible via workflows.

Moderate risk: depends on unmaintained or older libs (astaxie/beego v1.12.0 from 2019, xtaci/kcp-go for KCP protocol), no visible test suite in file structure, and security-critical proxy code should have extensive testing coverage. Last major dependency update appears dated; audit crypto dependencies before production deployment.

Active release pipeline via .github/workflows/release.yml suggests recent deployments; documentation in docs/ is comprehensive with API, features, and examples; Dockerfile.nps and Dockerfile.npc indicate containerization is supported; no specific PR or milestone data visible but structure suggests maintenance.

git clone https://github.com/ehang-io/nps.git
cd nps
make
# For server: ./bin/nps
# For client: ./bin/npc

Or download pre-built binaries from releases page. Requires Go 1.15+.

Daily commands: Server: sudo ./nps start (Linux/Darwin) or nps.exe start (Windows admin cmd); default config at /etc/nps/ (Linux/Darwin) or C:\Program Files\nps (Windows); listens on ports 80, 443, 8080 (web UI), 8024 (bridge). Client: ./npc -server=SERVER_IP:8024 -vkey=YOUR_KEY with config from conf/npc.conf.

• cmd/nps/nps.go — Server entry point; initializes the NPS proxy server, loads config, and starts all listeners
• cmd/npc/npc.go — Client entry point; connects NPC client to NPS server and manages tunnels
• lib/config/config.go — Configuration parser for clients, hosts, tasks, and server settings; core to initialization
• bridge/bridge.go — Core bridge logic for proxying traffic between clients and backend services
• client/client.go — Client connection state machine; handles registration, health checks, and lifecycle
• lib/conn/conn.go — Low-level connection abstraction with encryption, compression, and multiplexing support
• lib/crypt/crypt.go — Encryption/decryption layer providing TLS and custom crypto for secure tunnels

• NPS Server (cmd/nps) — Listens for NPC client connections, routes inbound proxy requests

Add a new protocol tunnel type

1. Define task structure in lib/config/config.go for the new protocol (e.g., new TaskType constant) (lib/config/config.go)
2. Add listener registration in cmd/nps/nps.go to spawn a listener for the new protocol (cmd/nps/nps.go)
3. Implement protocol-specific forwarding logic in bridge/bridge.go or create new file bridge/protocol_name.go (bridge/bridge.go)
4. Extend client/local.go to bind NPC to a new local service endpoint type (client/local.go)

Add a new configuration option

1. Add field to Config struct in lib/config/config.go and parse logic from JSON/conf file (lib/config/config.go)
2. Update sample config files (conf/nps.conf, conf/clients.json, conf/tasks.json) (conf/nps.conf)
3. Use new config value in the appropriate module (e.g., cmd/nps/nps.go or client/client.go) (cmd/nps/nps.go)

Add encryption/crypto support

1. Create new cipher in lib/crypt/crypt.go with Encrypt/Decrypt methods (lib/crypt/crypt.go)
2. Register cipher type in client registration flow client/register.go (client/register.go)
3. Update TLS config or key exchange in lib/crypt/tls.go if needed (lib/crypt/tls.go)
4. Test cipher integration at connection time in lib/conn/conn.go (lib/conn/conn.go)

Add a new client command or API

1. Define control message type in client/control.go with serializable struct (client/control.go)
2. Add handler in cmd/npc/npc.go or expose via SDK in cmd/npc/sdk.go (cmd/npc/sdk.go)
3. Integrate with state machine in client/client.go to process new message type (client/client.go)

• Beego web framework — Powers the web management terminal for admins to configure tunnels and monitor traffic
• Go goroutines & connection multiplexing (ehang.io/nps-mux) — Enables thousands of concurrent tunnels over single persistent connection; low-overhead concurrency
• Snappy compression — Reduces bandwidth for high-latency intranet scenarios without heavy CPU cost
• TLS + custom crypto layer — Protects tunnel contents from inspection; allows custom key exchange for client-server auth
• JSON-based config + file persistence — Simple, human-readable configuration; no database dependency; easy distributed sync

• Single long-lived mux connection per client instead of individual TCP per tunnel

  • Why: Reduces NAT/firewall blocking, lowers setup latency, enables efficient resource pooling
  • Consequence: If mux connection fails, all tunnels on that client go down; requires robust health monitoring

• JSON + file-based storage instead of SQL database

  • Why: Zero external dependency; lightweight; suitable for small-to-medium deployments
  • Consequence: Scales to ~10k tasks; no hot-reloading without restart; file corruption risk without proper locking

• Compression optional, encryption mandatory at connection layer

  • Why: Security first; optional compression avoids CPU overhead for fast networks
  • Consequence: Users must manage key distribution; no standard cert-based auth in base config

• Goroutine-per-link model rather than async I/O

  • Why: Simpler code; Go's scheduler handles thread pool implicitly
  • Consequence: High goroutine count under 10k+ concurrent connections; potential memory pressure

• Does not provide built-in user authentication for web management UI (relies on external reverse proxy/firewall)
• Does not support cluster mode or distributed server deployment; single-server only
• Not designed for real-time streaming or latency-critical protocols (gaming, VoIP)
• No built-in DDoS or rate-limiting per client (defer to OS/firewall)
• Does not support dynamic TLS cert generation; requires pre-provisioned PEM/KEY files

TLS certificates: server.pem and server.key in conf/ are required for HTTPS; missing or expired certs break https proxy mode. Bridge port 8024: must be accessible from clients; firewall rules or NAT config can silently block client registration. vkey authentication: client must match server's vkey exactly; mismatches fail silently in logs. Config file locations: paths differ by OS (/etc/nps on Linux vs C:\Program Files\nps on Windows); relative vs absolute paths cause startup issues. Beego deprecated version: v1.12.0 is from 2019; may have security gaps — check security advisories. No embedded tests: no *_test.go files visible; functionality relies on integration testing.

• Intranet penetration / reverse proxy tunneling — Core problem NPS solves; understanding NAT traversal, port forwarding, and how clients expose internal services is essential to contribute to bridge/, client/, or server routing logic
• Connection multiplexing (mux) — NPS-mux dependency handles multiple logical tunnels over single TCP/UDP connection; critical for understanding how multiple proxied services share one client-server link in bridge/bridge.go and client/control.go
• KCP (Kalman filter fast reliable protocol) — NPS supports KCP for UDP-based low-latency tunneling instead of TCP retransmit penalties; configurable in npc.conf and nps.conf; understanding tradeoffs (speed vs reliability) matters for tunnel selection
• SOCKS5 proxy protocol — NPS natively proxies SOCKS5 requests; requires understanding SOCKS5 handshake (RFC 1928) for client/local.go protocol handling and debugging proxy chains
• Goroutine pooling with worker threads (ants library) — NPS uses panjf2000/ants for bounded concurrency; prevents goroutine explosion under load; critical for understanding scalability limits and memory efficiency of high-tunneling-count deployments
• Host header rewriting and SNI termination — NPS supports custom headers and HTTPS certificate multiplexing via domain routing; understanding Host header injection in bridge.go and certificate selection in conf/ is crucial for HTTPS tunnel debugging
• Cross-platform service lifecycle management (systemd, Windows Services) — NPS installs as system service via kardianos/service; understanding init system integration (Linux systemd, Windows SCM, macOS launchd) critical for debugging startup failures on different OS targets

• fatedier/frp — Direct competitor: Go-based intranet penetration proxy with similar TCP/UDP/HTTP tunneling, but more mature with 80k+ stars and extensive plugin ecosystem
• inconshreveable/ngrok — Industry standard for reverse proxies and intranet exposure; proprietary but influential; NPS borrows architectural patterns (bridge, mux, multi-protocol support)
• ehang-io/nps-mux — Required dependency (go.mod: nps-mux v0.0.0-20210407130203); implements connection multiplexing for NPS tunnels, must understand for protocol extensions
• xtaci/kcp-go — KCP protocol implementation dependency; NPS uses it for UDP-based fast, unreliable tunneling; understanding KCP parameters critical for tuning high-latency connections
• panjf2000/ants — Goroutine pool library dependency (v2.4.2); NPS uses ants for worker thread management in high-concurrency proxy scenarios

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 client/control.go and bridge/bridge.go

The repo lacks unit tests for critical control flow and bridging logic. Given that NPS handles complex protocol tunneling (tcp, udp, socks5, http), the control.go and bridge.go modules are mission-critical. Adding tests would catch regressions in connection management, protocol switching, and error handling.

• [ ] Create client/control_test.go with tests for control message parsing, authentication flow, and connection state transitions
• [ ] Create bridge/bridge_test.go with tests for protocol bridging, data forwarding, and connection lifecycle
• [ ] Use Go's testing package with table-driven tests for multiple protocol scenarios
• [ ] Aim for >80% code coverage on these two files

Add GitHub Actions workflow for multi-platform binary testing (Go 1.15+)

The repo has release.yml but no automated testing workflow. Given NPS supports linux, windows, macos, and Synology, adding a CI workflow that tests builds on multiple platforms would catch platform-specific bugs early. The .travis.yml file appears unused (deprecated).

• [ ] Create .github/workflows/test.yml that runs 'go test ./...' on ubuntu-latest, windows-latest, and macos-latest
• [ ] Add 'go build' steps for each platform to verify cross-platform compilation works (linux, windows, darwin)
• [ ] Include linting via golangci-lint to catch code quality issues
• [ ] Remove or deprecate .travis.yml since GitHub Actions is now the primary CI

Document SDK usage and npc extension mechanism in docs/npc_sdk.md with concrete examples

The docs folder lists npc_sdk.md and npc_extend.md but these are likely sparse. Given that cmd/npc/sdk.go exists and the project supports custom extensions, new contributors need clear examples of how to build custom npc clients or extend functionality. This would reduce support questions.

• [ ] Expand docs/npc_sdk.md with a step-by-step guide showing how to use the SDK from cmd/npc/sdk.go
• [ ] Add code examples demonstrating: basic connection setup, registering a custom protocol task, and handling tunnel data
• [ ] Document the config format for conf/npc.conf with all available options and their purposes
• [ ] Add a 'Common Patterns' section covering use cases like SSH tunneling, local service exposure, and SOCKS5 proxy setup

• Add unit tests for client/local.go: implement TestLocalConn* functions to cover connection multiplexing logic; no *_test.go files visible suggests gap in local traffic routing coverage
• Document protocol extension guide: create docs/PROTOCOL_EXTENSION.md with concrete example of adding a new protocol handler to client/local.go and server counterpart, filling gap in docs/contribute.md
• Add health check metrics to bridge/bridge.go: enhance client/health.go to export Prometheus metrics (tunnel_up, bytes_transferred_total) for monitoring; current health.go lacks observability instrumentation

• Critical · Hardcoded SSL/TLS Certificates in Repository — conf/server.key, conf/server.pem. The repository contains hardcoded SSL/TLS certificates (server.key and server.pem) in the conf/ directory. These private keys should never be committed to version control as they can be exposed to anyone with access to the repository history. Fix: Remove these files from the repository immediately and add to .gitignore. Generate new certificates for production use. Use environment variables or secure key management systems for certificate distribution.
• High · Outdated Go Dependencies with Known Vulnerabilities — go.mod - golang.org/x packages. Multiple dependencies have known security vulnerabilities: golang.org/x/crypto (v0.0.0-20210322153248-0c34fe9e7dc2), golang.org/x/net (v0.0.0-20210405180319-a5a99cb37ef4), and golang.org/x/sys (v0.0.0-20210403161142-5e06dd20ab57) are significantly outdated (from 2021). These contain patched CVEs related to cryptographic operations and network handling. Fix: Update all golang.org/x packages to the latest stable versions. Run 'go get -u golang.org/x/crypto golang.org/x/net golang.org/x/sys' and review breaking changes.
• High · Deprecated Beego Framework Version — go.mod - astaxie/beego dependency. The codebase uses github.com/astaxie/beego v1.12.0, which is outdated and no longer actively maintained. Beego 1.x has known security issues and lacks modern security features. The custom fork (exfly/beego) with 'export-init' raises additional concerns about code transparency. Fix: Migrate to Beego v2.x or consider switching to a more actively maintained web framework (e.g., Gin, Echo). Audit the exfly/beego fork for any malicious modifications.
• High · Potential SQL Injection in Multi-Account Configuration — conf/multi_account.conf, Web management terminal code (not visible). The presence of 'multi_account.conf' and 'clients.json' configuration files suggests database operations for user management. Without access to the actual code, the handling of these configurations in the beego-based web management terminal poses SQL injection risks, especially given the outdated framework version. Fix: Implement parameterized queries/prepared statements for all database operations. Add input validation and sanitization for all user-supplied data. Use ORM frameworks safely.
• High · Intranet Penetration Service Security Model — Overall architecture - bridge/, client/, server components. NPS is designed for intranet penetration and proxy services, which inherently exposes internal networks. The combination of comprehensive protocol support (tcp, udp, socks5, http) without explicit mention of end-to-end encryption could allow traffic interception. Fix: Implement mandatory TLS encryption for all traffic. Use certificate pinning. Implement strong authentication mechanisms beyond basic credentials. Add audit logging for all connections.
• Medium · Hardcoded Configuration Files in Repository — conf/ directory. Multiple configuration files are included in the repository (nps.conf, npc.conf, clients.json, hosts.json, tasks.json) with potential default values that could be exploited if used as-is in production. Fix: Remove example/default configuration files from the repository. Provide template files with .example extensions. Enforce that production configs are not tracked in git.
• Medium · Missing Security Headers Configuration — Web management terminal (cmd/nps/nps.go and related). The web management terminal (astaxie/beego) may not be configured with modern security headers (CSP, HSTS, X-Frame-Options, etc.), especially given the outdated framework version. Fix: Implement security middleware that adds CSP, HSTS, X-Frame-Options, X-Content-Type-Options, and X-XSS-Protection headers. Use a security-focused middleware library.
• Medium · Insufficient Input Validation on Dynamic Configuration — undefined. Configuration files like tasks.json, hosts.json, and multi_account.conf are 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.