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/vnt-dev/vnt 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

• Last commit 2mo ago
• 7 active contributors
• Apache-2.0 licensed
• CI configured
• ⚠ Single-maintainer risk — top contributor 88% of recent commits
• ⚠ No test directory 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 vnt-dev/vnt repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/vnt-dev/vnt.

What it runs against: a local clone of vnt-dev/vnt — 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 vnt-dev/vnt | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.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 ≤ 97 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.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 "vnt/src/channel/mod.rs" \\
  && ok "vnt/src/channel/mod.rs" \\
  || miss "missing critical file: vnt/src/channel/mod.rs"
test -f "vnt/src/cipher/aes_cbc/mod.rs" \\
  && ok "vnt/src/cipher/aes_cbc/mod.rs" \\
  || miss "missing critical file: vnt/src/cipher/aes_cbc/mod.rs"
test -f "vnt-cli/src/main.rs" \\
  && ok "vnt-cli/src/main.rs" \\
  || miss "missing critical file: vnt-cli/src/main.rs"
test -f "common/src/command/mod.rs" \\
  && ok "common/src/command/mod.rs" \\
  || miss "missing critical file: common/src/command/mod.rs"
test -f "vnt/packet/src/lib.rs" \\
  && ok "vnt/packet/src/lib.rs" \\
  || miss "missing critical file: vnt/packet/src/lib.rs"

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

