Спецификация команд и протокола IPC NetDbg

NetDbg в режиме CLI (NetDbg_CLI.exe) работает как фоновый демон управления. Взаимодействие со сторонними программами и графической оболочкой осуществляется через стандартные потоки ввода-вывода (stdin и stdout) с использованием протокола JSON-Lines (NDJSON).

1. Протокол взаимодействия (IPC)

Одна строка — один JSON-объект. Каждая отправляемая команда и каждый ответ должны оканчиваться символом перевода строки \n.
Сигнал готовности (READY): При старте процесса CLI выводит в stdout сообщение о готовности:
```
{"event": "READY", "version": "1.0.0", "message": "NetDbg CLI is ready for commands"}
```
Сторонняя программа должна дождаться этой строки перед отправкой команд.

Общий формат запроса

{
  "cmd": "<имя_команды>",
  "args": {
    "<параметр_1>": "<значение>",
    "<параметр_2>": "<значение>"
  }
}

Общий формат ответа

{
  "status": "success" | "error",
  "data": null | object | list | string,
  "error": null | string
}

2. Справочник команд

2.1. Управление SOCKS5 Сервером

`start_server`

Запускает локальный SOCKS5 прокси-сервер.

Параметры (args):
- port (int, опционально, default: 1080) — порт SOCKS5 сервера (при указании 0 выбирается свободный порт ОС).
- byte_order (string, опционально, default: "little") — порядок байт ("little" или "big").
- include_len (bool, опционально, default: false) — режим расчета длины пакета.
- len_bytes (int, опционально, default: 2) — количество байт под заголовок длины.
- opcode_bytes (int, опционально, default: 2) — количество байт под код операции (опкод).

Пример запроса:

{"cmd": "start_server", "args": {"port": 1080, "byte_order": "little", "include_len": false}}

Пример ответа:

{
  "status": "success",
  "data": {
    "message": "SOCKS5 Proxy server started on port 1080",
    "port": 1080,
    "include_len": false,
    "len_bytes": 2,
    "opcode_bytes": 2
  },
  "error": null
}

`status`

Возвращает текущий статус сервера, метрики соединений и буфера.

Параметры (args): {} (нет параметров).
Пример запроса:
```
{"cmd": "status", "args": {}}
```

Пример ответа:

{
  "status": "success",
  "data": {
    "running": true,
    "port": 1080,
    "include_len": false,
    "active_sessions": 2,
    "recording": true,
    "buffered_packets_count": 48
  },
  "error": null
}

`stop_server`

Останавливает SOCKS5 сервер и закрывает все активные клиентские сессии.

Параметры (args): {}.
Пример запроса:
```
{"cmd": "stop_server", "args": {}}
```

Пример ответа:

{
  "status": "success",
  "data": {"message": "SOCKS5 Proxy server stopped"},
  "error": null
}

`close`

Полное корректное завершение процесса CLI демона.

Параметры (args): {}.
Пример запроса:
```
{"cmd": "close", "args": {}}
```

Пример ответа:

{
  "status": "success",
  "data": {"message": "NetDbg CLI shutting down"},
  "error": null
}

2.2. Управление записью (Recording)

`start`

Включает перехват и запись сетевых пакетов в буфер.

Параметры (args):
- ip (string, опционально) — фильтр по удаленному IP назначения.
- port (int, опционально) — фильтр по удаленному порту назначения.
- opcode (string/int, опционально) — фильтр по опкоду пакета (в HEX формате или числом).
- direction (string, опционально) — "in" (сервер → клиент) или "out" (клиент → сервер).

Пример запроса:

{"cmd": "start", "args": {"port": 7777, "direction": "in", "opcode": "00a1"}}

Пример ответа:

{
  "status": "success",
  "data": {"message": "Recording started with specified filters"},
  "error": null
}

`stop`

Останавливает запись пакетов (трафик продолжает проксироваться без сохранения).

Параметры (args): {}.
Пример запроса:
```
{"cmd": "stop", "args": {}}
```

Пример ответа:

{
  "status": "success",
  "data": {"message": "Recording stopped"},
  "error": null
}

`clear`

Очищает внутренний буфер перехваченных пакетов.

Параметры (args): {}.
Пример запроса:
```
{"cmd": "clear", "args": {}}
```

Пример ответа:

{
  "status": "success",
  "data": {"message": "Packet buffer cleared"},
  "error": null
}

`read`

