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/nxtrace/NTrace-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.

WAIT — Single-maintainer risk — review before adopting

• Last commit 3d ago
• 2 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 97% 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 nxtrace/NTrace-core repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/nxtrace/NTrace-core.

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

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

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

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

NextTrace is a lightweight, open-source CLI tool written in Go for visual route tracking and network path analysis. It performs traceroute operations with real-time visualization, IP geolocation enrichment (via MaxMind), and supports multiple probe modes (ICMP, TCP, UDP) across Linux, macOS, and Windows platforms, with special Windows support via WinDivert packet injection. Monolithic CLI application: cmd/ contains the main command handlers (cmd.go, mtr_mode.go, speed_mode.go, mtu_mode.go, nali_mode.go, etc.), config/ manages settings via Viper, dn42/ handles DN42 geofeed lookups, assets/windivert/ contains platform-specific Windows drivers. Build flavors are separated into deploy_full.go, flavor_full.go, flavor_ntr.go, flavor_tiny.go for different binary sizes and feature sets.

Network engineers, DevOps practitioners, and system administrators who need lightweight, visual traceroute diagnostics with geolocation context. Contributors are primarily Go developers working on network tools and CLI applications.

Actively developed and production-ready. The project uses Go 1.26.1, has comprehensive CI/CD via GitHub Actions (build.yml, test.yml, regression.yml), organized workflow automation for releases and Debian repo publishing, and appears to be in regular maintenance with multiple flavors (full, ntr, tiny) and platform-specific builds. The dual-repo strategy (NTrace-dev as beta, NTrace-core as stable) indicates mature release management.

Low to moderate risk. The dependency tree is reasonable (~25 direct dependencies, mostly well-maintained libraries like google/gopacket, oschwald/maxminddb-golang, spf13/viper). The primary risk is the Windows-specific WinDivert integration (proprietary packet driver in assets/windivert/) which requires binary DLLs/SYS files and may have compatibility fragility. No obvious evidence of stale commits in the visible structure, though the repo emphasizes that most development happens in NTrace-dev and NTrace-core is synced periodically.

Active feature development across multiple execution modes: MTR mode visualization, MTU discovery, speed testing, and globalping integration (globalping_full.go, globalping_disabled.go). Recent work includes test coverage expansion (cmd_test.go, mtr_mode_test.go, mtu_mode_test.go, nali_mode_test.go, speed_mode_test.go) and deployment automation (dependabot.yml suggests active dependency updates). The presence of both publish and regression workflows indicates continuous refinement of the release pipeline.

git clone https://github.com/nxtrace/NTrace-core.git
cd NTrace-core
go build -o ntrace ./cmd
./ntrace --help

For development with tests: go test ./... (test files present in cmd/ directory).

Daily commands: Development: go run ./cmd/cmd.go <target> or build binary: go build -o ntrace ./cmd && ./ntrace 8.8.8.8. Multi-platform cross-compilation via .cross_compile.sh script provided. Platform-specific entry points detected via build tags (implied by flavor files: deploy_full.go, flavor_ntr.go, flavor_tiny.go).

• cmd/cmd.go: Main entry point and command dispatcher; defines the CLI argument parser (akamensky/argparse) and routes to mode handlers
• cmd/mtr_mode.go: Reference implementation for multi-round traceroute visualization mode; shows how packet injection, round iteration, and result aggregation work
• config/viper.go: Configuration loading and validation; handles YAML/TOML config files and environment variable overrides
• dn42/dn42.go: Core geofeed lookup and IP-to-location enrichment logic; essential for adding geographic context to hops
• assets/windivert/divert.go: Windows-specific packet injection abstraction wrapping WinDivert DLLs; necessary for Windows raw packet support
• .cross_compile.sh: Multi-platform build orchestration script; shows how the project compiles for Linux, macOS, Windows, and ARM targets

New tracing modes: Add file cmd/{modename}_mode.go following pattern of cmd/mtr_mode.go. Config: Edit config/basic.go for CLI args, config/viper.go for file-based settings. Geolocation: Extend dn42/dn42.go or dn42/geofeed.go. UI: cmd/mtr_ui.go handles terminal rendering (color, table format via rodaine/table). Tests: Pair new modes with cmd/{modename}_mode_test.go using existing testify/assert patterns.

