# YouNetMonitor-MCP

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE.md)
[![MCP Protocol](https://img.shields.io/badge/MCP-2024--11--05-purple.svg)](https://modelcontextprotocol.io/)

**MCP server for attaching Frida-based network/traffic interceptors (TCP/UDP/TLS) to any application — built on [deluder](https://github.com/Warxim/deluder).**

YouNetMonitor-MCP exposes deluder's traffic-interception capabilities as 15 [Model Context Protocol](https://modelcontextprotocol.io/) tools, so an AI assistant (Claude Desktop, VS Code, Copilot, etc.) can:

- List running processes on the local or a remote machine
- Attach Frida hooks to any process by PID or by name
- Spawn a new app with hooks already attached
- Intercept TCP/UDP traffic (Winsock, libc sockets) **and** TLS traffic (OpenSSL, GnuTLS, SChannel) **in plaintext before encryption / after decryption**
- Drain captured events as JSON-RPC tool results
- Search captured payloads by substring (ASCII or hex)
- Manage multiple parallel capture sessions

---

## What's vendored

The full `deluder/` package (v1.2.1) is vendored in this repo so no separate install is needed. deluder is GPL-3.0; this derivative inherits the same license.

| Deluder script   | Library                          | Hooks                                                                  |
|------------------|----------------------------------|------------------------------------------------------------------------|
| `winsock`        | `ws2_32.dll`, `wsock32.dll`      | send, sendto, recv, recvfrom, WSASend, WSASendTo, WSARecv, WSARecvFrom |
| `libc`           | `libc.so` (Linux/macOS)          | send, sendto, recv, recvfrom                                           |
| `openssl`        | `libssl.dll/.so/.dylib`          | SSL_write, SSL_write_ex, SSL_read, SSL_read_ex                         |
| `gnutls`         | `libgnutls.so/.dll/.dylib`        | gnutls_record_send, gnutls_record_recv                                 |
| `schannel`       | `Secur32.dll` (Windows)          | EncryptMessage, DecryptMessage                                         |

---

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│            MCP Client (Claude / VS Code / Copilot)          │
│                       ▼ MCP protocol (stdio)                │
├─────────────────────────────────────────────────────────────┤
│                  YouNetMonitor-MCP Server                    │
│  ┌────────────────────────┐  ┌──────────────────────────┐   │
│  │  Session Manager        │  │  14 MCP Tools           │   │
│  │  (per-session thread + │  │  (attach/spawn/drain/   │   │
│  │   in-memory ring buffer)│  │   search/stop/stats)    │   │
│  └──────────┬─────────────┘  └──────────────────────────┘   │
│             │                                                │
│             ▼                                                │
│  ┌─────────────────────────────────────────────────────────┐│
│  │            deluder (vendored, GPL-3.0)                 ││
│  │  Frida-based dynamic instrumentation engine            ││
│  └──────────┬──────────────────────────────────────────────┘│
│             │                                                │
│             ▼                                                │
│  ┌─────────────────────────────────────────────────────────┐│
│  │  Frida runtime + JS hook scripts                        ││
│  │  (winsock.js, openssl.js, schannel.js, gnutls.js, libc) ││
│  └──────────┬──────────────────────────────────────────────┘│
│             │                                                │
│             ▼                                                │
│  ┌─────────────────────────────────────────────────────────┐│
│  │  Target process (local PID or remote frida-server host) ││
│  │  - any Windows / Linux / macOS app                      ││
│  │  - captures TCP/UDP + decrypted TLS in plaintext        ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
```

---

## Installation

**Requirements:** Python 3.10+, [Frida runtime](https://frida.re/) (pip-installable)

```bash
# From source
git clone https://github.com/YouKnowMako/YouNetMonitor-MCP.git
cd YouNetMonitor-MCP
pip install -e .

# Verify
younetmonitor-mcp --version
younetmonitor-mcp --list-tools
```

---

## MCP client configuration

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "younetmonitor": {
      "command": "younetmonitor-mcp"
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "mcpServers": {
    "younetmonitor": {
      "command": "python",
      "args": ["-m", "younetmonitor"]
    }
  }
}
```

### Generic MCP bridge (relay)

If your bridge spawns MCP servers via `command` + `args`, register YouNetMonitor-MCP the same way you would any stdio MCP server.

---

## Available tools (15)

| Tool                              | Description                                                                 |
|-----------------------------------|-----------------------------------------------------------------------------|
| `ynm_status`                      | Server version, deluder version, available scripts/interceptors             |
| `ynm_list_supported_scripts`      | List networking-library hook scripts (winsock, libc, openssl, gnutls, schannel) |
| `ynm_list_supported_interceptors` | List interceptor modules (log, proxifier, petep, **buffer**)                |
| `ynm_list_processes`              | List running processes (local or remote frida-server)                       |
| `ynm_get_process_by_name`         | Find a process by name (exact or substring match)                           |
| `ynm_attach_to_process`           | Attach deluder to a running PID/process-name → returns `session_id`         |
| `ynm_spawn_process`               | Spawn a new app with deluder attached → returns `session_id`               |
| `ynm_list_sessions`               | List all active capture sessions with status and config                     |
| `ynm_get_session`                 | Get detailed status of a single session (state, pid, error, stats)         |
| `ynm_stop_session`                | Stop a capture session (detaches frida; for spawned apps, kills the app)   |
| `ynm_remove_session`              | Remove a stopped session from the registry                                  |
| `ynm_get_events`                  | Drain (or peek) captured events, optionally filtered by timestamp/direction |
| `ynm_search_events`               | Search captured payloads by substring (ASCII or hex)                        |
| `ynm_get_session_stats`           | Per-session stats: total buffered, counts by direction, buffer capacity   |
| `ynm_default_config`              | Default session config as a template                                       |

---

## Example session (MCP tool calls)

In natural language:

> "Find the process `Telegram.exe`, attach deluder to it, then capture all TLS traffic for 30 seconds. Show me any event containing the word `account`."

Under the hood, the MCP client makes these tool calls:

1. `ynm_get_process_by_name({ "name": "Telegram.exe" })` → `{ "found": true, "pid": 12345 }`
2. `ynm_attach_to_process({ "target": "12345", "scripts": ["openssl", "schannel"] })` → `{ "session": { "session_id": "sess_abc123", "state": "running", ... } }`
3. *wait 30 seconds*
4. `ynm_search_events({ "session_id": "sess_abc123", "needle": "account" })` → `{ "matches": [ { "ts": ..., "direction": "send", "data_ascii": "POST /api/account HTTP/1.1\r\n..." } ] }`
5. `ynm_stop_session({ "session_id": "sess_abc123" })`

---

## Remote capture (frida-server)

To intercept a process on a different machine:

1. On the remote machine, download and run `frida-server`:
   ```bash
   frida-server -l 0.0.0.0:27042
   ```
2. From the MCP client, pass `remote_host: "REMOTE_IP:27042"` to `ynm_attach_to_process` (or `ynm_spawn_process`, `ynm_list_processes`).

---

## How it works

YouNetMonitor-MCP adds a new **`buffer`** interceptor to deluder's pipeline. When deluder's Frida hooks fire (e.g. `SSL_write` inside the target process), the captured data flows:

```
Frida JS hook (in target process)
    ↓ send() message
deluder MessageRouter
    ↓ route()
BufferMessageInterceptor.intercept()
    ↓ CaptureEvent stored in deque(maxlen=N)
SessionManager (per-session thread)
    ↓ drained via ynm_get_events tool
MCP JSON-RPC response to the client
```

Each session has its own background thread (deluder's `delude()` is blocking), and its own bounded ring buffer. The buffer is drained by the `ynm_get_events` MCP tool.

---

## Limitations

- **Plaintext only when the TLS library is hookable.** If an app uses a statically-linked TLS stack with no exported symbols (some game engines, embedded Chromium-based UIs), deluder can't intercept plaintext — you'd see raw encrypted bytes instead. Use `ynm_list_supported_scripts` to see which libraries are hookable.
- **Plaintext TLS hooks capture before encryption / after decryption.** This means the bytes you see in `data_ascii` are the actual HTTP/protocol payloads — headers, body, query strings, etc.
- **Buffer is in-memory only.** Restart the server and buffered events are lost. For persistent capture, write events to a file from a downstream interceptor.
- **GPL-3.0 license.** Inherited from deluder. Commercial use requires source-code disclosure of derivatives.

---

## Project structure

```
YouNetMonitor-MCP/
├── younetmonitor/
│   ├── __init__.py          # Package exports
│   ├── __main__.py          # python -m younetmonitor
│   ├── common.py            # Constants, data classes
│   ├── session.py           # Session manager (per-session deluder thread)
│   ├── mcp_server.py       # MCP stdio JSON-RPC server (14 tools)
│   └── interceptors/
│       ├── __init__.py      # Registers 'buffer' in deluder's registry
│       └── buffer.py        # In-memory ring buffer interceptor
├── deluder/                 # Vendored deluder v1.2.1 (GPL-3.0)
│   ├── common.py
│   ├── core.py
│   ├── interceptors/        # log, proxifier, petep, (buffer added at runtime)
│   └── scripts/             # winsock.js, openssl.js, schannel.js, gnutls.js, libc.js
├── tests/
│   └── test_mcp_server.py   # Smoke tests for tool dispatch and protocol
├── examples/
│   └── usage.py             # Standalone Python example (no MCP client needed)
├── pyproject.toml
├── requirements.txt
├── LICENSE.md               # GPL-3.0
└── README.md
```

---

## Credits

- **deluder** by [Warxim](https://github.com/Warxim) — the underlying Frida-based traffic interception engine, vendored unchanged.
- **[Frida](https://frida.re/)** — dynamic instrumentation toolkit.

---

## License

[GNU General Public License v3.0](LICENSE.md) — inherited from deluder.