Считывает накопленные пакеты из буфера.

Параметры (args):
- output_type (string, опционально, default: "return") — "return" или "file".
- file_path (string, опционально) — путь к файлу (обязателен, если output_type: "file").
Пример запроса (вывод в программу):
```
{"cmd": "read", "args": {"output_type": "return"}}
```

Пример ответа:

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "packet": "064000a1ffeeddcc",
      "length": 1600,
      "opcode": "00a1",
      "dst_ip": "195.12.34.56",
      "dst_port": 7777,
      "direction": "out",
      "timestamp": 1717992000.123
    }
  ],
  "error": null
}

Пример запроса (сохранение в файл):

{"cmd": "read", "args": {"output_type": "file", "file_path": "dumps/packets.json"}}

Пример ответа:

{
  "status": "success",
  "data": {
    "message": "1 packets saved to dumps/packets.json",
    "file_path": "dumps/packets.json",
    "count": 1
  },
  "error": null
}

`fast_record`

Автоматизированный цикл записи: очищает буфер → запускает запись с заданными фильтрами → ждет duration секунд → останавливает запись → выгружает данные в return или файл → очищает буфер за собой.

Параметры (args):
- duration (float, обязательно) — время записи в секундах.
- ip, port, opcode, direction (опционально) — фильтры записи.
- output_type (string, default: "return") — "return" или "file".
- file_path (string, опционально) — путь сохранения файла.

Пример запроса:

{
  "cmd": "fast_record",
  "args": {
    "duration": 5.0,
    "port": 7777,
    "output_type": "file",
    "file_path": "dumps/fast_dump.json"
  }
}

Пример ответа:

{
  "status": "success",
  "data": {
    "message": "Fast record completed for 5.0s. Dumped 12 packets.",
    "file_path": "dumps/fast_dump.json",
    "count": 12
  },
  "error": null
}

2.3. Имитация и Воспроизведение (Injection & Replay)

`send_data`

Выполняет инъекцию произвольных сырых байт в активные соединения.

Параметры (args):
- data (string, обязательно) — HEX-строка данных для отправки.
- direction (string, обязательно):
  - "in" — эмуляция ответа удаленного сервера клиенту.
  - "out" — эмуляция исходящего запроса клиента к удаленному серверу.
- ip (string, опционально) — IP удаленного сервера назначения.
- port (int, опционально) — порт удаленного сервера назначения.
Правила таргетинга:
- Если ip и port не заданы → отправка во все активные соединения.
- Если задан только port → во все соединения с этим удаленным портом.
- Если задан только ip → во все соединения с этим удаленным IP.
- Если заданы оба → точечная отправка.

Пример запроса:

{
  "cmd": "send_data",
  "args": {
    "data": "000400a1",
    "direction": "in",
    "port": 7777
  }
}

Пример ответа:

{
  "status": "success",
  "data": {
    "matched_sockets": 1,
    "bytes_sent": 4,
    "direction": "in"
  },
  "error": null
}

`replay_file`

Считывает дамп пакетов из JSON-файла и последовательно отправляет их в соответствующие каналы.

Параметры (args):
- file_path (string, обязательно) — путь к файлу дампа.
- delay_between (float, опционально, default: 0.0) — задержка между пакетами в секундах.

Пример запроса:

{"cmd": "replay_file", "args": {"file_path": "dumps/packets.json", "delay_between": 0.02}}

Пример ответа:

{
  "status": "success",
  "data": {
    "replayed_packets": 24,
    "file": "dumps/packets.json"
  },
  "error": null
}

`replay_line_file`

Отправляет конкретный единичный пакет из файла дампа по его индексу (0-based).

Параметры (args):
- file_path (string, обязательно) — путь к файлу дампа.
- line (int, обязательно) — индекс пакета в массиве JSON (начиная с 0).

Пример запроса:

{"cmd": "replay_line_file", "args": {"file_path": "dumps/packets.json", "line": 0}}

Пример ответа:

{
  "status": "success",
  "data": {
    "replayed_packet_index": 0,
    "direction": "out",
    "matched_sockets": 1,
    "bytes_sent": 8,
    "status": "sent"
  },
  "error": null
}

3. Примеры интеграции сторонних программ

Пример на Python (автоматизация тестов через NetDbg_CLI.exe)

import subprocess
import json

class NetDbgClient:
    def __init__(self, cli_exe_path="NetDbg_CLI.exe"):
        self.proc = subprocess.Popen(
            [cli_exe_path],
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
            stderr=subprocess.STDOUT,
            text=True,
            bufsize=1
        )
        # Ожидание сигнала READY
        ready_line = self.proc.stdout.readline()
        ready_data = json.loads(ready_line)
        assert ready_data.get("event") == "READY", "CLI failed to initialize"

    def send(self, cmd: str, args: dict = None) -> dict:
        payload = json.dumps({"cmd": cmd, "args": args or {}}) + "\n"
        self.proc.stdin.write(payload)
        self.proc.stdin.flush()
        response_line = self.proc.stdout.readline()
        return json.loads(response_line)

    def close(self):
        self.send("close")
        self.proc.terminate()

# Пример использования:
client = NetDbgClient()

# 1. Запуск прокси сервера на порту 1080
res = client.send("start_server", {"port": 1080, "include_len": False})
print("Start Server:", res)

# 2. Быстрая запись сетевой активности в течение 3 секунд
record_res = client.send("fast_record", {
    "duration": 3.0,
    "port": 7777,
    "output_type": "return"
})
print("Captured Packets:", record_res["data"]["count"])

# 3. Инъекция имитированного пакета
inj_res = client.send("send_data", {
    "data": "000400a1",
    "direction": "in",
    "port": 7777
})
print("Injection Result:", inj_res)

client.close()

Пример на C# (.NET)

using System;
using System.Diagnostics;
using System.IO;
using System.Text.Json;

class NetDbgClient : IDisposable
{
    private Process _process;
    private StreamWriter _writer;
    private StreamReader _reader;

    public NetDbgClient(string pythonPath, string mainPyPath)
    {
        _process = new Process
        {
            StartInfo = new ProcessStartInfo
            {
                FileName = pythonPath,
                Arguments = $"\"{mainPyPath}\" --cli",
                UseShellExecute = false,
                RedirectStandardInput = true,
                RedirectStandardOutput = true,
                CreateNoWindow = true
            }
        };

        _process.Start();
        _writer = _process.StandardInput;
        _reader = _process.StandardOutput;

        // Ждем READY
        string readyLine = _reader.ReadLine();
    }

    public string SendCommand(string cmd, object args = null)
    {
        var request = new { cmd = cmd, args = args ?? new { } };
        string jsonRequest = JsonSerializer.Serialize(request);
        _writer.WriteLine(jsonRequest);
        _writer.Flush();
        return _reader.ReadLine();
    }

    public void Dispose()
    {
        try { SendCommand("close"); } catch { }
        _process?.Dispose();
    }
}

Пример на Node.js

const { spawn } = require('child_process');
const readline = require('readline');

const netdbg = spawn('python', ['main.py', '--cli']);
const rl = readline.createInterface({ input: netdbg.stdout });

let onReadyCallback = null;
let currentResolve = null;

rl.on('line', (line) => {
  const data = JSON.parse(line);
  if (data.event === 'READY') {
    if (onReadyCallback) onReadyCallback();
    return;
  }
  if (currentResolve) {
    const resolve = currentResolve;
    currentResolve = null;
    resolve(data);
  }
});

function sendCommand(cmd, args = {}) {
  return new Promise((resolve) => {
    currentResolve = resolve;
    netdbg.stdin.write(JSON.stringify({ cmd, args }) + '\n');
  });
}

onReadyCallback = async () => {
  console.log("NetDbg Ready!");
  const res = await sendCommand('start_server', { port: 1080 });
  console.log('Server started:', res);
};

FilesExpand file tree

COMMANDS.md

Latest commit

History

COMMANDS.md

File metadata and controls

Спецификация команд и протокола IPC NetDbg

1. Протокол взаимодействия (IPC)

Общий формат запроса

Общий формат ответа

2. Справочник команд

2.1. Управление SOCKS5 Сервером

start_server

status

stop_server

close

2.2. Управление записью (Recording)

start

stop

clear

read

fast_record

2.3. Имитация и Воспроизведение (Injection & Replay)

send_data

replay_file

replay_line_file

3. Примеры интеграции сторонних программ

Пример на Python (автоматизация тестов через NetDbg_CLI.exe)

Пример на C# (.NET)

Пример на Node.js

`start_server`

`status`

`stop_server`

`close`

`start`

`stop`

`clear`

`read`

`fast_record`

`send_data`

`replay_file`

`replay_line_file`