WinDivert setup: Windows builds require WinDivert.dll and .sys drivers (in assets/windivert/) to be present and privileged execution; missing or incompatible DLLs will silently fail on Windows. MaxMind GeoIP: The dn42/geofeed.go logic depends on external geofeed or MaxMindDB files; if not provisioned, IP location enrichment silently degrades. Platform detection: Build flavors (flavor_full.go, flavor_ntr.go, flavor_tiny.go) use compile-time feature flags—runtime errors won't reveal missing capabilities. Privileged access: Raw packet operations require root/admin; non-root execution will fail with unclear error messages.

• Traceroute / ICMP Echo and TTL expiry — The fundamental mechanism NextTrace uses to discover the network path; understanding TTL decrement and ICMP Time Exceeded responses is essential to all probe modes
• Raw packet injection and packet crafting — NextTrace constructs custom ICMP/TCP/UDP packets via gopacket; WinDivert integration on Windows requires understanding how to inject non-fragmented, custom-header packets into the network stack
• MaxMind GeoIP2/Geofeed enrichment — The dn42/geofeed.go module performs IP-to-geolocation lookups to annotate hops with country, city, ASN; essential for the 'visual' part of 'visual route tracking'
• Cross-platform capability abstraction (syndtr/gocapability) — Linux requires CAP_NET_RAW for raw sockets; NextTrace uses gocapability to detect and enforce privilege requirements across platforms
• WinDivert packet driver architecture (Windows-specific) — Windows lacks raw socket support like Linux; WinDivert is a userspace packet filter driver that NextTrace wraps via xjasonlyu/windivert-go to inject/intercept packets on Windows
• CLI flavor builds and compile-time feature toggling — NextTrace ships three binary variants (full, ntr, tiny) controlled by deploy_full.go, deploy_disabled.go, etc.; understanding feature-gating avoids runtime surprises when deployed flavor lacks expected modes
• WebSocket real-time updates for live visualization — cmd/mtr_ui.go and gorilla/websocket integration enable live streaming of hop results to web clients; essential for the interactive 'visual' display

• traceroute-ng/traceroute-ng — Modern traceroute implementation with similar geolocation enrichment goals; architectural inspiration for cross-platform packet handling
• MTstatus/mtr — The classic MTR (My Traceroute) tool that NextTrace's MTR mode directly emulates; reference for multi-round probe aggregation and live visualization patterns
• nxtrace/NTrace-dev — Official development repository where all PRs should be submitted; NTrace-core is the stable sync target, so active contributors work against NTrace-dev first
• google/gopacket — Core dependency for packet crafting and analysis; understanding its API (layers, flow parsing) is essential for extending probe types
• oschwald/maxminddb-golang — Core dependency for IP geolocation lookups; required for understanding how dn42/dn42.go performs country/city enrichment

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 fast_trace package

The fast_trace directory contains core tracing logic (fast_trace.go, fast_trace_ipv6.go, basic.go) with only one test file (fast_trace_test.go). Given this is the performance-critical path of the application, comprehensive test coverage for IPv6 tracing, error handling, and edge cases would significantly improve reliability. This is especially important since the file names suggest dual IPv4/IPv6 support that likely needs thorough validation.

• [ ] Review fast_trace/fast_trace_ipv6.go for untested code paths and edge cases
• [ ] Create fast_trace/basic_test.go covering initialization and configuration
• [ ] Expand fast_trace_test.go with IPv6-specific test cases, timeout handling, and malformed packet scenarios
• [ ] Add integration tests for fast_trace with mock network conditions
• [ ] Ensure test coverage reaches >80% for the fast_trace package

Add CI workflow for cross-platform binary validation

The repo has .cross_compile.sh script and Windows-specific WinDivert assets (assets/windivert/ with .dll and .sys files), but the existing workflows (build.yml, test.yml) don't validate that binaries work correctly on Windows and Linux after compilation. A new workflow should test compiled binaries on multiple platforms to catch platform-specific bugs early.

• [ ] Create .github/workflows/cross_platform_test.yml that runs on windows-latest, ubuntu-latest, and macos-latest
• [ ] Add build steps that compile binaries using .cross_compile.sh logic
• [ ] Add validation steps that execute basic commands (e.g., 'nexttrace --version', 'nexttrace --help') on each platform
• [ ] Validate WinDivert DLL loading on Windows builds by checking assets/windivert dependencies
• [ ] Set workflow to trigger on PR and commits to main branch

Add missing unit tests for cmd package modes

