NetDbg — Network Debugger, SOCKS5 Proxy & Packet Injector

🌐 Language Note / Языковое примечание:
This English documentation is a translation/transliteration of the project.
The original and primary source documentation is written in Russian: README_RU.md.

---

NetDbg is a modular network debugger designed for analyzing, capturing, injecting, and replaying TCP packets during the development, testing, and reverse engineering of proprietary network applications and custom protocols. Similar to application-level debuggers (such as WinDbg), NetDbg enables automated protocol debugging via deep CLI IPC (NDJSON) integration and an intuitive Tkinter-based GUI.

---

⚠️ DISCLAIMER (IMPORTANT NOTICE)

WARNING:
This software is intended strictly for testing, analyzing, and debugging personal applications, proprietary services, and authorized development environments. The tool is built to streamline protocol development and debugging workflows on systems and software you own or are explicitly authorized to test.

Using this software to intercept, inspect, or tamper with third-party network traffic without explicit written permission from the network/system owner may violate local and international laws and can result in severe legal consequences. The author accepts no liability and is not responsible for any misuse or damage caused by this program.

---

Key Features

• Asynchronous SOCKS5 Proxy Server (RFC 1928):
  • Standard CONNECT command support, configurable listening port (default: 1080).
  • Seamless compatibility with Proxifier, web browsers, and any generic SOCKS5 client.
• Flexible Packet Framer:
  • Real-time stream parsing from continuous TCP byte streams into discrete application packets.
  • Byte Order Support: Little-Endian (little, standard for x86 and game protocols) and Big-Endian (big, network standard).
  • Configurable length field size (len_bytes, 1/2/4 bytes) and opcode field size (opcode_bytes, 1/2/4 bytes).
  • include_len Mode:
    • False: Length header specifies only payload size (L). Total frame size = len_bytes + L.
    • True: Length header specifies total packet size (L). Total frame size = L.
• Advanced Traffic Log (LogView):
  • 2D Scrolling: Horizontal and vertical scrollbars for inspecting extra-long packets.
  • Dedicated RAW HEX Line: Clean hex string under every packet for instant double-click copying.
  • Formatted HEX & ASCII: Spaced bytes (00 04 AA BB) alongside ASCII decoded representation.
  • Direction indicators: ◄── [IN | Srv -> Cli] (green) and ──► [OUT | Cli -> Srv] (blue).
• Traffic Recording & Buffering:
  • Dynamic on-the-fly filtering by Destination IP, Destination Port, Opcode, and Direction (in / out).
  • Buffer export: "Read to Log" (display directly in GUI) and "Save Buffer to JSON..." (export to disk).
  • Timer-based Fast Record: Automated packet capture over N seconds directly to log or a JSON dump file.
• Packet Simulation & Injection:
  • Omnivorous HEX parser: handles spaces, colons (00:04), hyphens (00-04), commas, and 0x prefixes.
  • Emulate server responses (direction: in) or client requests (direction: out).
  • Targeting options: broadcast to all connections or filter by target IP and/or port.
• Traffic Replay:
  • Sequential file replay (replay_file) with adjustable delay intervals.
  • Single-packet replay by 0-based index (replay_line_file).
• Multilingual GUI (English / Russian):
  • Dynamic language switcher with persistent settings stored in gui_settings.json (English by default).
• Dual Interface & Standalone Windows Launchers:
  • NetDbg.exe (GUI): Clean graphical application without console popups.
  • NetDbg_CLI.exe (CLI): Background daemon for external process automation via JSON-IPC (stdin/stdout).

---

Project Structure

NetDbg/
├── build_exe.bat             # Compilation script for NetDbg.exe and NetDbg_CLI.exe
├── NetDbg.cs                 # C# launcher for GUI application (.NET)
├── NetDbg_CLI.cs             # C# launcher for CLI daemon (.NET)
├── config.py                 # Global default configurations
├── main.py                   # Python entry point (--gui or --cli)
├── COMMANDS.md               # IPC protocol specification and command reference
├── requirements.txt          # Dependencies (Pure Python standard library 3.10+)
│
├── core/                     # Core debugger engine
│   ├── socks5.py             # Async SOCKS5 proxy server
│   ├── session.py            # Active proxy session and socket manager
│   ├── framer.py             # Stream packet framer (little/big endian, include_len)
│   ├── recorder.py           # Ring buffer packet capture and filtering
│   └── injector.py           # Packet injection engine
│
├── cli/                      # Command Line Interface & IPC daemon
│   ├── controller.py         # Command dispatcher and executor
│   └── daemon.py             # Async stdin reader / stdout writer daemon
│
├── gui/                      # Tkinter graphical interface
│   ├── app.py                # Main NetDbgApp window
│   ├── cli_bridge.py         # Subprocess bridge connecting GUI with CLI core
│   ├── i18n.py               # Internationalization & translation manager (EN / RU)
│   └── widgets/              # UI Widgets
│       ├── log_view.py       # 2D scrollable log with RAW/HEX/ASCII views
│       └── packet_sender.py  # Injection and replay control forms
│
├── utils/                    # Helper utilities
│   ├── serializer.py         # Universal HEX/JSON parsers and converters
│   └── file_io.py            # Dump file read/write helpers
│
└── tests/                    # Automated test suite (20 tests)
    ├── test_framer.py
    ├── test_recorder.py
    ├── test_socks5_and_injection.py
    ├── test_cli_controller.py
    ├── test_fast_record.py
    ├── test_gui.py
    └── test_exe.py

---

Requirements

• Python 3.10+ (Windows, Linux, macOS) or local python/ folder (Embedded Python).
• No external Python dependencies required (pure standard library: asyncio, tkinter, socket, json, threading, subprocess, binascii, dataclasses).

---

Build & Run

1. Building Standalone .exe Binaries (Windows)

Run the automated build script:

build_exe.bat

This compiles NetDbg.exe (silent GUI mode) and NetDbg_CLI.exe (CLI daemon).

2. Launch Graphical Interface (GUI)

NetDbg.exe

or via Python directly:

python main.py --gui

3. Launch CLI Daemon

NetDbg_CLI.exe

or via Python:

python main.py --cli

---

Quick CLI Usage Example (JSON-IPC)

Commands are sent as JSON-Lines strings over stdin:

// 1. Start SOCKS5 proxy server on port 1080 with Little-Endian byte order
{"cmd": "start_server", "args": {"port": 1080, "byte_order": "little", "include_len": false}}

// 2. Start capturing incoming server packets for destination port 1239
{"cmd": "start", "args": {"port": 1239, "direction": "in"}}

// 3. Inject simulated packet to the client (emulating a server response)
{"cmd": "send_data", "args": {"data": "5100dd0403000148", "direction": "in", "port": 1239}}

// 4. Fast Record network traffic for 5 seconds directly to a file
{"cmd": "fast_record", "args": {"duration": 5.0, "port": 1239, "output_type": "file", "file_path": "dumps/fast.json"}}

// 5. Shutdown daemon
{"cmd": "close", "args": {}}

Full command documentation and SDK examples in Python, C#, and JavaScript/Node.js are available in COMMANDS.md.

---

Running Automated Tests

Run the complete test suite:

python run_tests.py