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/Archeb/opentrace 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 3w ago
• 4 active contributors
• GPL-3.0 licensed
• CI configured
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 95% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ 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 Archeb/opentrace repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Archeb/opentrace.

What it runs against: a local clone of Archeb/opentrace — 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 Archeb/opentrace | 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 dev exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 50 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Archeb/opentrace(\\.git)?\\b" \\
  && ok "origin remote is Archeb/opentrace" \\
  || miss "origin remote is not Archeb/opentrace (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 dev >/dev/null 2>&1 \\
  && ok "default branch dev exists" \\
  || miss "default branch dev no longer exists"

# 4. Critical files exist
test -f "Program.cs" \\
  && ok "Program.cs" \\
  || miss "missing critical file: Program.cs"
test -f "UI/MainForm.cs" \\
  && ok "UI/MainForm.cs" \\
  || miss "missing critical file: UI/MainForm.cs"
test -f "Services/NextTraceWrapper.cs" \\
  && ok "Services/NextTraceWrapper.cs" \\
  || miss "missing critical file: Services/NextTraceWrapper.cs"
test -f "Models/TracerouteResult.cs" \\
  && ok "Models/TracerouteResult.cs" \\
  || miss "missing critical file: Models/TracerouteResult.cs"
test -f "Services/PlatformService.cs" \\
  && ok "Services/PlatformService.cs" \\
  || miss "missing critical file: Services/PlatformService.cs"

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

OpenTrace is a cross-platform native GUI application for visualized route tracing (traceroute) that runs on Windows, macOS, and Linux. It wraps NextTrace as a backend, providing MTR (My Traceroute) functionality with a user-friendly interface that displays network hop information on interactive maps (OpenStreetMap, Google Maps, Baidu Maps). It supports custom DNS resolvers, MMDB geolocation databases, and TCP/UDP traceroute modes. Monolithic desktop app structure: Program.cs is the entry point, Models/ contains TracerouteHop.cs and TracerouteResult.cs for domain objects, Infrastructure/UserSettings.cs handles config, Properties/ manages i18n resources across languages, and Assets/MapPages/ + Assets/Scripts/ contain HTML/JS for embedded map rendering (openStreetMap.js, googleMap.js, baiduMap.js). Platform-specific UI is compiled per-target (WPF/GTK/Cocoa) via the same C# codebase.

Network administrators, security researchers, and developers who need to debug network connectivity issues visually across multiple operating systems. Users typically want to trace routes to destinations and see hops plotted geographically without command-line complexity.