The cmd directory has multiple mode files (mtr_mode.go, mtu_mode.go, nali_mode.go, speed_mode.go, globalping_full.go) with corresponding test files, but cmd.go itself lacks comprehensive tests. Additionally, deploy_full.go and flavor variants (flavor_full.go, flavor_ntr.go, flavor_tiny.go) have no visible test coverage. These files control command-line behavior and need validation to prevent regressions.

• [ ] Create comprehensive cmd_test.go additions covering all command flags and argument parsing from cmd.go
• [ ] Add deploy_full_test.go covering deployment scenarios and error handling
• [ ] Create flavor_test.go validating flavor selection logic and build configuration differences
• [ ] Add tests for globalping_disabled.go and deploy_disabled.go edge cases
• [ ] Ensure all cmd package functions have corresponding test cases with >75% coverage

• Add unit tests for config/basic.go (currently no test file visible; parsing and validation logic should have test coverage for edge cases like missing required fields, invalid CIDR ranges, timeout bounds)
• Extend dn42/geofeed_test.go with additional test cases for geofeed parsing robustness (currently only geofeed_test.go exists; test invalid feed formats, network timeouts, and malformed JSON responses)
• Document the flavor build system in README.md with concrete examples: show cmd/ to build ntrace-full vs ntrace-ntr vs ntrace-tiny, and which features (MTR, speed test, globalping) are compiled into each

• High · Outdated Go Version Specification — go.mod. The go.mod file specifies 'go 1.26.1' which does not exist. Go's latest stable version is 1.23.x. This appears to be a typo or misconfiguration that could indicate the project is not being properly maintained or tested against actual Go versions, leading to potential compatibility issues and missing security patches. Fix: Update go.mod to specify a valid, currently supported Go version (e.g., 'go 1.23' or later). Ensure all dependencies are compatible with the specified version.
• High · Deprecated golang.org/x/net Version — go.mod - golang.org/x/net v0.53.0. The dependency 'golang.org/x/net v0.53.0' is significantly outdated. Current versions are in the v0.24+ range. This version may contain known security vulnerabilities including potential network-based exploits. Fix: Update golang.org/x/net to the latest stable version. Run 'go get -u golang.org/x/net' and test the application thoroughly.
• High · Outdated golang.org/x/sys Dependency — go.mod - golang.org/x/sys v0.43.0. The dependency 'golang.org/x/sys v0.43.0' is outdated. This package contains system-level interfaces and may have security-relevant fixes in newer versions. The current version is several releases behind. Fix: Update golang.org/x/sys to the latest stable version. Run 'go get -u golang.org/x/sys' to resolve potential system-level security issues.
• High · Outdated golang.org/x/term Dependency — go.mod - golang.org/x/term v0.42.0. The dependency 'golang.org/x/term v0.42.0' is outdated and may contain security vulnerabilities related to terminal handling and input processing. Fix: Update golang.org/x/term to the latest stable version to ensure security fixes for terminal-related vulnerabilities are applied.
• Medium · Network Packet Inspection Library — go.mod - github.com/google/gopacket v1.1.19. The project uses 'github.com/google/gopacket v1.1.19' for packet manipulation. While legitimate for network tracing, this requires careful handling to prevent packet injection attacks or malformed packet processing that could crash the application. Fix: Ensure robust input validation and error handling for all packet processing. Implement rate limiting and sanitization for packet data. Add security tests for malformed packet handling.
• Medium · WinDivert Driver Binary Distribution — assets/windivert/x86/ and assets/windivert/x64/. The codebase includes compiled Windows driver binaries (WinDivert.dll, WinDivert32.sys, WinDivert64.sys) checked into the repository. These are sensitive system-level components that could be targets for supply chain attacks or could cause security issues if tampered with. Fix: Consider fetching these binaries from a signed, official source at runtime rather than bundling them. If bundled, implement code signing verification. Regularly audit these binaries against official checksums.
• Medium · WebSocket Dependency Without Version Control — go.mod - github.com/gorilla/websocket v1.5.3. The 'github.com/gorilla/websocket v1.5.3' dependency is used but WebSocket implementations require careful handling to prevent privilege escalation, injection attacks, or data leakage. Fix: Implement proper authentication and authorization checks on all WebSocket endpoints. Sanitize all WebSocket input data. Implement rate limiting and connection limits.
• Medium · Gin Web Framework Security Configuration — go.mod - github.com/gin-gonic/gin v1.12.0 and cmd/ directory. The project uses 'github.com/gin-gonic/gin v1.12.0' which provides a web server. The repository lacks visible security headers configuration, CORS policy, or rate limiting middleware setup. Fix: Implement security middleware including CORS headers, rate

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.