VNT is a Rust-based VPN tool that creates virtual LANs by establishing P2P connections between devices with a shared token, falling back to relay servers for NAT traversal. It provides encrypted point-to-point networking with built-in port mapping and IP proxy capabilities, enabling devices across networks to communicate as if on the same local network. Workspace monorepo: vnt-cli/ is the primary CLI binary; common/ provides shared config, command parsing, and entity definitions; vn-link/ implements port mapping (in_mapping/tcp.rs, in_mapping/udp.rs, out_mapping/*); vnt/ is the core networking library. Features are modular (compile-time toggles for encryption, port_mapping, ip_proxy, file_config).

Network administrators and DevOps engineers who need to quickly establish secure virtual networks across geographically distributed devices without complex VPN infrastructure; also developers building internal tools requiring private networking between services.

Actively developed with production-ready binaries available (releases published). The codebase is substantial (678KB Rust) with workspace structure spanning multiple crates (vnt, common, vnt-cli, vn-link). CI is set up via GitHub Actions (.github/workflows/rust.yml). Evidence of active use and deployment exists, though commit recency cannot be assessed from provided data.

Standard open source risks apply.

No specific PR or milestone data visible in provided artifacts. Repository appears stable with releases published. Focus likely on maintaining relay server capacity and adding features via cargo features (openssl, ring-cipher variants). vn-link subsystem suggests active work on port-mapping expansion.

git clone https://github.com/vnt-dev/vnt.git
cd vnt
cargo build -p vnt-cli --release
./target/release/vnt-cli -k YOUR_TOKEN
./target/release/vnt-cli --info  # Check virtual IP

Daily commands: For local development: cargo build -p vnt-cli produces debug binary; cargo build -p vnt-cli --release for optimized release. To test: ./target/release/vnt-cli -k test-token starts the client; requires root on Linux/macOS (see vnt-cli/src/root_check/mod.rs); --info flag displays connection status.

• vnt/src/channel/mod.rs — Core channel abstraction for VPN packet routing and connection management; all data flows through here
• vnt/src/cipher/aes_cbc/mod.rs — Encryption/decryption pipeline for all VPN traffic; security-critical path
• vnt-cli/src/main.rs — CLI entry point and orchestrator; initializes the VPN client and handles user commands
• common/src/command/mod.rs — Command dispatcher and protocol handler for client-server communication
• vnt/packet/src/lib.rs — Packet parsing and serialization for all network layer protocols (IP, TCP, UDP, ARP, ICMP)
• vn-link/src/config.rs — Configuration parser for port mapping and relay settings; affects network behavior
• Cargo.toml — Workspace configuration and dependency manifest; controls all builds and versions

Add a new VPN transport protocol (e.g., QUIC)

1. Create new transport module in vnt/src/channel/ (vnt/src/channel/mod.rs)
2. Implement channel trait matching UDP/TCP patterns (send, recv, connect methods) (vnt/src/channel/udp_channel.rs)
3. Register new transport in channel handler and connection logic (vnt/src/channel/handler.rs)
4. Add transport option to CLI arguments (common/src/cli.rs)

Add a new network protocol handler (e.g., IPv6)

1. Create protocol module under vnt/packet/src/ip/ (vnt/packet/src/ip/mod.rs)
2. Implement packet parsing and serialization (vnt/packet/src/ip/ipv4/packet.rs)
3. Register protocol in ethernet or IP dispatcher (vnt/packet/src/ethernet/protocol.rs)
4. Add routing logic in channel handler (vnt/src/channel/handler.rs)

Add a new CLI command (e.g., statistics)

1. Define command entity in shared struct (common/src/command/entity.rs)
2. Implement client handler (common/src/command/client.rs)
3. Add argument parser in CLI (common/src/cli.rs)
4. Wire command dispatcher in main (vnt-cli/src/main.rs)

Add a new port mapping rule for vn-link

1. Update config structure to accept new mapping type (vn-link/src/config.rs)
2. Create handler in inbound or outbound module (vn-link/src/in_mapping/tcp.rs)
3. Instantiate in vnt_link module (vn-link/src/vnt_link/mod.rs)

• Rust + async/await (Tokio) — High performance, low-latency VPN requires efficient I/O multiplexing and minimal memory overhead; Rust's memory safety prevents buffer overflows in packet processing
• AES-CBC encryption — Standard symmetric encryption for VPN payload protection; CBC mode provides semantic security for streaming data
• Protobuf (message.proto) — Efficient binary protocol for inter-node communication; language-agnostic and compact wire format for bandwidth optimization
• Workspace with multiple crates (vnt, vnt-cli, vn-link, common) — Modular architecture allows CLI tool, core VPN engine, and relay/port-mapping tool to share common code while maintaining clear separation of concerns

• UDP primary transport with TCP fallback

  • Why: UDP minimizes latency for P2P; TCP used only when NAT/firewall blocks UDP to maintain connectivity
  • Consequence: Requires separate channel implementations and NAT hole-punching logic; adds complexity but achieves near-optimal performance in most networks

• P2P with relay server fallback (hybrid mode)

  • Why: P2P avoids relay server bottlenecks and reduces latency; relay ensures connectivity for symmetric NAT nodes
  • Consequence: Requires server infrastructure and relay capacity planning; token-based auth adds modest overhead

• Aggressive release-profile optimization (LTO, strip, opt-level=z)

  • Why: VPN software runs continuously; minimal binary size and optimized code reduce resource usage on edge devices and mobile
  • Consequence: Slower compilation; harder to debug production binaries; core functionality must be thoroughly tested pre-release

• Virtual NIC abstraction (per-OS socket implementation)

  • Why: Allows transparent packet injection without routing table changes; supports Windows, Linux, macOS with unified API
  • Consequence: OS-specific code paths in vnt/src/channel/socket/ increase maintenance burden; kernel updates may require socket handler changes

• Does not provide authentication beyond token-based node pairing
• Does not handle end-to-end encryption between individual users (only transport-layer VPN encryption)
• Not designed for mobile-first use (runs on desktop/server; no native mobile SDKs)
• Does not include web UI or dashboard (CLI-only interface)
• Does not support IPv6 natively (IPv4-only virtual networks)
• Does not provide firewall/stateful filtering (acts as transparent tunnel)

Root privileges: vnt-cli requires root/admin on Linux/macOS/Windows to create virtual network interfaces (checked in vnt-cli/src/root_check/mod.rs). Token uniqueness: Default uses public servers; duplicate tokens cause collision with other users' networks—must use UUID for security. Relay server bottleneck: Hardcoded relay server at compile time (or configured via file_config.rs); self-hosting requires compiling vnts separately. Platform-specific TUN device: Virtual interface creation differs per OS; failures here are silent if no logs enabled. Feature interaction: Some encryption features may conflict; review Cargo.toml feature flags when adding ciphers.

• NAT Traversal (Cone NAT detection) — VNT detects NAT type (shown in --info output as 'Cone') to decide if P2P is viable; understanding this is critical to diagnosing why connections fall back to relay
• Virtual Network Interface (TUN/TAP) — VNT creates a virtual ethernet interface to assign virtual IPs (10.26.0.x); platform-specific kernel integration is required and often the source of silent failures
• P2P Relay Fallback Model — VNT attempts direct peer connections but transparently falls back to relay servers; understanding the decision logic helps tune performance and diagnose connectivity issues
• Token-based Network Segmentation — A single shared token defines which devices join the same virtual network; token collision on public servers creates accidental network merging—critical for security model
• Symmetric Encryption Cipher Selection (AES-GCM vs. ChaCha20) — VNT supports multiple ciphers via compile-time features; choice affects CPU usage, compatibility, and security—requires understanding tradeoffs for different hardware
• Workspace Monorepo with Feature Gates — VNT uses Cargo workspaces and conditional compilation (#[cfg(feature)]) extensively; understanding feature interaction is essential for correct compilation and minimal binary size
• Port Mapping / Network Address Translation (Inbound/Outbound) — vn-link handles both inbound (external → virtual) and outbound (virtual → external) mappings for TCP/UDP; this layer bridges virtual and physical networks

• vnt-dev/vnts — Official relay server implementation for VNT; users self-hosting need this alongside vnt-cli
• WireGuard/wireguard-rs — Alternative Rust-based VPN with kernel-mode performance; differs in philosophy (mesh overlay vs. WireGuard protocol)
• tailscale/tailscale — Commercial mesh VPN with similar virtual LAN model; reference implementation for P2P + relay architecture
• getlantern/lantern — Lightweight circumvention tool overlapping with VNT's NAT traversal and relay fallback patterns

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 integration tests for vnt-cli command parsing and execution

The vnt-cli/src/main.rs and common/src/args_parse.rs handle command-line argument parsing for a network tool with complex flags (-k, --info, --list, etc.). There are no visible test files for these critical paths. Adding integration tests would catch regressions in command parsing, improve reliability for cross-platform usage (Windows/Linux/macOS), and serve as executable documentation for the CLI interface.

• [ ] Create vnt-cli/tests/integration_test.rs with test cases for key flags: -k (token), --info, --list, --help
• [ ] Add tests in common/tests/ to verify args_parse.rs correctly parses various argument combinations
• [ ] Test platform-specific behavior (especially root_check from vnt-cli/src/root_check/unix.rs and windows.rs)
• [ ] Ensure tests run in CI via rust.yml GitHub Actions workflow

Add unit tests for packet handling in vnt/packet/src (ARP, Ethernet, ICMP)

The vnt/packet crate handles low-level network protocol parsing (ARP, Ethernet, ICMP, IGMP) which is security and correctness-critical. The file structure shows protocol parsers but no visible test files. Malformed packets could crash the VPN or cause vulnerabilities. Unit tests would verify packet parsing logic handles edge cases, invalid data, and boundary conditions correctly.

• [ ] Create vnt/packet/src/arp/tests.rs with test cases for ARP packet parsing (valid packets, malformed packets, boundary sizes)
• [ ] Create vnt/packet/src/ethernet/tests.rs for Ethernet frame parsing and protocol type handling
• [ ] Create vnt/packet/src/icmp/tests.rs for ICMP message validation and error handling
• [ ] Add property-based tests using quickcheck crate for fuzzing packet parsing with random byte sequences

Add comprehensive documentation for vn-link (port mapping) configuration in vn-link/README.md

vn-link handles both inbound and outbound port mapping (tcp.rs, udp.rs in both in_mapping/ and out_mapping/) but vn-link/README.md appears minimal or missing detailed usage. The vnt-cli/README.md is referenced in the main README but vn-link configuration is not documented, creating a barrier for users wanting to use port forwarding features. A concrete configuration guide would increase adoption of this feature.

• [ ] Create or expand vn-link/README.md with example YAML/config format for in_mapping (TCP and UDP)
• [ ] Document out_mapping configuration with real-world examples (e.g., forwarding port 8080 to remote service)
• [ ] Add comparison/migration guide showing how vn-link config relates to vnt-cli parameters
• [ ] Include troubleshooting section referencing vn-link/src/config.rs structure and common misconfigurations

• Add logging output for port mapping events (vn-link/src/in_mapping/ and out_mapping/) to help debug why specific TCP/UDP flows fail—currently appears to have minimal visibility
• Write integration tests in common/src/config/ that validate file_config.rs YAML parsing against documented schema (README lists feature flags but no example config file exists)
• Document and test the vn-link CLI (vn-link-cli/src/main.rs)—README mentions vnt-cli extensively but vn-link-cli is underdocumented despite being a separate binary

• High · Insufficient Input Validation on Token Parameter — vnt-cli/src/main.rs, common/src/cli.rs, common/src/args_parse.rs. The VNT CLI accepts a token parameter (-k flag) that is used for authentication across the VPN network. Based on the README examples, tokens like '123456' are accepted, which suggests minimal validation. No evidence of token strength requirements, rate limiting, or brute-force protection is visible in the file structure. This could allow weak tokens to be exploited. Fix: Implement token validation requirements (minimum length, complexity), implement rate limiting on failed authentication attempts, use cryptographically secure token generation, and consider implementing HMAC-based authentication instead of simple token matching.
• High · Potential Privilege Escalation - Root Check Not Enforced — vnt-cli/src/root_check/mod.rs, vnt-cli/src/root_check/unix.rs, vnt-cli/src/root_check/windows.rs. The codebase includes root_check modules for Unix and Windows (vnt-cli/src/root_check/), but there's no evidence in the partial file listing that this check is mandatory or properly enforced before executing privileged operations. Running VPN software without proper privilege validation could allow unauthorized network access. Fix: Ensure root/admin privilege checks are mandatory before executing any network-level operations. Implement clear error messages and prevent execution if privileges are insufficient. Consider using capability-based security on Linux instead of requiring full root access.
• High · Lack of TLS/Encryption Visibility in Architecture — vnt/proto/message.proto, vnt/packet/src/, vnt/src/. The protocol implementation (vnt/proto/message.proto) and packet handling (vnt/packet/src/) show network protocol implementations, but there's no visible evidence of TLS, end-to-end encryption, or secure handshake mechanisms in the file structure. Communication between VPN nodes could be vulnerable to eavesdropping and man-in-the-middle attacks. Fix: Implement TLS 1.3 or higher for all node-to-server and node-to-node communications. Use perfect forward secrecy. Implement certificate pinning for the relay server. Ensure all sensitive data (tokens, keys) are encrypted in transit.
• High · Relay Server Configuration Not Visible — vn-link/src/config.rs, common/src/config/file_config.rs, common/src/config/mod.rs. The README shows relay server addresses being used (e.g., '43.139.56.10:29871'), but there's no visible configuration for relay server certificate validation, TLS verification, or protection against relay server compromise. A compromised relay server could intercept all VPN traffic. Fix: Implement certificate pinning or public key pinning for relay servers. Add configuration for certificate validation. Implement server authentication before sending any traffic. Consider implementing backup relay servers with automatic failover.
• Medium · Aggressive Release Build Optimization May Hide Security Issues — Cargo.toml - [profile.release] section. The Cargo.toml contains aggressive optimization settings (opt-level='z', strip='debuginfo', lto=true, panic='abort') which may hide security-relevant debugging information and stack traces. This could make post-incident forensics difficult. Fix: While optimization is good for performance, consider keeping debug symbols for security-critical builds. Use 'strip' selectively and keep panic information for production builds. Enable 'debug-assertions' for release builds to catch logic errors.
• Medium · Network Packet Handling Without Visible Input Validation — vnt/packet/src/arp/arp.rs, vnt/packet/src/tcp/tcp.rs, vnt/packet/src/udp/udp.rs, vnt/packet/src/icmp/icmp.rs. The packet parsing modules (vnt/packet/src/arp/, tcp/, udp/, icmp/) handle raw network data but the file structure doesn't show evidence of comprehensive input validation, bounds checking, or protection against malformed packets. This could lead to buffer overflows or DoS attacks. Fix: Implement comprehensive input validation for all packet parsing. Add bounds checking before accessing packet data. Implement packet size limits. Use fuzzing to test packet parsing with malformed input. Consider using safe parsing libraries.
• Medium · Insufficient Logging — undefined. undefined 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.