Actively developed with multi-platform CI/CD pipelines (.github/workflows/ for Windows, macOS, Linux builds) and i18n support across 6 languages (zh-CN, en, fr, es, ja, ru via Properties/Resources.*.resx). The codebase is substantial (134K C#, 46K HTML, 19K JavaScript) and published on Flathub and AUR, indicating production maturity, though commit recency and test coverage are not visible in provided metadata.

Single apparent maintainer (Archeb) increases maintenance risk. Windows TCP/UDP tracing depends on external Npcap driver (npcap.com), and the app critically depends on NextTrace binary being in PATH or manually specified—missing this breaks core functionality. The WinDivert.dll and WinDivert64.sys in .github/ suggest low-level Windows driver integration which adds compatibility fragility across Windows versions.

Visible infrastructure: build workflows for Windows, macOS, and Linux with release pipelines; multi-language resources being maintained; no specific PR/issue data in provided files, but the repo accepts feature requests and bug reports via templated GitHub issues (.github/ISSUE_TEMPLATE/).

git clone https://github.com/Archeb/opentrace.git
cd opentrace
# Requires .NET SDK and platform-specific deps (WPF/GTK/Cocoa)
# Install NextTrace from https://github.com/nxtrace/Ntrace-V1/releases and place in PATH
# On Windows, install Npcap from https://npcap.com/#download
dotnet build OpenTrace.csproj
dotnet run

Daily commands:

# Development build and run
dotnet build OpenTrace.csproj
dotnet run --project OpenTrace.csproj

# Or platform-specific (detected automatically)
# Windows: builds WPF
# Linux: builds GTK
# macOS: builds Cocoa with Entitlements.plist for sandboxing

• Program.cs — Application entry point and initialization; every contributor must understand the startup sequence and dependency injection setup
• UI/MainForm.cs — Primary UI controller and state management; core to understanding how traceroute requests flow through the UI
• Services/NextTraceWrapper.cs — Wrapper around the NextTrace binary; critical abstraction for cross-platform traceroute execution
• Models/TracerouteResult.cs — Core data model for traceroute results; defines the contract between backend service and UI layers
• Services/PlatformService.cs — Platform detection and path resolution; essential for cross-platform (macOS/Windows/Linux) compatibility
• Infrastructure/UserSettings.cs — User preferences and configuration persistence; required for understanding state management across sessions
• OpenTrace.csproj — Project configuration and build targets; defines platform-specific builds and dependencies

Add support for a new mapping provider

1. Create new HTML map template (e.g., leaflet.html) in Assets/MapPages/ (Assets/MapPages/)
2. Implement JavaScript map rendering logic in Assets/Scripts/ (following openStreetMap.js pattern) (Assets/Scripts/)
3. Add map selection option in PreferencesDialog.xeto UI binding (UI/Dialogs/PreferencesDialog.xeto)
4. Update MainForm.cs to load selected map provider and pass results to map JavaScript (UI/MainForm.cs)

Add a new system language localization

1. Create new .resx file (e.g., Properties/Resources.pt-BR.resx) by copying Properties/Resources.resx (Properties/Resources.resx)
2. Translate all string values in the new .resx file to target language (Properties/Resources.pt-BR.resx)
3. Add language culture selection to PreferencesDialog for user preference (UI/Dialogs/PreferencesDialog.xeto.cs)
4. Load localized resources in Program.cs during initialization (Program.cs)

Add a new result output format (e.g., CSV export)

1. Create new Form class (e.g., CsvExportForm.xeto.cs) extending TextOutputForm pattern (UI/Forms/TextOutputForm.xeto.cs)
2. Implement CSV formatter method accepting TracerouteResult model (Models/TracerouteResult.cs)
3. Add export button and handler in MainForm.UI.cs to instantiate and show export form (UI/MainForm.UI.cs)
4. Add file save dialog and write formatted output using System.IO (UI/MainForm.cs)

Integrate a new data source for IP geolocation

1. Create new service class (e.g., Services/GeoIPService.cs) implementing IP lookup interface (Services/IPDBLoader.cs)
2. Add service initialization and configuration option in Infrastructure/UserSettings.cs (Infrastructure/UserSettings.cs)
3. Update NextTraceWrapper.cs to call new geolocation service when enriching hop data (Services/NextTraceWrapper.cs)
4. Add UI preference toggle in PreferencesDialog.xeto for selecting geolocation provider (UI/Dialogs/PreferencesDialog.xeto)

• C# / .NET Framework — Enables single codebase for Windows/macOS/Linux via Eto.Forms; tight integration with NextTrace binary
• Eto.Forms — Cross-platform UI framework reduces duplication of window/dialog code across desktop targets
• NextTrace binary (external dependency) — Proven, feature-rich traceroute engine; wrapper pattern isolates platform-specific execution details
• HTML/JavaScript map rendering — Embeds OpenStreetMap/Baidu/Google Maps without requiring native mapping libraries; lightweight and portable
• Node.js + static site generator (HomePage) — Decoupled homepage build; i18n support without backend; serves as marketing + download endpoint

• Wrapper around external NextTrace binary vs. reimplementing traceroute in C#

  • Why: NextTrace is mature, multi-platform, and actively maintained; reimplementation would duplicate effort and complexity
  • Consequence: Application requires NextTrace binary in PATH or manual configuration; adds deployment complexity but ensures feature parity with upstream

• Client-side HTML/JS maps vs. server-rendered map tiles

  • Why: Desktop app has no server; client-side approach is stateless and self-contained
  • Consequence: Maps require internet connectivity and JavaScript runtime; lighter footprint but less offline capability

• IP geolocation embedded database vs. online API queries

  • Why: Embedded DB avoids per-request API rate limits and latency; works offline
  • Consequence: Database must be bundled/updated periodically; larger app size; trade-off accepted for UX consistency

• Monolithic project structure (single .csproj) vs. modular services

  • Why: Simpler dependency management and build pipeline for a desktop app; Services already provide loose coupling where needed
  • Consequence: Harder to reuse individual components; acceptable for single-purpose desktop tool

• Real-time packet capture or low-level network monitoring (delegated to NextTrace)
• Server-side result storage or multi-user session management (desktop-only, local execution)
• Mobile platform support (Windows/macOS/Linux desktop and Linux server targets only)
• Network packet manipulation or ISP-level routing control (traceroute visualization only, no injection)
• Custom traceroute protocol implementation (relies entirely on NextTrace binary)

NextTrace binary must be discoverable at runtime—if not in PATH and not manually configured in UserSettings, the app fails silently or shows unhelpful error. Windows Npcap driver is a separate install (npcap.com) required for TCP/UDP modes, not bundled. The app expects WinDivert.dll/.sys in runtime path on Windows for raw socket access—wrong bitness (32 vs 64) causes crashes. MMDB geolocation databases are optional but traceroute without them shows no coordinates; user must manually download and point to via settings. Map scripts (baiduMap.js, googleMap.js) require internet connectivity to load tile servers unless offline caching is configured. Entitlements.plist on macOS is critical for sandboxing permissions; missing entries break features. Properties/Resources.*.resx files must stay synchronized—strings added to English but not translated will not appear in localized builds.

• Traceroute (ICMP/UDP/TCP variants) — Core protocol this app visualizes—understanding packet TTL decrement and ICMP Time Exceeded responses explains how hops are discovered and why TCP/UDP variants exist
• GeoIP / MaxMind MMDB format — App supports custom .MMDB database files to map IP addresses to coordinates for map visualization—knowing MMDB binary format explains why UserSettings must specify path and how hop geolocation works
• Platform-specific native UI frameworks (WPF/GTK/Cocoa) — Same C# codebase compiles to three different native UI toolkits per OS—understanding conditional compilation in .csproj and platform abstraction patterns is essential for modifying UI
• DNS over HTTPS (DoH) — App supports custom DNS resolvers including DoH—understanding DNS vs DoH explains why UserSettings allows resolver selection and how traceroute result hostname resolution varies
• Embedded WebView for map rendering — Maps are rendered as embedded HTML/JavaScript in platform WebViews rather than native map controls—explains why Assets/MapPages/ contain .html templates and why Assets/Scripts/ must handle browser-JS communication
• Internationalization (i18n) with resource files — App supports 6 languages via Properties/Resources.*.resx files—understanding .NET resource fallback and language-specific builds is essential for adding translations or new strings
• Raw sockets and packet capture (WinDivert/Npcap) — Windows TCP/UDP traceroute requires low-level packet manipulation via WinDivert driver and Npcap—understanding driver requirements explains setup complexity and why bitness/version mismatches break functionality

• nxtrace/Ntrace-V1 — The backend engine OpenTrace wraps; handles actual traceroute execution and raw output generation
• tracetcp/tracetcp — Alternative TCP traceroute tool; shows how cross-platform traceroute can be implemented if NextTrace backend is replaced
• WireGuard/wireguard-tools — Related network diagnostics tool with similar multi-platform native UI requirements and system integration challenges (WinDivert, root/admin access)
• belarusian/mtr — Modern MTR (My Traceroute) implementation; OpenTrace mirrors its MTR feature set but with graphical interface
• Archeb/opentrace-homepage — Official website built from HomePage/ directory (build.js, i18n.json, template.html); distributes releases and documentation

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 platform-specific integration tests for NextTraceWrapper.cs

The Services/NextTraceWrapper.cs file is critical for cross-platform functionality (Windows, macOS, Linux) but there are no visible test files in the repo. Given that the project wraps NextTrace and handles platform-specific binaries (evidenced by .github/WinDivert.dll and .github/WinDivert64.sys), adding integration tests would catch platform-specific bugs early. This is especially valuable since the build workflows (.github/workflows/build-*.yml) suggest multi-platform complexity.

• [ ] Create Tests/ directory with NextTraceWrapperTests.cs
• [ ] Add unit tests for process spawning on Windows (WinDivert scenarios)
• [ ] Add unit tests for process spawning on Linux/macOS (standard traceroute)
• [ ] Mock PlatformService.cs to simulate different OS environments
• [ ] Verify timeout and error handling for failed NextTrace calls

Create comprehensive README documentation for Services layer

The Services/ directory contains critical components (DnsResolverService.cs, IPDBLoader.cs, NextTraceWrapper.cs, PlatformService.cs, UpdateService.cs) but the main README only mentions downloading NextTrace—it doesn't explain how these services orchestrate the application or how contributors should work with them. This creates friction for new contributors trying to understand the architecture.

• [ ] Create Services/README.md documenting each service's responsibility
• [ ] Add a sequence diagram showing how NextTraceWrapper.cs, PlatformService.cs, and DnsResolverService.cs interact
• [ ] Document the IPDBLoader.cs initialization flow and supported database formats
• [ ] Explain UpdateService.cs versioning strategy (referenced in workflows but not documented)
• [ ] Include code examples for calling each service from MainForm.cs

Add end-to-end UI tests for MainForm using the Eto framework

The UI layer (UI/MainForm.cs, UI/MainForm.UI.cs, and form dialogs) uses the Eto cross-platform framework but has no visible test coverage. The project supports Windows, macOS, and Linux—each with different UI behaviors. Adding Eto-based UI tests would prevent regressions when modifying UI code and serve as executable documentation for the form workflows.

• [ ] Create UITests/ directory with MainFormTests.cs
• [ ] Add tests for the preferences dialog flow (UI/Dialogs/PreferencesDialog.xeto.cs)
• [ ] Add tests for text output form display (UI/Forms/TextOutputForm.xeto.cs)
• [ ] Add tests for exceptional output handling (UI/Forms/ExceptionalOutputForm.xeto.cs)
• [ ] Verify i18n string loading works correctly for all 7 languages (Properties/Resources.*.resx files)

• Add unit tests for Models/TracerouteHop.cs and Models/TracerouteResult.cs parsing logic—currently no /Tests directory visible; contributor could create XUnit test project and add coverage for coordinate parsing and hop aggregation
• Create missing documentation for Infrastructure/UserSettings.cs configuration file format and environment variables—README only mentions 'manually specify the path' but not where settings persist or how to script it; document all config keys
• Enhance Assets/Scripts/openStreetMap.js to display hop latency tooltips on map marker hover—visible in Models but not rendered; would improve UX for identifying slow hops visually

• High · Potential Command Injection via NextTrace Wrapper — Services/NextTraceWrapper.cs. The file 'Services/NextTraceWrapper.cs' suggests execution of external NextTrace binary. Without seeing the implementation, there's a high risk of command injection if user input (IP addresses, hostnames) is not properly sanitized before being passed to the external process. Fix: Implement strict input validation and sanitization for all parameters passed to NextTrace. Use parameterized execution methods (ProcessStartInfo with arguments array) rather than shell string concatenation. Validate IP addresses and hostnames against strict regex patterns.
• High · Hardcoded Binary Dependencies in Repository — .github/WinDivert.dll, .github/WinDivert64.sys. WinDivert.dll and WinDivert64.sys are stored directly in the repository (.github/WinDivert.dll and .github/WinDivert64.sys). This poses security risks: (1) difficulty tracking version changes, (2) potential for supply chain attacks if binaries are compromised, (3) no integrity verification mechanism visible. Fix: Move binary dependencies to a separate release artifact or dependency management system (NuGet for Windows dependencies). Implement cryptographic signature verification for all binary files. Document the source and version of each dependency.
• Medium · DNS Resolver Service - Potential DNS Spoofing/Cache Poisoning — Services/DnsResolverService.cs. The presence of 'Services/DnsResolverService.cs' indicates DNS lookups are performed. Without seeing the implementation, there's a concern that DNS results might not be validated or that DNSSEC validation is not implemented, making the application vulnerable to DNS spoofing attacks. Fix: Implement DNSSEC validation where possible. Add timeout and retry limits to prevent hanging on unresponsive DNS servers. Consider using secure DNS protocols (DoH/DoT). Validate that resolved IPs match expected ranges.
• Medium · IP Geolocation Database Security — Services/IPDBLoader.cs. The 'Services/IPDBLoader.cs' loads IP geolocation databases. If these databases are downloaded from the internet without integrity verification (no checksums, signatures), they could be compromised or substituted with malicious data. Fix: Implement cryptographic signature verification (SHA-256 or better) for downloaded IP databases. Use HTTPS exclusively for downloads. Pin the expected hash of legitimate databases. Implement expiration dates for cached databases.
• Medium · Potential XSS in HTML Map Pages — Assets/MapPages/openStreetMap.html, Assets/Scripts/. The Assets/MapPages directory contains HTML files (openStreetMap.html) that are rendered in the UI. If map data or trace results are dynamically injected without proper encoding, this could lead to XSS attacks. Fix: Ensure all dynamic content is HTML-entity encoded before insertion. Use Content Security Policy (CSP) headers. Avoid dangerouslySetInnerHTML patterns. Use framework-provided templating with auto-escaping.
• Medium · Update Service - Potential MITM/Downgrade Attack — Services/UpdateService.cs. The 'Services/UpdateService.cs' handles application updates. Without visible HTTPS enforcement and signature verification, updates could be intercepted or downgraded to older vulnerable versions. Fix: Enforce HTTPS-only for all update checks. Implement cryptographic signature verification of downloaded updates. Use certificate pinning for the update server. Never perform downgrades, always verify the new version is >= current version.
• Medium · User Settings Storage - Potential Information Disclosure — Infrastructure/UserSettings.cs. The 'Infrastructure/UserSettings.cs' handles user preferences. If sensitive data (API keys, recent hosts) is stored in plaintext or with weak encryption, it could be extracted by local attackers. Fix: Use platform-specific secure storage (Windows: DPAPI, macOS: Keychain, Linux: libsecret). Never store sensitive data in plaintext. Implement access controls and encrypt at rest. Document what data is stored and why.
• Low · Missing Security Headers Documentation — undefined. No visible security configuration files (Security.txt, SECURITY.md) or CSP headers defined for the application, particularly for the HomePage web component. 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.