rcdebug 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,776 @@
1
+ """
2
+ Client Runtime Bridge (rcdebug --client):
3
+ - Local HTTP & WebSocket listener on 127.0.0.1:8765
4
+ - Auto-copies Luau diagnostic & telemetry snippet to macOS clipboard via pbcopy
5
+ - Processes runtime security findings, Remote Traffic Profiler data, and 10s Instance/Memory Diffs
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import base64
11
+ import hashlib
12
+ import json
13
+ import re
14
+ import struct
15
+ import threading
16
+ import time
17
+ from datetime import datetime
18
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
19
+ from pathlib import Path
20
+ from urllib.request import Request, urlopen
21
+
22
+ from .exporter import export_markdown_report
23
+ from .flaw_catalog import get_catalog
24
+ from .luau_payload import build_luau_bridge_script
25
+ from .models import AuditSession, Finding, MemorySnapshot, RemoteTrafficStat
26
+ from .terminal import (
27
+ BOLD,
28
+ CYAN,
29
+ DIM,
30
+ GREEN,
31
+ MAGENTA,
32
+ RED,
33
+ RESET,
34
+ WHITE,
35
+ YELLOW,
36
+ copy_to_clipboard,
37
+ normalize_filter_label,
38
+ print_banner,
39
+ print_finding,
40
+ print_memory_diff,
41
+ print_remote_traffic_update,
42
+ print_session_summary,
43
+ )
44
+
45
+ WS_MAGIC_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
46
+
47
+
48
+ class RuntimeBridgeServer(ThreadingHTTPServer):
49
+ allow_reuse_address = True
50
+
51
+ def __init__(
52
+ self,
53
+ server_address: tuple[str, int],
54
+ handler_class: type[BaseHTTPRequestHandler],
55
+ session: AuditSession,
56
+ filter_level: str | None = None,
57
+ ) -> None:
58
+ self.session = session
59
+ self.filter_level = filter_level
60
+ self.lock = threading.Lock()
61
+ try:
62
+ super().__init__(server_address, handler_class)
63
+ except Exception:
64
+ try:
65
+ self.server_close()
66
+ except Exception:
67
+ pass
68
+ raise
69
+
70
+
71
+ def process_report_payload(
72
+ server: RuntimeBridgeServer,
73
+ payload: dict | list,
74
+ ) -> int:
75
+ items = payload if isinstance(payload, list) else [payload]
76
+ catalog = get_catalog()
77
+ added_count = 0
78
+ with server.lock:
79
+ for item in items:
80
+ if not isinstance(item, dict):
81
+ continue
82
+ finding = Finding(
83
+ severity=str(item.get("severity", "INFO")),
84
+ title=str(item.get("title", "Security Finding")),
85
+ path=str(item.get("path", "Unknown")),
86
+ flaw=str(item.get("flaw", "")),
87
+ abuse=str(item.get("abuse", "")),
88
+ fix=str(item.get("fix", "")),
89
+ category=str(item.get("category", "RuntimeAudit")),
90
+ code_example=str(item.get("code_example", "")),
91
+ )
92
+ catalog.enrich_finding(finding)
93
+ if server.session.add_finding(finding):
94
+ added_count += 1
95
+ print_finding(finding, filter_level=server.filter_level)
96
+ return added_count
97
+
98
+
99
+ def process_telemetry_payload(
100
+ server: RuntimeBridgeServer,
101
+ payload: dict,
102
+ ) -> None:
103
+ with server.lock:
104
+ now_str = datetime.now().strftime("%H:%M:%S")
105
+ elapsed = float(payload.get("elapsed_sec", 0.0))
106
+ ws_inst = int(payload.get("workspace_instances", 0))
107
+ pl_inst = int(payload.get("player_instances", 0))
108
+ mem_mb = float(payload.get("total_memory_mb", 0.0))
109
+
110
+ prev_snap = (
111
+ server.session.memory_snapshots[-1]
112
+ if server.session.memory_snapshots
113
+ else None
114
+ )
115
+ curr_snap = MemorySnapshot(
116
+ timestamp=now_str,
117
+ elapsed_sec=elapsed,
118
+ workspace_instances=ws_inst,
119
+ player_instances=pl_inst,
120
+ total_memory_mb=mem_mb,
121
+ )
122
+ server.session.memory_snapshots.append(curr_snap)
123
+ print_memory_diff(prev_snap, curr_snap)
124
+
125
+ # Detect instance leak or memory spike between 10s snapshots
126
+ if prev_snap is not None:
127
+ ws_delta = curr_snap.workspace_instances - prev_snap.workspace_instances
128
+ pl_delta = curr_snap.player_instances - prev_snap.player_instances
129
+ mem_delta = curr_snap.total_memory_mb - prev_snap.total_memory_mb
130
+
131
+ if ws_delta >= 75 or mem_delta >= 20.0:
132
+ sev = "CRITICAL" if (ws_delta >= 200 or mem_delta >= 50.0) else "WARN"
133
+ leak_finding = Finding(
134
+ severity=sev,
135
+ category="MemoryDiff",
136
+ title=f"Instance / Memory Growth Spike (+{ws_delta} Workspace instances, {mem_delta:+.1f} MB)",
137
+ path="Workspace / Memory",
138
+ flaw=(
139
+ f"Between 10s snapshots ({prev_snap.timestamp} -> {curr_snap.timestamp}), "
140
+ f"Workspace grew by {ws_delta:+d} instances (Players {pl_delta:+d}) and "
141
+ f"total memory changed by {mem_delta:+.2f} MB."
142
+ ),
143
+ abuse=(
144
+ "Uncleaned projectiles, VFX parts, or disconnected event connections cause progressive "
145
+ "server lag, replication choke, and eventual server crash."
146
+ ),
147
+ fix=(
148
+ "Schedule transient instances for cleanup with Debris:AddItem(instance, lifetime), "
149
+ "pool high-frequency projectiles, and disconnect RBXScriptConnections on destroy."
150
+ ),
151
+ code_example=(
152
+ 'local Debris = game:GetService("Debris")\n'
153
+ "local fxPart = projectileTemplate:Clone()\n"
154
+ "fxPart.Parent = workspace.Effects\n"
155
+ "Debris:AddItem(fxPart, 3) -- Guaranteed cleanup after 3 seconds"
156
+ ),
157
+ )
158
+ server.session.add_finding(leak_finding)
159
+ print_finding(leak_finding, filter_level=server.filter_level)
160
+
161
+ # Process Remote Traffic Profiler samples
162
+ remotes = payload.get("remotes", [])
163
+ if isinstance(remotes, list):
164
+ for rem in remotes:
165
+ if not isinstance(rem, dict):
166
+ continue
167
+ rpath = str(rem.get("remote_path", "UnknownRemote"))
168
+ rtype = str(rem.get("remote_type", "RemoteEvent"))
169
+ total_calls = int(rem.get("total_calls", 0))
170
+ rate = float(rem.get("rate_per_sec", 0.0))
171
+
172
+ stat = server.session.remote_traffic.get(rpath)
173
+ if stat is None:
174
+ stat = RemoteTrafficStat(remote_path=rpath, remote_type=rtype)
175
+ server.session.remote_traffic[rpath] = stat
176
+
177
+ stat.total_calls = total_calls
178
+ stat.last_rate_per_sec = rate
179
+ if rate > stat.peak_rate_per_sec:
180
+ stat.peak_rate_per_sec = rate
181
+
182
+ if rate > 0:
183
+ print_remote_traffic_update(rpath, rate, total_calls)
184
+
185
+ if rate >= 12.0 and not stat.has_cooldown_warning:
186
+ stat.has_cooldown_warning = True
187
+ sev = "CRITICAL" if rate >= 25.0 else "WARN"
188
+ spam_finding = Finding(
189
+ severity=sev,
190
+ category="RemoteTraffic",
191
+ title=f"Unthrottled Remote Traffic ({rate:.1f} calls/sec): {rpath}",
192
+ path=rpath,
193
+ flaw=(
194
+ f"Remote '{rpath}' is firing at {rate:.1f} calls/sec "
195
+ f"(total {total_calls} calls) without effective server-side rate limiting."
196
+ ),
197
+ abuse=(
198
+ "Exploiters can fire this remote hundreds of times per frame to exhaust server CPU, "
199
+ "flood replication queues, or exploit non-atomic datastore/currency operations."
200
+ ),
201
+ fix=(
202
+ "Add a per-player rate limiter (os.clock() cooldown map or token bucket) at the very "
203
+ "start of OnServerEvent before performing any workspace, table, or datastore work."
204
+ ),
205
+ code_example=(
206
+ "local COOLDOWN = 0.25\n"
207
+ "local lastCall: {[Player]: number} = {}\n"
208
+ "Players.PlayerRemoving:Connect(function(plr) lastCall[plr] = nil end)\n\n"
209
+ "remote.OnServerEvent:Connect(function(plr, ...)\n"
210
+ " local now = os.clock()\n"
211
+ " if now - (lastCall[plr] or 0) < COOLDOWN then return end\n"
212
+ " lastCall[plr] = now\n"
213
+ " -- Safe to process request\n"
214
+ "end)"
215
+ ),
216
+ )
217
+ server.session.add_finding(spam_finding)
218
+ print_finding(spam_finding, filter_level=server.filter_level)
219
+
220
+
221
+ class DebugReportHandler(BaseHTTPRequestHandler):
222
+ server: RuntimeBridgeServer # type annotation for IDE/typechecker
223
+
224
+ def log_message(self, format: str, *args: object) -> None:
225
+ # Suppress default HTTP access logs for clean terminal dashboard output
226
+ pass
227
+
228
+ def _send_json(self, status_code: int, data: dict) -> None:
229
+ body = json.dumps(data).encode("utf-8")
230
+ self.send_response(status_code)
231
+ self.send_header("Content-Type", "application/json")
232
+ self.send_header("Content-Length", str(len(body)))
233
+ self.end_headers()
234
+ self.wfile.write(body)
235
+
236
+ def do_GET(self) -> None:
237
+ # Check if client requested a WebSocket upgrade
238
+ upgrade = self.headers.get("Upgrade", "").lower()
239
+ if upgrade == "websocket":
240
+ self._handle_websocket()
241
+ return
242
+
243
+ if self.path in ("/", "/status", "/health"):
244
+ counts = self.server.session.counts_by_severity()
245
+ self._send_json(
246
+ 200,
247
+ {
248
+ "status": "ok",
249
+ "tool": "rcdebug",
250
+ "mode": self.server.session.mode,
251
+ "findings_count": len(self.server.session.findings),
252
+ "severity_counts": counts,
253
+ "snapshots_count": len(self.server.session.memory_snapshots),
254
+ "remotes_profiled": len(self.server.session.remote_traffic),
255
+ },
256
+ )
257
+ return
258
+
259
+ self._send_json(404, {"error": "not_found"})
260
+
261
+ def do_POST(self) -> None:
262
+ content_length = int(self.headers.get("Content-Length", 0))
263
+ raw_body = self.rfile.read(content_length).decode("utf-8", errors="replace")
264
+
265
+ try:
266
+ data = json.loads(raw_body) if raw_body else {}
267
+ except json.JSONDecodeError:
268
+ self._send_json(400, {"error": "invalid_json"})
269
+ return
270
+
271
+ if self.path == "/report":
272
+ added = process_report_payload(self.server, data)
273
+ self._send_json(200, {"status": "ok", "added": added})
274
+ elif self.path == "/telemetry":
275
+ if isinstance(data, dict):
276
+ process_telemetry_payload(self.server, data)
277
+ self._send_json(200, {"status": "ok"})
278
+ else:
279
+ self._send_json(400, {"error": "expected_object"})
280
+ elif self.path == "/shutdown":
281
+ self._send_json(200, {"status": "shutting_down"})
282
+ threading.Thread(target=self.server.shutdown, daemon=True).start()
283
+ else:
284
+ self._send_json(404, {"error": "not_found"})
285
+
286
+ def _handle_websocket(self) -> None:
287
+ """Minimal RFC 6455 WebSocket handler for Studio WebSocket streams."""
288
+ ws_key = self.headers.get("Sec-WebSocket-Key", "")
289
+ if not ws_key:
290
+ self.send_response(400)
291
+ self.end_headers()
292
+ return
293
+
294
+ accept_raw = hashlib.sha1((ws_key + WS_MAGIC_GUID).encode("utf-8")).digest()
295
+ accept_key = base64.b64encode(accept_raw).decode("utf-8")
296
+
297
+ self.send_response(101, "Switching Protocols")
298
+ self.send_header("Upgrade", "websocket")
299
+ self.send_header("Connection", "Upgrade")
300
+ self.send_header("Sec-WebSocket-Accept", accept_key)
301
+ self.end_headers()
302
+
303
+ while True:
304
+ try:
305
+ header = self.rfile.read(2)
306
+ if not header or len(header) < 2:
307
+ break
308
+ b1, b2 = header[0], header[1]
309
+ opcode = b1 & 0x0F
310
+ if opcode == 0x8: # Close frame
311
+ break
312
+ masked = bool(b2 & 0x80)
313
+ payload_len = b2 & 0x7F
314
+ if payload_len == 126:
315
+ ext = self.rfile.read(2)
316
+ payload_len = struct.unpack(">H", ext)[0]
317
+ elif payload_len == 127:
318
+ ext = self.rfile.read(8)
319
+ payload_len = struct.unpack(">Q", ext)[0]
320
+
321
+ mask_key = self.rfile.read(4) if masked else b""
322
+ payload_bytes = bytearray(self.rfile.read(payload_len))
323
+ if masked and mask_key:
324
+ for i in range(len(payload_bytes)):
325
+ payload_bytes[i] ^= mask_key[i % 4]
326
+
327
+ text = payload_bytes.decode("utf-8", errors="replace")
328
+ msg = json.loads(text)
329
+ if isinstance(msg, dict) and "workspace_instances" in msg:
330
+ process_telemetry_payload(self.server, msg)
331
+ else:
332
+ process_report_payload(self.server, msg)
333
+ except Exception:
334
+ break
335
+
336
+
337
+ ROBLOX_LOGS_DIR = Path.home() / "Library" / "Logs" / "Roblox"
338
+
339
+ _WIRE_REPORT_RE = re.compile(r"\[rcdebug-wire:report\]\s+(\{.*\})\s*$")
340
+ _WIRE_TELEMETRY_RE = re.compile(r"\[rcdebug-wire:telemetry\]\s+(\{.*\})\s*$")
341
+ _CONSOLE_FINDING_RE = re.compile(
342
+ r"\[rcdebug-console\]\s+\[(CRITICAL|WARN|INFO)\]\s+\[([^\]]+)\]\s+(.+?)\s+\|\s+(.+?)\s*$"
343
+ )
344
+ _CONSOLE_TELEMETRY_RE = re.compile(
345
+ r"\[rcdebug-console\]\s+t=([\d.]+)s\s+\|\s+Workspace=(\d+)\s+\|\s+(?:LocalPlayer|Players)=(\d+)\s+\|\s+Mem=([\d.]+)\s+MB"
346
+ )
347
+
348
+
349
+ def ingest_log_line(server: RuntimeBridgeServer, line: str) -> bool:
350
+ """
351
+ Parses a single Roblox log line for rcdebug wire JSON or console fallback messages
352
+ and dispatches them to the active RuntimeBridgeServer session.
353
+ Returns True if the line was handled.
354
+ """
355
+ if "[rcdebug" not in line:
356
+ return False
357
+
358
+ m_rep = _WIRE_REPORT_RE.search(line)
359
+ if m_rep:
360
+ try:
361
+ data = json.loads(m_rep.group(1))
362
+ process_report_payload(server, data)
363
+ return True
364
+ except json.JSONDecodeError:
365
+ pass
366
+
367
+ m_tel = _WIRE_TELEMETRY_RE.search(line)
368
+ if m_tel:
369
+ try:
370
+ data = json.loads(m_tel.group(1))
371
+ if isinstance(data, dict):
372
+ process_telemetry_payload(server, data)
373
+ return True
374
+ except json.JSONDecodeError:
375
+ pass
376
+
377
+ m_cf = _CONSOLE_FINDING_RE.search(line)
378
+ if m_cf:
379
+ sev, cat, title, path = m_cf.groups()
380
+ process_report_payload(
381
+ server,
382
+ {
383
+ "severity": sev,
384
+ "category": cat,
385
+ "title": title,
386
+ "path": path,
387
+ "flaw": f"Detected via Roblox Client Console ({cat}) on {path}.",
388
+ "abuse": "Client-exposed state, remote, or unanchored physics surface can be manipulated locally.",
389
+ "fix": "Enforce server-authoritative validation, cooldowns, and ServerScriptService state.",
390
+ },
391
+ )
392
+ return True
393
+
394
+ m_ct = _CONSOLE_TELEMETRY_RE.search(line)
395
+ if m_ct:
396
+ elapsed, ws_inst, pl_inst, mem_mb = m_ct.groups()
397
+ process_telemetry_payload(
398
+ server,
399
+ {
400
+ "elapsed_sec": float(elapsed),
401
+ "workspace_instances": int(ws_inst),
402
+ "player_instances": int(pl_inst),
403
+ "total_memory_mb": float(mem_mb),
404
+ "remotes": [],
405
+ },
406
+ )
407
+ return True
408
+
409
+ return False
410
+
411
+
412
+ class RobloxLogTailer:
413
+ """
414
+ Tails active Roblox Player & Studio log files on macOS (~/Library/Logs/Roblox/)
415
+ so 100% client-sided scripts stream seamlessly to the terminal even when
416
+ Roblox restricts HttpService.PostAsync inside live Client contexts.
417
+ """
418
+
419
+ def __init__(
420
+ self,
421
+ server: RuntimeBridgeServer,
422
+ log_dir: Path = ROBLOX_LOGS_DIR,
423
+ replay_latest: bool = False,
424
+ poll_interval: float = 0.2,
425
+ ) -> None:
426
+ self.server = server
427
+ self.log_dir = log_dir
428
+ self.replay_latest = replay_latest
429
+ self.poll_interval = poll_interval
430
+ self._stop_event = threading.Event()
431
+ self._offsets: dict[Path, int] = {}
432
+ self._thread: threading.Thread | None = None
433
+
434
+ def _candidate_logs(self) -> list[Path]:
435
+ if not self.log_dir.exists():
436
+ return []
437
+ files = []
438
+ for p in self.log_dir.iterdir():
439
+ if not p.is_file() or not p.name.endswith("_last.log"):
440
+ continue
441
+ if "CrashHandler" in p.name:
442
+ continue
443
+ if "_Player_" in p.name or "_Studio_" in p.name:
444
+ files.append(p)
445
+ files.sort(key=lambda p: p.stat().st_mtime, reverse=True)
446
+ return files
447
+
448
+ def _init_offsets(self) -> None:
449
+ candidates = self._candidate_logs()
450
+ for idx, path in enumerate(candidates):
451
+ try:
452
+ if self.replay_latest and idx == 0:
453
+ self._offsets[path] = 0
454
+ else:
455
+ self._offsets[path] = path.stat().st_size
456
+ except OSError:
457
+ continue
458
+
459
+ def poll_once(self) -> int:
460
+ processed = 0
461
+ for path in self._candidate_logs():
462
+ try:
463
+ size = path.stat().st_size
464
+ except OSError:
465
+ continue
466
+
467
+ if path not in self._offsets:
468
+ # Newly created log file after rcdebug started -> read from byte 0
469
+ self._offsets[path] = 0
470
+ elif size < self._offsets[path]:
471
+ # File rotated/truncated
472
+ self._offsets[path] = 0
473
+
474
+ offset = self._offsets[path]
475
+ if size <= offset:
476
+ continue
477
+
478
+ try:
479
+ with path.open("r", encoding="utf-8", errors="replace") as fh:
480
+ fh.seek(offset)
481
+ chunk = fh.read()
482
+ self._offsets[path] = fh.tell()
483
+ except OSError:
484
+ continue
485
+
486
+ for line in chunk.splitlines():
487
+ if ingest_log_line(self.server, line):
488
+ processed += 1
489
+ return processed
490
+
491
+ def start(self) -> None:
492
+ self._init_offsets()
493
+ if self.replay_latest:
494
+ self.poll_once()
495
+ self._thread = threading.Thread(target=self._run_loop, daemon=True)
496
+ self._thread.start()
497
+
498
+ def _run_loop(self) -> None:
499
+ while not self._stop_event.is_set():
500
+ self.poll_once()
501
+ self._stop_event.wait(self.poll_interval)
502
+
503
+ def stop(self) -> None:
504
+ self._stop_event.set()
505
+ if self._thread and self._thread.is_alive():
506
+ self._thread.join(timeout=1.0)
507
+
508
+
509
+ def simulate_studio_playtest_traffic(host: str, port: int) -> None:
510
+ """
511
+ Sends realistic synthetic Roblox Studio playtest findings and telemetry snapshots
512
+ to the local rcdebug listener (used when --simulate is passed).
513
+ """
514
+ time.sleep(0.35)
515
+ report_url = f"http://{host}:{port}/report"
516
+ telemetry_url = f"http://{host}:{port}/telemetry"
517
+
518
+ def post(url: str, data: dict | list) -> None:
519
+ req = Request(
520
+ url,
521
+ data=json.dumps(data).encode("utf-8"),
522
+ headers={"Content-Type": "application/json"},
523
+ method="POST",
524
+ )
525
+ with urlopen(req, timeout=3) as resp:
526
+ resp.read()
527
+
528
+ sample_findings = [
529
+ {
530
+ "severity": "CRITICAL",
531
+ "category": "StateReplication",
532
+ "title": "Sensitive IntValue in Character: Cash",
533
+ "path": "Workspace.Player1.Cash",
534
+ "flaw": "Gameplay state ('cash') is stored in an IntValue parented inside the player's Character model.",
535
+ "abuse": (
536
+ "Because the Character model is subject to client physics/replication quirks and often read by poorly "
537
+ "written scripts, storing currency in Character allows tampering or state desync on respawn."
538
+ ),
539
+ "fix": "Move authoritative currency state into a ServerScriptService module table and expose read-only Attributes on Player.",
540
+ "code_example": (
541
+ "local Balances: {[number]: number} = {}\n"
542
+ "function AddCash(player: Player, delta: number)\n"
543
+ " Balances[player.UserId] = (Balances[player.UserId] or 0) + delta\n"
544
+ ' player:SetAttribute("Cash", Balances[player.UserId])\n'
545
+ "end"
546
+ ),
547
+ },
548
+ {
549
+ "severity": "WARN",
550
+ "category": "RemoteSecurity",
551
+ "title": "High-Value Network Endpoint: GiveCashRemote (matched 'cash')",
552
+ "path": "ReplicatedStorage.Remotes.GiveCashRemote",
553
+ "flaw": "RemoteEvent name suggests privileged currency mutation accessible to all clients.",
554
+ "abuse": "Malicious clients can fire GiveCashRemote:FireServer(999999999) or pass negative values to drain/mint currency.",
555
+ "fix": "Remove direct reward remotes; calculate rewards strictly inside server-side objective/combat completion handlers.",
556
+ "code_example": (
557
+ "-- Do NOT let clients request arbitrary currency.\n"
558
+ "-- Award currency on the server only when a verified server event completes."
559
+ ),
560
+ },
561
+ {
562
+ "severity": "WARN",
563
+ "category": "NetworkOwnership",
564
+ "title": "Unanchored Part with Client/Auto NetworkOwnership: VaultDoor",
565
+ "path": "Workspace.BankLevel.VaultDoor",
566
+ "flaw": "Unanchored interactive BasePart allows automatic client physics ownership (Current Owner: Auto).",
567
+ "abuse": "Exploiters standing near VaultDoor gain physics authority and can set its CFrame to bypass locked barriers.",
568
+ "fix": "Anchor the door and animate via server TweenService, or lock physics authority to the server via part:SetNetworkOwner(nil).",
569
+ "code_example": "workspace.BankLevel.VaultDoor:SetNetworkOwner(nil)",
570
+ },
571
+ {
572
+ "severity": "INFO",
573
+ "category": "RemoteSecurity",
574
+ "title": "Exposed Network Endpoint: SprintToggle",
575
+ "path": "ReplicatedStorage.Remotes.SprintToggle",
576
+ "flaw": "Client-accessible RemoteEvent found in ReplicatedStorage.",
577
+ "abuse": "Clients can fire SprintToggle with non-boolean payloads or spam it every frame.",
578
+ "fix": "Validate typeof(isSprinting) == 'boolean' and enforce a 0.15s per-player debounce on the server.",
579
+ },
580
+ ]
581
+
582
+ for f in sample_findings:
583
+ post(report_url, f)
584
+ time.sleep(0.1)
585
+
586
+ # Send baseline telemetry snapshot
587
+ post(
588
+ telemetry_url,
589
+ {
590
+ "elapsed_sec": 0.0,
591
+ "workspace_instances": 1420,
592
+ "player_instances": 85,
593
+ "total_memory_mb": 412.5,
594
+ "remotes": [
595
+ {
596
+ "remote_path": "ReplicatedStorage.Remotes.SprintToggle",
597
+ "remote_type": "RemoteEvent",
598
+ "total_calls": 4,
599
+ "rate_per_sec": 0.4,
600
+ }
601
+ ],
602
+ },
603
+ )
604
+ time.sleep(0.15)
605
+
606
+ # Send 10s snapshot with simulated remote spam & uncleaned debris spike
607
+ post(
608
+ telemetry_url,
609
+ {
610
+ "elapsed_sec": 10.0,
611
+ "workspace_instances": 1665,
612
+ "player_instances": 92,
613
+ "total_memory_mb": 448.2,
614
+ "remotes": [
615
+ {
616
+ "remote_path": "ReplicatedStorage.Remotes.GiveCashRemote",
617
+ "remote_type": "RemoteEvent",
618
+ "total_calls": 340,
619
+ "rate_per_sec": 34.0,
620
+ }
621
+ ],
622
+ },
623
+ )
624
+
625
+
626
+ def _try_reclaim_rcdebug_port(host: str, port: int) -> bool:
627
+ """If an older rcdebug listener is holding `host:port`, request a clean shutdown."""
628
+ try:
629
+ with urlopen(f"http://{host}:{port}/status", timeout=0.4) as resp:
630
+ info = json.loads(resp.read().decode("utf-8", errors="replace"))
631
+ if isinstance(info, dict) and info.get("tool") == "rcdebug":
632
+ req = Request(f"http://{host}:{port}/shutdown", data=b"{}", method="POST")
633
+ with urlopen(req, timeout=0.5) as sresp:
634
+ sresp.read()
635
+ time.sleep(0.15)
636
+ return True
637
+ except Exception:
638
+ pass
639
+ return False
640
+
641
+
642
+ def bind_runtime_bridge_server(
643
+ host: str,
644
+ preferred_port: int,
645
+ session: AuditSession,
646
+ filter_level: str | None = None,
647
+ max_tries: int = 50,
648
+ ) -> tuple[RuntimeBridgeServer, int, bool]:
649
+ """
650
+ Binds RuntimeBridgeServer to `preferred_port`. If another process (such as
651
+ MacSploit or another service) is already holding `preferred_port`, automatically
652
+ selects the next available port so `--client` never crashes with Errno 48.
653
+ """
654
+ try:
655
+ srv = RuntimeBridgeServer((host, preferred_port), DebugReportHandler, session=session, filter_level=filter_level)
656
+ return srv, int(srv.server_address[1]), False
657
+ except OSError:
658
+ if _try_reclaim_rcdebug_port(host, preferred_port):
659
+ try:
660
+ srv = RuntimeBridgeServer((host, preferred_port), DebugReportHandler, session=session, filter_level=filter_level)
661
+ return srv, int(srv.server_address[1]), False
662
+ except OSError:
663
+ pass
664
+
665
+ for offset in range(1, max_tries + 1):
666
+ candidate = preferred_port + offset
667
+ if candidate > 65535:
668
+ break
669
+ try:
670
+ srv = RuntimeBridgeServer((host, candidate), DebugReportHandler, session=session, filter_level=filter_level)
671
+ return srv, int(srv.server_address[1]), True
672
+ except OSError:
673
+ continue
674
+
675
+ srv = RuntimeBridgeServer((host, 0), DebugReportHandler, session=session, filter_level=filter_level)
676
+ return srv, int(srv.server_address[1]), True
677
+
678
+
679
+ def run_client_mode(
680
+ host: str = "127.0.0.1",
681
+ port: int = 8765,
682
+ filter_level: str | None = None,
683
+ export_path: str | None = None,
684
+ auto_clipboard: bool = True,
685
+ simulate: bool = False,
686
+ enable_log_tail: bool = True,
687
+ replay_latest_log: bool = False,
688
+ ) -> AuditSession:
689
+ catalog = get_catalog()
690
+ session = AuditSession(
691
+ mode="client",
692
+ target_name=f"Roblox Client Runtime Bridge ({host}:{port})",
693
+ )
694
+ server, actual_port, used_fallback = bind_runtime_bridge_server(
695
+ host=host,
696
+ preferred_port=port,
697
+ session=session,
698
+ filter_level=filter_level,
699
+ )
700
+ session.target_name = f"Roblox Client Runtime Bridge ({host}:{actual_port})"
701
+
702
+ print_banner(
703
+ "CLIENT RUNTIME BRIDGE",
704
+ subtitle=f"HTTP/WS ({host}:{actual_port}) + Log Bridge | {catalog.count():,} Flaw Signatures | Filter: {normalize_filter_label(filter_level)}",
705
+ )
706
+ if used_fallback:
707
+ print(
708
+ f"\n{YELLOW}{BOLD}⚠ Port {port} is in use by another process; "
709
+ f"automatically bound to {host}:{actual_port}.{RESET}"
710
+ )
711
+
712
+ luau_script = build_luau_bridge_script(host=host, port=actual_port)
713
+
714
+ if auto_clipboard:
715
+ copied = copy_to_clipboard(luau_script)
716
+ if copied:
717
+ print(f"\n{GREEN}{BOLD}✔ Luau diagnostic snippet automatically copied to macOS clipboard (pbcopy)!{RESET}")
718
+ print(f" {WHITE}Paste ({BOLD}Cmd+V{RESET}{WHITE}) into Roblox Client / Studio Command Bar.{RESET}")
719
+ else:
720
+ print(f"\n{YELLOW}⚠ Could not copy to clipboard automatically; copy the snippet below.{RESET}")
721
+
722
+ print(f"\n{YELLOW}{BOLD}─── Luau Diagnostic & Telemetry Bridge Snippet ───{RESET}")
723
+ print(f"{DIM}{luau_script.strip()}{RESET}")
724
+ print(f"{YELLOW}{BOLD}──────────────────────────────────────────────────{RESET}\n")
725
+
726
+ print(
727
+ f"{BOLD}{GREEN}● Listening for telemetry on{RESET} "
728
+ f"{BOLD}{CYAN}http://{host}:{actual_port}/report{RESET} & {BOLD}{CYAN}ws://{host}:{actual_port}/ws{RESET}"
729
+ )
730
+
731
+ log_tailer: RobloxLogTailer | None = None
732
+ if enable_log_tail and not simulate:
733
+ log_tailer = RobloxLogTailer(server, replay_latest=replay_latest_log)
734
+ log_tailer.start()
735
+ print(
736
+ f"{BOLD}{GREEN}● Roblox Log Bridge active — tailing{RESET} "
737
+ f"{BOLD}{CYAN}{ROBLOX_LOGS_DIR}{RESET}"
738
+ )
739
+
740
+ print(f"{DIM} Press Ctrl+C to stop listener and finalize session report.{RESET}")
741
+
742
+ if simulate:
743
+ print(f"\n{MAGENTA}{BOLD}[SIMULATION MODE]{RESET} Injecting sample playtest findings & 10s telemetry snapshots...")
744
+ sim_thread = threading.Thread(target=simulate_studio_playtest_traffic, args=(host, actual_port), daemon=True)
745
+ sim_thread.start()
746
+
747
+ def auto_stop() -> None:
748
+ sim_thread.join(timeout=5.0)
749
+ time.sleep(0.25)
750
+ server.shutdown()
751
+
752
+ threading.Thread(target=auto_stop, daemon=True).start()
753
+
754
+ try:
755
+ server.serve_forever()
756
+ except KeyboardInterrupt:
757
+ print(f"\n{YELLOW}[rcdebug] Stopping Client Runtime Bridge listener...{RESET}")
758
+ finally:
759
+ if log_tailer is not None:
760
+ log_tailer.stop()
761
+ server.server_close()
762
+
763
+ print_session_summary(session, filter_level=filter_level)
764
+
765
+ if session.findings:
766
+ learned_new = catalog.learner.learn_from_session(session, catalog)
767
+ print(
768
+ f"{GREEN}{BOLD}✔ Adaptive Learner:{RESET} +{learned_new} new pattern(s) learned "
769
+ f"({len(catalog.learner.learned_tokens)} total) -> {CYAN}{catalog.learner.store_path}{RESET}"
770
+ )
771
+
772
+ if export_path:
773
+ saved_file = export_markdown_report(session, export_path, filter_level=filter_level)
774
+ print(f"{GREEN}{BOLD}✔ Exported Markdown audit report to:{RESET} {CYAN}{saved_file}{RESET}\n")
775
+
776
+ return session