diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..ebaecd6 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +.omc +Paralogue_MITM.ini +frida_hooks/gui_config.json \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..231a61a --- /dev/null +++ b/README.md @@ -0,0 +1,195 @@ +# Paralogue MITM Toolkit + +Man-in-the-middle proxy and protocol analysis toolkit for **Operation Lovecraft: Fallen Doll** (Paralogue). Intercepts, decodes, modifies, and injects game network traffic in real time via a desktop GUI. + +## Features + +- **Real-time packet inspector** — decoded protobuf messages with JSON syntax highlighting and hex dump +- **Bidirectional wire decryption** — ChaCha20 key extraction via Frida, proxy-side decrypt/re-encrypt +- **Packet modification** — frame-aware S->C rewriter with pluggable modifier callbacks +- **Packet injection** — send custom or replayed packets in both C->S and S->C directions +- **Full type mapping** — all 191 dispatch-table msg_ids resolved to protobuf type names via Frida GetTypeName() +- **ImGui GUI** with 6 tabs: Packets, Config, Session, Wire, Dispatch, Composer + +## Requirements + +- Python 3.12+ (tested on 3.13) +- Windows 10/11 +- [Frida](https://frida.re/) (`pip install frida-tools`) +- [imgui-bundle](https://github.com/pthom/imgui_bundle) (`pip install imgui-bundle`) +- [cryptography](https://pypi.org/project/cryptography/) (`pip install cryptography`) +- [protobuf](https://pypi.org/project/protobuf/) (`pip install protobuf`) + +``` +pip install frida-tools imgui-bundle cryptography protobuf +``` + +## Quick Start + +### GUI mode (recommended) + +```bat +cd frida_hooks +run_gui.bat +``` + +1. GUI opens with proxy listening on ports 11001 (game) and 18801 (HTTP dispatch) +2. Click **"Launch Game (Steam)"** or launch via Steam manually +3. Frida auto-attaches, hooks installed, redirect active +4. Log in — packets stream into the **Packets** tab +5. Toggle modifiers in the **Config** tab +6. Click any packet → **Send** tab → **"Replay Original"** or **"Open in Composer"** + +### Headless mode (CLI) + +```bat +cd frida_hooks +run_mitm.bat :: normal passthrough +run_mitm.bat --inject-items :: with all modifiers active +run_mitm.bat --no-decoder :: proxy only, no Frida +``` + +### Re-extract type names (after game update) + +```bat +:: Game must be running +cd frida_hooks +run_extract_types.bat +``` + +Updates `dispatch_type_names.json`, `known_msg_ids.json`, and `factory_to_type.json`. + +## Architecture + +``` +┌────────────┐ ┌─────────────────────┐ ┌──────────────┐ +│ Game │◄──►│ Proxy (port 11001) │◄──►│ Real Server │ +│ Client │ │ ┌───────────────┐ │ │ 3.33.185.193│ +│ │ │ │ WireRewriter │ │ │ │ +│ Frida ────┼────┤ │ S->C + C->S │ │ │ │ +│ hooks │ │ └───────────────┘ │ │ │ +└────────────┘ │ ┌───────────────┐ │ └──────────────┘ + │ │ Modifier Chain│ │ + │ └───────────────┘ │ + └──────────┬──────────┘ + │ SharedState + ┌──────────▼──────────┐ + │ ImGui GUI │ + │ (main thread) │ + └─────────────────────┘ +``` + +### Threading model + +- **Main thread**: ImGui render loop at ~60fps +- **Background daemon thread**: asyncio event loop running the TCP proxy, Frida bridge, and injection consumer +- **SharedState**: thread-safe bridge (deque for packets, Lock for config, inject_queue for packet injection) + +### Encryption + +The game uses **ChaCha20** stream cipher with a shared key+nonce for both directions but independent byte counters: + +| Offset | Field | Usage | +|--------|-------|-------| +| +0x68 | key ptr | 32B ChaCha20 key (shared) | +| +0x78 | nonce ptr | 12B nonce (shared) | +| +0x88 | EVP ctx | encrypt (C->S) | +| +0x90 | EVP ctx | decrypt (S->C) | +| +0x98 | counter | encrypt byte offset (C->S) | +| +0xA0 | counter | decrypt byte offset (S->C) | + +The proxy uses `WireRewriter` per direction to decrypt→modify→re-encrypt. ChaCha20 XOR involution means identity transforms produce byte-identical output. + +### Wire format + +``` +[2B big-endian prefix N][N-byte PacketHead protobuf][body_len bytes body] +``` + +PacketHead fields: `msg_id`, `body_len`, `packet_id` (request-response correlation), `seq_id`, `flag`, `total_pack_count`. + +## GUI Tabs + +### Packets +Real-time scrolling table of decoded messages. Filter by direction, source (Frida/wire), msg_id, or type name. Click a row to expand: +- **Tree** — recursive protobuf field viewer +- **JSON** — syntax-highlighted JSON via TextEditor +- **Hex** — formatted hex dump with ASCII sidebar +- **Send** — replay original or open in Composer + +### Config +Toggle modifiers individually: +- **Card Bag Expand** — `CardBagOpenRsp.rets` → 0..2000 (unlock experiments) +- **Inject Blueprints** — add 11000..11999 to bag (lootbox items) +- **Role Attrs Saturate** — max affection, dilation, unlock all roles +- **Inject Bag Items** — dense fill across cloth/card/normal ranges +- **Unlock Functions** — populate `PlayerMainDataRsp.unlockFunctions` + +Parameter sliders for card range, attr values. Auto-saves to `gui_config.json`. + +### Session +Session key/nonce, game PID, Frida status (color-coded), proxy ports, dispatch summary, packet counts. Action buttons: +- **Restart Frida** — reattach after game relaunch +- **Launch Game (Steam)** — opens via `steam://rungameid/2701680` + +### Wire +Raw encrypted traffic hex viewer with timestamps and direction arrows. + +### Dispatch +All 191 msg_id → protobuf type mappings. Green = pinned (resolved), red = unknown. Searchable by type name. + +### Composer +Compose and send custom protobuf packets: +1. Select type from dropdown (all 191 dispatch types) +2. Edit JSON in syntax-highlighted editor +3. Choose direction (C->S / S->C) +4. Click Send + +## Files + +| File | Purpose | +|------|---------| +| `frida_hooks/paralogue_gui.py` | ImGui GUI application | +| `frida_hooks/paralogue_mitm.py` | Core proxy + Frida bridge + WireRewriter | +| `frida_hooks/paralogue_decoder.py` | Protobuf framing, identification, parsing | +| `frida_hooks/protocol_decoder.js` | Frida hooks for decrypt/encrypt wrappers | +| `frida_hooks/redirect_connect.js` | Frida ws2_32!connect redirect hook | +| `frida_hooks/dispatch_dump.js` | Frida dispatch table walker | +| `frida_hooks/extract_type_names.js` | Frida GetTypeName() extraction | +| `frida_hooks/item_table_dump.js` | Frida bag item subsystem walker | +| `frida_hooks/paralogue_net_full.proto` | 239-message protobuf schema | +| `frida_hooks/paralogue_net_full_pb2.py` | Compiled protobuf module | +| `frida_hooks/dispatch_type_names.json` | msg_id → type name (ground truth, 191 entries) | +| `frida_hooks/factory_to_type.json` | vtable → type name (stable across runs) | +| `frida_hooks/known_msg_ids.json` | Merged msg_id → type cache | +| `frida_hooks/gui_config.json` | Persisted GUI modifier toggles | +| `frida_hooks/run_gui.bat` | GUI launcher | +| `frida_hooks/run_mitm.bat` | CLI launcher | +| `frida_hooks/run_extract_types.bat` | Type extraction launcher | +| `RESEARCH.md` | Detailed protocol research notes | + +## Game Data Model + +### Bag items (BagItemFullS2C, msg_id 1036) + +| ID range | Category | Description | +|----------|----------|-------------| +| 0-999 | Experiments/Cards | Unlocked via CardBagOpen | +| 11000-11999 | Pack/Blueprints | Lootbox items (open → grant card) | +| 20000-28999 | Card/Normal | Collectibles | +| 31000-31999 | Cloth | Outfit pieces | +| 40000-40999 | Normal | Misc items | +| 99000-99999 | Money | Currencies (with counts) | + +### Experiments +- Stored as client-side `learn_cards` collection (persisted on disk) +- Updated incrementally via `CardBagOpenRsp.rets[].card_id` +- UI filters by client DataTable (invalid IDs silently dropped) +- Unlock all: enable "Card Bag Expand" modifier, open one blueprint + +### Roles (RoleListFullS2C, msg_id 1202) +Per-role data: `name`, `is_unlock`, `favor_lv`, `worn_clothes[]`, `preset_clothes[]`, `attrs{}`, `appearance`, `clothes_colors`. + +## License + +Research and educational purposes only. Not affiliated with the game developers. diff --git a/RESEARCH.md b/RESEARCH.md index dbafb59..1b96db0 100644 --- a/RESEARCH.md +++ b/RESEARCH.md @@ -1542,6 +1542,38 @@ The JSON tab uses `imgui_color_text_edit.TextEditor` with but saturating to 999 had no visible UI effect. Likely achievement/stat counters, not unlock flags. +### Bidirectional packet injection + +Both S->C and C->S injection require a `WireRewriter` per direction +so the proxy controls the cipher counter for the entire byte stream. +Without a rewriter, injecting extra bytes permanently desynchronizes +the receiver's decrypt counter from the sender's encrypt counter. + +**S->C injection** (server push simulation): +- Encrypts via `s2c_rewriter.cipher_out` → `client_writer` +- Uses `packet_id=0` (push semantics; non-zero would imply a + response to a request the client never sent → disconnect) + +**C->S injection** (client request simulation): +- Encrypts via `c2s_rewriter.cipher_out` → `server_writer` +- Uses auto-incrementing `packet_id` (client requests are sequential) + +Both paths acquire a per-direction `asyncio.Lock` to prevent +interleaved writes between `pipe()` and the injection consumer. + +`build_frame(msg_id, body, packet_id, seq_id, flag)` constructs +wire frames: `[2B big-endian prefix][PacketHead protobuf][body]`. + +### PacketHead field semantics + +From captured traffic: +- `packet_id`: request-response correlation. C->S increments 1,2,3... + S->C responses echo the request's id. S->C pushes use 0. +- `seq_id`: always 0 in observed traffic. +- `flag`: always 0 in observed traffic. +- `total_pack_count`: always 0 (no fragmentation observed). +- `body_len`: body size in bytes (not including head or prefix). + ### Quick-start with GUI ``` @@ -1553,4 +1585,6 @@ frida_hooks\run_gui.bat # Login → packets stream into Packets tab # Toggle modifiers in Config tab as needed # Restart Frida after game relaunch via Session tab button +# Click any packet → Send tab → "Replay Original" or "Open in Composer" +# Composer tab → select type, edit JSON, Send ``` diff --git a/frida_hooks/paralogue_gui.py b/frida_hooks/paralogue_gui.py index f3f09f3..14d5f28 100644 --- a/frida_hooks/paralogue_gui.py +++ b/frida_hooks/paralogue_gui.py @@ -464,8 +464,7 @@ class GuiState: te.TextEditor.LanguageDefinitionId.json) self.json_editor.set_read_only_enabled(True) self.json_editor.set_show_whitespaces_enabled(False) - # Replay / edit-send state - self.edit_mode: bool = False # True = JSON editor is writable + # Replay state self.replay_dir: int = 0 # 0 = same as original, 1 = C->S, 2 = S->C # Wire tab self.selected_wire: int = -1 @@ -674,42 +673,37 @@ def _tab_packet_inspector(shared: SharedState) -> None: f"[GUI] replay {send_dir} msg_id={sel.get('msg_id')}") imgui.same_line() - _, gs.edit_mode = imgui.checkbox("Edit mode", gs.edit_mode) - gs.json_editor.set_read_only_enabled(not gs.edit_mode) - if gs.edit_mode: - imgui.same_line() - if imgui.button("Send Edited JSON"): - _send_edited_json(shared, gs, sel, send_dir) + if imgui.button("Open in Composer"): + _open_in_composer(gs, sel, send_dir) imgui.end_tab_item() imgui.end_tab_bar() -def _send_edited_json(shared: SharedState, gs, sel: dict, - direction: str) -> None: - """Parse the JSON editor content back to protobuf and push to inject queue.""" - jtext = gs.json_editor.get_text() - msg_id = sel.get("msg_id", 0) +def _open_in_composer(gs, sel: dict, direction: str) -> None: + """Copy a captured packet's JSON into the Composer tab for editing.""" type_name = sel.get("msg_type", "") - cls = getattr(pb_mod, type_name, None) - if cls is None: - shared.log_lines.append(f"[!] unknown type: {type_name}") - return + # Find the type in the composer dropdown list. try: - from google.protobuf import json_format - m = cls() - json_format.Parse(jtext, m) - body = m.SerializeToString() - except Exception as e: - shared.log_lines.append(f"[!] JSON parse error: {e}") - return - shared.inject_queue.append({ - "direction": direction, - "msg_id": msg_id, - "body": body, - }) - shared.log_lines.append( - f"[GUI] send edited {direction} msg_id={msg_id} " - f"type={type_name} body={len(body)}B") + idx = _COMPOSER_TYPES.index(type_name) + except ValueError: + idx = gs.composer_type_idx # keep current if not found + gs.composer_type_idx = idx + gs._composer_loaded_idx = -1 # force reload on next frame + # Set direction. + gs.composer_dir = 0 if direction == "C->S" else 1 + # Load the packet's JSON into composer editor. + jtext = sel.get("json_str", "") + if not jtext: + fields = sel.get("fields") + if fields: + try: + jtext = json.dumps(fields, indent=2, ensure_ascii=False, + default=str) + except Exception: + jtext = "{}" + if jtext: + gs.composer_editor.set_text(jtext) + gs._composer_loaded_idx = idx # prevent overwrite on next frame def _tab_configuration(shared: SharedState) -> None: